mcpField
A
adr-architecture

adr-architecture

github.com/lyndonkl开发187115 次安装9 周前更新
代码仓库

关于 adr-architecture

adr-architecture 是用于编写和审查架构决策记录（ADR）的技能，适合负责技术选型和架构变更的团队。它提供从梳理决策背景、记录备选方案与权衡，到质量检查和归档的流程。

主要功能

  1. 01梳理决策背景与约束
  2. 02选择 ADR 模板或方法
  3. 03记录决策、备选项和后果
  4. 04依据质量量表检查文档
  5. 05按编号和目录归档 ADR

适用场景

  1. 01记录数据库或框架选型
  2. 02说明架构迁移的权衡与方案
  3. 03记录标准变更或弃用决定

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/lyndonkl/claude --skill adr-architecture

安装后在 Claude Code 中输入/adr-architecture确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

resources/
methodology.md
template.md
resources/evaluators/
rubric_adr_architecture.json
resources/examples/
database-selection.md

详细介绍

架构决策记录（ADR）

目录

每份 ADR 都会记录：背景（是什么情况促使我们做出此决策）、决策（我们选择什么）、备选方案（考虑过的其他选项）、后果（权衡与影响）以及状态（提议、已接受、已弃用、已取代）。

快速示例：

# ADR-042: Use PostgreSQL for Primary Database

**Status:** Accepted
**Date:** 2024-01-15
**Deciders:** Backend team, CTO

## Context
Need to select primary database for new microservices platform.
Requirements: ACID transactions, complex queries, 10k+ QPS at launch.

## Decision
Use PostgreSQL 15+ as primary relational database.

## Alternatives Considered
- MySQL: Weaker JSON support, less robust constraint handling
- MongoDB: No ACID across documents, eventual consistency issues
- CockroachDB: Excellent but adds operational complexity we can't support yet

## Consequences
✓ Strong consistency and data integrity
✓ Excellent JSON support for semi-structured data
✓ Team has deep PostgreSQL experience
✗ Vertical scaling limits (will need read replicas at 50k+ QPS)
✗ More complex to shard than DynamoDB if we need it

工作流

复制此清单并跟踪进度：

ADR Progress:
- [ ] Step 1: Understand the decision
- [ ] Step 2: Choose ADR template
- [ ] Step 3: Document the decision
- [ ] Step 4: Validate quality
- [ ] Step 5: Deliver and file

步骤 1：理解决策

收集决策背景：需要做出什么决策、为何现在做出、由谁决定、有哪些约束（预算、时间线、技能、合规性）、有哪些要求（功能、非功能、业务）以及决策范围（单个服务还是整个组织）。这能确保 ADR 解决正确的问题。

步骤 2：选择 ADR 模板

对于技术选型（框架、库、数据库）→ 使用 resources/template.md。对于包含多个相互依赖选项的复杂架构决策 → 参考 resources/methodology.md。查看示例 → 查看 resources/examples/（database-selection.md、microservices-migration.md、api-versioning.md）。

步骤 3：记录决策

创建 adr-{number}-{short-title}.md，包含：清晰的标题、元数据（状态、日期、决策者）、背景（情况和要求）、决策（具体且可执行）、考虑过的备选方案（含优缺点）、后果（权衡、风险、收益）、相关时的实施说明，以及相关 ADR 的链接。请参阅常见模式，了解特定决策类型的指导。

步骤 4：验证质量

使用 resources/evaluators/rubric_adr_architecture.json 进行自检。确认：背景解释了原因，决策具体且可执行，记录了 2–3 个或更多备选方案及其权衡，后果包含收益和缺点，技术细节准确，陌生读者也能理解，并且如实说明了不足。最低标准：得分 ≥ 3.5（对于有争议或影响重大的决策，目标为 4.5 以上）。

步骤 5：交付并归档

提交已完成的 ADR 文件，重点说明已识别的关键权衡；如果未提供编号，则建议 ADR 编号；对于影响重大的决策，建议评审流程；并指出任何需要后续做出的决策。归档约定：将 ADR 按顺序编号存放在 docs/adr/ 或 architecture/decisions/ 目录中。

常见模式

对于技术选型：

  • 关注技术能力与要求的匹配度
  • 如有性能基准测试数据，请一并提供
  • 记录团队的专业水平
  • 考虑运维复杂度

对于架构变更：

  • 在后果中说明迁移策略
  • 记录对向后兼容性的影响
  • 考虑过渡期间对团队交付速度的影响
  • 说明监控和回滚计划

对于标准和约定：

  • 提供该标准的实际应用示例
  • 记录例外情况或灵活处理方式
  • 考虑执行机制
  • 说明对培训和入职的影响

对于弃用：

  • 将状态设为“已弃用”或“已取代”
  • 链接到取代它的 ADR
  • 记录停用时间表
  • 包含迁移指南

规范

要做：

  • 如实说明权衡（每种选择都有缺点）
  • 为缺乏当前背景信息的未来读者撰写
  • 提供具体的技术细节（版本、配置）
  • 承认不确定性和风险
  • 保持 ADR 不可变（状态可以变更，但内容不变）
  • 每项决策编写一份 ADR（范围聚焦）

不要：

  • 把决策说得比实际情况更好
  • 省略曾认真考虑过的备选方案
  • 使用未作解释的行话
  • 编写含糊的后果描述（“可能提升性能”）
  • 重新审视或编辑旧 ADR（应编写新的 ADR 取而代之）
  • 在一份 ADR 中合并多项彼此独立的决策

快速参考

  • 标准模板：resources/template.md
  • 复杂决策：resources/methodology.md
  • 示例：resources/examples/database-selection.md、resources/examples/microservices-migration.md、resources/examples/api-versioning.md
  • 质量评估标准：resources/evaluators/rubric_adr_architecture.json

ADR 命名约定：adr-{number}-{short-kebab-case-title}.md

  • 示例：adr-042-use-postgresql-for-primary-database.md

评论

支持 Markdown