五层不要一次全上:一条都没跑起来时,团队会得出「规范没用」的结论。
要一个能照着排的顺序,直接看每周做什么,找自己所在的周次那一行。
三个月后新来的人,能不能只靠仓库里的文件就知道该怎么做?
不能,说明这套规范还靠老人带,没有真的立住。答「不能」时先补仓库说明与规约模板,再谈其他四层。
顺序里最容易跳过第一步。跳过它先去配检查,会发现检查没东西可依据——因为「什么算对」还没写下来。检查能跑,但它判的标准是空的,于是所有改动都能过。
下面按周排,一周一个动作。每周末用「完成标准」那一列回答是或否;答「否」,就把这一周的动作留到下一周,不要跳到下一行。行里的周次以项目启动为第 1 周,项目周期不同可按比例压缩,但顺序不变。
| 周次 | 动作 | 产出物 | 完成标准(答「是」才算完) | 谁负责 |
|---|---|---|---|---|
| 第 1 周 | 写规约模板与仓库说明 | openspec/changes/ 四件套模板、AGENTS.md(≤ 200 行) | 新成员只读仓库,能说出一次改动要交哪四份文件 | 组内负责人 |
| 第 2 周 | 用模板做第一次真实改动 | 一个完整变更目录 + verify.md | 四件套齐,且规约与代码在同一次合并请求里 | 提出人 + 另一名组员 |
| 第 3 周 | 立检查入口 | Makefile 的 make check、pyproject.toml 里的阈值 | 本地 make check 在 60 秒内给出结果 | 组内负责人 |
| 第 4 周 | 接持续集成与分支保护 | .github/workflows/check.yml、分支保护两项 | 故意提交一个圈复杂度 15 的函数,它被挡在合并之外 | 组内负责人 |
| 第 5 周 | 改评审 | 合并请求模板、docs/checklists/spec-review.md | 最近 10 条评审意见里,格式类占比 ≤ 20% | 另一名组员 |
| 第 6 周 | 补防护与传统规范 | CODEOWNERS、依赖引入清单 | 外部贡献者能不能改 .claude/ 或 AGENTS.md?答案必须是「不能」 | 组内负责人 |
| 之后每月 | 用量与复盘 | docs/metrics/<周>.md、docs/usage/ | 周报里有一条「把上月反复出现的错误变成一条检查」 | 轮值的人 |
边界:这套排期假设每周合并一次。项目进入联调期、一周合三次以上时,可以把第 3 到第 5 周并到一周做完——它们互不依赖,都依赖第 2 周那次真实改动。
判据都写成了问句,因为验收这一步的方式是做一次对照实验:拿一个真实的不达标改动走一遍流程,看它在哪一步被挡住。挡不住,这一步就还没做完。
| 步 | 完成标准(能回答「是」才算完) | 产出物 |
|---|---|---|
| 1 规约与仓库说明 | 新成员只看仓库,助手产出的代码是否合乎团队习惯? | CHANGE 模板、AGENTS.md |
| 2 门禁 | 一个不达标的改动,会不会被自动拦下,而不是靠人看出来? | 检查入口、分支保护、CODEOWNERS |
| 3 评审 | 评审人的时间是不是花在意图和风险上,而不是格式和语法上? | 合并请求模板、高风险清单 |
| 4 防护与传统规范 | 外部贡献者能不能通过改指令文件操纵团队的助手? | 保护规则、依赖清单、保留的规范条目 |
| 5 成本与用量 | 随便挑一个已合并的变更,能不能说出它花了多少、贵在哪? | docs/usage-budget.md、用量记录 |
## 落地进度 - [x] 第 1 周 规约模板与仓库说明 已完成 - [x] 第 2 周 第一次真实改动 已完成 - [x] 第 3 周 make check 已完成 - [x] 第 4 周 持续集成与分支保护 已完成 - [ ] 第 5 周 改评审
认它的办法:每一条「已完成」能不能指向一个文件或一条命令输出。前四条全打了勾,但一条都拿不出来——这是「清单做完了,实验没做过」。这一页的验收方式不是填进度,是拿一个真实的不达标改动走一遍,看它在哪一步被挡住;挡不住,这一步就没做完。助手能把清单填得整整齐齐,它做不了那次对照实验——实验要有意提交一个错的东西。
本项目没配持续集成时,用「本地提交前钩子 + 一条 make check」代替第 3、4 周:钩子就是那个自动挡人的动作,检查入口本身不变。将来接上持续集成,不用改命令。
要做三个动作:写钩子文件、chmod +x、把 core.hooksPath 指过去。少任何一步,钩子都不会触发,而且不报错。
#!/bin/sh # 提交前跑同一条检查入口;不通过就不让提交 set -e echo "[pre-commit] make check" make check
把「让钩子生效」写成一条命令,新来的人不用被告知也能装上。
setup: git config core.hooksPath .githooks chmod +x .githooks/pre-commit pip install -r requirements-dev.txt
走这条降级路径,挡不住下面四类,它们都会真的发生:
| 挡不住的 | 可识别的现象 | 能做的补救 |
|---|---|---|
| 绕过钩子 | 一条 git commit --no-verify 就跳过了,提交历史里不留痕 | 写进 AGENTS.md;每周轮值的人抽一次,把最近 20 次提交在干净克隆上重跑 |
| 钩子没装上 | 同一份代码,A 提交得过、B 被挡——因为 B 执行过 make setup,A 没有 | 把 make setup 写进仓库说明的第一段;在合并请求模板里加一行「已跑 make check」 |
| 不挡推送与网页改文件 | 直接推到 main、或在网页上提交,钩子完全不参与 | 打开分支保护的「禁止直接推送」;这一项钩子替不了 |
| 工具版本不一致 | 本机过、别人那不过,同一份提交在两台机器上退出码不同 | 把工具版本锁在 requirements-dev.txt 里,用固定的解释器跑 |
记住一条结论:降级做法让检查在本地跑起来,但它不是门禁。门禁要求的是「人推不进去」,钩子做不到这一点。有条件接持续集成时,第 4 周的动作不能省。
make check 跑起来,纸面上的规范可以后补。proposal.md 里。团队复盘的结论如果是「大家意识不够」,说明还没找到下面这张表里真正的那一条。
| 症状 | 真实原因 | 修法 |
|---|---|---|
| 清单很长,没人读完 | 没过四问筛选 | 删到一屏:删掉之后不会出错的句子就删掉 |
| 门禁被绕过 | 只写了规则,没开分支保护 | 加分支保护与 CODEOWNERS,见质量门禁 |
| 评审还是在提格式意见 | 本地保存时没自动格式化 | 把格式化接进保存动作,和检查用同一份 pyproject.toml |
| 决议写在会议纪要里 | 没有落点 | 挪进 docs/decisions/ 下带编号的文件 |
| 助手反复犯同一个错 | 改的是对话,不是规则 | 第二次出现就改规则文件,和导致它变化的代码同一次合并 |
| 评测报告看起来很漂亮 | 问题集只有正常路径 | 补无答案与越权样本,并让判分规则判得动 |