SuperAPI AI 工具集

adr-records

通用与其它

查看项目

更新于 10-16 05:00

技能介绍

用途:维护架构上重要选择的决策日志,格式遵循 adr.github.io。适用场景包括用户要求 ADR 或决策日志、实施前遇到设计分叉或权衡、记录重大设计选择(技术栈、集成、安全、数据模型、部署)、更新 ADR 状态(accepted、deprecated、superseded)、使现有仓库对齐 MADR/Nygard 约定。

决策检查点:触发条件包括多个可行架构或工具(T1)、范围跨越北极星或仓库原型(T2)、不可逆变更如公共 API、模式、认证、难以回滚的迁移(T3)、新增同级仓库或 CI/注册表耦合(T4)、与已接受的 ADR 或章程冲突(T5)、安全相关如认证、PII、密钥、生产暴露(T6)、合并后回滚成本高(T7)、需要未声明假设(T8)。触发后应停止并询问,输出决策简报或状态为 proposed 的 ADR。

定位或初始化日志:依次查找 docs/decisions/、doc/adr/、docs/adr/、architecture/decisions/。若不存在则询问用户,除非用户要求创建。默认新日志位于 docs/decisions/,含 README.md 索引和 NNNN-title-with-dashes.md。可在根 README.md 或 CONTRIBUTING.md 添加一行指引。

编号与文件名:格式为 NNNN-kebab-case-title.md,四位零填充,下一个编号为现有最大编号加一,不得重复。可使用命令:bash scripts/next-adr-number.sh docs/decisions。

默认格式为 MADR bare 模板,必需部分包括 YAML frontmatter(status、date、decision-makers,已知时含 consulted/informed)、上下文与问题陈述、考虑过的选项、决策结果(选定选项及理由)、后果(好/坏/中性)、各选项利弊、更多信息。状态生命周期为 proposed、accepted、deprecated、superseded、rejected。替代格式为 Nygard 与 Y-Statement,需与仓库已有格式一致,未经批准不得混用。

编写流程:检查点、确认范围(一个 ADR 一个决策)、收集信息、草拟、加入索引、交叉链接、评审(后果必须包含缺点)。质量要求:具体、诚实、可追溯、简洁、不含密钥。创建 ADR 后告知文件路径、编号与标题、状态、索引是否更新及建议后续步骤。

安装:npx skills add arenukvern/skill_steward --skill adr-records。参考资料包括 decision-checkpoints.md、madr-bare-template.md 等。限制:资料未提供具体平台兼容性、收费或价格信息,暂未提供。