Spec Kit 实战 06 · 团队协作与规格维护

上一章：老项目接入 Spec Kit | 返回索引 | 下一章：反模式与故障排查

阅读指南 工件多起来之后，问题就从“怎么写”变成“谁说了算”。这一章定四件事：工件归谁所有、PR 怎么分两阶段、任务怎么并行、变更该回到哪个工件。OpenSpec 的并行变更规则和 CI 门禁也在这里。

场景：工件多了以后，谁说了算

Spec Kit 会留下多份工件。没有 owner、评审边界和变更规则，文档越多，冲突越容易被漏掉。本章把工具实际行为和团队建议分开写。

1. 工件所有权

【官方能力】自定义 checklist 是 reviewer-owned；/speckit.implement 只读取 checkbox 状态，不应自行勾选。

2. 两阶段 PR

【社区实践】复杂 feature 推荐两个评审边界：

Planning PR

包含：

1.specify/memory/constitution.md   # 只有确需修改时
2spec.md
3clarification changes
4plan.md
5research.md
6data-model.md
7contracts/
8quickstart.md
9checklists/
10tasks.md

合并条件：业务和技术决策已批准，Analyze 阻断项已处理，尚未开始大规模实现。

Implementation PR

包含代码、测试、迁移、tasks.md 状态、quickstart 实跑、Converge 结果。

小 feature 可以放同一 PR，但仍设置“工件批准后再 Implement”的明确 checkpoint。

用 OpenSpec 的团队可以把两个边界直接映射过去。Planning PR 对应 change 提案的评审，proposal、delta、design、tasks 作为一组工件合并评审；Implementation PR 对应 /opsx:apply 之后的代码与 /opsx:archive 归档结果。有一件小事别漏，delta 合并回 specs 的 diff 要随实现 PR 一起提交，不然代码进了主干，现行规格还停在上一版。

3. Git 扩展与普通 Git

工具实际行为

【官方能力】核心 Spec Kit 不要求 Git。可选扩展：

1specify extension add git

它支持仓库初始化、编号/时间戳 feature 分支、分支校验、远程检测和可配置 auto-commit。配置位于：

1.specify/extensions/git/git-config.yml

auto-commit 默认关闭。

推荐团队规则

• 初始化、spec、plan、tasks、implement 分别形成可读提交或提交组；
• 不强制“一任务一提交”，按可审查逻辑单元提交；
• specs/ 与代码一起进入版本控制；
• OpenSpec 仓库把 openspec validate --archived 加进 CI：归档项有未勾选任务即非 0 退出，规格同步从约定变成门禁；
• .specify/feature.json 是机器本地活动指针，按初始化的 .gitignore 处理；
• 切分支后不要假设活动 feature 自动变化，执行前核对指针。

4. 并行开发

任务带 [P] 只表示不同文件且无未完成依赖。它不是“可以盲目交给多个 agent”。

图书系统的安全并行点

Foundation 完成后：

• US1 的 T006-T007 可由一个开发者负责；
• US2 的 T008-T009 由另一个开发者负责；
• US3 的 T010-T015 可稍后或并行；
• LoanController.java 与 LoanServiceImpl.java 被 US3 内部多个任务先后修改，需明确 owner 或严格按任务顺序执行。

并行前置清单

• 所有人基于相同的 spec/plan/tasks commit。
• 公共 schema 与 contract 已批准。
• 同一文件只有一个 owner，或任务明确串行。
• 每个分支有独立验收与测试命令。
• 合并后重跑完整测试和必要的 Analyze/Converge。

OpenSpec 的并行变更

OpenSpec 下并行的单位是 change 而不是任务。规则比 Spec Kit 更宽松也更需要自觉核对：

• 两个 change 修改不同能力（如 post-query 与 post-publishing）或同一能力的不同 Requirement 时可以并行——各自只在自己的 delta 里声明差异，归档时分别合并，互不覆盖；
• 两个 change 的 MODIFIED 指向同一条 Requirement 时必须串行：先归档前者，后者的 delta 要基于合并后的现行规格重写再评审，否则第二个归档会以错误的“之前版本”做替换；
• 并行期间用 openspec list 盯着进行中的提案数量，changes/ 里堆积过多未归档提案通常意味着评审或落地环节堵塞——它应该像 PR 队列一样短，而不是第二个文档堆放处。

这与上文“共享 contract/schema 先合并”是同一条原则：差异可以并行产生，公共基准只能串行演进。

5. 规格维护模型

【官方能力】v1.0.5 文档命名三种模型，但没有默认值，也不是 CLI 配置项。

推荐选择方式

回答两个问题：

1. 已完成 feature 目录是历史记录还是可编辑工作区？
2. spec.md 是唯一源，还是 plan/tasks 也允许成为同级事实来源？

把答案写进 Constitution 或 CONTRIBUTING.md。

维护期如果想要比"约定"更强的强制力，可以把 Flow-forward 的"提案—归档—合并"环交给工具执行：第 5 章用 OpenSpec 演示了这套做法——变更先落成提案，归档时差异自动合并回现行规格，未勾完任务无法通过校验。

6. 变更进入哪个工件

1flowchart TD
2    A[发现变化] --> B{改变用户可见行为?}
3    B -- 是 --> C[修改 spec / clarify]
4    B -- 否 --> D{改变架构或技术决策?}
5    D -- 是 --> E[修改 research / plan]
6    D -- 否 --> F{只是遗漏工作?}
7    F -- 是 --> G[修改 tasks]
8    F -- 否 --> H[修复代码并记录证据]
9    C --> I[同步下游工件并 analyze]
10    E --> I
11    G --> I

图书系统示例

• 借期从 14 天改为月底：改 Spec，不只是改 T010；
• 单库 MySQL 撑不住并发或容量、需要分库分表：改 Research/Plan/Data Model，再改 Tasks；
• 漏测重复归还：加 Task；
• 实现中的变量名错误：改代码即可，不需要新 Spec。

博客示例

• 增加发布审批：新 feature（Flow-forward）最清晰；
• 错误码拼写修正：若已成为外部 contract，更新 contract/spec 并通知调用方；
• xxl-job 任务从每分钟调整为每 30 秒：若影响已承诺时效，先改 spec；否则属于 plan/运维决策。

7. 提示词评审规则

一个可执行提示词通常包含：

1目标行为 + 当前仓库事实 + 必须保留 + 明确不做
2+ 技术约束（仅 Plan/Implement）+ 验证命令 + 停止条件 + 汇报格式

Specify 提示词

写用户、目标、业务规则、边界、成功标准；不写框架实现。

Plan 提示词

写真实代码入口、批准的技术栈、兼容/迁移/回滚、需研究的问题和验证。

Implement 提示词

写任务范围、先跑哪些测试、禁止扩大哪些范围、遇到什么必须停止，以及结果需报告的命令和退出码。

8. 评审模板

1## Artifact review
2- Scope: [是否只覆盖批准需求]
3- Traceability: [需求 -> plan -> task -> test]
4- Compatibility: [旧 API/URL/数据/权限]
5- Data safety: [迁移、事务、回滚]
6- Evidence: [实际命令、退出码、环境]
7- Open decisions: [必须由谁确认]
8- Status: planned / implemented / tested / accepted / deployed / online-verified

本章完成检查清单

• 每个工件有人工 owner。
• 团队定义了 Planning 与 Implementation 的 gate。
• 活动 feature 与 Git 分支的关系已写清。
• 并行任务没有同文件或依赖冲突。
• OpenSpec 并行变更遵守"不同能力/不同 Requirement 可并行，同 Requirement 串行"。
• 已选择并记录规格维护模型。
• 变更会回到拥有该事实的工件，而不是只改代码。

下一章：反模式与故障排查