tlc-spec-lean

Tech Lead's Club——精简版规范

冻结义务，释放计划。由未参与构建的人来验证。源自 tlc-spec-driven 3.3.0（Felipe Rodrigues）、tlc-plan 和 tlc-implement。

┌──────┐   ┌────────┐   ┌───────┐   ┌────────┐
│ PLAN │ → │ CHECKS │ → │ BUILD │ → │ VERIFY │
└──────┘   └────────┘   └───────┘   └────────┘
 read it    obligations   yours       always

编码 Agent 常见的失败，是需求从未成为一项生效的义务，随后却声称已经完成。应对方法是建立一小组冻结的外部义务，并由作者之外的人进行验证，这样预算就能用在这些事情上，而不是花在编排模型上。人类在一份文档中确认必须满足的条件以及构建方式；只有这样，这些内容才会成为带有证明的义务。这里没有任务拆分，也没有组件目录：难以撤销的决策采用单向门，并明确其具体形式；其余事项则在构建过程中决定。

规则

即使没有读取任何参考文件，这些规则也依然适用。每条规则都写在这里；参考文件会指回这里。

1. 每项检查都是一个可观察的主张，包含具体值，以及能够判定其真伪的证据：一个由退出码决定结果的测试或命令；或者，对于由截图呈现的状态，提供一张与截图对照判断的图片（规则 9）。
2. 测试要断言检查所说的内容，而不是代码碰巧做了什么。不要通过阅读实现来编写测试。
3. 测试只随其证明的主张变更，并与其证明的代码在同一提交中一起提交。修改测试以通过测试套件，会掩盖它本应揭示的失败：检查有误时，应停下并询问。
4. validate_checks.py 通过后，检查即固定；如果流程或 Verifier 发现有遗漏的义务，可以追加检查。在计划中，Landing、Surface 和存储的形状是增补内容；路径和 Changes underneath 必须在变更它们的提交中保持真实准确。
5. Verifier 必须是全新的子 Agent，不能是作者；每项功能都必须运行 Verifier，并与 screens 子 Agent 同时运行。check_proofs.py 负责判定机械部分——每项证明都已运行且在 HEAD 上通过、图片、流程、被杀死的变异；Verifier 则专注于判断：错误规则仍会通过的变异、无人指出的示例，以及宽松于判定标准的断言。只有当所有发现都已通过提交解决，且 proofs.md 在 HEAD 上通过时，工作才算完成。
6. 变异数量在 checks.md 中声明（Mutations:，默认值为 3），它决定 Verifier 要探测多少条规则，而不是工作的质量：无论 N 是多少，都必须保证代码质量、每项检查背后的测试，以及完整的 Coverage 关联。检查只是底线；未被任何检查指出的边缘案例或防护措施仍然属于工作范围。
7. 完成门槛由脚本决定：validate_verification.py 退出码为 0。最终报告以该脚本的最后一行开头；如果门槛未通过，必须首先说明，不能留给读者自行发现。
8. 经批准的规格允许进行本地编辑和本地提交。执行 git push、部署和修改生产数据，均需针对该操作获得明确许可。
9. 截图呈现的状态必须用一张图片来证明。 作者应在浏览器窗口中达到该状态，并以截图的尺寸保存 <capture>.running.png，放在截图旁边——尺寸指像素尺寸乘以缩放比例：更宽的窗口会以不同方式排版页面，事后调整图片大小则会掩盖这种差异。任何人都不得重新打开应用来判断：由 screens 子 Agent 根据文件进行判断（verify-screens.md）；如果图片中的文字看起来比截图中的小，说明图片被调整过大小，必须重新截取。除了 ## Differences from the source 中列出的内容外，图片必须与截图一致。截图未呈现的状态，以及功能不会更改的现有屏幕，应通过测试或 walk 证明，不需要图片，也不需要评审。
10. 随请求提供的截图、原型图或在线网站均具有约束力，除非用户称其为灵感参考。只有用户可以更改具有约束力的来源。若要移除、重命名或偏离其中呈现的内容，必须先询问，将决定记录在 .specs/STATE.md 中，并在计划的 ## Differences from the source 下列出 Confirmed: y - AD-NNN。
11. 文件记录整个运行过程；聊天记录无法在压缩后保留。 用户的批准应写入 plan.md，格式为 **Approved**: <date> - user: "<their words>"，且绝不能写入用户未说过的话。每条回复都应在收到的当轮写入对应文件。每个子 Agent 派发前，都应先将其写入 checks.md 的 ## Handoff 下的 **Dispatched:** 行。压缩后或在新会话中，应重新阅读本文件和当前阶段的参考文件，然后从文件中恢复工作（memory.md）。

配置

项目在 AGENTS.md 或同等文件中声明此项；checks.md 会将计数复制到 Mutations: 行。

## tlc-spec-lean

mutations: 3

部分	运行方式	无法捕获的问题
check_proofs.py（始终运行）	每个 runner 在 HEAD 上对每项证明运行一次；每项检查都与其筛选条件选出的测试匹配；检查图片和操作流程；注入变异	因错误原因而通过的测试
Verifier（始终运行）	在规则所在位置注入 N 个变异；两个无人指定的示例；宽于其判定标准的断言；与有约束力的截图相矛盾的检查（verify.md）	未经变异探测的规则
screens 子 Agent（判定标准引用了截图时）	在指定的 HEAD 上，将每张截图与作者的图片逐一核对；每一行标记为 same 或 differs（verify-screens.md）	间距、颜色和字重；截图无法呈现的更细节内容；未被截图展示的界面

截图不进行变异测试；应将 N 用在错误实现代价最高的地方。如果某项功能的 N 看起来过低，请用一行说明，并让用户提高该值。

产物

.specs/
├── STATE.md                    # Decisions log (AD-NNN)
├── LESSONS.md                  # rendered by scripts/lessons.py - do not hand-edit
├── lessons.json                # machine-owned
└── features/<feature>/
    ├── plan.md                 # problem, shape, surface, doors, criteria
    ├── checks.md               # claims + proofs, the coverage join, swept, handoff
    ├── captures/               # binding source files, and the author's <capture>.running.png
    ├── screens.md              # the screens sub-agent's inventory and verdict, per picture
    ├── proofs.md               # written by check_proofs.py: every proof and mutation at HEAD
    ├── mutations.json          # the Verifier's mutations, re-run after the fix
    └── verification.md         # the Verifier's findings, each closed by a commit

对于大约不超过三个文件且没有不可逆决策的更改，只编写包含 ## Intent 段落的 checks.md，并跳过 plan.md。

阶段

阶段	产出内容	参考
计划	问题、方案、影响范围、决策关口、判定标准；默认的人工停顿点	plan.md
检查	带证明的声明；逐项关联每个集合中的成员；检查九个维度	checks.md
构建	根据检查编写测试、代码和提交；走查并保存界面	build.md
验证	规则 5	verify.md、verify-screens.md

决策和经验：memory.md。

脚本

将 <skill-dir> 解析为包含此 SKILL.md 的目录，并运行 python3 <skill-dir>/scripts/<name>.py。当 cwd 不是项目根目录时，传入 --root。退出码非零表示停止并修复。运行脚本，不要阅读脚本：脚本的消息会说明需要修改什么。

时机	命令
提交计划前	validate_plan.py <feature>
开始构建前	validate_checks.py <feature>——它还要求计划中包含 **Approved**: 行
每次提交前	check_commit.py --message "<msg>"
分派 Verifier 前，以及修复后	check_proofs.py <feature> [--mutations <mutations.json>]
宣布完成前	validate_verification.py <feature>
提炼经验时	lessons.py add ...
编辑验证器或模板后	selftest.py

selftest.py 会针对每条门禁规则，对 scripts/fixtures/ 中的固定样例进行一次变异，并要求每个变异版本都被识别为失败；这些固定样例也是一套通过检查的产物示例。

依赖

依赖	用途	缺少时
Python 3.8+（仅使用标准库）	所有脚本	门禁无法运行；各阶段仍然适用
git	mutate.py 和 check_proofs.py（HEAD、工作区干净）	不进行变异，也不检查 HEAD：在报告中说明
子 Agent	Verifier 和 screens 子 Agent	在新会话中运行其文件并写入 self-verified；门禁会发出警告
可读取图片的模型	screens 子 Agent	将图片和截图交给用户
Agent 可操控的浏览器	保存 <capture>.running.png 并执行操作流程	将步骤交给用户

测试运行器：check_proofs.py 会将 bun、vitest、jest、pytest 和 go test 各归为一次运行 （scripts/runners.py）；其他命令各自单独运行，并根据其退出码判定。

输出

生成产物；不要叙述阶段过程。先给出结论，并清楚说明决策。 章节标题保留英文；正文遵循项目语言；标识符一律不翻译。