adr-skill

架构决策

对于有重要备选方案或后果、需要长期记录的架构选择，请使用 ADR。常规修复和已有成熟做法无需新建 ADR。更改受其约束的代码前，请查阅相关的已接受记录。

记录决策

阅读项目说明、现有决策索引、相关记录、依赖项和受影响的代码。沿用现有惯例。在 Brain 树中，使用 .svx 编写正文。

从请求和来源中提取意图。仅在缺少的决策会妨碍准确记录时才提问。记录已确定的决策无需事先访谈或确认环节。尚未获批的选择应保持 proposed 状态；不要仅仅因为它在队列中排名第一就接受它。

记录触发原因、约束、考虑过的备选方案、选定方案、后果、非目标以及重新审视的条件。区分用户的决策和 Agent 的建议。

编写与验证

使用模板变体选择 assets/templates/ 中的简单模板或 MADR 模板。如果实现工作属于范围内，请包含受影响的路径、模式、实施步骤和可观察的验证结果。只列出该项工作实际需要的技能。

起草后阅读审查清单。根据来源修正事实和完整性方面的缺漏。对于尚未解决且影响重大的选择，要提出询问；不要纠结于常规编辑。仅在有助于阐明架构时添加图表；调用任何工具或斜杠命令前，都要先确认其有效性。

将 ADR 链接到受其约束的代码和实施凭证。在相关边界处添加简短的代码引用即可。在适用时，更新现有索引和可视化链接。

完成的标准是：记录准确说明决策及其状态、来源、后果、实施边界和验证情况。报告尚未解决的缺漏，不要凭空捏造接受决定。

生命周期

对于接受、拒绝、弃用或取代，遵循用户授权和项目的状态惯例。保留历史记录；取代其他记录时，双方都要添加链接。只有在检查实现并记录验证结果后，才能标记为已发布。

除非请求中明确包含，否则创建跟踪项和实施属于分开的操作。选择下一条 proposed ADR，并不代表获准接受或执行它。

对于现有的 JoelClaw ADR 存储库，同步事件为 system/adr.sync.requested，来源为 adr-skill；发出事件前，请验证当前负责处理该事件的处理器。其他情况请使用项目自身的索引路径。本地草稿并不意味着要进行无关的全平台同步。

工具与参考资料

使用前先阅读最新帮助：

• scripts/new_adr.js：从模板创建记录，并可选择更新索引。
• scripts/set_adr_status.js：更新记录状态。
• scripts/bootstrap_adr.js：按请求初始化 ADR 惯例。
• ADR 惯例：命名、状态和生命周期。
• 示例：已完成的记录。

如果请求搜索下一条 ADR，请检查 joelclaw vault adr --help。根据准备程度和价值对候选项排序，然后验证它们是否已发布。