by 运行时依赖
版本
初始版本：架构决策记录生成器，含分析工作流与 Nygard 模板
安装命令
点击复制技能文档
分析代码库或对话，生成 Architecture Decision Records（ADR）——结构化文档，捕捉技术选择背后的“为什么”，让后续开发者理解决策依据。
使用场景： “记录这个决策”“创建 ADR”“我们为何选 X”“记录架构决策”，或任何重大技术选择时刻。
什么是 ADR？
一份简短文档，记录一项重大架构决策：- 上下文
- 决策本身
- 备选方案
- 后果
ADR 形成决策日志，避免重复争论，帮助新成员快速理解代码库。
何时创建 ADR
- 选择框架、数据库或主要库
- 定义 API 契约或数据模式
- 制定团队规范（测试策略、分支模型、部署流程）
- 做出权衡（性能 vs 可维护性、单体 vs 微服务）
- 采用或弃用工具
- 任何可能让人日后问“为何这么做”的决策
分析步骤
1. 识别决策
从对话或代码审查中提取：- 决定了什么
- 时间（日期或 PR/commit 引用）
- 参与者（如已知）
2. 重构上下文
``bash
# 查看相关变更的 git 历史
git log --oneline --all --grep="" | head -20 # 查找依赖添加时间
git log --all --diff-filter=A -- package.json | head -5
git log -p --all -S '' -- package.json | head -40
# 在文档中搜索过往讨论
grep -ri "decision\|chose\|alternative\|trade-off\|migrate" docs/ README.md CONTRIBUTING.md 2>/dev/null
# 检查是否已有 ADR
find . -type f -name ".md" -path "/adr/" -o -name "decision" 2>/dev/null
ls docs/adr/ docs/decisions/ doc/architecture/ 2>/dev/null
`
3. 分析备选方案
针对框架/库决策：
`bash
# 查看评估过哪些选项
grep -ri "considered\|vs\|compared\|evaluated\|alternative" docs/ 2>/dev/null
git log --all --oneline | grep -i "try\|experiment\|spike\|poc\|prototype" | head -10 # 检查是否尝试过多种方案
git log --all --oneline --diff-filter=D -- '/package.json' | head -10
`
4. 评估后果
阅读当前实现，理解决策带来的助益与限制：
`bash
# 选择嵌入多深？
grep -rc "" --include=".{ts,js,py,go}" . 2>/dev/null | sort -t: -k2 -rn | head -10 # 是否有“后悔”痕迹？
grep -ri "hack\|workaround\|todo\|fixme\|technical debt" --include="*.{ts,js,py,go}" . 2>/dev/null | head -20
`
ADR 模板
采用 Michael Nygard 格式（行业标准）：
`markdown
# ADR-{NNN}: {标题 —— 简短名词短语}
Date: YYYY-MM-DD
Status: Proposed | Accepted | Deprecated | Superseded by ADR-XXX
Deciders: [姓名或角色] Context
描述促使决策的问题与动因。
说明技术约束、业务需求、团队能力、时间压力等。 Decision
用完整句子陈述决策。
“我们将使用 PostgreSQL 作为主数据库。”
“我们将采用 Turborepo 的 monorepo 结构。” Alternatives Considered
备选 A: [名称]
- Pros: …
- Cons: …
- Why not: …
备选 B: [名称]
- Pros: …
- Cons: …
- Why not: …
Consequences
Positive
- 决策带来的便利或新能力
Negative
- 变得困难、昂贵或被排除的选项
- 引入的技术债
Risks
- 可能出错的地方
- 何种条件下会重新考虑
References
- 相关 PR、issue、基准测试或外部资源链接
` 文件组织
标准存放路径（如不存在则创建）：
`
docs/adr/
0001-use-postgresql.md
0002-adopt-monorepo.md
0003-api-versioning-strategy.md
README.md # 所有 ADR 的一行摘要索引
` README.md 索引格式：
`markdown
# Architecture Decision Records
| # | Decision | Status | Date |
|---|----------|--------|------|
| 1 | Use PostgreSQL | Accepted | 2026-01-15 |
| 2 | Adopt monorepo | Accepted | 2026-02-01 |
``
提示
- ADR 保持简短——最多 1-2 页。太长说明决策过大，需拆分。
- 决策当下就写，别事后补。回顾式 ADR 会丢失“备选方案”上下文。
- 已接受的 ADR 不可修改。决策变更时，新建 ADR 并声明取代旧版。
- 按顺序编号。