1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | create-architectural-decision-record-github-awesome-copilot(技能目录名 create-architectural-decision-record) |
| 作者/维护者 | GitHub 官方社区合集 github/awesome-copilot |
| 来源链接 | https://github.com/github/awesome-copilot/tree/main/skills/create-architectural-decision-record |
| 许可证 | MIT(合集仓库,GitHub API) |
| GitHub Stars / Forks | 合集仓库整体 39,929 / 5,098(GitHub API);该数字属整个合集,不代表本技能自身热度 |
| 技能自身热度 | skills.sh 记录安装量 10.1K(Gen Agent Trust Hub、Socket、Snyk 三项安全审计均为 Pass) |
| 最新版本 | 无独立版本号;2026-02-19 由 prompt 形态转换为 skill,此后未再修订 |
| 安装方式 | npx skills add https://github.com/github/awesome-copilot --skill create-architectural-decision-record,或复制该目录到 agent 的 skills 目录 |
2. 功能介绍与亮点
为一项架构决策生成一份结构固定的 ADR(Architectural Decision Record)文档:
- 输入四项:决策标题、背景、所选方案、备选方案与干系人;缺项时先向用户追问,再动笔。
- 输出带 front matter(标题、状态、日期、作者、标签、supersedes/superseded_by)的 Markdown,章节依次为状态、背景、决策、后果、备选方案、实施说明、参考。
- “后果”拆成正面与负面两栏,“备选方案”强制写明被否决的理由;各条目用
POS-001、NEG-001、ALT-001这类编码,便于机器检索与交叉引用。 - 文件统一存到
/docs/adr/,按adr-NNNN-标题-slug.md顺序编号。
3. 适用场景
所属分类:工程效率与代码质量。适合需要把“为什么选 A 不选 B”留档的开发者和小团队,尤其是还没有 ADR 习惯、想要一份现成模板和固定写法的初中级工程师;也适合让 AI 助手在讨论完技术选型后直接落成文档。
4. 跨 Agent 兼容性
| Agent | 结论 | 依据 |
|---|---|---|
| Claude Code | 原生支持 | 标准 SKILL.md(name/description),纯提示词无依赖 |
| Codex | 需适配 | 格式同为 Agent Skills 规范,但 Codex 不自动发现 ~/.codex/skills,需手动引用 |
| OpenClaw | 未验证 | 未做实机核验 |
| Hermes Agent | 原生支持 | Hermes 按路径扫描子目录探测 SKILL.md;无运行依赖 |
5. 推荐理由
ADR 的价值在于半年后还能说清当初为什么这么选。本技能把“背景、决策、利弊、被否决的方案”固定成一个必填骨架,并强制写出负面后果和否决理由,避免只记结论不记取舍;编号条目让文档之后易于被检索和引用。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | 出自 GitHub 官方社区合集;技能自身 skills.sh 安装量约 10.1K,三项安全审计通过,未见具名第三方评价 |
| 可用性 | 7 | 复制即用、模板完整;但模板使用 ${input:...} 占位写法,在非 VS Code 环境需靠追问补齐输入;转换为 skill 后未再修订 |
| 安全性 | 9 | 纯提示词,无脚本、无外联、无凭据;仅在 /docs/adr/ 写一份 Markdown |
综合 = 三项均值 = 7.67。
安全检查清单:① 执行 shell:无,只写文件 ② 联网外发:无 ③ 凭据:不需要 ④ 可疑指令:未发现 ⑤ 作者/组织信誉:GitHub 官方合集,经维护者审核合并 ⑥ License:MIT ⑦ 维护:2026-02-19 转换后未再修订,属内容稳定的模板型技能。
7. 跟同类 Skills 相比的优势
| 方案 | 定位 | 差异 |
|---|---|---|
| 本技能 | 单一职责:只生成 ADR 文档 | 模板固定、条目编码、强制写负面后果与否决理由 |
| addyosmani/agent-skills 的 documentation-and-adrs | 文档编写与 ADR 的综合指南 | 覆盖更宽(README、API 文档等),ADR 只是其中一部分,没有固定的编号条目模板 |
| 手写 Michael Nygard 式 ADR 模板 | 极简模板(背景、决策、后果) | 轻,但缺备选方案与负面后果的强制栏位,质量依赖个人 |
核心差异:本技能专做 ADR,结构比通用文档技能更严,比极简模板更完整。
8. 用户评价
该技能目前在第三方平台尚无具名用户评价;skills.sh 上有约 10.1K 次安装记录。
9. 其他补充
- 状态栏支持 Proposed / Accepted / Rejected / Superseded / Deprecated,可用 supersedes 字段串起决策链。
10. 安装使用方式
npx skills add https://github.com/github/awesome-copilot --skill create-architectural-decision-record
也可把 skills/create-architectural-decision-record/ 复制到 agent 的 skills 目录。安装后对 agent 说“为〈决策〉写一份 ADR”并给出背景、方案、备选与干系人即可触发。
11. 注意事项
- 输入占位
${input:...}是 VS Code 风格写法,其他 agent 会改为对话追问,属正常行为。 - 文件固定写入
/docs/adr/,已有不同 ADR 目录约定的项目需在对话中说明。 - 技能不会替你做决策,备选方案与取舍需由使用者提供事实。