SuperAPI AI 工具集

decision-record

办公与效率

查看项目

更新于 10-16 01:31

技能介绍

用途:为设计系统选择创建结构化决策记录(ADR),涵盖组件决策、令牌架构、工具选型、治理策略,以及任何值得记录、以免未来贡献者反向推断理由的决策,包括被拒绝的提案(状态标为 Declined)。

开始前:核对本技能 frontmatter 中 references 的每个路径是否相对 SKILL.md 存在。若缺失则停止,说明安装不完整(常见于扁平化安装器丢掉仓库根的 knowledge-notes/ 目录),让用户按 1-INSTALL.md 重装并在安装根运行 verify-install.sh。仅在用户明确同意下继续,并在输出中注明未使用该参考材料。

主要能力与流程: 1)决策触发清单:影响多个消费团队、存在合理分歧的取舍、会被未来贡献评审引用、改变命名约定/令牌架构/API 契约、废弃或移除系统内容、有人问过且未记录、同一问题反复出现,满足任一即应写记录;仅影响单个组件内部实现、易回退无消费方影响、遵循既有约定时可不写。存疑时写。 2)查找团队已有记录:docs/adr/、docs/decisions/、adr/、decisions/、.adr-dir(adr-tools)、MADR 模板、log4brains 配置或用户指定的文档平台。有则沿用其分区名与编号(通常顺序 NNNN- 前缀,取下一个号);没有则用 docs/decisions/NNNN-<kebab-title>.md 从 0001 开始并说明。不要自创按日期的编号。 3)澄清决策:确认决定了什么(一句话)、何时决定、谁参与、已完成还是进行中、考虑过哪些选项及各自被否原因,来自用户或链接来源(会议记录、PR 讨论、RFC)。进行中的决策也写,状态标为进行中。 4)写记录:只记录用户给出或来源中出现的选项、理由与取舍。缺失处写 [unknown — ask X] 并注明谁知道;绝不推断理由,因为无人真正提出的合理解释比可见空白更糟。结构含 ID、Date、Status(Proposed / Accepted / Declined / Superseded / Deprecated)、Deciders、Author、Context(当时真实处境与约束,不把背景写成结论必然)、Decision drivers(3–5 个来自用户或来源的力量)、Options considered(真正评估过的选项及未选原因,选中项也列出并前向引用)、Decision(一句话加两三句主因,坦白已接受的取舍与非技术因素)、Impact assessment(仅当改动组件 API、令牌名或值或需消费方迁移时;按表列出受影响文件数、组件、消费团队、迁移工作量、令牌/API 变更数、是否破坏性变更、全面采用时间;可用搜索填充数量,未测量写 not measured 并指出可测量的审计技能,估算与时间线仅当用户提供并标明)、Consequences(意图结果与已知风险)、Supersedes / superseded by、Related records。 5)写文件:按第 2 步的位置与编号写入并说明路径;团队用文档平台则在对话中产出供粘贴并说明归属;位置未知且用户未说时只问一次,不要默认只留在对话里。 6)建议复审触发条件(一句话即可,如工具变更、团队规模阈值、依赖版本、时间里程碑)。 7)在对话中总结:标题(决策、状态、写入文件)、所有遗留的 [unknown — ask X]、后续可用的技能(如 deprecation-process、token-audit、version-bump-advisor、change-communication、governance-encoder、codemod-generator、stakeholder-brief)、读取的来源与影响计数出处。

质量检查:格式与编号匹配团队现有 ADR 并写入仓库或产出给平台;决策驱动因素齐全且可追溯;背景写实际处境;选项反映真实决策空间;一切可追溯、空白标注;决策部分写明已接受的取舍;后果覆盖意图与风险;面向未在场者写作;状态正确;含复审触发条件。

限制:本资料未提供具体收费、价格、平台支持范围或效果数据;也未给出可复制的安装命令细节,安装方式需参见 1-INSTALL.md。