tlc-spec-driven

技术负责人俱乐部 - 规范驱动开发

精准地规划并实现功能。任务粒度清晰。依赖关系明确。工具得当。不搞繁文缛节。

┌──────────┐   ┌──────────┐   ┌─────────┐   ┌─────────┐
│ SPECIFY  │ → │  DESIGN  │ → │  TASKS  │ → │ EXECUTE │
└──────────┘   └──────────┘   └─────────┘   └─────────┘
   required      optional*      optional*     required

* Agent auto-skips when scope doesn't need it

关键规则（行动前请阅读）

加载此技能的文件。 参考文件位于此技能自身目录下的 references/ 中（即此 SKILL.md 所在目录）。请以技能目录为基准解析路径，切勿以工作区根目录为基准。每当某个步骤要求你阅读参考文件时，必须读完后再采取行动。

运行此技能的脚本。 所有 scripts/*.py 都位于同一技能目录下：运行 python3 <skill-dir>/scripts/<name>.py ...，切勿从项目根目录运行 python3 scripts/...。.specs/ 下的项目数据以项目根目录为基准读写（如果当前工作目录在其他位置，请传入 --root）。运行脚本而非阅读脚本：脚本的消息会说明需要修改什么。

执行约定 - 每项任务都必须遵守（即使不打开参考文件也适用）：

1. 先询问，再等待批准。 所有属于用户决定的模糊事项——范围、产品行为、偏离约束性来源的情况——都必须在提交规范前询问；不得用假设代替询问。批准规范和批准任务，是需要人工确认的两个停顿点。无人回答时，以问题结束本轮。每项批准都必须写入 spec.md 和 tasks.md，格式为 **Approved**: <date> - user: "<their words>"；用户未提供的批准不得写入。每个回答都必须在收到的当轮写入对应文件——聊天记录不会跨越上下文压缩保留。
2. 测试必须源自规范的验收标准，并断言规范定义的结果——不得照搬实现。
3. 任务完成前，门禁必须通过——由测试运行器判定，而非自我评估。每项任务一个原子提交，并且先在 tasks.md 中标记完成；若仓库跟踪 .specs/，也要在该提交中包含此更改。若仓库忽略 .specs/，提交只包含代码及其测试，绝不强行纳入 .specs/。不得合并批量执行任务；不得为使测试通过而削弱、跳过或删除测试。
4. 每项标准都要有检查，每项检查都要有证明。 tasks.md 的 ## Checks 中，每项标准必须有一条对应声明，并注明用于选择其测试的命令。最后一项任务完成后，运行 check_proofs.py，在 HEAD 上一次性运行所有检查及构建；随后必须始终由一名全新的 Verifier（作者 ≠ 验证者）执行验证，不得询问用户是否需要验证：运行 **Mutations**: N 次变异测试（默认为 3 次），针对任何按规则仍会通过的情况、无人指出的示例，以及宽于对应标准的断言。只有所有发现都通过提交解决，且 validate_verification.py 以 0 退出，才算完成。
5. 屏幕必须符合其设计。 随请求附带的截图具有约束力，除非用户明确说明仅供参考；对应标准必须引用截图文件。截图中展示的每种状态，都必须以截图的尺寸从浏览器窗口保存为 captures/<capture>.running.png——事后调整图片尺寸会呈现不同布局；随后由全新的 screens 子 Agent 重新截图并评判（verify-screens.md）。
6. 规则的运行位置。 每项会改变用户所见内容的规则——包括筛选、搜索、排序和计数——都必须在仓库测试能够覆盖的层中运行。
7. 影响范围： 批准规范或任务仅授权本地实现和本地提交。git push、强制推送、部署、生产数据库变更及其他远程或破坏性操作，都必须针对该操作取得明确许可。

确定性门禁必须在人工审查前运行——不能凭记忆判断。 非零退出码意味着必须停止并修复：

何时	命令
呈现规格前	validate_spec.py <feature> - 检查 EARS 标准、已填写的假设、需求 ID，以及带有捕获内容的项：必须有绑定或引文、引用来源、展示内容，并且偏离项已获批准
呈现任务前	validate_tasks.py <feature> - 检查粒度、依赖关系、每项任务的 Tests 和 Gate、每项检查都有证明的 ## Checks、**Build**:、**Mutations**:
第一个任务开始前	validate_tasks.py <feature> --execute - 执行相同检查，并要求规格和任务都已得到用户明确批准
每次提交前	check_commit.py --message "<msg>"
最后一个任务完成后，以及修复后	check_proofs.py <feature> [--mutations <mutations.json>] - 写入 proofs.md
宣布功能完成前	validate_verification.py <feature> - 确保 HEAD 上的证明均通过、工作树干净、变异测试均被杀死、发现项均已关闭、图片在第 1 轮或第 2 轮中经过评审、演练已记录，且两项批准均已写入
编辑脚本或模板后	selftest.py

仅当没有可用的代码执行工具时才跳过脚本；此时通过阅读制品执行相同检查。

**执行前：**完整阅读 implement.md，并运行 validate_tasks.py <feature> --execute；该命令还要求用户明确给出两项批准。如果正式的 tasks.md 按任务预算分成多个批次（超过约 8 项任务），则先提出子 Agent 方案（参见 Sub-Agent Delegation）。

自动调整规模：核心原则

复杂度决定深度，而非固定流程。 开始任何功能前，先评估其范围，并只采用必要的步骤：

范围	内容	规范	设计	任务	执行
小型	≤3 个文件，一句话	单行规范（内联）	跳过	跳过	内联实现并验证
中型	明确的功能，<10 个任务	规范（简要）	跳过——在规范中内联设计	跳过——任务隐含其中	实现并验证
大型	多组件功能	完整规范 + 需求 ID	架构 + 组件	完整拆解 + 依赖关系	按任务实现并验证
复杂	存在模糊之处，属于新领域	完整规范 + 讨论模糊之处	调研 + 架构	拆解 + 阶段计划	实现 + 交互式 UAT

规则：

• 规范和执行始终必需——你始终需要明确要做什么，并实际去做
• 当变更简单明了时跳过设计（没有架构决策，也没有新模式）
• 当明显步骤不超过 3 步时跳过任务（这些步骤会隐含在执行阶段中）；此时将检查项放在 spec.md 末尾的 ## Checks 部分
• 当 Agent 发现需要用户输入的模糊之处，或功能涉及任何隐含需求维度（持久化/状态、外部调用、身份验证、支付、并发、状态转换）时，在规范阶段触发讨论
• 仅针对行为复杂的面向用户功能，在执行阶段触发交互式 UAT

安全阀： 即使跳过任务阶段，执行阶段也始终以在行内列出原子步骤开始（参见 implement.md）。如果列出的步骤超过 5 步或存在复杂依赖关系，则停止并创建正式的 tasks.md——这说明错误地跳过了任务阶段。

.specs 结构

.specs/
├── STATE.md            # Project memory: Decisions log (AD-NNN) + Handoff snapshot
├── LESSONS.md          # Self-improving lessons playbook (rendered by scripts/lessons.py - do not hand-edit)
├── lessons.json        # Canonical lessons state (machine-owned)
└── features/
    └── [feature]/
        ├── spec.md          # Requirements with traceable IDs, Differences from the source, Sources
        ├── captures/        # binding design files, and <capture>.running.png pictures
        ├── context.md       # User decisions for gray areas (only when discuss is triggered)
        ├── design.md        # Architecture & components (only for Large/Complex)
        ├── tasks.md         # Atomic tasks, ## Checks with a proof each, ## Handoff
        ├── proofs.md        # written by check_proofs.py: every proof and mutation at HEAD
        ├── mutations.json   # the Verifier's mutations, re-run after the fix
        ├── screens.md       # the screens sub-agent's inventory and verdict, per picture
        └── verification.md  # the Verifier's findings, each closed by a commit

按需创建产物。 仅在对应阶段产生内容时才编写各个文件——不要预先搭建空的 context.md、design.md 或 tasks.md。如果跳过某个阶段，缺少对应文件才是正确状态。

工作流

新功能：

1. 规范 →（设计）→（任务）→ 执行（自动调整深度）

继续工作——新会话，或压缩之后：

1. 重新阅读本文件，然后阅读文件所指向阶段的参考文档。摘要会保留任务，而不是这些规则。
2. 阅读 .specs/STATE.md 中的 Decisions，以及该功能的文件——spec.md 和 tasks.md（其中的 **Approved**: 行、标记和 ## Handoff）、proofs.md、verification.md、screens.md——并根据 git 对照核实：证据优先于记录。各文件所指向的阶段见：memory.md。
3. 如果运行中途发生压缩，且文件与 git 一致，则继续；只有发生冲突时才停止。在新会话中，先提出核对后的下一步，再编写代码。

上下文加载策略

仅加载当前步骤所需的内容：

• .specs/STATE.md - Decisions 部分（在 Specify 和 Design 时读取；恢复工作时重新读取）；Handoff 部分（仅在恢复工作时读取）
• 已确认的经验 - 在 Specify 和 Design 时通过 python3 <skill-dir>/scripts/lessons.py list --status confirmed 加载（lessons.md）；仅加载已确认的经验，绝不加载候选项
• spec.md、context.md、design.md、tasks.md - 在步骤需要使用这些文件时加载

切勿一次加载多个功能规格或多份架构文档。

子 Agent 委派

**触发条件：**统计任务总数。如果该功能需要分成多个按任务预算划分的批次（> 约 8 个任务）→ 提议使用子 Agent；如果能放入单个批次（≤ 约 8 个任务）→ 直接执行。

先提议，后确认 - 绝不自动启动。用户必须接受后，才能派出任何批次工作者。

每个按任务预算划分的批次安排一名工作者（约 7 个任务，按完整阶段划分）： 阶段是语义和依赖单元；批次是执行单元——将一个或多个连续的完整阶段组合到约 7 个任务。按顺序遍历各阶段，将完整阶段累积到当前批次，直到达到预算，然后开始下一个批次——绝不将一个阶段拆分给多个工作者。每名工作者按顺序执行其所有任务（实现 → 门禁检查 → 原子提交），然后汇报简要摘要（已完成任务、提交哈希、测试数量、偏差）。各批次依次运行。工作者绝不再启动子 Agent。

验证器和界面截图子 Agent（始终启用，绝不征求同意）： 最后一个任务完成后，编排器运行 check_proofs.py，然后针对同一个 HEAD 并行派出验证器和界面截图子 Agent；验证器使用 validate.md，当某项标准引用了截图时，界面截图子 Agent 使用 verify-screens.md。每次派遣（包括批次工作者）都必须先写入 tasks.md ## Handoff 中的 **Dispatched:** 行，然后再派出，这样压缩后的编排器会等待，而不是重复派遣。所有发现的问题都必须在一轮内修复；第二轮执行 check_proofs.py --mutations，并让界面截图子 Agent 检查存在差异的行，在 screens.md 中写入 **Round**: 2。不得启动第二个验证器，也不得进行第三轮；仍未通过的项目交由用户处理。然后运行门禁检查，再记录经验（lessons.md）。

按角色选择模型层级（仅当运行环境支持为每个子 Agent 选择模型时）：机械性批次使用更快的层级，核心领域批次和 Design 使用高推理能力层级，验证器使用中高层级。评估标准见 sub-agents.md。

独立运行的回退方案： 如果没有子 Agent，则在最终提交后分别于新会话中运行 validate.md 和 verify-screens.md，并在报告中写入 self-verified；门禁检查会发出警告。

命令

功能级（自动调整规模）：

触发模式	参考文档
规划功能、定义需求	specify.md
讨论功能、记录上下文、讨论应该如何运作	discuss.md
设计功能、架构设计	design.md
拆分任务、创建任务	tasks.md
实现任务、构建、执行	implement.md
验证、核验、测试、UAT、带我逐步完成	validate.md
根据设计评估界面截图	verify-screens.md

记忆：

触发模式	参考文档
记录决策，这是项目级决策	memory.md
暂停工作、结束会话、我需要停止	memory.md
恢复工作、继续、从上次中断处接着做	memory.md
加载经验、我们学到了什么、应用以往经验	lessons.md
记录经验、提炼经验（在门禁检查后运行）	lessons.md

知识

你查到的事实、你询问后得到的决定。先查看代码库及其惯例，再查看项目文档和 .specs/STATE.md，然后查看库文档，最后查看网络。绝不编造 API、模式或行为：“我找不到相关文档”胜过看似合理的杜撰；任何无法确认的内容都要说明尚不确定。

要求

需要	用于	缺少时
Python 3.8+（仅标准库）	每个脚本	门禁无法运行；各阶段仍然适用
git	mutate.py 和 check_proofs.py（HEAD、干净工作树）	不执行变更，也不检查 HEAD；在报告中说明
子 Agent	批量工作者、Verifier 和 screens 子 Agent	在当前会话中运行；在新会话中验证并写入 self-verified
能读取图像的模型	绑定截图和 screens 子 Agent	请用户描述每种状态；将图片交给用户
Agent 能够操作的浏览器	浏览过程和截图	将步骤交给用户

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

输出行为

完成工作；不要叙述过程。 根据阶段产出正确的成果，而不是宣布当前阶段。用户会评判输出。

以朴素、明确的语气撰写生成的成果。 规范、决策、报告、提交消息和聊天摘要应遵循 coding-principles.md 中的写作规则：开头先给结论，明确陈述决定，删去填充语和模棱两可的表述。章节标题保留英文；正文遵循项目要求；标识符绝不翻译。