夜雨聆风团队用 AI 写代码，最怕的不是慢，而是没人接得住
OpenSpec 工程化实践 03/03。 前两篇分别讲了“为什么要踩刹车”和“如何给 AI 一张施工单”。这一篇把视角放到团队：多人、多需求、多 AI 工具一起进入研发流程时，OpenSpec 怎么落地，才不会变成新的流程负担。
个人用 AI，问题通常还比较好收拾
一个人用 AI 写代码，即使走偏了，问题通常还在自己手里。
上下文是你给的。 代码是你让它改的。 出问题了，也大概率是你自己回头修。
团队里不一样。
一个需求可能来自产品，一个开发负责后端，一个开发负责前端，另一个人负责 Review，还有测试同学要验收。现在再加上 AI，事情会变得更快，也更容易散。
产品说的是 A。 开发理解成 B。 AI 实现成 C。 测试按 D 去验。
以前这种偏差也会发生，只是没那么快。
AI 加进来以后，偏差会被放大。因为它可以很快生成代码，也可以很快把一个模糊需求扩成一大堆改动。等团队发现“好像不是这么回事”的时候，代码可能已经堆了不少。
所以团队用 AI，先要解决的不是“怎么让 AI 更快写代码”。
更关键的问题是：
AI 写出来的东西，团队怎么接得住？OpenSpec 能派上用场，也是因为它给团队提供了一个承载规则的地方。
团队落地，先别全员强制
我不建议一上来就规定：
以后所有需求都必须走 OpenSpec。
这种做法听起来很工程化，实际很容易让人反感。
因为不是所有改动都值得走完整流程。
改一个错别字。 调一个按钮边距。 写一个临时脚本。 修一个非常明确的小 bug。
这些事情如果都要求写 proposal、spec、design、tasks，大家很快就会觉得 OpenSpec 是负担。
更好的方式，是先定使用边界。
我会把需求分成三类：
第一类，可以直接改。
比如文案、样式微调、简单配置、非常小的 bug。这类改动 AI 可以直接辅助，不必为了流程而流程。
第二类，建议走 OpenSpec。
比如新增一个用户可见功能、修改一段已有业务行为、涉及多个文件或模块、后面需要别人 Review。这些改动不一定很大，但已经需要把范围和行为说清楚。
第三类，必须走 OpenSpec。
比如权限、支付、数据迁移、对外 API、核心业务流程、跨团队协作、线上风险较高的改动。这些需求如果只靠聊天和代码 diff，后面很容易出问题。
这条边界越早说清楚，团队越容易接受。
因为它传递的不是“又多了一个流程”，而是“有些事情值得认真一点，有些事情不必”。
工具不应该替代判断。
它应该服务判断。
把 change 当成团队的工作单元
团队真正开始用 OpenSpec 后，心智上要做一个转换：
不要把一次 AI 对话当成工作单元。
要把一个 change 当成工作单元。
也就是：
Issue / 需求 -> openspec change -> 分支 / PR -> archive这不是要求每个团队都严格绑定 Issue、分支和 change 名称，但最好有一条能对上的线。
比如：
Issue: 用户希望夜间使用时支持暗色模式
Change: add-dark-mode
Branch: feature/add-dark-mode
PR: Add dark mode support
这样 Review 时，大家看的不只是代码 diff，而是同一件事的不同层面：
Issue 说明问题来源
proposal 说明本次范围
specs 说明行为变化
design 说明技术取舍
tasks 说明执行进度
PR 说明代码实现
archive 留下历史
这条线一旦连起来，AI 的输出就不再是一段聊天里的结果，而是进入了团队原本的研发结构。
每个 change 都应该有人负责
这里还有一个很实际的问题：谁来维护 OpenSpec artifacts？
我的建议是，每个 change 都要有 owner。
owner 不一定是唯一写代码的人，但他要对这次变更的上下文负责。
他的职责不是“把文档补齐”这么简单，而是：
确保 proposal 的范围说得清楚
确保 specs 写的是行为，不是实现细节
确保 design 反映真实技术方案
确保 tasks 可执行、可验证
确保 AI 改代码后 artifacts 没有过期
确保 archive 前变更真的闭环
如果没有 owner，OpenSpec 很容易变成“AI 生成的一堆文件”。
刚开始看起来很完整，过几天没人维护，就开始失真。proposal 写着 A，代码实现了 B；design 说用现有能力，实际新造了一套；tasks 勾完了，但测试根本没覆盖关键场景。
这种 OpenSpec 不但没帮忙，反而会制造新的误导。
所以团队落地时，先别急着追求 artifacts 多漂亮。
先让每个 change 有人负责它的真实性。
名字起好，比想象中重要
OpenSpec 会把每一次变更放在 openspec/changes/<change-name>/ 下。
所以 change name 其实就是团队的变更索引。
名字起得好，后面查起来很舒服。
比如：
add-dark-mode
fix-login-redirect
optimize-product-query
implement-member-expiration
这些名字一眼能看出要做什么。
反过来，下面这些名字就很糟糕：
update
fix
test
wip
change-1
它们在刚创建时可能没问题，但过两周再看，基本等于没名字。
团队可以定一个很简单的命名规则：
动词 + 对象 + 必要限定比如：
add-member-export
fix-payment-timeout
refactor-auth-session
remove-legacy-theme
这不是形式主义。
当一个项目里同时有十几个 changes 时，命名就是协作效率。
PR Review 不要只看代码 diff
很多团队接入 AI 后，Review 会变难。
以前 Review 一个人写的代码，至少还能从代码风格、提交习惯和沟通记录里看出一些上下文。现在 AI 可能一次改很多文件，而且看起来都挺像那么回事。
如果 Review 只看代码 diff，很容易漏掉更前面的偏差：
需求是不是理解错了？ 范围是不是扩太大了？ 行为是不是和产品预期不一致？ 技术方案是不是绕过了现有架构？ 测试是不是只验证了 happy path？
OpenSpec 可以把 Review 往前移一点。
一个比较实用的 PR Review 顺序是：
先看 proposal.md。
这一步看的是：为什么做、做什么、不做什么，范围有没有说清楚。尤其要看 out of scope，因为 AI 很容易把“相关”理解成“应该一起做”。
再看 specs/。
这一步看的是：用户可见行为有没有定义清楚，新增、修改、移除的行为有没有写对。spec 里如果出现内部类名、函数名、文件路径，就要警惕它是不是写偏了。
再看 design.md。
这一步看的是：技术方案是否适合当前项目，有没有明显风险，是否复用了已有模式。如果 design 写的是方案 A，代码实现却走了方案 B，要么改代码，要么更新 design。不能让它们分叉。
再看 tasks.md。
这一步看的是：任务是否可执行、可检查，是否有测试或手动验证项。任务全部勾上，不代表真的完成；要看每个勾选背后有没有证据。
最后才看代码 diff。
不是说代码不重要。
而是代码应该放在上下文里看。
如果 proposal 本身就没说清楚，代码再漂亮也可能是在解决错问题。
CI 里先接轻量检查
团队落地 OpenSpec，不一定第一天就做复杂自动化。
但我建议至少把 validate 接到 CI 里。
OpenSpec CLI 支持结构校验，比如：
openspec validate --all--json或者更严格一点：
openspec validate --all --strict --concurrency 12CI 里先做这件事就够了：
检查 specs 和 changes 的基本结构有没有问题。它不能替你判断需求对不对，也不能替你判断技术方案好不好。
但它能避免一些低级问题：
spec 格式不对
requirement 缺少 scenario
change 结构不完整
delta 写法不符合预期
archive 前遗留明显结构问题
这类检查适合自动化。
因为它不需要人反复看格式。
人应该把精力留给更重要的判断：范围、行为、方案、风险。
多人并行时，changes 是隔离层
真实团队不会只有一个需求。
常见情况是：
一个人在做暗色模式。 一个人在修登录跳转。 一个人在优化商品查询。 另一个人在调整会员权益。
如果所有讨论都堆在聊天里，很快就乱了。
OpenSpec 的 changes/ 目录，天然适合做工作隔离。
每个 change 有自己的 proposal、specs、design、tasks。
这意味着团队可以并行推进多个变更，而不是把所有需求塞进同一个“大文档”。
比如：
openspec/ changes/ add-dark-mode/ fix-login-redirect/ optimize-product-query/ implement-member-expiration/每个目录都回答同一组问题：
为什么做？ 行为怎么变？ 方案怎么定？ 任务怎么拆？ 现在做到哪里？
这对团队协作非常实际。
当某个人被临时拉去修线上问题，他可以新建一个 change，不会把原来的需求上下文弄乱。当他回到原需求，也能从 tasks 里继续。
如果多个 change 都改了同一个 spec，归档时就要更谨慎。OpenSpec 在 expanded workflow 里也提供 /opsx:bulk-archive 这类能力，帮助处理多个已完成 changes 的归档。
但我的建议是：团队刚开始不要急着批量归档。
先养成单个 change 清晰收尾的习惯。
先让每一次变更可读，再追求批量效率。
团队规则应该写进 config
团队规范如果只靠口头说，很快就会忘。
OpenSpec 的 openspec/config.yaml 可以放一些项目上下文和生成规则。
比如：
schema: spec-driven context: | 技术栈：TypeScript、React、Node.js、PostgreSQL API 风格：RESTful 测试：Jest + React Testing Library 所有公开 API 需要保持向后兼容 rules: proposal: - 必须写清楚本次不做什么 - 涉及线上风险时必须写回滚方式 specs: - 使用 Given/When/Then 或同等清晰的场景描述 - 不要把内部类名、函数名写进 spec design: - 说明是否复用现有架构 - 涉及数据迁移时必须写风险和回滚 tasks: - 每个任务必须可验证 - 涉及用户行为变化时必须包含测试或手动验证项这样做的好处是：AI 在生成 artifacts 时，会带着团队上下文。
它不会每次都像第一次进项目一样，从零猜你的技术栈、测试偏好和兼容性要求。
当然，config 不应该写得太长。
它不是团队制度大全。
它只需要写那些会反复影响 AI 输出质量的东西。
什么时候需要自定义 schema？
大部分团队一开始用默认 spec-driven 就够了。
也就是：
proposal -> specs -> design -> tasks -> implement不要一开始就急着定制复杂流程。
但如果团队已经形成比较明确的研发习惯，可以考虑自定义 schema。
比如有的团队希望在 tasks 前增加一个 review.md：
proposal -> specs -> design -> review -> tasks -> implement这适合高风险变更比较多的团队。
还有些团队会做 research-first：
research -> proposal -> specs -> design -> tasks这适合性能优化、架构重构、疑难问题排查。
但我建议把自定义 schema 放到第二阶段。
第一阶段先让大家理解 OpenSpec 的基本模型，形成习惯。等默认流程真的不够用了，再加新 artifact。
流程不是越完整越好。
流程是刚好能托住当前团队的问题，就够了。
跨仓库协作，不要一开始就复杂化
有些团队会问：如果一个需求同时改前端、后端、网关、文档，OpenSpec 应该放在哪里？
这个问题没有一个永远正确的答案。
我的建议是先分清两层：
repo-local change：某个仓库自己负责的实现变更 coordination context：跨仓库需求的协调上下文大多数团队刚开始用 OpenSpec，先从 repo-local 做起就够了。哪个仓库承担主要实现，就在哪个仓库里维护 change。
如果团队已经频繁做跨仓库项目，再去看 OpenSpec 的 workspace / initiative 这类能力会更合适。它们更像是多仓库场景下的协调视图，而不是每个团队第一天就必须引入的东西。
别一上来就把工具用到最复杂。
先把单仓库、单 change 的闭环做好。
不要把 OpenSpec 变成“文档税”
这是我觉得最需要警惕的地方。
OpenSpec 的目标不是让团队多写文档。
它的目标是让 AI 参与研发后，需求和实现之间有一条可追踪的线。
所以团队落地时，最好避开几个反模式。
第一个反模式：所有小改动都强制走完整流程。
这会让大家很快讨厌它。
第二个反模式：spec 写成实现文档。
比如把具体类名、函数名、文件路径塞进 spec。这样 spec 很快会过期，也会让行为定义变得很难读。
第三个反模式：tasks 写得太大。
一个任务叫“完成会员系统”，这对 AI 没什么帮助，也不方便 Review。
第四个反模式：archive 不及时。
change 做完后一直放在 active changes 里，久了以后大家就不知道哪些是正在做，哪些已经结束。
第五个反模式：把 OpenSpec 当成替人判断的工具。
它能帮你组织上下文，但不能替你判断业务优先级、技术风险和用户价值。
如果这些反模式出现，团队应该先收缩范围，而不是继续加规则。
我建议的落地路线
如果让我在一个团队里引入 OpenSpec，我不会一上来开会讲一堆概念。
我会分三步。
第一步，选一个中等复杂度需求试点。
不要选太小的，也不要选风险最高的。最好是一个需要前后端协作、用户能感知、但风险可控的需求。
用它跑一次完整流程：proposal、specs、design、tasks、apply、sync、archive。
第二步，把 Review 顺序固定下来。
以后遇到类似需求，PR 不只看代码，也看 OpenSpec artifacts。先看 proposal，再看 specs，再看 design/tasks，最后看代码。
第三步，把少量规则写进 config 和 CI。
比如 config 里写技术栈、测试要求、spec 写法；CI 里加 openspec validate --all --json。
这三步做完，OpenSpec 就不再只是个人习惯，而开始进入团队流程。
后面如果团队真的需要，再考虑 expanded workflow、verify、bulk-archive、自定义 schema、workspace 这些能力。
不要把成熟形态当成起步形态。
最后，团队需要的是能接住速度的结构
这组三篇文章写到这里，我想表达的其实不是“大家一定要用 OpenSpec”。
更准确地说，我想表达的是：
AI 进入研发流程后，我们需要重新设计协作方式。
以前我们习惯讨论人和人怎么协作。 现在还要考虑人和 AI 怎么协作。 更进一步，还要考虑多人、多 AI、多需求怎么协作。
只靠 Prompt，很难托住这些复杂度。
OpenSpec 提供的是一个很朴素的思路：
把需求说清楚。 把行为写下来。 把方案留下来。 把任务拆出来。 把完成后的历史归档。
这几件事并不新。
它们本来就是工程里该做的事。
只是 AI 把代码生成速度拉快以后，这些事变得更重要了。
团队用 AI，最怕的不是慢。
最怕的是快得没人接得住。
OpenSpec 的意义，就是让团队在享受 AI 速度的同时，还有一套能接住它的工程结构。
