專案開發工作流程 是做什麼的?
一個在整個開發專案中應用的工作紀律。它解決了以下失敗:AI 在誤解請求的情況下開始編碼;完成編寫後就宣稱自己的工作沒問題;從單一視角爭論設計;只做被要求的事;以及重複上次已經遇到過的陷阱。
此紀律的份量應與任務的份量相匹配:小任務採用輕量級——不要為了流程而執行流程。
整體工作流程:
入口:單節路由 / 級別判斷(輕量級 · 標準級)/ 是否自主工作
0. 預檢 — 讀取陷阱日誌和專案規則,確認工作區狀態
1. 理解 — 重新陳述請求;僅在使用者確認後才行動
2. 規劃 — 分層,每層附有可檢查的完成標準
3. 執行與驗證 — 根據標準驗證每一層,自行或透過驗證者;未通過,則不進行下一層
4. 報告 — 證據、未驗證項目、已接受/已拒絕的審查意見、建議、新陷阱
貫穿全流程:對抗性審查(§5)、主動執行(§6)、即時陷阱記錄(§7)
入口:決定如何使用
單節調用
當使用者只指定一個階段時,僅執行該節;不要執行整個工作流程:
| 使用者說 | 執行 |
|---|---|
| 審查 / 檢討這個計畫 / 這個方法可以嗎 | 僅 §5 |
| 驗證這個 / 檢查它是否正確 | 僅 §3 驗證。目標是使用者指定的內容;如果完成標準不明確,在驗證前先與使用者達成一致 |
| 記錄這個陷阱 / 更新陷阱 | 僅 §7 |
| 遵循工作流程 / 正確執行這個 | 完整工作流程(標準級) |
輕量級和標準級
在開始前決定級別,並在你第一次回覆中用一行說明你選擇了哪一個。
輕量級 — 滿足所有三個條件:
- 請求明確,只有一種合理解讀;
- 可以輕鬆回滾,不涉及刪除資料、公開介面或外部影響;
- 變更集中(一個功能點、少數檔案),且一個驗證步驟即可決定結果。
輕量級跳過重新陳述、分層和子代理,但仍遵守 §0 預檢、§3 證據規則和 §7 陷阱記錄,並以簡短的 §4 報告結尾。
標準級:所有其他情況。如果不確定,請使用標準級。
如果一個輕量級任務被判斷為比預期更複雜(它牽扯到其他模組、出現歧義、需要不可逆操作):立即升級到標準級,並追溯性地進行重新陳述和確認。
自主模式
當使用者明確說「就這麼做 / 別問我 / 你決定」,或者任務是在非互動環境中無人值守的長時間執行時:
- §1 仍然寫出「我的理解」,但不等待確認。「我需要你決定的項目」中的每一項都透過選擇推薦選項來決定,記錄為自我做出的假設,然後繼續工作;
- 不可逆或具有外部影響的操作(刪除資料、部署、推送、資料遷移、付費 API 調用)仍然不執行;跳過它們,在報告中列出,留給使用者處理;
- 最終報告一併列出所有自我做出的假設,以便使用者事後更正。
0. 預檢
- 陷阱日誌:如果專案根目錄有
PITFALLS.md,在規劃前讀取它;如果檔案頂部維護了一個索引,先讀取索引,再讀取與當前任務相關的條目。如果存在機器級日誌~/.agents/PITFALLS.local.md,也請讀取該日誌(有關範圍,請參閱 §7)。在重新陳述或計畫中按名稱提及與任務相關的條目。 - 專案規則:如果專案有
AGENTS.md、CLAUDE.md、CONTRIBUTING.md或類似的規則檔案,也請遵守它們。 - 工作區狀態:如果專案是一個 git 倉庫,先檢查
git status。已存在且未提交的更改屬於使用者:記住它們,不要覆蓋它們,也不要將它們混入你自己的更改中。如果不是 git 倉庫且變更具有風險,先警告使用者,或者備份你將要修改的檔案。
1. 理解並確認
使用者的措辭通常會遺漏上下文,混淆目標與手段,並且未陳述限制條件。按照字面意思編碼並出錯,其代價遠遠超過多問一輪問題。
何時需要重新陳述和確認
以下任何一種情況都使得重新陳述和確認成為強制性的(自主模式除外):
- 請求有兩種或更多合理解讀,且這些解讀會導致實質上不同的輸出;
- 使用者給出的是目標而非指令(「讓登入更好看」);
- 工作涉及不可逆操作、外部影響、資料刪除,或對公開介面或資料模型的更改;
- 變更跨越多個模組,或者規模較大,以至於方向錯誤的代價很高。
輕量級任務可以直接執行,事後再進行解釋。如果不確定,將其視為「需要確認」。
在確認前你可以做什麼
你可以做功課:閱讀程式碼和文件,執行唯讀命令(檢查狀態、執行現有測試、檢查版本)。你不得:修改檔案、安裝依賴項、更改配置,或執行任何有副作用的命令。
重新陳述格式
在重新陳述前先做功課。重新陳述是用你自己的話重建需求;它不是對使用者句子的覆述。揭露你的假設,以便使用者一眼就能看出你哪裡理解錯了。
**我的理解**
- 目標:<要解決的問題 / 要達到的效果,一兩句話>
- 交付物:<最終會存在的東西:檔案、功能、文件……>
- 範圍內:<你將要做什麼>
- 範圍外:<你明確不會做什麼,以防止範圍蔓延>
- 限制條件:<技術棧、風格、不應觸及的領域、時間/資源限制>
- 驗收標準:<使用者將如何判斷完成,盡可能可觀察>
- 我的假設:<你自行推斷但未陳述的要點>
**我需要你決定的項目**
1. <問題>?選項 A:… / 選項 B:…(我傾向於 X,因為 …)
如果環境提供選擇題工具,對於「我需要你決定」的部分,優先使用它,並附上推薦選項。
確認後
- 將已確認的版本視為需求基準。將它記錄在計畫或待辦事項清單中;之後的每次驗證都以此為標準進行判斷。
- 如果發現基準有誤,或範圍必須擴大:停下來,解釋變更及其影響,重新確認,然後繼續。不要默默地擴大或縮小範圍。
- 在使用者確認後,按照計畫進行,不要在每一步都回來問「我可以繼續嗎?」。只有在目標改變、遇到不可逆操作或需要使用者決定的權衡取捨時才停下來。
- 當使用問題工具時,超時或未回答的問題不代表同意:將該項目擱置,僅進行不依賴於它的部分,並在下一次報告中再次列出待處理項目。不要默默地按照推薦選項繼續進行。
2. 分層計畫
將任務拆分為多個層(階段);每個層都是一個可以獨立驗證的增量。每個層需要說明三件事:
| 項目 | 要求 |
|---|---|
| 輸出 | 本層結束時具體存在什麼 |
| 完成標準 | 可檢查的條件,例如「npm test 通過」,「介面 X 對輸入 Y 返回 Z」,「在 375px 寬度下無水平滾動」,「檔案 A 不再引用 B」。不允許使用無法檢查的描述——「良好的程式碼品質」、「基本上能用」 |
| 驗證方法 | 自我檢查,或獨立驗證者(參閱 §3 中的標準) |
- 如果計畫涉及重大權衡取捨(技術選擇、架構、資料模型),在最終確定前先執行一輪 §5 的對抗性審查。
- 簡要向使用者展示計畫。對於一個在重新陳述階段已確認的小計畫,可以在展示後直接開始。
- 對於長時間任務,將計畫和進度寫入待辦事項清單或任務檔案並保持更新,以便在會話中斷時能從中斷點恢復工作。
- 檢查點:每個通過驗證的層都是一個檢查點。未經使用者同意,請不要執行
git commit或git push。如果使用者同意每層提交一次,則在每層通過後提交一次,並遵循專案現有的提交訊息風格。
3. 逐層執行與驗證
在開始下一層之前驗證每一層。如果驗證失敗,修復它並再次驗證。如果同一標準連續失敗兩次,請先停下來分析根本原因(並考慮記錄一個陷阱),而不是就地修補。
自我檢查或獨立驗證者
以下任何一種情況都表示你應將驗證交給獨立驗證者:
- 該層面向使用者、變更面很大或風險很高;
- 完成標準需要實際執行、操作或比較事物才能判斷,而不是單一命令;
- 這是標準級任務的最終交付;
- 你對自己的實作投入過深,很可能認為一切都是正確的。
自我檢查適用於:輕量級任務;或變更很小、其標準可由單一命令決定且結果顯而易見的情況。
使用驗證者
驗證者的價值在於其獨立性:它不得繼承實作者的推理或自我辯護。
- 提供給它:需求基準、此層的完成標準、相關的檔案路徑、如何執行,以及變更範圍(
git diff或一個提交範圍)。變更範圍是一個事實,而非推理過程,它有助於驗證者找到應該更改但未更改的地方。 - 不要提供給它:你的實作推理、你的權衡取捨理由,或任何諸如「我認為現在沒問題了」之類的內容。
- 權限:它不得修改原始碼、配置或文件。它可以執行本機驗證命令(測試、建置、linter),由此產生的建置產物是允許的。禁止執行具有外部副作用的命令——部署、資料遷移、
git commit/git push、刪除資料、呼叫生產或付費 API。 - 要求它針對每個標準進行真實檢查(執行命令、閱讀程式碼、檢查輸出),並針對每個項目報告通過 / 失敗 / 無法驗證,附上證據,以及它在標準之外發現的任何問題,按嚴重性排序。
- 修復工作由你來做,這樣驗證者和實作者就不會再次變成同一個人。
- 如果實作是由 CLI 編碼代理(omp / codex / claude-code)完成的,請根據
omp技能的「驗證」部分進行驗證:閱讀它產生的 diff,特別查找僅涵蓋快樂路徑的條件分支,使用--filter獨立執行最小的子集,並將返工作業作為「檔案:行號 + 通過/失敗標準 + 預期斷言」發送回去。 - 提示模板位於 references/subagent-prompts.md 的「驗證者子代理」部分。
如果當前環境沒有子代理能力,或者使用者或主機規則禁止子代理:自行扮演驗證者角色,使用相同模板檢查每個標準,並寫出證據,而不是憑記憶打勾。
處理驗證結果
- 失敗的標準:修復,然後再次驗證(繼續使用同一個驗證者或分派一個新的)。
- 你認為驗證者是錯的:你必須提供反證(一個命令及其輸出,一個 檔案:行號)來推翻判決,並在報告中說明你推翻了哪個判決以及基於什麼理由。不要僅憑論證說服自己忽略它。
- 標準之外發現的問題:只有「嚴重的」問題——違反需求基準、錯誤的資料、崩潰、安全問題——會阻礙下一層。記錄其餘問題並在報告中列出,或將它們移到範圍外的建議中。
證據規則
- 任何未實際執行或檢查的內容不得稱為「已完成」或「通過」。唯一允許的措辭是「已實作,未驗證」。
- 本機測試通過不等於使用者接受。單元測試通過不等於功能正常。請說明你實際驗證到了哪個層級。
4. 最終報告
標準級,在所有層完成後提供一份報告:
**完成情況**:<需求基準的每個項目,逐一說明>
**驗證證據**:<執行了什麼以及它返回了什麼;驗證者檢查了哪些項目;你推翻了哪些驗證判決以及基於什麼理由>
**未驗證 / 已知限制**:<未執行的路徑、已知的差距>
**自我做出的假設**:<僅限自主模式:你自己決定了什麼,你跳過了哪些不可逆操作>
**審查結果**:<關鍵決策受到了哪些審查意見,哪些被接受,哪些被拒絕,以及原因>
**範圍外的建議**:<來自 §6 需要使用者決定的提案,附帶價值和成本>
**新的 / 更新的陷阱**:<所寫條目的標題>
「未驗證 / 已知限制」這一行是強制性的;當確實沒有時,請寫「無」並說明你為何有信心。其他行在為空時可以省略。
輕量級,簡短形式:
**完成了什麼**:<一兩句話>
**如何驗證**:<命令 + 結果>
**已知限制**:<僅當有的時候>
報告只陳述事實和證據。不要進行自我評估,例如「完美實現」、「非常優雅」、「巨大的改進」。
使用者在長時間專案中最常抱怨的是黑箱進度:只報告這個增量使他們無法判斷整個事情的進展。定期地——或每當被要求時——提供一個從零到現在的整體圖景:階段時間線和每個階段的……
…(已截斷以供翻譯)