SuperAPI AI 工具集

ai-adr

编程与开发

查看项目

更新于 11-10 00:11

技能介绍

用途

维护项目的架构决策日志(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 承载。