工作流
Coograph 初始化过的项目里，每个变更都走同一条五步流水线：Plan → Propose → Apply → Review → Archive。例外仅限狭义且字面的情形——拼写订正、仅改注释、用户口述的配置值调整，以及在已批准的进行中提案上的跟进。
“琐碎”、“显而易见”、“小”、“就一处调整”不是例外。拿不准就走 Propose。
工作流的意义不是仪式感。是 AI 代理特别擅长自信地交付错误的东西，而工作流强制在那之前打断一次。
Plan
/coograph-plan（Claude Code）或 @Planner（VS Code Copilot）。
Planner 代理调查代码库，一次只问一个聚焦的澄清问题。它从不写代码。输出是对变更需要什么的清晰理解——文件、集成点、风险。
跳过 Plan 的情形：
- 评审输出已在对话里。
- 用户已指定问题、文件和修复方向。
- 修复是字面例外清单里的单行变更。
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 规范 / 生成的类型。
- 构建报错不直观时，跑
/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/ 里只剩进行中的工作——代理在会话启动时会读进行中的提案。
代理
没有单独的 @Implementer。做 Plan 的代理也负责实施。
| 代理 | 用途 | 关键约束 |
|---|---|---|
| Planner | 访谈式规划 | 一次一问。从不实施。 |
| Reviewer | 严格只读的代码评审 | 每条结论都引用逐字原文。 |
| Debugger | 根因分析，最小修复 | Reproduce → Evidence → Fix → Verify。3 次尝试熔断。 |
| Verifier | 基于证据的完成检查 | 自己跑命令。PASS/FAIL/INCOMPLETE 三档结论。 |
| Explore | 快速只读的代码库问答 | 快 / 中 / 深三档深度。 |
所有代理都必须先调用 code-graph。回退到 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 | 会话启动时报告代码图状态。graph.db 缺失时打印重建提示。 |
warn-scope.py | 存在进行中的 OpenSpec 时，编辑 tasks.md 未引用的文件会发出警告。暴露范围蔓延，但不阻断工作。 |
这些自动运行——不需要代理决策，也不需要 prompt 工程。
可靠性属性
- 抗幻觉。 Reviewer 的结论要求来自新读取的逐字原文。代理在使用任何名称前先 grep。对话超过 10 轮后重新读文件；代理永远不把自己之前的输出当作证据。
- 熔断机制。 修复 3 次重试上限，评审循环 3 次上限。
- 功能清单。 编辑任何文件前，先列出它现有的功能并逐项确认保留。
- 范围蔓延检测。 Debugger 每次修复后审查自己的 diff，撤回无关变更。
- 基于风险的分级。 鉴权、安全、支付、迁移无论文件数多少，一律按 Complex 处理。
这些不是对正确性的承诺。它们是设计上让代理出错时大声失败的约束。