本层判断标准

三个月后新来的人,能不能只靠仓库里的文件就知道该怎么做?

不能,说明这套规范还靠老人带,没有真的立住。答「不能」时先补仓库说明与规约模板,再谈其他四层。

五步,按这个顺序

第一步做规约与仓库说明先让全组用同一套规则和同一份判据。产出物是仓库里的 CHANGE 四件套模板,和一份 200 行以内的仓库说明。这一步不需要任何检查就能生效——只要有人照着模板交东西,判据就存在了。
第二步立门禁把能被工具判断的东西挡在合并之外。产出物是一条能跑的检查入口,加上分支保护。这一步做完,评审的人才有时间——格式与语法不再进评审。
第三步改评审把评审人的精力从语法移到意图和风险。产出物是合并请求模板和一份四类高风险路径清单。
第四步补防护与传统规范按团队规模和安全要求补。产出物是指令目录的保护规则、依赖引入清单,以及只保留「审查方式变了」和「必须死守」两类传统条目。
第五步量出成本与用量等前四步跑起来之后再管。产出物是一份按变更归因的用量记录和一条额度线,见 成本与用量。放在最后不是因为不重要,是因为前四步没有落点之前,用量数字解释不了任何事。

顺序里最容易跳过第一步。跳过它先去配检查,会发现检查没东西可依据——因为「什么算对」还没写下来。检查能跑,但它判的标准是空的,于是所有改动都能过。

每周做什么

下面按周排,一周一个动作。每周末用「完成标准」那一列回答是或否;答「否」,就把这一周的动作留到下一周,不要跳到下一行。行里的周次以项目启动为第 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 周:钩子就是那个自动挡人的动作,检查入口本身不变。将来接上持续集成,不用改命令。

.githooks/pre-commit(提交前跑同一条入口)

要做三个动作:写钩子文件、chmod +x、把 core.hooksPath 指过去。少任何一步,钩子都不会触发,而且不报错。

#!/bin/sh
# 提交前跑同一条检查入口;不通过就不让提交
set -e
echo "[pre-commit] make check"
make check

Makefile 里的 setup 目标(新克隆仓库后执行一次)

把「让钩子生效」写成一条命令,新来的人不用被告知也能装上。

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 周的动作不能省。

起步期的三条禁令

不要同时改门禁和功能放宽检查这件事混在功能改动里,是这个阶段最常见的失守方式。发现时症状是:一次合并请求的改动差异里既有新功能,又有一处阈值从 10 调到 15。
不要先写长篇规范再谈工具手册越厚,越没人读。先让 make check 跑起来,纸面上的规范可以后补。
不要在争议没定时把口头结论写成决议写进决议的每一条都要能被检查;还在争论的,先记在 proposal.md 里。

常见的「上了但没用」

团队复盘的结论如果是「大家意识不够」,说明还没找到下面这张表里真正的那一条。

症状真实原因修法
清单很长,没人读完没过四问筛选删到一屏:删掉之后不会出错的句子就删掉
门禁被绕过只写了规则,没开分支保护加分支保护与 CODEOWNERS,见质量门禁
评审还是在提格式意见本地保存时没自动格式化把格式化接进保存动作,和检查用同一份 pyproject.toml
决议写在会议纪要里没有落点挪进 docs/decisions/ 下带编号的文件
助手反复犯同一个错改的是对话,不是规则第二次出现就改规则文件,和导致它变化的代码同一次合并
评测报告看起来很漂亮问题集只有正常路径补无答案与越权样本,并让判分规则判得动