SuperAPI AI 工具集

adr

编程与开发

查看项目

更新于 10-26 17:11

技能介绍

adr 是一个用于编写、重写和删除架构决策记录(ADR)的技能,其文件存放于 design-docs/adr/,索引存放于 design-docs/ADR.md。技能的核心原则是:ADR 记录当前生效的决策,而不是历史提案;git 保存过去的措辞,目录树中只保留今天仍然成立的决策。主要读者是即将修改受决策约束代码的智能体,因此当前规则放在最前,被替换的内容不应出现在其上方。

【什么值得写 ADR】 技能规定,只有同时满足两个条件的决策才值得写 ADR:有一个可行的替代方案因可陈述的理由落选;并且没有该 ADR 时,未来的智能体很可能会撤销这个选择。不满足任一条件的决策不写 ADR;如果读者仍需要理由,则把它写成一条带理由的规则(约 30 词),放在拥有该项或模块的文档中,或放在 CLAUDE.md 中作为面向智能体的约定。ADR 应在决策做出后编写;仍开放的选项留在规划文档或对话中,ADR 目录不存放提案。理由必须来自证据(任务、用户原话、测量、issue);证据未给出的理由应写为 unknown 或按 issue 标注,不得推断。

【文件与标识】 ADR 文件路径为 design-docs/adr/<group>.<n>-<topic>.md。group 是记录该决策的规划倡议编号;不运行倡议的项目使用 group 1。新 ADR 取其组内最大编号加一;删除组内最后一个 ADR 会释放该编号,中间空缺保留。topic 命名 ADR 所回答的问题而非答案(例如 sync-transport 而非 sync-uses-websocket)。重写会更改标题但绝不更改文件名;范围变化的 topic 会被重命名,所有引用在同一变更中更新。引用 ADR 使用从仓库根开始的路径 /design-docs/adr/<file>,链接文本中包含编号。

【结构】 每份 ADR 从 ${CLAUDE_SKILL_DIR}/assets/adr-template.md 开始,依次包含:Header(日期、Governs 约束路径、Pinned by 测试、pending 行)、Summary(1 至 3 句)、Decision(完整句子表述规则及范围)、Why(选择背后的力量,每个事实最多一个决定性数字)、Consequences(代价与缺陷,每项一个量级)、Rejected(每个可能被重新提出的选项一行及否定它的事实)、Revisit if(重新开启决策的假设及信心)、History(最新在前,每条规则变更一行;新 ADR 没有 History 部分)。正文从 Summary 到 Revisit if 目标不超过 65 行,达到 100 行时应考虑拆出第二个决策,超过 150 行应在提交前拆分或删减;History 不计入这些限制。

【ADR 中绝不允许的内容】 不允许 Revised 块、Amendment 章节、“(revised below)” 标记或新旧规则对比句;不允许 Status 行或 supersedes、superseded by、amends、extends 行(树中每份 ADR 均生效,pending 行是唯一状态);不允许编号列表(除非顺序本身是列表要表达的内容)或按位置引用条目;不允许增量表、样本统计超出那个决定性数字、带范围或机器负载的成本运行记录;不允许对代码库当前状态的计数(测试、文件、声明数),因为它在下一次变更后即失效;不允许重述另一份 ADR 的规则,应链接该 ADR。

【修改决策】 技能用一个测试判断所有变更:该 ADR 回答的问题是否仍需要自己的答案?如果是且答案更新,重写 Summary 到 Revisit if 并增加一行 History,删除被替换的措辞;如果另一份 ADR 回答了它,把仍决定的内容移入该 ADR,在那里增加 History 行并删除本文件;如果它不再值得写 ADR,把它作为一条带理由的规则移到拥有它的位置并删除文件;如果问题已不需要答案(受约束代码已删除或所命令的变更已完成),删除文件。删除 ADR 的提交需说明它退役了什么、为什么、内容去了哪里。不改变规则的变更(措辞修正、链接、路径重锚)不增加 History 行。合并、降级、删除 ADR 以及按任务重写 ADR 无需询问,但需在变更摘要中逐一命名。只有在有证据表明决策被有意更改时,才重写 ADR 以匹配代码;否则应修复代码,或用 pending 行标记差距并报告。当任务与 ADR 冲突时应停下询问:逆转决策由用户决定,执行逆转由智能体负责。

【待实现状态与索引】 代码尚未满足其规则的 ADR 在 Header 中携带 pending 行(如 Implementation: pending — <代码尚未做到的事>(issue 或 not scheduled))。完成实现的变更在同一提交中把 ADR 更新为实际构建内容并移除该行。design-docs/ADR.md 列出所有 ADR 并被导入项目 CLAUDE.md,使每个会话都持有它。索引从 ${CLAUDE_SKILL_DIR}/assets/adr-index-template.md 创建,并在 CLAUDE.md 中添加 @design-docs/ADR.md 导入。每个 ADR 在索引中占一行:- <group>.<n> <title>,按区域(## <path>)分组,区域按路径字母顺序、行按编号排序。

【变更后的状态要求】 涉及 ADR 或受 ADR 约束代码的变更需使仓库处于以下状态:没有文件链接到不存在的 ADR 路径;每个 Governs 路径都存在;没有 pending 行指向已完成的变更;每份 ADR 恰好有一行索引且编号、标题、区域匹配;同一组内没有两份 ADR 共享编号。技能还提到与 alignment 技能的关系:alignment 在规划倡议中确定决策并交给本技能,本技能拥有 ADR、其格式、编号和索引。

【限制】 资料未提供该技能的安装命令、收费模式、支持平台或官方发布渠道等信息,暂未提供。