记录决策
概述
决策是持久的基础设施；记忆和聊天历史不是。记录的成本只需支付一次，而丢失决策的成本则是每次有人从代码中逆向推导意图时都要支付。
记录结构
每个非琐碎的决策都会生成一个具有固定结构的记录，以便任何读者都知道去哪里查看：
| 部分 | 内容 |
|---|---|
| 架构 | 解决方案的形态和关键文件 |
| 数据模型 | 实体、字段、关系 |
| 决策（含WHY） | 每个选择及其理由——为什么是强制性的 |
| 接口 | 其他代码如何使用它 |
| 约束 | 必须保持成立的条件 |
| 陷阱 | 下一个人容易忽略的非显而易见的问题 |
| 被拒绝的备选方案 | 考虑过但被放弃的方案，以及原因——避免重新讨论已解决的问题 |
三个配套工件
- 一个索引：包含所有决策，带有明确的依赖追踪（哪个构建在哪个之上）以及一个被取代部分。将一堆记录变成一个可导航的图。
- 一个“未来考虑”文档：记录暂缓的想法和已知问题，在开始新工作时查阅，以确保不会无声无息地遗忘任何事情。事件行动项和带有触发条件的暂缓决策都放在这里。
- 一个存档：被取代的记录移动到这里，而不是被删除。历史被保留，而不是被覆盖。
快速参考
- 记录位置约定：
docs/superpowers/decisions/YYYY-MM-DD-<主题>.md，包含YAML前置元数据（title、date、component、status、supersedes、dependencies）。 - 未来考虑文档位于
docs/superpowers/future-considerations.md。每个条目都有一个状态（open/triggered/done/dropped），以及一个适用的触发条件，用于重新激活该条目。在开始新工作时查阅它。 - 前置元数据用于支撑自动生成的索引——请保持其准确。
- 理由和被拒绝的备选方案是两个价值最高的部分。没有它们的记录就是一个地雷。
- 在管道的记录阶段（参见
designing-before-building）编写记录，即在执行之后。
捆绑工具
此技能自带其脚本和模板，因此它们可以在安装该技能的任何仓库中工作。它们位于 SKILL.md 旁边：
recording-decisions/
scripts/doc-archive.sh 查找缺少决策记录的规格/计划
scripts/index-rebuild.sh 根据记录前置元数据重新生成索引
templates/decision-record.md
找到它们——该技能可以按项目或全局安装：
for base in .claude/skills ~/.claude/skills; do
d="$base/recording-decisions/scripts"
[ -d "$d" ] && echo "$d" && break
done
doc-archive.sh [specs_dir] [plans_dir] [decisions_dir] [archive_dir]
列出没有匹配决策记录的规格，并打印一个基于模板的转换提示。默认目录为 docs/superpowers/{specs,plans,decisions,archive}。
index-rebuild.sh [decisions_dir] [output_file]
根据每条记录的前置元数据重写 docs/superpowers/index.md——一个活动表（组件、标题、日期、依赖项）和一个被取代表（组件、标题、被…取代）。整个重新生成，因此永远不要手动编辑它。
两者都是无依赖的Bash脚本：使用该技能的项目不需要yq、jq或任务运行器。如果脚本缺失，上述过程是自包含的——直接手动完成工作。
为何这对上下文很重要
规格和计划故意写得很冗长；它们是供人类跟随推理过程而写的。每次Claude打开一个时，这种冗长都会消耗上下文。而决策记录只需大约30-50行就能保留下一步所需的内容——决策、理由、接口、约束、陷阱、被拒绝的备选方案——同时原始规格移到archive/，那里对人类保持可读性，且除非故意打开，否则不消耗上下文。
何时不要使用
琐碎的、不言自明的更改不需要记录。判断标准是：以后会有人问“为什么这样实现？”吗？ 如果是，就记录它。
完整理由：宪法第二条，捆绑在 engineering-constitution/references/engineering-constitution.md 中。