第 30 章：进阶——团队、CI、扩展

学习目标

把这套搬到其他场景：多人、CI、新角色。

多人协作

flowchart TB
    Repo["Git 仓库"] --> Shared["团队共享 (入 git)"]
    Repo --> Personal["个人 (gitignore)"]

    Shared --> Sh1["CLAUDE.md"]
    Shared --> Sh2[".claude/agents/"]
    Shared --> Sh3[".claude/commands/"]
    Shared --> Sh4[".claude/hooks/"]
    Shared --> Sh5[".claude/settings.json"]
    Shared --> Sh6["openspec/"]

    Personal --> P1[".claude/settings.local.json"]
    Personal --> P2[".claude/telegram-notify.json"]
    Personal --> P3[".claude/.notify-sent"]

    style Shared fill:#c8e6c9
    style Personal fill:#fff9c4

→ 共享的进 git，个人的 gitignore。每个新人 clone 后立刻有同样的角色 + 规则。

多人协作的状态文件

review/N.md         入 git（评审痕迹有审计价值）
test-reports/N.md   入 git
STUCK.md            入 git
e2e-report.md       入 git
.notify-sent        gitignore（个人状态）
dist/               gitignore（运行产物）

→ A 跑一半下班，B 第二天 git pull 看到 review/N.md 就能接着跑。

CI 集成

GitHub Actions 例子：

# .github/workflows/test.yml
name: tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "3.11" }
      - run: pip install -e ".[dev]"
      - run: pytest tests/ -v -m "unit or functional"
        # 不跑 e2e（需要 macOS GUI）

→ CI 跑单元 + 功能测试，不跑 E2E。

CI 跑什么、不跑什么

测试类型	CI 跑	本地跑
单元测试	✅	✅
功能测试（real subprocess）	✅ Linux runner	✅
E2E（macOS GUI）	❌	✅
Spec 一致性检查	✅（openspec validate）	✅

CI 完整流程：

flowchart TB
    Push["开发者 git push"] --> Trigger["GitHub Actions 触发"]
    Trigger --> Setup["Linux runner
setup Python 3.11"]
    Setup --> Install["pip install -e .[dev]"]
    Install --> Spec["openspec validate
(规约一致性)"]
    Install --> Unit["pytest -m unit"]
    Install --> Func["pytest -m functional"]
    Spec --> Pass{全部通过?}
    Unit --> Pass
    Func --> Pass
    Pass -->|是| Green["✓ PR 状态绿"]
    Pass -->|否| Red["✗ 阻断合并"]

    Green --> Local["本地补跑 E2E"]
    Local --> Approve["人 review + 合并"]

    Note["⚠️ E2E 在 CI 跑不动
(macOS avfoundation)"] -.-> Trigger

    style Green fill:#c8e6c9
    style Red fill:#ffcdd2
    style Approve fill:#bbdefb

扩展角色

按你的项目需求加 agent：

.claude/agents/
├── developer.md           核心
├── tester.md              核心
├── reviewer.md            核心
├── e2e-tester.md          核心
├── architect.md           核心
├── doc-writer.md          可选：同步更新 README/CHANGELOG
├── security-reviewer.md   可选：扫漏洞
├── refactor-agent.md      可选：长期重构
├── migration-agent.md     可选：数据库 schema
└── perf-tester.md         可选：性能回归

每个新角色都遵循"权限矩阵 + 4 段式 system prompt"。

不适合用这套的场景

✗ 1 小时一次性脚本
   → 开销远大于收益

✗ 已陷入遗留系统的大重构
   → 先小步重构出可写 spec 的接口

✗ 与 Jira/Notion 强耦合的团队
   → 双系统冲突，先选一个

✗ 探索性原型（Jupyter notebook 玩玩）
   → 规约会拖慢实验

✗ 纯 UI / 设计驱动项目
   → spec 难以写出可测的 Scenario

这套的真实价值场景

✅ 中型工具/库（doc2video 这种）
✅ SaaS 业务逻辑（合规、可审计）
✅ 长期维护项目（>6 个月）
✅ 多人协作
✅ 接手他人项目
✅ AI 协同密集的开发（>50% 代码 AI 写）

未来兼容性

Claude Code 在向"原生多 agent"演进（看 changelog 2.1.x 系列）。但：

✅ Spec-driven 是产品中性的——OpenSpec 可与任何 agent 系统配合
✅ 角色分工原则是产品中性的——任何编排器都能复用
✅ 状态机基于文件——不依赖具体 agent runtime
⚠️ 具体 agent 文件格式可能改——但迁移成本低（重写 system prompt）
⚠️ slash command 格式可能变——但伪代码逻辑可移植

→ 核心方法论可以传承。具体语法跟着 Claude Code 升级。

你现在能做什么

把这套搬到团队（gitignore + 共享）
配 CI 跑测试（不跑 E2E）
按需加新角色 agent
判断什么项目不适合用这套

flowchart TB
    Start["你"] --> S1["✓ 用 OpenSpec 把需求结构化"]
    Start --> S2["✓ 设计多角色 agent 系统"]
    Start --> S3["✓ 写 CLAUDE.md 让 main Claude 按规则办事"]
    Start --> S4["✓ 用 /dev 自动化整个开发流水线"]
    Start --> S5["✓ 用 hook 防危险操作 + 主动通知"]
    Start --> S6["✓ 跑出从想法到 ship 的完整 cycle"]
    Start --> S7["✓ 卡住能独立诊断"]

    S1 & S2 & S3 & S4 & S5 & S6 & S7 --> End["从 0 到自治化开发流水线"]

    style End fill:#c8e6c9

完整能力清单

知识层（Part III）:
  ✓ 写 proposal / design / spec / tasks 4 件套
  ✓ Requirement + Scenario 的可测格式
  ✓ delta 操作（ADDED/MODIFIED/REMOVED/RENAMED）

治理层（Part IV~VI）:
  ✓ 4+ 角色 agent 设计
  ✓ Escalation 升级链 + architect 兜底
  ✓ CLAUDE.md 项目宪法
  ✓ 基于文件的状态机
  ✓ /dev 编排命令
  ✓ permission + hook 安全护栏
  ✓ Stop hook 通知集成

实战（Part VII）:
  ✓ 起跑 checklist
  ✓ 三大调试工具
  ✓ 沙盒选择
  ✓ 团队 / CI / 扩展

接下来

马上做：在自己的项目跑一次完整 cycle，把每个章节学的应用上
一周后：写一份你自己的 CLAUDE.md，加上你项目独有的规则
一个月后：扩展角色 agent，让流水线适配你的领域
三个月后：教别人这套（教是最好的学）

📎 附录 A：20 个 Q&A

下面 20 个问题来自真实初学者的高频疑惑。每个回答 100~200 字，直接给结论 + 简短理由。

关于哲学（Q1~Q5）

Q1. 为什么不让一个 Claude 写完所有代码？

简单：制衡。 一个 agent 既写代码、又写测试、又审自己的代码——它会写"刚好让自己代码通过的测试"，给自己写"看着顺眼的 review"。三个月后你查不出问题在哪。多角色 = 自然的代码审核 + 测试驱动 + 黑盒验证。每个角色有独立视角和职责边界，互相检查。这跟人类组织一样：开发不审自己的 code，QA 不写产品代码，tech lead 看全局——分工不是低效，是质量基础设施。

Q2. OpenSpec 跟 Notion / Confluence 的本质区别？

OpenSpec 是"编译型"——specs 是系统当下承诺的契约，change 是 migration（每次变更带提案+设计+任务+delta）。Notion 是"快照型"——只是文字记录，没有版本对齐。具体差异：(1) OpenSpec 有 delta 机制，Notion 写整版；(2) OpenSpec 跟代码同 git 仓库，commit 关联可追溯，Notion 是另一个系统会漂移；(3) OpenSpec spec 有可机读 schema（Requirement/Scenario），可被 AI 理解，Notion 是自由文本。一句话：OpenSpec 像数据库 schema migration，Notion 像 Word 文档。

Q3. 我已经用 Cursor / Copilot，还需要这套吗？

不冲突，解决的层不同。Cursor / Copilot 是"实时辅助"——你写代码时它补全、解释、改 bug，是 IDE 内的 pair programming。这套是"批量自治"——你定义 spec 和角色后，多 agent 自己跑完整 cycle，是 PM + 团队级的抽象。两者可叠加：你用 Cursor 处理细节，让 /dev 跑大块工作。如果你只用 Cursor，遇到"想花一周做个完整功能且需求要长期演进"时会缺一层——那一层就是 OpenSpec + 多 agent。

Q4. 这套适合什么规模？

下限:  1 人 MVP，但项目得有"长期演进可能"
       一次性 1 小时脚本不值得
上限:  10 人产品规模都试过
       再大需要切多个 OpenSpec 仓库
最佳:  1~3 人、3 周~6 个月的中型项目（比如 doc2video）

手工管 50+ task 的细节会崩溃，工具搭好后边际成本极低。不适合：纯 1 小时探索 / 已陷遗留系统的大重构 / 与 Jira/Notion 强耦合的团队（双系统冲突）。

Q5. 多 agent 是不是很费 token？账单会爆吗？

会比单 Claude 贵但有控制。我们 doc2video 13 组、61 task 估算 $15~$30 跑完——手工同样规模 1~2 周工时 = 几千美元，所以 ROI 极高。控制方法：(1) 默认 sonnet，卡住才升 opus（escalation tier，省 5x）；(2) 阈值断保险防死循环；(3) prompt caching 自动起效（重复读的 spec 会被缓存）；(4) 单组完成立即归档 raw/，不让上下文越积越大。月初先跑一组观察实际花费，校准预期再放手跑。

关于实操（Q6~Q12）

Q6. agent 之间会不会"打架"？

会，但有内置防御。最常见冲突：reviewer 拒、developer 改、reviewer 又拒新地方——拉锯战。两个机制防：(1) F2 累积 review 规则——reviewer 第 2 轮起只复审上次的 Required Changes，不能新挑刺（除非上次修复引入新问题）；(2) 死循环阈值——拒 3 次自动升 developer-deep 重新质疑前提，再卡升 architect 诊断。最终人介入的频率约每 5~10 组一次，远低于全手工。

Q7. 我已有代码怎么把这套加上去？

不要回头补 spec。具体步骤：(1) openspec init + commit；(2) 写一份反向描述当前能力的 specs/——只覆盖你 confident 的部分，不全；(3) 之后所有新功能/重构走 change 流程（propose → apply → archive）；(4) spec 通过 archive 自然累积，不主动补。对老代码"硬补 spec"是无底洞——它们写时没考虑可测性，逆向工程出 Scenario 极痛苦。让 spec 跟着新工作演进就好。

Q8. 一个 change 多久跑完？

按 task 数粗算：

规模	task 数	时间
小	5~10	30 分钟~1 小时
中	20~30	2~4 小时
大	50+	半天~一天

doc2video 是 61 task，预计半天跑完 MVP。变量：网络好坏、escalation 次数、人介入频次。第一组通常慢一倍（环境磨合）；后面进入节奏会快很多。如果一个 change 估算超 2 天，先拆——OpenSpec 一个 change 控制在 1 天内体验最好。

Q9. agent 写的代码能直接 ship 吗？

技术上能，实践上最后一道闸是你。reviewer + tester + e2e-tester 已经挡住 90% 问题，但生产 ship 前你应该做：(1) 跑一遍 git diff 自己看；(2) 在 staging 实际跑一次；(3) 检查 review/N.md 有没有 reviewer 标"我不太确定"的地方。多 agent 把"显然错"和"明显违规"都拦了，剩下 10% 是"风格、品味、业务直觉"——这是人的领域。把它当一个可信的 junior 团队——能干活，但 ship 前 lead 看一眼。

Q10. 跑到一半停下来会丢上下文吗？

不会。状态全在文件（CLAUDE.md 的核心设计——见 Ch 20）。具体可恢复的状态：(1) tasks.md 的 checkbox 进度；(2) review/N.md 的 round 数与 Required Changes；(3) test-reports/N.md 的 PASS/FAIL；(4) STUCK.md 的诊断。重启 Claude Code 后跑 /dev status 立刻看到上次到哪。即使 /clear 主对话或换设备，全部信息从文件恢复。这是为什么我们坚决"基于文件的状态机"——内存状态会丢，文件不会。

Q11. CLAUDE.md 改了要不要重启？

新会话才生效。当前会话已加载的 CLAUDE.md 不会自动重读——除非你 /clear 或重启 claude。最佳实践：改完 CLAUDE.md 立刻起新会话验证。改大规则（角色调度、状态机）一定要重启，改小规则（命令速查表）当前会话也能勉强用。判断方法：跑一次 /dev status，看 main Claude 是否按新规则解释状态——按了就是真的读到了。

Q12. 不同项目能共用 agent 吗？

可以，分两层：

用户级（~/.claude/agents/<name>.md）：跟你账号走，所有项目可用——适合通用 agent 如 doc-writer、refactor-agent、security-reviewer
项目级（<project>/.claude/agents/）：跟项目走，团队共享——适合项目专属 agent

反模式：把项目专属规则放用户级——结果其他项目莫名报错。建议：通用骨架放用户级，项目专属约束放项目级 + 在项目 agent 里覆盖（手动复制必要内容）。

关于设计（Q13~Q17）

Q13. agent 文件越写越长是不是错了？

是。超 200 行通常意味着两个问题之一：

agent 职责太宽——拆成多个 agent。例：developer 同时管"写代码 + 配置 CI"，拆出 ci-agent
写了 main Claude 该写的事——比如把整个状态机塞进 developer.md，应该搬到 CLAUDE.md

判断标准：能去掉这一句而不影响 agent 行为吗？能 → 删。agent 文件理想长度 60~150 行，超出就该 review 是不是哪里冗余。

Q14. 为什么 reviewer 用 opus，sonnet 不行吗？

可以但效果差。Opus 强项是"找出别人没看到的不一致"——code review 的核心能力。Sonnet 评审常变 LGTM——表面看着对就过，找不出微妙问题（D5 决策被实现违反但代码看着像对、Scenario 被静默削弱、依赖偷偷加了）。我们实测：sonnet reviewer 漏过的问题，换 opus 一审就指出来。Reviewer 调用频率不高（每组 1~2 次），用 opus 的成本占比不大但回报巨大。这是 Ch 17 "升级而非顶配"的反例——reviewer 是默认就上 opus 的角色。

Q15. 能让 agent 直接 commit + push to main 吗？

技术上能（permission allow）但坚决反对。git push 是"对外副作用"——一推就影响线上、CI、其他人。push 应该是人类拍板的最后一步。具体做法：让 developer 只到 commit 为止（本地 commit 留痕但没出去），人类做 PR review + push。/dev 跑完一组在你 Telegram 上弹通知"组 N 已通过，可推"——你看一眼，确认没问题，手动推。这一秒人类介入挡掉 99% 的事故。给 agent push 权限 = 把方向盘交给副驾驶。

Q16. permission deny 太多 agent 会卡住吗？

不会卡死，会报错并请求修正。命中 deny 时 Claude Code 显示拒绝原因，main Claude 收到错误信息会说"我尝试 X 但被拦了，建议改用 Y"。坏处：你被打断节奏。最佳策略：(1) 起步保守 deny + 跑一段时间观察被拦记录；(2) 真实合法但被误伤的加例外；(3) deny 太严 = 自治化体验差。我们 doc2video 的 deny 列表是迭代调出来的——刚开始误伤过几次，加例外后顺畅。反模式：被拦了就 disable 整条规则——这是关安全网。

Q17. Stop hook 失败会影响 Claude Code 吗？

不影响主流程。hook 退出码非 0 时 Claude Code 显示警告但继续工作——你的 turn 该完成的还是完成了，只是没收到通知。最坏情况是错过 Telegram 推送，可以补查 transcript。原因：Anthropic 把 hook 设计成"增强而非阻塞"——hook 崩溃不能让用户丢工作。反模式：hook 里写主流程逻辑（"必须 hook 成功才进下一步"）——一旦网络抖动就卡 deploy。Hook 只该做"额外动作"（通知、日志、监控），永不该是关键路径。

关于扩展（Q18~Q20）

Q18. 能跨 git 仓库共享 settings.json 吗？

项目级不能（在 .claude/ 内随项目走）。共享方法：

用户级——~/.claude/settings.json 写通用部分（默认 model、theme），所有项目继承
配置模板——团队维护一个 claude-template/ 仓库，新项目 cp -r template/.claude/ ./.claude/
Skill / Plugin 化——把通用 agent / hook 打包成 plugin 发布
dotfile 同步——chezmoi/yadm 等工具同步 ~/.claude/

关键原则：共享通用、项目化差异。完全跨仓库的 settings.json 不存在——这是 Claude Code 的设计选择（避免一处坏全部坏）。

Q19. 多个 agent 同时改同一文件会冲突吗？

我们的设计不允许并发 dispatch 同一组——每组串行。CLAUDE.md 明确：dispatch 以组为单位、组内串行。跨组并行理论可以，但需要：

两组改的文件完全不重叠（看 tasks.md 推断）
编排器（dev.md）显式启用并行模式
失败回滚机制完备

MVP 阶段不开并行——多 agent 已经够复杂，再加并发是 debug 噩梦。等真实需要再加（比如 30+ 组项目要赶时间）。doc2video 13 组全串行，实测半天跑完 MVP，没必要并行。

Q20. 这套以后会被 Claude Code 内建吗？我现在投入会白费吗？

部分会被内建，但核心方法论不会过时：

Claude Code 在向"原生多 agent"演进（看 changelog 2.1.x 加了 EnterWorktree、subagent 等基础设施），所以编排层可能被简化，自定义 /dev 命令以后会变标准命令
但 spec-driven 是产品中性的——OpenSpec 跟任何 agent 系统都能配合，方法论可移植
角色分工原则、escalation tier、状态机基于文件——这些是软件工程模式，跨工具通用

结论：今天的工具配置可能 1 年后要重写，但你脑子里的方法论 5 年后依然适用。投入不亏。

📎 附录 B：术语表

按类别组织，每条 1~2 句定义 + 在哪一章详讲。

OpenSpec 术语

术语	定义	详见
Capability	一个能力域，对应 `specs/<name>/spec.md` 一份文件	Ch 7, 12
Spec	系统当前承诺的契约文档（`specs/`），由所有归档 change 累积合并而来	Ch 7
Change	一次正在进行的变更，含 proposal/design/specs/tasks 4 件套	Ch 7, 10
Archive	已完成 change 的存档，保留完整历史	Ch 7
Proposal	一个 change 的 "why + what"，1~2 页	Ch 10
Design	一个 change 的 "how"，记录技术决策与取舍	Ch 11
Requirement	一条系统承诺，用 SHALL/MUST 句式	Ch 12
Scenario	一个 Requirement 的具体行为，WHEN/THEN 格式，4 个 # 标记	Ch 12
Delta	change 中的 spec 变更（ADDED/MODIFIED/REMOVED/RENAMED）	Ch 12
Task	tasks.md 中一个 `- [ ]` 项，可被开发者勾选	Ch 13
Group	tasks.md 中 `## N. 名` 划分的任务组，是 dispatch 的最小单位	Ch 13
Active change	当前正在实施的 change（archive 标记为 false 的那个）	Ch 6, 21

Claude Code 术语

术语	定义	详见
main Claude	你直接对话的 Claude Code 主进程，承担 dispatcher 角色	Ch 3, 14
subagent	通过 `.claude/agents/<name>.md` 定义的可被 dispatch 的 agent	Ch 14
Skill	一段可被 main Claude 调用的标准化流程（如 `/opsx:propose`）	Ch 6, 14
Slash command	用户输入 `/xxx` 触发的提示模板	Ch 21
CLAUDE.md	项目根目录的"项目宪法"，main Claude 启动时自动读	Ch 19
Hook	工具调用前/后由 Claude Code 触发的外部脚本	Ch 25, 26
PreToolUse hook	工具调用前的 hook，可拦截	Ch 25
Stop hook	main Claude 完成一段输出后触发，常用于通知	Ch 26
Permission mode	`default` / `acceptEdits` / `bypassPermissions`	Ch 24
`$CLAUDE_PROJECT_DIR`	项目根的环境变量，hook 里常用	Ch 25
MCP	Model Context Protocol，连接外部服务（如 Telegram、Gmail）的协议	Ch 26
Frontmatter	agent / command 文件顶部的 YAML 元数据	Ch 16, 21

多角色与编排术语

术语	定义	详见
Dispatcher	调度者角色，main Claude 在多 agent 系统中的身份	Ch 19
Doer	执行者，与 dispatcher 相对——main Claude 必须不当 doer	Ch 19
Briefing	dispatch 时附给 subagent 的提示，必须自包含	Ch 14, 21
Round	同一组 / 同一 agent 的迭代次数（`reviewerRound`、`testFailRound`）	Ch 18
Threshold	死循环阈值（拒 3 次升级、失 5 次升 architect 等）	Ch 18
Escalation	卡住时自动升级到更强 agent（sonnet → opus）	Ch 18
Tier	升级层级——developer / developer-deep / architect 三层	Ch 18
Marker	输出中的固定前缀（⚠️ / ✓ / ✗），供 hook 识别重要事件	Ch 21, 26
Path A	deep agent 标记 spec 缺陷的路径（不写代码）	Ch 18
Path B	deep agent 差异化重做的路径（用结构性不同方案）	Ch 18
STUCK.md	architect 写的诊断报告，含根因 + 3 个 option	Ch 18
State machine	基于文件的状态机（PENDING/DEVELOPING/TESTING/REVIEWING/...）	Ch 20
Crash-safe	状态在文件，进程崩溃后可重读恢复	Ch 20

4 个角色

角色	职责	模型	详见
developer	实现 tasks.md 的某一组	sonnet	Ch 15, 16
developer-deep	developer 的升级版（卡住时用）	opus	Ch 18
tester	写单元 + 功能测试	sonnet	Ch 15
tester-deep	tester 的升级版	opus	Ch 18
e2e-tester	黑盒端到端测试（不读 src/）	sonnet	Ch 15
reviewer	对照 spec/design 评审	opus	Ch 15
architect	兜底诊断（不写代码）	opus	Ch 18

安全与权限术语

术语	定义	详见
Allow rule	允许规则，命中即通过	Ch 24
Deny rule	拒绝规则，命中即拒（优先于 allow）	Ch 24
Bypass mode	`bypassPermissions`——绕过弹问，仅靠 deny + hook 兜底	Ch 24
Path-aware check	路径感知校验，如"项目内 rm 放行 / 项目外 rm 拦"——必须靠 hook	Ch 25
Bind mount	Docker 把宿主目录挂进容器——文件共享、进程隔离	Ch 29
Sandbox tier	L1 (worktree+venv) / L2 (Docker) / L3 (VM) 三档	Ch 29

项目特定（doc2video）术语

术语	定义
doc2video	案例项目——把 markdown 教学文档编译为视频
edge-tts	微软 Edge 浏览器的 TTS 服务（免费），生成 mp3 配音
avfoundation	macOS 内建的音视频框架，ffmpeg 用它录屏
tmux	终端复用器，可被脚本控制，用于真实执行命令
`:::manual`	doc2video 的 markdown 扩展，标记纯讲解步骤（无终端命令）
TTS	Text-to-Speech，文本转语音
Headless browser	无 GUI 的浏览器，用于自动化测试
Marker（命令完成检测）	tmux send-keys 后用唯一字符串包裹，用以可靠检测命令结束

📎 附录 C：与其他工具对比

工具全景

flowchart LR
    subgraph IDE["IDE 内实时辅助"]
        Cursor["Cursor"]
        Copilot["GitHub Copilot"]
        Continue["Continue"]
    end

    subgraph CLI["CLI 编辑式"]
        Aider["Aider"]
        Cline["Cline"]
    end

    subgraph Agent["自治 agent"]
        Devin["Devin"]
        Sweep["Sweep AI"]
        ThisStack["这套
(Claude Code+OpenSpec+多agent)"]
    end

    subgraph Chat["纯对话"]
        ClaudeWeb["Claude.ai"]
        ChatGPT["ChatGPT"]
    end

    style ThisStack fill:#c8e6c9

对比矩阵

维度	纯 Claude.ai	Cursor	Copilot	Aider	Devin	Cline	本套
介入方式	对话	IDE 实时	IDE 补全	CLI 编辑	全自治	CLI 自治	CLI 编排 + 多 agent
上下文管理	手工	文件感知	当前文件	git 感知	任务管理	项目级	OpenSpec spec
多 agent	❌	❌	❌	❌	部分（内部）	单 agent	✅ 4~7 角色
规约支持	❌	❌	❌	❌	❌	❌	✅ OpenSpec
自治程度	低	中	低	中	极高	高	高（可调）
权限/沙盒	n/a	IDE 限制	IDE 限制	git 操作	内部 sandbox	配置	可配 hook
状态可恢复	❌	有限	❌	git	内部	有限	✅ 文件状态机
成本	月费	月费	月费	按 token	$$$/任务	按 token	按 token
学习曲线	极低	低	极低	中	低（黑盒）	中	高
最适合	快速咨询	日常编码	补全	已有 git 项目	完整任务委托	CLI 党	中长期项目

详细对比

vs Cursor

Cursor:    IDE 内"伴侣"——你写代码它实时建议
本套:      "团队"——你设计目标，它自己干完

不冲突，叠加用。Cursor 处理"现在这一行该怎么写"，本套处理"这一周要做的功能"。

vs GitHub Copilot

Copilot:   补全级别（光标处下一句）
本套:      项目级别（spec → 实现 → 测试 → 评审）

Copilot 看不到项目意图，只看局部上下文。本套整个 OpenSpec 给 agent 做"全图"。

vs Aider

Aider:    单 agent，CLI 操作 git，每次一个任务
本套:     多 agent，编排器，长跑流水线

Aider 适合"我要修这个 bug 这个 PR"。本套适合"我要做一个新功能 + 长期演进"。

vs Cline / Roo（VS Code 内的 Claude 客户端）

Cline:    Claude Code 的 IDE 化，单 agent + permission
本套:     在 Claude Code 之上加 OpenSpec + 多 agent + escalation

如果你用 Cline，可以把本套思想 70% 搬过去——Cline 也支持 hook + 自定义 prompt。差异是 OpenSpec 工具链需要 Claude Code 的 skill 系统才完整。

vs Devin（autonomous agent）

Devin:    黑盒——你给任务，它自己拆解、执行、报告
本套:     白盒——每个步骤、决策、状态都在文件可见可改

Devin 像外包给 sealed engineer。本套像自己组建可控团队。Devin 失控时你只能看 log 干瞪眼；本套失控时你能改 spec、改 agent、改 hook。

vs Sweep AI（GitHub 自动 PR）

Sweep:    issue → PR 黑盒生成
本套:     需求 → spec → 多 agent 实现 → review → PR

Sweep 适合"这个 issue 帮我搞定"，单次。本套适合"这个项目长期我都想这么干"。

vs 纯 Claude Code（不加 OpenSpec、不加多 agent）

纯 Claude Code:   你和单个 Claude 对话，它干所有事
本套:             加 OpenSpec（规约层）+ 多 agent（治理层）

这是教程的核心对比。纯 Claude Code 在中型项目会撞 Ch 1 的三个痛点——需求漂移、自证陷阱、权限放任。本套是给纯 Claude Code 加 3 层基础设施。

选择指南

flowchart TD
    Q1{项目持续多久?}
    Q1 -->|1 小时| Chat["Claude.ai 对话"]
    Q1 -->|1 天到 1 周| IDE["Cursor / Copilot"]
    Q1 -->|1 月以上| Q2{长期演进?}
    Q2 -->|否| Aider["Aider"]
    Q2 -->|是| Q3{需要团队协作?}
    Q3 -->|否| Cline["Cline / Claude Code 单 agent"]
    Q3 -->|是| ThisStack["✓ 本套"]

    style ThisStack fill:#c8e6c9

工具叠加而非二选一

实际工作流里大概率是这样：

日常开发（光标处）       → Cursor
日常 commit / 小改        → Aider 偶尔用
功能级（一个新 feature）  → 本套（OpenSpec + 多 agent）
快速咨询 / 学习           → Claude.ai 对话

不冲突——它们解决不同抽象层。

📎 附录 D：doc2video 完整代码索引

本附录列出我们一路构建的所有文件，便于读者按图索骥。每个文件标注：路径 + 行数 + 角色 + 详见章节。

项目目录树

~/work/openspec/
├── CLAUDE.md                           266 行   项目宪法（Ch 19）
├── docs/
│   └── tutorial.md                     4500+ 行 本教程
├── openspec/
│   ├── specs/                          (空，待累积)
│   └── changes/
│       ├── archive/                    (空)
│       └── add-doc2video/              当前 active change
│           ├── proposal.md             (~30 行)  Why + What  (Ch 10)
│           ├── design.md               (~120 行) 9 决策 + Risks (Ch 11)
│           ├── specs/
│           │   └── doc2video/spec.md   (~150 行) 11 Requirement (Ch 12)
│           └── tasks.md                (~80 行)  13 组 / 61 task (Ch 13)
└── .claude/
    ├── .gitignore                      gitignore 个人化文件
    ├── settings.json                   57 行    permission + hook (Ch 23, 24)
    ├── agents/
    │   ├── developer.md                84 行    sonnet 实现 (Ch 16)
    │   ├── developer-deep.md           112 行   opus 升级 (Ch 18)
    │   ├── tester.md                   110 行   sonnet 测试 (Ch 15, 16)
    │   ├── tester-deep.md              82 行    opus 升级 (Ch 18)
    │   ├── e2e-tester.md               106 行   sonnet 黑盒 (Ch 15)
    │   ├── reviewer.md                 124 行   opus 评审 (Ch 15, 17)
    │   └── architect.md                142 行   opus 兜底诊断 (Ch 18)
    ├── commands/
    │   └── dev.md                      276 行   /dev 编排命令 (Ch 21)
    └── hooks/
        ├── guard-bash.py               106 行   PreToolUse 路径校验 (Ch 25)
        └── notify-escalation.py        159 行   Stop hook 通知 (Ch 26)

总计：12 个核心文件（不含 OpenSpec 工件）+ 4 个 OpenSpec 工件 ≈ 1700 行配置。

文件分类索引

规约层（OpenSpec 工件）

文件	内容	谁读谁写
`proposal.md`	Why + What Changes + Capabilities + Impact	propose 时生成；reviewer 读
`design.md`	Goals/Non-Goals + 9 Decisions + Risks	propose 时生成；developer & reviewer 读
`specs/doc2video/spec.md`	11 Requirement + 30+ Scenario	propose 时生成；tester 翻译为测试
`tasks.md`	13 组 / 61 个 task checkbox	developer 勾选；其他角色按组识别工作范围

治理层（CLAUDE.md + agents + commands）

文件	角色	关键内容
`CLAUDE.md`	项目宪法	角色调度、状态机、dispatch 协议、escalation 规则
`agents/developer.md`	实现工程师	4 段式 prompt + 严格约束（不写测试 / 不改 spec）
`agents/developer-deep.md`	升级版	Path A（标记缺陷）/ Path B（差异化重做）
`agents/tester.md`	测试工程师	Scenario → pytest 翻译规则
`agents/tester-deep.md`	升级版	判断 Scenario 是否可测
`agents/e2e-tester.md`	黑盒测试	禁读 src/，仅看输出
`agents/reviewer.md`	评审者	F2 累积 review，只读+写 review/N.md
`agents/architect.md`	兜底诊断	写 STUCK.md，6 类根因分类
`commands/dev.md`	编排命令	4 模式（status/N/e2e/auto）+ 升级路由

安全层（settings + hooks）

文件	作用
`settings.json`	bypassPermissions + 大量 deny + hook 注册
`hooks/guard-bash.py`	rm/mv/cp 路径校验，处理 bash -c 嵌套
`hooks/notify-escalation.py`	抓 ⚠️ / ✓ / ✗ marker → Telegram
`.gitignore`	排除 .notify-sent / telegram-notify.json / settings.local.json

状态层（运行时产生）

路径	何时产生	含义
`tasks.md` checkbox 状态	developer 勾选	DEV 进度
`review/N.md`	reviewer 写	REVIEW 状态
`test-reports/N.md`	tester 写	TEST 状态
`e2e-report.md`	e2e-tester 写	E2E 状态
`STUCK.md`	architect 写	卡住诊断

入门"按图索骥"路径

如果你想从零搭一遍同样的项目结构，按这个顺序看文件：

1. 先看 CLAUDE.md                       理解整体协议
2. 再看 settings.json + hooks/          理解安全层
3. 然后看 agents/developer.md           最核心的 agent
4. 看 commands/dev.md                   理解编排
5. 最后看 reviewer.md + architect.md    高阶角色

每份文件本教程都有专门章节解读——附录 B 的"详见 Ch X"会指引。

复用建议

把这套搬到新项目，通用部分直接复制：

✅ CLAUDE.md            改项目名 + 关键路径即可复用
✅ agents/*.md          改"项目特定约束"段，骨架不变
✅ commands/dev.md      99% 通用
✅ settings.json        deny 列表通用，paths 改一下
✅ hooks/*.py           完全通用（用 $CLAUDE_PROJECT_DIR）
❌ openspec/            必然项目专属

→ 15 分钟搭好骨架，然后专注写你项目的 OpenSpec 工件。

🎯 教程完结

如果你跑通了 doc2video，恭喜——你已经掌握了 2026 年最先进的 AI 协同开发方法。

flowchart LR
    Read["读完 30 章"] --> Try["跑通 doc2video"]
    Try --> Adapt["搬到自己项目"]
    Adapt --> Teach["教给同事"]
    Teach --> Master["真正掌握"]

    style Master fill:#c8e6c9

反馈与贡献

发现错误 / 建议改进：在 OpenSpec 项目仓库提 issue
想法 / 实践分享：欢迎 PR 加入"实战案例"附录

致谢

本教程基于一次真实从 0 到 1 构建 doc2video 项目的经验提炼。所有 mermaid 图表、代码片段、决策矩阵都来自实际开发过程——不是教科书的虚构案例。

把这份文档分享给同事吧。

第 30 章 | 进阶——团队、CI、扩展