affaan-m/ECC

architecture-decision-records

在Claude Code会话期间，将做出的架构决策捕获为结构化的架构决策记录（ADR）。自动检测决策时刻，记录上下文、考虑的替代方案和理由。维护一个ADR日志，以便未来的开发人员理解代码库为何以当前方式构建。

67CollectingClaude Code

See how to use it View GitHub source

npx skills add https://github.com/affaan-m/ECC --skill "docs/zh-CN/skills/architecture-decision-records"

Automated source guide

Source checked Jul 28, 2026·Refresh due Oct 26, 2026

Reorganized from the pinned upstream SKILL.md

Turn architecture-decision-records's source instructions into a guide you can follow

According to the pinned SKILL.md from affaan-m/ECC: 在编码会话期间捕捉架构决策。让决策不仅存在于 Slack 线程、PR 评论或某人的记忆中，此技能将生成结构化的 ADR 文档，并与代码并存。

npx skills add https://github.com/affaan-m/ECC --skill "docs/zh-CN/skills/architecture-decision-records"

Check the pinned source

Best fit

在Claude Code会话期间，将做出的架构决策捕获为结构化的架构决策记录（ADR）。自动检测决策时刻，记录上下文、考虑的替代方案和理由。维护一个ADR日志，以便未来的开发人员理解代码库为何以当前方式构建。

Bring this context

A concrete task that matches the documented purpose of architecture-decision-records.
The files, examples, or context the task depends on.
Your constraints, target environment, and definition of done.

Expected outputs

A result that follows the pinned architecture-decision-records instructions.
A concise record of assumptions, inputs used, and unresolved questions.
A final check against the source workflow and relevant permission signals.

Key source sections

Read architecture-decision-records through these 5 source sections

Sections are extracted automatically from the pinned SKILL.md and link back to the source.

何时激活

用户明确说"让我们记录这个决定"或"为这个做 ADR" 用户在重要的备选方案（框架、库、模式、数据库、API 设计）之间做出选择用户说"我们决定..."或"我们选择 X 而不是 Y 的原因是..." 用户询问"我们为什么选择了 X？"（读取现有 ADR）在讨论架构权衡的规划阶段

SKILL.md · 何时激活

用户明确说"让我们记录这个决定"或"为这个做 ADR"用户在重要的备选方案（框架、库、模式、数据库、API 设计）之间做出选择用户说"我们决定..."或"我们选择 X 而不是 Y 的原因是..."

ADR 格式

使用 Michael Nygard 提出的轻量级 ADR 格式，并针对 AI 辅助开发进行调整：

SKILL.md · ADR 格式

使用 Michael Nygard 提出的轻量级 ADR 格式，并针对 AI 辅助开发进行调整：

ADR-NNNN: [决策标题]

日期: YYYY-MM-DD 状态: 提议中 | 已接受 | 已弃用 | 被 ADR-NNNN 取代决策者: [相关人员]

SKILL.md · ADR-NNNN: [决策标题]

优点: [益处]缺点: [弊端]为何不选: [被拒绝的具体原因]

背景

[用 2-5 句话描述当前情况、约束条件和影响因素]

SKILL.md · 背景

[用 2-5 句话描述当前情况、约束条件和影响因素]

决策

Review the “决策” section in the pinned source before continuing.

SKILL.md · 决策

Review and apply the “决策” source section.

SkillSignal prompt templates

Provide the task, context, and acceptance criteria

These prompts were written by SkillSignal from the source structure; they are not upstream text.

Task-start prompt

Confirm source fit, inputs, and outputs before acting.

Use architecture-decision-records to help me with: [specific task]. Context: [files, data, or background]. Constraints: [environment, scope, and prohibited actions]. Before acting, check the pinned SKILL.md and explain which sections apply, what inputs are still missing, and what you will deliver.

Source-guided execution

Make the Agent explicitly follow the key extracted sections.

Apply the pinned architecture-decision-records source to [task]. Pay particular attention to these source sections: “何时激活”, “ADR 格式”, “ADR-NNNN: [决策标题]”, “背景”, “决策”. Preserve the important decision at each step. Mark facts not covered by the source as “needs confirmation” instead of inventing them. Then verify the result against my acceptance criteria: [criteria].

Result-review prompt

Check omissions, permissions, and source drift before delivery.

Review the current architecture-decision-records result: (1) does it satisfy the original task; (2) were any applicable steps or limits in the pinned SKILL.md missed; (3) did it perform any unauthorized file, command, network, or data action; and (4) which conclusions remain unverified? List issues first, then fix only what the source or user authorization supports.

Output checklist

Verify each item before delivery

The task matches the purpose documented in the SKILL.md.

The source section “何时激活” has been checked.

The source section “ADR 格式” has been checked.

The source section “ADR-NNNN: [决策标题]” has been checked.

The source section “背景” has been checked.

Inputs, constraints, and acceptance criteria are explicit.

Unverified facts, compatibility, and outcome claims are clearly marked.

Any file, command, network, or data action has been reviewed.

Choose a different workflow

When another Skill is the better fit

architecture-decision-records

Capture architectural decisions made during Claude Code sessions as structured ADRs. Auto-detects decision moments, records context, alternatives considered, and rationale. Maintains an ADR log so future developers understand why the codebase is shaped the way it is.

A separate implementation from affaan-m/ECC; compare its source, maintenance signals, and permission requirements.

Open source detail

architecture-decision-records

Write and maintain Architecture Decision Records (ADRs) following best practices for technical decision documentation. Use when documenting significant technical decisions, reviewing past architectural choices, or establishing decision processes.

A separate implementation from wshobson/agents; compare its source, maintenance signals, and permission requirements.

Open source detail

architecture-decision-records

コーディングセッション中にアーキテクチャ決定を構造化ADRとして記録し、自動的に決定の瞬間を検出し、コンテキスト、検討された代替案、根拠を記録します。今後の開発者がコードベースの形成理由を理解するためのADRログを維持します。

A separate implementation from affaan-m/ECC; compare its source, maintenance signals, and permission requirements.

Open source detail

FAQ

What does architecture-decision-records do?

在编码会话期间捕捉架构决策。让决策不仅存在于 Slack 线程、PR 评论或某人的记忆中，此技能将生成结构化的 ADR 文档，并与代码并存。

How do I start using architecture-decision-records?

The catalog detected this source-specific install command: npx skills add https://github.com/affaan-m/ECC --skill "docs/zh-CN/skills/architecture-decision-records". Inspect the command and pinned source before running it.

Which Agent platforms does it declare?

claude code

Repository stars

234,327

Repository forks

35,711

Quality

67/100

Source repository last pushed

2026-07-27

Quality breakdown

Based on traceable docs and repository signals; stars are not treated as quality.

67/100

Documentation21/30

Specificity14/25

Maintenance20/20

Trust signals12/25

Compare before choosing

Related Agent Skills and source variants

These links are selected from shared tasks, functions, stacks, platforms, and same-name variants. Compare the source owner, documentation, permissions, and maintenance signals.

architecture-decision-records by affaan-m

architecture-decision-records by wshobson

architecture-decision-records by affaan-m

claude-skill-spec-audit by jackchuka

Audit skill SKILL.md files for compliance with the agentskills.io specification and house conventions. Checks frontmatter fields (name, description, compatibility, metadata, argument-hint), metadata sub-fields (author, scope, layer, confirms), and layer/suffix consistency. Use when adding new skills, reviewing skill quality, or ensuring all skills follow the spec. Triggers: "audit skills", "check skill spec", "skill compliance", "are my skills up to spec", "/claude-skill-spec-audit".

autonomous-loops by affaan-m

Patterns and architectures for autonomous Claude Code loops — from simple sequential pipelines to RFC-driven multi-agent DAG systems.

View original Skill.mdThis page is parsed directly from the repository SKILL.md without editorial rewriting. Collected: Jul 28, 2026 · about 2 min

架构决策记录

在编码会话期间捕捉架构决策。让决策不仅存在于 Slack 线程、PR 评论或某人的记忆中，此技能将生成结构化的 ADR 文档，并与代码并存。

何时激活

用户明确说"让我们记录这个决定"或"为这个做 ADR"
用户在重要的备选方案（框架、库、模式、数据库、API 设计）之间做出选择
用户说"我们决定..."或"我们选择 X 而不是 Y 的原因是..."
用户询问"我们为什么选择了 X？"（读取现有 ADR）
在讨论架构权衡的规划阶段

ADR 格式

使用 Michael Nygard 提出的轻量级 ADR 格式，并针对 AI 辅助开发进行调整：

# ADR-NNNN: [决策标题]

**日期**: YYYY-MM-DD
**状态**: 提议中 | 已接受 | 已弃用 | 被 ADR-NNNN 取代
**决策者**: [相关人员]

## 背景

我们观察到的促使做出此决策或变更的问题是什么？

[用 2-5 句话描述当前情况、约束条件和影响因素]

## 决策

我们提议和/或正在进行的变更是什么？

[用 1-3 句话清晰地陈述决策]

## 考虑的备选方案

### 备选方案 1: [名称]
- **优点**: [益处]
- **缺点**: [弊端]
- **为何不选**: [被拒绝的具体原因]

### 备选方案 2: [名称]
- **优点**: [益处]
- **缺点**: [弊端]
- **为何不选**: [被拒绝的具体原因]

## 影响

由于此变更，哪些事情会变得更容易或更困难？

### 积极影响
- [益处 1]
- [益处 2]

### 消极影响
- [权衡 1]
- [权衡 2]

### 风险
- [风险及缓解措施]

工作流程

捕捉新的 ADR

当检测到决策时刻时：

初始化（仅首次） — 如果 docs/adr/ 不存在，在创建目录、一个包含索引表头（见下方 ADR 索引格式）的 README.md 以及一个供手动使用的空白 template.md 之前，询问用户进行确认。未经明确同意，不要创建文件。
识别决策 — 提取正在做出的核心架构选择
收集上下文 — 是什么问题引发了此决策？存在哪些约束？
记录备选方案 — 考虑了哪些其他选项？为什么拒绝了它们？
陈述后果 — 权衡是什么？什么变得更容易/更难？
分配编号 — 扫描 docs/adr/ 中的现有 ADR 并递增
确认并写入 — 向用户展示 ADR 草稿以供审查。仅在获得明确批准后写入 docs/adr/NNNN-decision-title.md。如果用户拒绝，则丢弃草稿，不写入任何文件。
更新索引 — 追加到 docs/adr/README.md

读取现有 ADR

当用户询问"我们为什么选择了 X？"时：

检查 docs/adr/ 是否存在 — 如果不存在，回复："在此项目中未找到 ADR。您想开始记录架构决策吗？"
如果存在，扫描 docs/adr/README.md 索引以查找相关条目
读取匹配的 ADR 文件并呈现上下文和决策部分
如果未找到匹配项，回复："未找到关于该决策的 ADR。您现在想记录一个吗？"

ADR 目录结构

docs/
└── adr/
    ├── README.md              ← 所有 ADR 的索引
    ├── 0001-use-nextjs.md
    ├── 0002-postgres-over-mongo.md
    ├── 0003-rest-over-graphql.md
    └── template.md            ← 供手动使用的空白模板

ADR 索引格式

# 架构决策记录

| ADR | 标题 | 状态 | 日期 |
|-----|-------|--------|------|
| [0001](0001-use-nextjs.md) | 使用 Next.js 作为前端框架 | 已采纳 | 2026-01-15 |
| [0002](0002-postgres-over-mongo.md) | 主数据存储选用 PostgreSQL 而非 MongoDB | 已采纳 | 2026-01-20 |
| [0003](0003-rest-over-graphql.md) | 选用 REST API 而非 GraphQL | 已采纳 | 2026-02-01 |

决策检测信号

留意对话中指示架构决策的以下模式：

显式信号

"让我们选择 X"
"我们应该使用 X 而不是 Y"
"权衡是值得的，因为..."
"将此记录为 ADR"

隐式信号（建议记录 ADR — 未经用户确认不要自动创建）

比较两个框架或库并得出结论
做出数据库模式设计选择并陈述理由
在架构模式之间选择（单体 vs 微服务，REST vs GraphQL）
决定身份验证/授权策略
评估备选方案后选择部署基础设施

优秀 ADR 的要素

应该做

具体明确 — "使用 Prisma ORM"，而不是"使用一个 ORM"
记录原因 — 理由比内容更重要
包含被拒绝的备选方案 — 未来的开发者需要知道考虑了哪些选项
诚实地陈述后果 — 每个决策都有权衡
保持简短 — 一份 ADR 应在 2 分钟内可读完
使用现在时态 — "我们使用 X"，而不是"我们将使用 X"

不应该做

记录琐碎的决定 — 变量命名或格式化选择不需要 ADR
写成论文 — 如果上下文部分超过 10 行，就太长了
省略备选方案 — "我们只是选了它"不是一个有效的理由
追溯记录而不加标记 — 如果记录过去的决定，请注明原始日期
让 ADR 过时 — 被取代的决策应引用其替代品

ADR 生命周期

proposed → accepted → [deprecated | superseded by ADR-NNNN]

proposed：决策正在讨论中，尚未确定
accepted：决策已生效并正在遵循
deprecated：决策不再相关（例如，功能已移除）
superseded：更新的 ADR 取代了此决策（始终链接替代品）

值得记录的决策类别

类别	示例
技术选择	框架、语言、数据库、云提供商
架构模式	单体 vs 微服务、事件驱动、CQRS
API 设计	REST vs GraphQL、版本控制策略、认证机制
数据建模	模式设计、规范化决策、缓存策略
基础设施	部署模型、CI/CD 流水线、监控堆栈
安全	认证策略、加密方法、密钥管理
测试	测试框架、覆盖率目标、E2E 与集成测试的平衡
流程	分支策略、评审流程、发布节奏

与其他技能的集成

规划代理：当规划者提出架构变更时，建议创建 ADR
代码审查代理：标记引入架构变更但未附带相应 ADR 的 PR

Source repo: affaan-m/ECC
Skill path: docs/zh-CN/skills/architecture-decision-records/SKILL.md
Commit SHA: 4e973d3eaf92
Repository license: MIT
Data collected: Jul 28, 2026