| name | write-decisions |
| description | 记录架构决策(ADR)。触发条件:(1) 艰难选择——在方案间纠结、选了A但B也有优势、知道有副作用 (2) 重构/重大修改后——改了3+次才定方案、每次改有新考虑 (3) 奇怪代码——被问"为什么这样写"、审查被质疑、自己回看也觉得奇怪 (4) 用户做出重大决策或出现决策疑问 |
执行流程
- 按 check-list 逐项确认
- 满足条件才创建决策文档
- 复制决策文档到项目级 + 全局级(内容相同)
- 更新 index.md 和 user-design-summary.md(两个位置各自维护)
Check-List
决策必须满足以下全部条件才创建:
决策不需要创建的场景:
- 只是执行常规操作,没有权衡
- 问题有唯一解,不存在替代方案
- 用户只是询问信息,没有做决策
触发场景
以下 3 个场景满足 checklist 条件时,必须触发写入:
场景 1:艰难选择
标志:在两个方案间纠结了很久;选了 A 但 B 也有明显优势;知道选择有副作用。
行动:决策完成后立即写 ADR,记录考虑了哪些方案、为什么选这个、有什么已知限制。
场景 2:重构或重大修改后
标志:改了 3+ 次才找到合适方案;每次改都有新的考虑;最终方案看起来不是"最直接的"。
行动:重构完成后写 ADR,记录演进历史(为什么改了 3 次)、每次改解决了什么问题、当前方案的权衡。使用 decision-template.md 中的"演进历史"节。
场景 3:看起来奇怪的代码
标志:新人或 AI 问"为什么这样写";代码审查时有人质疑;自己回看代码时也觉得奇怪。
行动:补写 ADR,使用补写模式(见下方)。
补写模式
对于场景 3(看起来奇怪的代码),使用简化流程:
- 跳过"问题界定"和"可选方案"的完整分析
- 重点记录:为什么这样写、尝试过什么方法、为什么其他方法不行
- frontmatter 的 abstract 直接说明"补记:解释为什么代码这样写"
信息来源规则(Not To Do)
决策内容必须基于:
- 用户在对话中明确表达的判断、偏好、选择
- 用户指定的文档、spec、设计稿
- 对话中讨论过的方案对比和权衡
决策内容禁止基于:
- 代码实现本身(代码可能由其他 AI 编写,不代表用户意图)
- 代码注释或 commit message(可能是 AI 生成的)
- 项目中已有的实现方式(不代表这是用户的决策,可能只是 AI 的选择)
如果用户没有指定文档,且对话中没有足够信息推断决策依据,必须向用户确认,不能自行推断。
决策文档存储
决策文档是独立文件,复制到两个位置,内容完全相同:
| 位置 | 路径 | 用途 |
|---|
| 项目级 | docs\ADR\YYYY-MM-DD-{具体内容}.md | 团队和 agent 参考 |
| 全局级 | D:\desktop\quackDocs\my_notes\my-decisions\YYYY-MM-DD-{具体内容}.md | 跨项目积累 |
写入后更新对应的 index.md:
- 项目级:
docs\ADR\index.md
- 全局级:
D:\desktop\quackDocs\my_notes\my-decisions\index.md
全局级 index.md 格式:
| YYYY-MM-DD | 决策标题 | decided\undecided | 项目名 | [详情](YYYY-MM-DD-{具体内容}.md) |
项目名从当前工作目录的文件夹名推断。
如果全局目录不存在,创建它。
决策文档编写
使用模板:references\decision-template.md
模板中的各节按需保留,无内容的节直接删除。
User Design Summary 编写
使用模板:references\user-design-summary-template.md
User Design Summary 是聚合文档,两个位置各自维护(链接格式不同,条目可能不同):
| 位置 | 路径 | 链接格式 |
|---|
| 项目级 | docs\ADR\user-design-summary.md | [决策标题](.\YYYY-MM-DD-{具体内容}.md) |
| 全局级 | D:\desktop\quackDocs\my_notes\my-decisions\user-design-summary.md | [决策标题](YYYY-MM-DD-{具体内容}.md) |
编写原则:
- 以批判性视角记录,不迎合用户观点
- 记录用户决策的判断方式,而非决策内容本身
- 如果认为决策不太可取,明确说明风险,让后续 agent 不要盲目参考
- 两个位置都必须更新,注意链接格式差异