规划：先写 intent
动手之前，先被拷问一轮，再用一页纸写清做什么、为什么、约束、不做什么和成功指标，由你确认
任何实质改动，先写 intent：做什么、为什么、约束、不做什么、怎么算成功。它就是 spec 文件的第一节，写在 docs/specs/YYYY-MM-DD_<slug>.md 的开头。先让 agent 拷问你一轮把想法问清楚，再落成文字；你确认之后，才进入设计。
| 产物 | 人工关卡 | 衡量指标 |
|---|---|---|
| spec 文件的第一节：intent | 你确认 intent：要做的事、原因、明确不做的部分 | 从第一次对话到 intent 提交用了多久；提交后又被推翻了几次 |
为什么
agent 最常见的失败不是写错代码，而是做了你没想要的东西。Matt Pocock 把这叫作对齐失败（misalignment），他的解法是 grilling：让 agent 反过来拷问你，直到双方对要做的事有同样的理解。
Anthropic 的 Playbook 把 intent 放在第一招：一个短小、进版本控制的文件，说清要什么、为什么、在什么约束下。来源可以是一个想法、一张工单，也可以是一条告警。它衡量这一招的领先指标是“从第一次对话到 intent 提交的时间”，预期从几周的需求往返缩短到几个小时。
我没有单独建 intent.md，而是把 intent 写成 spec 的第一节：一个人既提需求又做设计，两个文件来回切没有收益；同一个文件从上往下读，就是从“为什么”到“怎么做”。
怎么做
先被拷问，再动笔
/mattpocock-skills:grill-me 我想给产品加一个按月导出账单的功能grill-me 把你的想法当成一棵决策树，一轮一轮地问：每一轮把当前已经能问的问题一次问完，每题都附上它推荐的答案，你回答“是”就等于采纳。查事实是它的事（读代码、查文档），做决定是你的事。直到所有分支都问过、没有默认假设遗留，才算结束。试用中
grill-me 只是手动调用的入口，背后是同一个 grilling skill，说一句“拷问我一下”也能触发。还在想“这件事值不值得做”的新方向，可以先用 gstack 的 /office-hours，它是 YC office hours 式的追问。业界做法
把结论写成 intent
让 Claude 按模板写 spec 文件的第一节，此时文件里只有这一节：
# 按月导出账单
## Intent
- 做什么：一句话说清
- 为什么：谁的什么问题，为什么是现在
- 约束：技术、合规、预算、时间
- 不做什么：明确排除的范围
- 成功指标：上线后看哪个数，目标是多少
- 待定问题：还没想清楚、留给设计阶段回答的
- 来源：想法、Issue 或告警的链接完整模板见 intent 模板。
人工关卡：你确认
逐条读，改掉 Claude 理解偏的地方，然后提交。确认的标准：
- 一个没参与对话的人只读这一节，能说出要做什么、不做什么
- 成功指标能量化，上线后真的看得到
- “不做什么”至少写了一条
- 待定问题列出来了，而不是被悄悄假设掉
Playbook 里这一关由产品负责人把守，产品负责人审改 agent 写的 intent 之后才提交。一个人做产品，这个人就是你。提交就是确认，git 历史会记下时间和每一次修改。
亲历：这本手册的需求是拷问出来的
写这本手册之前，我先让 Claude 用 Matt 的 grilling 拷问了我几轮，最后落成一张 8 行的决策表：性质（个人项目、直接公开）、读者优先级、语言、公开边界（两个组织都不点名）、流程引擎、网站技术、可信度标签、附带插件。后面的写作分工、页面取舍，都以这张表为准。
这张表里，边界类的决定和“做什么”一样重要：两个组织都不点名，不做工具大全，不写没验证过的做法。intent 里的“不做什么”写清楚了，后面才有依据拒绝那些顺手想加进来的东西。
什么时候可以跳过
一行级的小修复，比如改错别字、调一个常量，可以不写 intent，但也在提交信息里留一句为什么改。判断标准：这个改动将来需不需要有人回头理解它的来龙去脉。需要，就写。
常见坑
- 实质改动先留文档再动手：结果是对的，但没留 spec，事后没法审计、没法交接
- 对外内容先读权威文档：intent 里引用的外部事实，先读原文再写，别凭记忆
相关
- intent 模板
- spec 模板
- 上一步：第 0 步：起步
- 下一步：设计：从 intent 到 spec