Agent 笔记
Agent 笔记保持决策体量精简且权威：每条笔记仅记录代码和文档无法承载的设计理由，除此之外不记录任何其他内容。布局、分类和文件内格式规则位于 .agents/notes/README.md；本技能负责管理其工作流程。根据语义判断每条笔记；字数和使用时间是发现辅助手段，而非判断标准。此为指导原则，而非清单。
判断是否需要笔记
仅在需要记录持久的决策理由时才编写或更新笔记：为什么某个设计方案胜出、它牺牲了什么、哪些备选方案落败及其原因、以及哪些验证锚定了该决策。不要为机械性或局部性修改（包括本地 UI 呈现变更）、或属于代码、API 文档、README 或操作手册的事实编写笔记。
- 针对重大未来工作的提案应放入
proposed/<class>/；当前变更中做出的决策放入implemented/<class>/。 - 如果一条活跃的笔记已经涵盖了该决策，则应更新它，而不是创建重复内容。
- 对某个决策的逆转是一条新的笔记，需要交叉链接旧笔记；切勿将一条笔记编辑为不同的决策。
编写笔记
- 从
.agents/notes/README.md的表格中选择分类，并以yyyy-mm-dd-topic-title.md格式命名文件，日期使用该主题首次被提议的日期。 - 使用 README 中确切的标题和生命周期的章节框架。
## Alternatives considered是必填项：记录每个真实的备选方案及其落败原因；切勿虚构备选方案。 - 将已实现的笔记以现在时写成已交付的现实：不包含计划、验收清单或“应该”之类的词。保留锚定行为的验证信息以及任何已命名的覆盖缺口。
- 使用相对 Markdown 链接链接其他笔记和文档。遵循 prose-standard 和 trim-cot-leakage：不包含审查流程、会话引用或笔记自身变更历史章节之外的变更叙述。
检查每条新笔记的替代关系
在起草之前，搜索活跃树（proposed/、implemented/、rejected/）中涉及相同决策、机制或被否决备选方案的笔记。在编写新笔记时对每个匹配项进行分类：
- 完全替代一条已实现的笔记： 合并（新笔记保留所有独特的理由、备选方案、后果、验证和覆盖缺口，然后删除旧笔记并修复入站链接）或在同一变更中将其归档。
- 部分替代： 两条笔记都保持活跃，相互交叉链接，并更新所有仍保持当前状态的事实。
- 过时的提案： 将其移至
rejected/，并附上诚实的单行理由。 - 过时的拒绝： 当它不再阻止一个可能的错误时将其删除。
不要将已知的匹配项推迟到以后的审计中。
按未来价值对现有笔记进行分类
在审计或精简时，根据生命周期应用以下结果：
- 已实现，删除： 仅描述小的 UI 调整或纯机械性变更的笔记。修复或删除入站链接。本地错误修复、性能变更、新能力以及实质性行为或所有权决策，不能仅因其实施规模小而被归为此类。在判断保留或归档之前先应用此测试。
- 已实现，保持活跃： 理由、备选方案、否定保证、持久或线缆语义、所有权边界、安全规则或恢复条件等可能指导未来变更的内容。根据决策本身分类，而不是其实施规模：即使是机械性重命名，也可能记录持久的命名或兼容性规则。
- 已实现，归档： 一个完整的、不太可能指导未来工作的实质性历史决策，但其理由仍值得保留。
- 提议，永不归档： 保持一个活跃的提议；如果它不再值得推进，则用诚实的理由将其拒绝。
- 已拒绝，仅作为护栏保留： 仅当失败的提案仍然是一个诱人的、有意义的错误，并且笔记解释了它为何失败时，才保留一条拒绝记录；否则将其删除。
不要为了达到某个配额而归档。检查范围内的每条笔记，将类似的笔记按一个原则分组分类，并为真正的边界情况记录到报告中。
校准：一条关于折叠侧边栏控件样式的笔记无论多长都应删除；一条确定会话是事件溯源、或指定存储目录的唯一所有者的笔记无论多短都应保持活跃；一条记录为什么两个包不能合并的笔记，只要合并它们仍然有诱惑力，就应作为护栏保留。
归档一条已实现的笔记
- 将完整的笔记及其任何翻译版本，从
implemented/<class>/移动到archived/<class>/。 - 不对正文进行编辑。在每个语言文件的
Status: implemented下方立即插入Archived: YYYY-MM-DD，日期相同。 - 搜索活跃内容中的入站链接。将它们重定向到当前权威源，只有当有意引用历史快照时才将链接目标改为归档路径，或者删除这些链接。切勿验证或修复已归档笔记中的链接。
归档后，永远不要编辑、移动、翻译、重新格式化或删除该笔记。归档笔记仍然是有效的链接目标，但不是当前行为的权威依据。
验证和报告
运行配置文件的 commands.docs-check 和 git diff --check，并确认所有更改过的相对链接都能解析。报告创建或更新的笔记、保持活跃、删除、归档或拒绝的笔记，以及每个带有所选结果的边界情况。