决策笔记
明确区分用户拒绝、失败尝试、比较后未选择的选项、推迟事项和范围外事项。不要将它们一概视为永久不可行。
笔记不用于未解决的提案、完整的需求、实施步骤、任务进度或故障排除日志。将提案和实施计划保存在设计和计划文档中；在所属子系统文档中维护当前行为，并根据源代码进行验证。在笔记中维护长期理由；在其他地方总结并链接到它。
1. 决策与变更前搜索
在开始以下工作之前，请查阅适用的项目级约束、相关子系统文档和相关的笔记：
- 提出具体解决方案、确定行为或做出关键设计权衡。
- 修改相关实现或行为测试；对于跨子系统的工作，需涵盖相关接口和共享约束。
- 创建或更改决策记录；首先搜索同一主题的现有结论。
当用户询问历史、发现决策指针或出现冲突时，直接阅读相关记录。纯粹的拼写、格式和状态更新，如果不涉及已建立的约束，则不需要新的搜索。
按以下顺序定位和评估记录：
- 使用项目的 Agent 入口点找到实际笔记位置和适用的全局约束。使用子系统文档定位当前职责、契约、源代码、测试和相关笔记。一个子系统可能跨越多个包或仓库，一个笔记可能涉及多个子系统。
- 遵循链接，然后根据需要按问题、机制、解决方案名称和约束进行搜索。缺少链接、相应代码或匹配名称并不能证明没有相关历史。如果不存在子系统页面，则从可用材料和任务主题中定位相关上下文；不要提前创建空文档。
- 从标题、
Status、Scope和结论开始；在相关时阅读理由、替代方案和证据。优先选择当前有效的记录，然后根据相关性追溯历史。当重新考虑旧选项或当前指导不足时，直接搜索已归档的记录。根据所讨论的范围追溯取代关系；不要随意追踪一条链条直到其末端。 - 确认记录的适用性和当前事实。如果目录确实不存在，则继续；仅在首次需要记录时才创建它。读取失败或搜索无匹配并不证明没有历史。
在同一任务中，重用已验证且仍然适用的结果。当范围、关键前提或相关记录发生变化，或出现冲突时，重新检查受影响的部分。不要仅仅因为轮次或技能改变而重新扫描所有内容。
仅当旧选项的前提条件发生明显变化时，才主动重新提出它，并解释之前未被选择的原因、哪些条件发生了变化以及影响。如果用户明确更改了先前的决定，请遵循新指示，无需再次请求批准。常规的实施授权不会自动取消现有的拒绝或范围限制。
2. 决定是否创建记录
新的记录应满足以下所有条件：
- 结论已确定。 它已被采用、拒绝、推迟或范围受限，或者存在值得长期保留的失败结果和条件。未解决的提案和等待验证的假设属于设计文档和计划。
- 具有持久价值。 没有理由的话，未来的 Agent 可能会再次提出旧选项、重复有意义的失败尝试或意外更改重要的约束。仅仅重述当前行为不满足此阈值。
- 需要单独的记录。 已搜索相关历史，并且无法通过更新事实、添加证据或澄清范围来捕获信息。真正的决策变更需要根据取代规则创建新的记录。不要按日期、交付数量或替代方案数量机械地创建记录。
典型主题包括：非明显的子系统边界、接口或持久性和兼容性选择；重要的选择及未选择替代方案的原因；故意避免缓存或自动重试的原因；重要的拒绝或可能再次提出的推迟；有证据支持的长期失败结论或跨任务策略。
通常，不要为格式化、机械重命名、从代码和测试中可以理解的普通实现或修复、常规依赖升级、一般故障排除尝试、日志、TODO 或进度创建笔记。大小不是标准。如果工作使现有笔记不准确，则维护它；如果工作产生了满足阈值的新决策，则记录它。
如果没有需要保留的独特的长期价值，不要仅仅为了填充模板而创建记录。如果用户明确要求保留重要决策，请重用或创建适当的来源；不要默默丢弃它。
3. 及时记录真实结论
一旦重要结论明确，就要及时记录；不要等到完成、会话结束或提交批准。决策可能来自用户，或来自Agent在授权范围内做出的选择。记录不会增加批准步骤，尚未等待用户决策的权衡不能通过写笔记来解决。
在编写之前，请阅读 格式与示例。默认位置是目标项目中的 .agents/notes/YYYY-MM-DD-topic.md；优先选择现有的项目位置。每个文件一个决策主题，保持路径稳定。不要按状态或子系统将笔记组织到目录中。
- 保留标题、
Status和Scope。正文以结论、理由和权衡为中心；根据需要添加其他部分。正文默认使用英语，除非项目有统一语言。不要编造替代方案、要求固定数量或强制添加正面/负面结果标签。 - 说明每个结论的范围和条件。不要将已采用但未实现的目标描述为当前的实现、迁移或部署事实。设计和计划文档拥有实施进度。
- 如果缺少理由，请说明未提供或未记录。对于失败，保留其条件、结果和必要的证据或证据缺口；不要推断其永久不可行。不要仅依赖后续会话无法访问的聊天或临时输出。
4. 更新、取代和组织
| 状态 | 含义 |
|---|---|
active | 明确采用并在其声明范围内仍然适用；有效的拒绝和推迟也使用此状态 |
superseded | 整个范围已被一个或多个新决策所取代 |
retired | 没有任何内容仍然有效，并且没有新的决策完全接管它 |
状态不表示实施进度或候选解决方案的处理方式。如果事实、名称、路径或证据发生变化但决策不变，则更新现有记录。当核心选择或约束发生明显变化时，创建新记录。当证据失效时重新评估；不要自动更改决策。
在更改状态、取代决策、处理部分取代或恢复旧选项之前，请阅读 状态与取代。通过范围交叉链接新旧记录；在部分取代后保留剩余的约束。如果旧选项再次被采用，则创建新记录，而不是擦除中间的决策。
在归档、合并或删除之前，请阅读 保留与组织。默认情况下保留记录。逻辑归档不移动路径；合并不得抹去真正的决策变更；删除前，请迁移唯一信息并更新引用。仅组织受当前任务影响的记录；完整的清理必须在范围内。
5. 交付前检查
检查与此工作相关的记录和相关范围。即使没有创建新笔记，也要检查更改是否导致现有笔记不准确。
- 遗漏和重复： 重要结论和长期理由是否已保存？是否仅在对话中？现有记录是否已经足够？
- 真实性和证据： 不要将推荐描述为决策，将目标描述为当前状态，将失败描述为永久拒绝，将未选择的选项描述为禁止，或将推迟描述为实现承诺。准确说明未知、未提供和未验证的信息。
- 状态和范围： 范围和条件是否准确？部分取代是否保留了剩余义务？对于相同范围和条件，是否存在冲突的有效结论？归档是否隐藏了当前约束？
- 文档所有权： 更新受影响的子系统文档、设计、计划和笔记；每个源拥有其信息，其他位置链接到它。
- 链接和取代链： 能否找到必要的来源？能否在没有自链接、断开链接或循环的情况下按范围追溯结论？组织是否保留了唯一的理由、证据和有意义的历史参考？
- 验证： 运行项目中已可用的相关检查并审查其结果。如果未配置任何检查，则手动检查。不要自动添加依赖项、脚本、CI 或格式迁移。纠正发现的真实问题；不要编造内容。当相关内容未更改时，重用成功的结果。
通过格式检查并不能证明理由是正确、检索是完整的，或者实现遵循了决策。如果当前事实与记录冲突，请区分过渡安排、过时文档、不完整实现和实际冲突。纠正已确认的错误。如果关键判断仍不明确，请解释冲突并请求决策；不要覆盖新的用户指令或声称已完成。继续不依赖于答案的工作。
在添加、实质性更新、取代或组织笔记时，简要说明更改内容、原因以及任何差距，并提供链接。当没有相关内容更改时，不要发出固定的“未添加笔记”消息。
将代码、相关文档和笔记作为一个待交付项保持在一起。完成本轮的更改和检查并显示结果后，询问工作是否完成以及是否可以创建本地提交。如果用户提供更多反馈，请继续编辑。保存或验证笔记并不授权提交、推送或发布，也不要求提前提交笔记。