用途
维护项目的架构决策日志(ADR)。首次运行时建立日志目录,之后根据输入编写新的决策记录,或移动已有记录的生命周期状态。仅当用户显式调用 /ai-adr 时触发,不自动执行,也不允许智能体自行调用。
主要能力
- 建立日志:在项目没有日志时,创建
docs/adr目录,并在仓库根目录写入.adr-dir记录路径;同时生成索引README.md和一条“记录架构决策”的初始记录。 - 编写记录:每个决策保存为一个 Markdown 文件,包含上下文、决策和后果三个部分,按照参考格式规范编写。
- 生命周期流转:根据输入中的动词(accept/approve/ratify、decline/reject、propose、deprecate)和记录标识(文件名 slug 或标题),移动记录状态。合法转换规则为:提议(Proposed)状态下可自由编辑;接受(Accepted)或拒绝(Rejected)后,只允许 Accepted → Superseded 和 Accepted → Deprecated。
- 索引维护:在日志根目录的
README.md中按 Accepted、Proposed、Retired 分组列出所有记录链接。 - 代理上下文提示:首次运行时,可向根目录
CLAUDE.md添加一段用标记包裹的说明,指向日志路径,仅在用户确认后应用。
使用方式
通过命令行调用 /ai-adr "<决策描述>" 来编写新记录,或 /ai-adr <动词> <记录标识> 来移动记录状态。工具会读取 references/adr-format.md 和 references/voice.md 以确保格式与文风一致。日期通过 date +%F 获取,作者通过 git config user.name 获取;若未设置则询问用户。写入范围限于当前工作目录内,临时文件除外。
适用场景
适用于需要长期维护架构决策记录的项目,尤其适合希望由人工显式记录决策、避免智能体自动修改日志的团队。
限制
- 仅通过人类显式调用
/ai-adr触发,智能体不得自行调用。 - 不接受模糊的生命周期动词(如 adopt、confirm、sign off 等),仅识别明确列表。
- 对于已 Accepted 或 Rejected 的记录,拒绝非法的状态转换(如 Accepted → Rejected),并提示可选的合法操作。
- 如果记录中仍存在未解决的
— *(inferred)*标记,则阻止 accept 和 decline 操作。 - 不写入
.ai-skills.toml配置文件,日志路径仅由.adr-dir承载。