當軟體工程團隊引入 Sweep AI 協助處理例行性 Bug 修復、小型功能開發與程式碼重構時，最常遭遇的挑戰是如何確保 AI 自動提交的 Pull Request（PR）嚴格符合團隊既有的編碼規範與架構約定。若缺乏明確的規則約束，AI 容易產出風格不一致的程式碼、遺漏單元測試、使用已被廢棄的內部工具函式，甚至無意間改動關鍵的 CI/CD 流程或資安配置。
為確保自動化 PR 真正達到生產環境的驗收標準，開發團隊通常以儲存庫根目錄下的 sweep.yaml 設定檔為核心，結合儲存庫規範文件（例如 SWEEP.md）、目錄保護機制以及 GitHub Actions 閉環回饋，建構一套完整的 AI 程式碼治理流程。
1. 核心控制平面：sweep.yaml 架構解析
sweep.yaml 位於專案儲存庫的根目錄，是 Sweep AI 代理行為的核心宣告文件。檔案內的各項參數直接決定 AI 如何解析專案結構、規劃變更範圍以及發起 PR。
以下是 sweep.yaml 的關鍵設定欄位：
| 參數 | 型別 | 預設值 | 功能說明 |
|---|---|---|---|
rules | list[str] | [] | 明確的編碼規範與約束指令清單，會直接注入 Sweep 的程式碼生成提示詞中。 |
description | str | "" | 專案全域架構、技術棧、主要端點與設計模式的高階說明。 |
blocked_dirs | list[str] | [] | 嚴格禁止 Sweep 進行修改的目錄或檔案清單（如 CI 設定、資料庫遷移版本、憑證配置）。 |
gha_enabled | bool | true | 是否允許 Sweep 讀取 GitHub Actions 的執行記錄，並在 CI 報錯時自動提交修正 Commit。 |
draft | bool | false | 是否預設以草稿（Draft）形式發起 PR，避免過度觸發耗時且昂貴的測試流水線。 |
branch | str | "main" | Sweep 讀取程式碼與提交 PR 的目標基準分支。 |
sandbox | dict | {} | 沙箱環境下的安裝與檢查指令（例如格式化工具、靜態分析指令）。 |
2. 如何在 sweep.yaml 中制定具約束力的規則
rules 欄位是團隊將內部工程規範轉化為大型語言模型約束條件的核心。模型面對「保持程式碼乾淨」這類模糊的要求往往無法有效落實，團隊必須提供具體、具命令式語氣且能被自動化驗證的指令。
重點規則類別與實踐方式
-
測試與涵蓋率規範
- 明確規定所有新增業務邏輯皆必須附帶同目錄或指定目錄下的單元測試。
- 範例：
"All new business logic must include corresponding unit tests in the same directory or tests/. Use pytest and unittest.mock."
-
型別系統與靜態分析
- 明確指示函式簽章的型別標註規範，避免過時或不推薦的語法。
- 範例：
"Annotate all function parameters and return types with type hints. Use built-in generics (list, tuple, dict) instead of importing from typing."
-
日誌標準與除錯程式碼清理
- 統一系統日誌輸出庫，嚴禁將除錯輸出或未經處理的列印語句帶入生產程式碼。
- 範例：
"Use loguru for application logging. In except blocks, call logger.exception with structured f-strings. Never leave print() statements in production code."
-
模組化架構與冗餘清理
- 約束單一函式的複雜度，並在重構時徹底解決遺留標記。
- 範例：
"Keep functions modular; refactor procedures longer than 50 lines. Remove redundant comments that merely restate the code. Handle all leftover TODOs."
3. 生產環境級 sweep.yaml 配置藍圖
以下是一份適用於現代後端或全端專案的典型 sweep.yaml 設定範例：
# sweep.yaml - Sweep AI 儲存庫自動化設定檔
# 指定 PR 的基準目標分支
branch: main
# 專案架構概覽、執行環境需求與主要入口點說明
description: >
This is a Python 3.10 microservice built on FastAPI with PostgreSQL.
The primary API routes are registered in app/api/v1/.
Use SQLAlchemy 2.0 async sessions for database access.
Strictly adhere to PEP 8 standards and asynchronous I/O paradigms.
# 新 PR 是否以草稿發起（團隊初檢確認後再轉為正式 PR）
draft: false
# 啟用 GitHub Actions 閉環：CI 失敗時由 Sweep 自動分析記錄並修復
gha_enabled: true
# 目錄防護：嚴禁 AI 修改 CI/CD 工作流程、資料庫遷移版本與金鑰憑證
blocked_dirs:
- ".github/"
- "alembic/versions/"
- "deploy/"
- "config/secrets/"
# 具體編碼標準清單
rules:
- "All new endpoints and service logic must include corresponding unit and integration tests using pytest."
- "Annotate all function parameters and return values with strict type hints."
- "Use structured logging via loguru; use logger.exception inside catch blocks. Never use print() statements."
- "Use list, dict, and tuple built-ins for type annotations instead of importing from typing."
- "Resolve any remaining TODO items created during refactoring before finalizing the PR."
- "Follow existing repository import conventions: group external libraries first, then internal module imports."
- "Do not modify database migrations or schema files without explicit issue instructions."
4. 進階治理：SWEEP.md 與儲存庫規範協同
在實務架構中，除了負責宣告機器參數的 sweep.yaml 之外，團隊經常在專案根目錄建立 SWEEP.md。
SWEEP.md 的核心定位
SWEEP.md 的概念類似於 CLAUDE.md 或 .cursorrules，主要提供持久化的專案情境。它不僅能指引 GitHub 端的自主 PR 生成，也能在開發者使用 IDE 擴充套件（如 JetBrains 插件）時提供完全一致的專案上下文。
標準的 SWEEP.md 通常劃分為四大核心內容：
- 建置與驗證命令： 清楚列出單元測試、靜態分析與程式碼格式化的執行指令（如
npm run lint、pytest tests/unit/ -v）。 - 程式碼風格偏好： 檔案命名慣例（如統一使用 kebab-case）、模組組織原則與推薦採用的內部共用庫。
- 架構與資料流向： 服務之間的相依關係、狀態管理方式及 API 介面協議。
- 審查檢驗清單： PR 標題格式、關聯 Issue 規則與變更日誌記錄標準。
團隊可以在 Sweep 設定介面的 Rules 頁籤中，點選 Generate SWEEP.md，由系統自動從現有的專案規範中萃取並生成基礎檔案。
5. CI/CD 閉環機制：依託 GitHub Actions 的自動修復循環
即使在提示詞中定義了嚴謹的規則，大語言模型在處理複雜專案的多檔案相依、全域型別推導或語法細節時，偶爾仍會出現語法或格式誤差。Sweep 確保程式碼品質最關鍵的機制，在於其與 GitHub Actions 的自動化自癒閉環（gha_enabled: true）。
+------------------+ +--------------------+ +--------------------+
| GitHub 發起 Issue | ------> | Sweep AI 規劃並生成 | ------> | 向目標分支發起 PR |
| / 需求工單 | | 程式碼與修改計畫 | | |
+------------------+ +--------------------+ +--------------------+
|
v
+--------------------+
| GitHub Actions |
| 執行 Linter、型別檢查 |
| 與單元測試 |
+--------------------+
|
+----------------------------------+
|
[通過] | [失敗報錯]
v | v
+-------------------+ | +--------------------+
| 進入人工審查階段 | | | Sweep 自動讀取 CI |
| (Code Review) | | | 錯誤記錄與行號細節 |
+-------------------+ | +--------------------+
| |
| v
| +--------------------+
+--------| 針對性修正並推送 Commit |
| 修復程式碼 |
+--------------------+
閉環運作機制說明：
- 建立分支與發起 PR： Sweep 依據 Issue 描述與
sweep.yaml規則完成程式碼變更並提交 PR。 - 觸發 CI 自動化驗證： GitHub Actions 執行儲存庫中既有的代碼檢查器（如 ESLint、Ruff、Trunk）、型別檢查器（
tsc、pyright）與測試套件。 - 錯誤日誌即時截取： 當 CI 步驟失敗時，Sweep 自動擷取失敗步驟的錯誤輸出與呼叫堆疊。
- 定位並自我修復： Sweep 精確鎖定報錯檔案、行號與具體錯誤訊息（如遺漏引用、型別衝突、縮排不合），透過差異修補演算法生成補丁，並直接向該 PR 分支追加 Commit。
- 大幅降低審查負擔： 人工工程師介入審查時，所有語法、排版與單元測試皆已確保通過，審核重心得以聚焦於商業邏輯與架構合理性。
6. 團隊落地的工程防護實踐
為了在提升開發速度的同時嚴格把控安全底線，建議團隊採取以下實務做法：
- 嚴格限制敏感目錄： 務必將
.github/、雲端部署設定、資料庫遷移腳本與金鑰目錄加入blocked_dirs，防止 AI 變更核心基礎設施。 - 縮小單次任務範疇： 保持任務精準小巧。每次 Issue 涉及的修改檔案建議控制在 3 到 5 個以內，總變更行數在 300 行以下，可顯著提升模型的成功率。
- 編寫具體明確的工單： 在建立 Issue 時清楚標明目標檔案、改動邏輯與參考模式（例如：
"In app/services/billing.py, refactor discount calculation using Decimal instead of float; follow patterns in app/services/tax.py"）。 - 利用 PR 留言進行微調： 若發現細微調整需求，團隊可在 PR 留言區輸入以
sweep:為前綴的指令，Sweep 會自動讀取並進行後續修訂，無需工程師手動切換分支。 - 導入初期採用 Draft 模式： 在剛引入 Sweep 或面對大型既有專案時，可先於
sweep.yaml設定draft: true，待人工初步篩選後再轉為正式 PR 觸發完整檢驗流程。