11 · 决策记忆
Agent Note、复盘与升级指南
关键文件
.agents/notes/README.md.agents/notes/AGENTS.mdscripts/agent-note-tree.tsdocs/postmortem/docs/upgrade-guide/模型不记得上一次会话为什么这样决定，所以理由必须写进仓库。仓库把这类文件称为 Agent Note，相当于由 Agent 撰写的 RFC：记录"为什么"和"放弃了什么"，这是代码和文档承载不了的部分。
{lifecycle}/{class}/yyyy-mm-dd-topic.md。完全被取代的已实现 Note 可以合并进新的 owner 后删除，前提是保留所有独有的理由、备选方案和验证要求。部分取代时两条都保留并互相链接。什么时候写，写什么
- 只为持久的决策理由写。代码、测试和现有文档解释不了的才写。机械性和局部改动（包括局部 UI 调整）不写，这一条本身就在防止模型过度产出文档。
- class 是封闭集合：feature、bug-fix、simplification、architecture、process、testing，由
scripts/agent-note-tree.ts定义。refactor 被刻意排除，因为它与 simplification 重叠。 - 固定格式：提案要有 Problem、Proposal、Alternatives considered、Acceptance criteria、Risks；
verify-agent-note-format检查表头和章节。 - 每个新 Note 都要做取代检查：搜索已有 Note 是否覆盖同一决策，用
dsh-archive-agent-notes分类处理，同一 PR 里完成归档。 - 已实现的 Note 跟随代码：代码移动文件、改包名、换默认值时，在同一改动里更新 Note 的事实部分。Note 不能被改成另一个决定；要换决定就写新 Note 取代旧的。
- 归档即冻结：
archived/下的文件永远不改，也不当作现行依据。verify-archived-agent-notes用哈希清单强制执行。
复盘与升级指南
docs/postmortem/ 是唯一允许写事故经过的地方，记录事件顺序、证据、因果链、影响和预防措施。目前有四篇，例如 0001 记录了 ACP 插件的默认导出导致 Loader 丢弃 inject，这一事故直接产生了 packages/AGENTS.md 的插件导出规则和对应的测试断言。
外部可感知的破坏性变更（CLI、profile、配置键、持久化数据、SDK 或协议、包入口）必须立刻写进 docs/upgrade-guide/v<版本>/<条目>/guide.md，格式由 verify-upgrade-guides 检查。