工作流程
Coograph 初始化過的專案，每筆變動都走同一條五步管線：Plan → Propose → Apply → Review → Archive。例外又窄又字面 — 錯字修正、純註解編輯、使用者明確指示的設定值調整，以及已核可、進行中提案的後續動作。
「微不足道」、「顯而易見」、「很小」、「只調一下」不是例外。有疑問就 propose。
工作流程不是儀式。它存在的理由是 AI 代理特別擅長自信地交付錯的東西，工作流程強制在那之前插入中斷點。
Plan
/coograph-plan（Claude Code）或 @Planner（VS Code Copilot）。
Planner 代理會調查程式碼庫，一次只問一個聚焦的釐清問題。它不寫程式。產出是對這次變動需求的清楚理解 — 檔案、整合點、風險。
下列情況跳過 Plan：
- 對話裡已有 Review 產出。
- 使用者已指定問題、檔案和修正方向。
- 修正屬於上面字面清單裡的單行例外。
Propose
coograph-propose 技能會在 openspec/changes/<YYYY-MM-DD>-<slug>/ 建立 OpenSpec 變更目錄，內含：
.openspec.yaml
proposal.md ← Why, Goals, Non-Goals, Decisions, Impact, Risks
specs/<capability>/spec.md ← Requirements + Scenarios
tasks.md ← 3–8 task groups, last is Verification使用者審閱後，要嘛說「proceed」，要嘛回傳修改。核可前不寫程式碼。
Apply
代理依序處理 tasks.md，做完就標記。
- 編輯前先讀過每個檔案。
- 假設名稱前，先檢查 API spec 或產生的型別。
- 建置錯誤如果不明顯，跑
/coograph-debug。 - 實作途中需求有變，先更新 OpenSpec，再繼續。
所有任務完成後，跑品質關卡：typecheck、lint、format、tests。修到乾淨為止。
Review
/coograph-review 或 @Reviewer。
Reviewer 是唯讀的。每則發現都要引用剛讀過檔案的逐字片段 — diff 和對話記憶不是有效來源。
發現有嚴重度：Critical（合併前必修）、Warning（應該修）、Suggestion（可以修）。實作者修 Critical/Warning，重跑品質關卡，只有修動幅度大才重審。
Archive
把完成的提案搬走：
mv openspec/changes/<slug>/ openspec/changes/archive/<slug>/這讓 openspec/changes/ 只留進行中的工作 — 代理在 session 開始時會讀進行中的提案。
代理
沒有獨立的 @Implementer。負責 plan 的代理也負責實作。
| 代理 | 用途 | 關鍵約束 |
|---|---|---|
| Planner | 面談式規劃 | 一次一個問題。永不實作。 |
| Reviewer | 嚴格唯讀程式碼審查 | 每則發現都要引用逐字片段。 |
| Debugger | 根因分析、最小修正 | Reproduce → Evidence → Fix → Verify。三次嘗試斷路器。 |
| Verifier | 基於證據的完工檢查 | 自己跑指令。PASS/FAIL/INCOMPLETE 結論。 |
| Explore | 快速唯讀程式碼庫問答 | quick / medium / thorough 三種深度。 |
所有代理都必須先呼叫 code-graph。只有在圖 DB 確實不存在時，才允許退到 sqlite3 .code-graph/graph.db，然後才退到 grep。方便不是跳過的理由。
生命週期鉤子
Claude Code 的生命週期鉤子放在 .claude/hooks/：
| 鉤子 | 用途 |
|---|---|
block-generated.py | 擋掉對 generated/、dist/、build/ 等目錄的編輯，以及前 5 行含 @generated / DO NOT EDIT 的任何檔案。 |
log-bash.py | 把每個 bash 指令附加到 .claude/session.log（列入 gitignore）。稽核軌跡。 |
report-graph.py | session 開始時回報 code-graph 狀態。graph.db 不存在就印重建提示。 |
warn-scope.py | 有進行中的 OpenSpec 時，編輯不在 tasks.md 裡的檔案會被警告。讓範圍蔓延浮現，但不阻止工作。 |
這些都會自動跑 — 不用代理決策、不用 prompt 工程。
可靠性特性
- 抗幻覺。 Reviewer 發現必須來自剛讀過檔案的逐字片段。代理用任何名稱前都先 grep。對話 10 輪以上要重讀檔案；代理絕不引用自己之前的輸出當證據。
- 斷路器。 修正三次重試上限、審查三輪循環上限。
- 功能盤點。 編輯任何檔案前，列出它現有的功能並逐一確認都保留。
- 範圍蔓延偵測。 Debugger 每次修完都會審自己的 diff，把無關變動還原。
- 風險分級。 認證、安全、金流、遷移無論檔案數多少，一律當複雜案件處理。