tlc-plan

TLC 计划

持续提问，直到没有任何决定需要构建者作出。把内容写下来，让陌生人也能据此构建。

┌─────┐   ┌───────┐   ┌──────┐   ┌─────────┐
│ ASK │ → │ SHAPE │ → │ CHECK│ → │ APPROVE │ → tlc-implement
└─────┘   └───────┘   └──────┘   └─────────┘

编码 Agent 常见的失败，是某项要求从未成为义务，之后却声称已完成。问题从这里开始：计划靠猜测敲定的灰色地带、被当作建议的截图、请求中无处落实的一句话。这项技能会产出唯一一份人类能在代码写出前阅读并提出异议的文档；它是构建者的完整需求说明，而构建者往往是对这段对话一无所知的另一个 Agent。

规则

1. 每条验收标准都是一个可观察的结果，带有具体值——状态码、字段、边界、标签——一次运行即可判定。“优雅地”、百分位数或“这些列存在”都不算验收标准。
2. 提交计划前，先询问每个灰色地带：这是用户需要作出的决定，有多个合理答案，且代码中尚无定论。绝不以假设代替问题来省事。提问是为了明确如何添加能力，而不是是否添加能力。
3. 请求中附带的截图、帧或线上站点均具有约束力，除非用户称其仅供参考。只有用户可以更改具有约束力的来源：如需偏离，必须先询问，将决定记为 .specs/STATE.md 中的 AD-NNN，并列入 ## 与来源的差异。
4. 会改变用户所见内容的规则，必须在仓库测试能够覆盖的层中运行。筛选、搜索、排序和计数都属于规则。
5. 这里只决定难以撤销的事项，并明确其具体形式。符合约定的内部位置、名称和类型由构建者决定，并在差异中敲定。
6. 提交计划前，validate_plan.py 必须以状态码 0 退出；人工审核是唯一的停靠点。批准信息须写在计划标题下，格式为 **Approved**: <date> - user: "<their words>"，且绝不能写入用户未提供的话。每条答复都要在收到答复的当轮写入计划：上下文压缩会保留文件，而不会保留聊天记录。在此之后，或在新会话中，重新阅读此文件和计划引用，然后从 plan.md 继续。构建过程中计划须保持准确：Landing、Surface 和数据均为增量添加；路径和 Changes underneath 则在更改它们的提交中更新。

划分：需要多少份计划

完整阅读每个来源，然后决定拆分成多少份计划。默认一份。这样所有单向门都能一起审查，彼此之间的影响也一目了然；若拆成六份，同样的单向门会分六批出现，没人能看到全貌。

只有在证据足以支持的理由下才拆分：某部分若不等另一部分就无法上线而不影响生产；某部分等待只有他人才能给出的答复；或某部分属于另一个团队。此时，每个部分都应有自己的功能文件夹和计划。

如果规模很大，要说明大在哪里：先列出单向门，再列出其中的迁移，然后说明拆分数量。展示现有的衔接关系——先列出顺序约束，并标明哪些不能合并——再由用户选择拆分位置。

计划中的一个切片，是某人能够观察到的一个结果，绝不是某个层。无法独立证明任何结果的准备工作——如可空列、没有调用方的客户端——属于提交，不是切片。

产物

.specs/
├── STATE.md                    # decisions log (AD-NNN)
├── LESSONS.md                  # rendered by scripts/lessons.py - read it
└── features/<feature>/
    ├── plan.md                 # problem, shape, surface, doors, criteria
    └── captures/               # the binding source files

计划格式、提问方式、界面巡查和 EARS：references/plan.md。其章节标题是 tlc-implement 和验证器读取的模式；正文遵循项目使用的语言，标识符绝不翻译。

Decisions and lessons

.specs/STATE.md 保存未来功能必须遵循的决策：

# Project state

## Decisions

| ID | Decision | Rationale | Status | Date |
| --- | --- | --- | --- | --- |
| AD-001 | Webhook ingest is idempotent on provider delivery id | replays are routine and cheap to dedup at the edge | active | 2026-02-14 |

仅编辑 ## Decisions 的正文。如果仓库已有 ADR 或决策日志，则追加到那里。每条 active 条目都会约束计划：要么遵循，要么追加一条取代它的决策（旧行的状态变为 superseded by AD-NNN），并说明原因。偏离约束性来源的回答就是一项决策：它说明产品实际会显示什么，并在理由中引用问题和所选选项。

tlc-implement 根据实际验证结果记录经验教训。提出任何问题前，先阅读该领域已确认的经验教训：

python3 <skill-dir>/scripts/lessons.py --root <project> list --status confirmed [--scope <area>]

Scripts

将 <skill-dir> 解析为包含此 SKILL.md 的目录。如果当前工作目录不是项目根目录，则传入 --root。运行脚本，不要阅读脚本：脚本的消息会说明需要更改什么。

When	Command
在展示计划前，以及每次修改计划后	python3 <skill-dir>/scripts/validate_plan.py <feature>
提出任何问题前	python3 <skill-dir>/scripts/lessons.py --root <project> list --status confirmed
编辑验证器或模板后	python3 <skill-dir>/scripts/selftest.py

Requires

Needs	For	Without it
Python 3.8+（仅使用标准库）	脚本	计划仍然适用；说明验证器未运行
能读取图像的模型	约束性截图	请用户描述每个状态，并在 Sources 中说明
访问设计源文件（文件、MCP、URL）	将每个状态导出到 captures/	通过 blocks 问题索要文件

Output

生成成果；不要叙述阶段过程。停止时，先给出结论：计划、优先列出阻碍推进的问题并给出建议，然后列出你选择的默认项，供用户更正。章节标题保持英文。