全方位進行專案程式碼審查,產生詳細且清楚的審查報告,並根據報告自動建立 OpenSpec change 的所有提案文件,用來規劃並修復所有發現的問題。
當使用者要求全面程式碼審查(Comprehensive Code Review)並建立對應的 OpenSpec 修復計畫時,請自動執行以下兩個主要階段:
蒐集專案脈絡:
README.md 或其他架構文件了解系統現況與業務邏輯。多維度深入分析: 請以擁有 20 年經驗的資深架構師與資安工程師的視角,針對以下面向進行最嚴格的審查:
產出審查報告:
P0_CRITICAL 致命, P1_HIGH 嚴重, P2_MEDIUM 中等, P3_LOW 輕微)。docs/CODE_REVIEW_REPORT.md。若有迭代版本,最終必須回寫整併至同一主檔(詳見「階段四:文件整理與合併」)。在產出報告後,須自動把這些問題轉化為具有行動力的 OpenSpec 修改提案:
建立新的 OpenSpec Change:
comprehensive-code-review-fixes 或針對特定模組更具體的名稱(若是迭代修復可附加序列號,如 fixes-iteration-2)。openspec new change "comprehensive-code-review-fixes"。產生並填寫 OpenSpec 提案文件: 主動根據審查報告來撰寫接下來的核心計畫 artifacts,省去使用者反覆確認的步驟:
proposal.md):
執行 openspec instructions proposal --change "<change-name>"。
說明發起原因為全面程式碼審查,目標為消除 P0-P3 的各項風險,並列出影響範圍。design.md):
執行 openspec instructions design --change "<change-name>"。
針對報告中提出的問題,逐一給出詳細的架構修改或技術實作設計。必須確保設計符合 Clean Code 標準並兼顧最佳執行效能。tasks.md):
執行 openspec instructions tasks --change "<change-name>"。
將修復設計拆解為具體、細粒度可執行的開發與測試步驟,並包含驗收標準 (AC)。由於一次修復可能無法根絕所有問題,或者修復過程中可能產生新的副作用,因此必須採用 「自動審查 $\to$ 自動修復 $\to$ 自動審查」 的無縫迭代循環:
/opsx-apply (或執行 openspec-apply-change 原理流程) 來根據 tasks.md 自動完成所有程式碼修復與測試,不需要等待使用者下指令。fixes-iteration-2),然後回到第 1 步繼續自動實作。README.md。docs/ 資料夾(或其他專用文件資料夾)中的相關文件與架構圖說明,確保文件與最新的程式碼實作保持絕對一致。docs/*),不得只留在對話訊息中。CODE_REVIEW_REPORT_v2.md、fixes-iteration-2 等)整理、合併並歸檔,避免 docs/ 留下多份同名或版本尾碼文件。openspec archive change "<change-name>" 來正式歸檔該 OpenSpec change,並在 CHANGELOG.md 中記錄此次修復的核心內容與影響。在 review-fix 全流程結束後,必須執行以下文件整併步驟,確保 docs/ 不殘留重複檔:
docs/ 下與審查流程相關的重複 Markdown,例如:
CODE_REVIEW_REPORT*.mdOPENSPEC_REVIEW_FIX_PLAN*.mddocs/CODE_REVIEW_REPORT.mddocs/OPENSPEC_REVIEW_FIX_PLAN.mddocs/ 根目錄。docs/archive/review-fix/(建議包含日期資料夾)。docs/ 根目錄中,審查主檔僅保留一份 canonical 檔名。在修復流程中,必須遵守以下 Git 工作規範:
先建立修復分支:
review-fix/<change-name>)。高頻提交(Small-Batch Commits):
提交順序建議:
fix: 漏洞修補test: 測試補強docs: 報告與文件同步chore: 文件整併/歸檔與收尾最終狀態:
在過程中可適時讓使用者知道目前進度。當「所有迭代循環完全結束」且「文件更新完畢」後,請以「臺灣繁體中文」向使用者總結:
docs/CODE_REVIEW_REPORT.md(及其迭代版本)已產生,並簡述盤點與修復的核心問題。README.md 與 docs/ 相關文件已經同步更新完畢。
3.1 若有重要提醒事項,已寫入對應文件且可被長期追蹤。docs/ 重複 Markdown 的整併,並說明 canonical 檔案與歸檔位置。當上述流程全部完成(含文件整併與最終 commit)後,必須主動詢問使用者是否要發起 PR,再進行後續 PR 建立動作。
另外,若需產生或更新 docs/CODE_REVIEW_REPORT.md(含迭代版本),其內容同樣必須維持「臺灣慣用語」的繁體中文一致性。
為了降低重複工,先執行以下腳本自動產生審查骨架與 OpenSpec 指令清單,再進入人工審查與修復:
python3 review-fix/scripts/bootstrap_review_fix.py --repo .
常用參數:
--change-name <name>:指定 OpenSpec change 名稱。--report-out <path>:指定報告輸出位置(預設 docs/CODE_REVIEW_REPORT.md)。--plan-out <path>:指定 OpenSpec 計畫輸出位置(預設 docs/OPENSPEC_REVIEW_FIX_PLAN.md)。--print-only:僅輸出內容,不寫入檔案。避免無限循環,最多迭代 3 輪;若連續 2 輪無新增 P0/P1 問題,或僅剩 P3 非阻斷項,即可結束並彙整後續改善項目。
當環境可使用 subagent 時,請優先採用以下編排,以縮短整體週期。
同時啟動 4 個 explorer,主責如下:
security-explorer:認證授權、輸入驗證、敏感資訊、注入風險。performance-explorer:N+1、重複計算、I/O 熱點、快取策略。quality-explorer:複雜度、重複邏輯、型別與可維護性。test-explorer:測試覆蓋缺口、脆弱測試、CI 風險。每個 explorer 都必須輸出:
主 agent 負責:
P0/P1/P2/P3。docs/CODE_REVIEW_REPORT.md。依模組切分 ownership 後,啟動多個 worker 平行修復。每位 worker 必須:
主 agent 最後統一執行全域測試與回歸確認。
Explorer 模板:
你是 {domain} explorer。請只做審查,不要改碼。
輸出:
1) Findings(含檔案:行號,依嚴重度排序)
2) Top 3 修復建議(含驗證方法)
3) 不確定假設與需要人工確認項目
Worker 模板:
你是 {module} worker,負責檔案範圍:{owned_files}。
你不是唯一在此 repo 工作的 agent,不可回退他人變更。
目標:修復指定 findings,補齊必要測試,回報變更檔案與測試結果。