SuperAPI AI 工具集

documenting-decisions

编程与开发

查看项目

更新于 11-03 16:18

技能介绍

用途

该技能用于把设计与规划过程中形成的架构决策,整理为可长期查阅的架构决策记录(Architecture Decision Records,ADR)。ADR 以统一格式记录决定了什么、依据是什么,以及曾考虑过哪些替代方案,为后续工程师提供历史背景。

主要能力

  • 读取设计文档,提取问题陈述、选定方案、替代方案与权衡取舍。
  • 将提取内容展示给用户确认,以用户确认结果作为 ADR 内容的权威来源。
  • 确认决策状态:Accepted(默认)、Proposed、Deprecated、Superseded;若为 Superseded,还需提供替代它的 ADR 编号与标题。
  • 扫描 docs/decisions/ 下已有 ADR 文件,确定下一个四位顺序编号(无文件时从 0001 开始)。
  • 按固定模板生成 ADR 文件,路径为 docs/decisions/NNNN-kebab-case-title.md,标题转为 kebab-case 作为文件名。

使用方式

可将设计文档路径作为参数传入。路径须为项目目录内的相对路径,技能会拒绝绝对路径(以 / 或 ~ 开头)以及包含 .. 段的路径;路径无效时会提示用户提供 docs/ 下的相对路径。若未提供路径,技能会按 docs/plans/*-design.md 查找最近的设计文档并让用户选择;若不存在设计文档,则请用户直接描述决策。

过程包括:识别设计文档、提取决策内容并请用户确认、确定状态、确定顺序编号、必要时创建 docs/decisions/ 目录、生成 ADR 文件并确认完成。

技能在 RPI 工作流中的位置为:/rpikit:brainstorming → /rpikit:writing-plans → /rpikit:documenting-decisions → docs/decisions/NNNN-.md。设计文档(-design.md)与规划文档(*-plan.md)是主要输入。

ADR 模板

生成的 ADR 使用以下结构:标题为“# NNNN. Decision Title”,包含日期(YYYY-MM-DD,为 ADR 创建日期而非决策日期)、状态、Context(问题与背景)、Decision(决定了什么及理由)、Consequences(分 Positive 与 Negative 两个子节)、Alternatives Considered(每个替代方案单独一节并说明未被选用的原因)。标题编号与文件编号一致。

状态生命周期

Proposed → Accepted → Deprecated,Accepted 也可转为 Superseded by NNNN。Superseded 状态需渲染为指向替代 ADR 的链接:Superseded by NNNN。新 ADR 取代旧决策时,应在 Context 中引用旧 ADR。

适用场景

  • 头脑风暴或规划中已作出设计决策。
  • 需要为架构选择留下长期记录。
  • 需要记录为何选择某方案而非其他方案。
  • 既有决策被取代或废弃。

限制与不适用场景

  • 决策过于琐碎(如格式、命名约定)时不应使用。
  • 未考虑任何替代方案时不适用。
  • 临时性或实验性变更不适用。
  • ADR 应记录架构决策而非实现细节,例如不应记录“在登录表单中用 React hooks 管理状态”,而应记录“选择客户端状态管理而非服务端会话”。
  • 必须记录被考虑的替代方案及被否决原因,否则失去 ADR 的价值。
  • 后果描述须具体,避免“可能会有问题”这类模糊表述。
  • 若决策未经结构化评估即已作出,应在 Context 中如实说明,而非事后合理化。

暂未提供

该技能的收费、价格、平台支持范围及运行环境要求,资料中暂未提供。