Agent skill

Architecture Decision Records

by affaan-m in affaan-m/ECC

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

MITAuto-check passedDevelopment

Install Architecture Decision Records

skills CLI
$ npx skills add affaan-m/ECC --skill architecture-decision-records -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install affaan-m/ECC architecture-decision-records --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/affaan-m/ECC.git skills-src && mkdir -p .claude/skills && cp -r skills-src/docs/zh-CN/skills/architecture-decision-records .claude/skills/architecture-decision-records && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
architecture-decision-records
GitHub stars
277k
Used in
1 other repo
Token cost
~863 tokens
SKILL.md length
206 words
Files
1
Skills in repo
683
Repo updated
First seen
Licence
MIT

At a glance

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

  • Works in 8 steps: 初始化(仅首次) — 如果 docs/adr/… → 识别决策 — 提取正在做出的核心架构选择 → 收集上下文 — 是什么问题引发了此决策?存在哪些约束? → …
  • Tasks that involve Architecture decision records
  • SKILL.md covers 何时激活, ADR 格式, 工作流程 and 决策检测信号, plus 4 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Architecture Decision Records is an agent skill from affaan-m/ECC. 在Claude Code会话期间,将做出的架构决策捕获为结构化的架构决策记录(ADR)。自动检测决策时刻,记录上下文、考虑的替代方案和理由。维护一个ADR日志,以便未来的开发人员理解代码库为何以当前方式构建。

Its SKILL.md is about 860 tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Development, covering Architecture decision records. The repository describes itself as: The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond. The licence is MIT.

When your agent uses it

  • Tasks that involve Architecture decision records

Example prompts

  • “/architecture-decision-records”

Workflow steps

8 steps, taken from the first numbered list in SKILL.md.

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

What it can do on your machine

Read from SKILL.md and the folder at commit 2d515e4. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are markdown).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Architecture Decision Records loads about 863 tokens when it runs. Until then it costs about 34 tokens; SKILL.md has 206 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~34
When it runs · the whole SKILL.md, loaded when a task matches
~863

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from affaan-m/ECC at commit 2d515e4, republished under its MIT licence (© affaan-m). 206 words, ~863 tokens.

Download SKILL.mdSave it as .claude/skills/architecture-decision-records/SKILL.md (or your agent's skills folder).
name
architecture-decision-records
description
在Claude Code会话期间,将做出的架构决策捕获为结构化的架构决策记录(ADR)。自动检测决策时刻,记录上下文、考虑的替代方案和理由。维护一个ADR日志,以便未来的开发人员理解代码库为何以当前方式构建。
origin
ECC

架构决策记录

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

何时激活

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

ADR 格式

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

markdown
# ADR-NNNN: [决策标题]

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

## 背景

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

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

## 决策

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

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

## 考虑的备选方案

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

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

## 影响

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

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

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

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

工作流程

捕捉新的 ADR

当检测到决策时刻时:

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

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

  1. 检查 docs/adr/ 是否存在 — 如果不存在,回复:"在此项目中未找到 ADR。您想开始记录架构决策吗?"
  2. 如果存在,扫描 docs/adr/README.md 索引以查找相关条目
  3. 读取匹配的 ADR 文件并呈现上下文和决策部分
  4. 如果未找到匹配项,回复:"未找到关于该决策的 ADR。您现在想记录一个吗?"
ADR 目录结构
docs/
└── adr/
    ├── README.md              ← 所有 ADR 的索引
    ├── 0001-use-nextjs.md
    ├── 0002-postgres-over-mongo.md
    ├── 0003-rest-over-graphql.md
    └── template.md            ← 供手动使用的空白模板
ADR 索引格式
markdown
# 架构决策记录

| 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

© affaan-m, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in docs/zh-CN/skills/architecture-decision-records of affaan-m/ECC.

Open the folder on GitHubat commit 2d515e4

Used in 1 other repository

We found 1 copy of this SKILL.md (exact, near-identical or edited) in other folders, from 1 other GitHub owner. This page covers the copy in affaan-m/ECC, which our catalogue first saw on October 7, 2026.

Compare with similar skills

Architecture Decision Records next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Architecture Decision Records compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Architecture Decision Records this skillaffaan-m/ECC277k1 repos~863Automated safety check: PassMIT
PR Design DocOpenHands/OpenHands91k—~2.4kAutomated safety check: PassMIT
Cto AdvisorIbrahim-3d/orchestrator-supaconductor3814 repos~2.4kAutomated safety check: PassMIT
Domain Modelingbrim-borium/spotify_sdk1667 repos~806Automated safety check: PassApache-2.0
Architecture DecisionDonchitos/Claude-Code-Game-Studios26k—~1.7kAutomated safety check: PassMIT
Improve Codebase Architectureywwynm/EverythingDone14415 repos~1.3kAutomated safety check: PassGPL-3.0

Similar skills

  • PR Design Doc

    OpenHands/OpenHands

    For a non-trivial pull request, write a self-contained HTML design doc under the temporary .pr/ directory and link a visibility-appropriate preview in the PR description, so maintainers grasp the…

    91k GitHub stars~2.4k tokensUpdated today
    DevelopmentAuto-check passed
  • Cto Advisor

    Ibrahim-3d/orchestrator-supaconductor

    Technical leadership guidance for engineering teams, architecture decisions, and technology strategy.

    381 GitHub starsUsed in 4 repos~2.4k tokens
    DevelopmentAuto-check passed
  • Domain Modeling

    brim-borium/spotify_sdk

    Build and sharpen a project's domain model. An agent skill from brim-borium/spotify_sdk.

    166 GitHub starsUsed in 7 repos~806 tokens
    DevelopmentAuto-check passed
  • Architecture Decision

    Donchitos/Claude-Code-Game-Studios

    Create an ADR documenting a technical decision: context, alternatives considered, consequences.

    26k GitHub stars~1.7k tokensUpdated 3 days ago
    DevelopmentAuto-check passed
  • Improve Codebase Architecture

    ywwynm/EverythingDone

    Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/.

    144 GitHub starsUsed in 15 repos~1.3k tokens
    DevelopmentAuto-check passed
  • Design Doc Mermaid

    SpillwaveSolutions/design-doc-mermaid

    Create Mermaid diagrams (flowchart, sequence, class, ER, state, C4, architecture) from text or source code.

    176 GitHub starsUsed in 1 repo~5.6k tokens
    DevelopmentAuto-check passed

More from affaan-m/ECC

All 682 skills in this repo
  • Skill Stocktake

    affaan-m/ECC

    Audits your installed Claude skills and commands for quality, with a quick mode for recently changed skills and a full mode that evaluates all of them through subagents.

    277k GitHub starsUsed in 5 repos~3.1k tokens
    Auto-check passed
  • Ingests, indexes, searches, edits and monitors video, audio and live streams through the VideoDB Python SDK, returning stream links, clips and timestamps.

    277k GitHub starsUsed in 3 repos~3.5k tokens
    Auto-check: notes
  • Docs Governance

    affaan-m/ECC

    Route broad documentation-governance requests to existing ECC skills and run an opt-in, read-only audit of mapped documentation roles, links, ADR indexes, and evidence references.

    277k GitHub stars~1.1k tokensUpdated today
    Auto-check passed
  • Rules Distillation

    affaan-m/ECC

    Scans installed skills for principles that recur across them and proposes rule-file changes: append, revise, add a section, create a file or leave as covered.

    277k GitHub starsUsed in 2 repos~2.3k tokens
    Auto-check passed
  • Builds DRAFT counterparty agreements from one markdown template and a small JSON spec per party, with clauses picked by the party's role.

    277k GitHub stars~2.9k tokensUpdated today
    Auto-check passed
  • Set an ECC-specific frontend design direction for production UI work.

    277k GitHub starsUsed in 1 repo~2.2k tokens
    Auto-check passed

Categories

Questions about Architecture Decision Records

What does Architecture Decision Records do?

在Claude Code会话期间,将做出的架构决策捕获为结构化的架构决策记录(ADR)。自动检测决策时刻,记录上下文、考虑的替代方案和理由。维护一个ADR日志,以便未来的开发人员理解代码库为何以当前方式构建。. Architecture Decision Records is an agent skill from affaan-m/ECC.

When should I use Architecture Decision Records?

Architecture Decision Records fits situations like: tasks that involve Architecture decision records.

How do I install Architecture Decision Records in Claude Code?

Run `npx skills add affaan-m/ECC --skill architecture-decision-records -a claude-code`. Or copy the skill folder (docs/zh-CN/skills/architecture-decision-records in affaan-m/ECC) into .claude/skills/architecture-decision-records in your project. Claude Code loads it when a task matches its description.

How do I install Architecture Decision Records in Codex?

Run `npx skills add affaan-m/ECC --skill architecture-decision-records -a codex`. Or copy the skill folder (docs/zh-CN/skills/architecture-decision-records in affaan-m/ECC) into .agents/skills/architecture-decision-records in your project. Codex loads it when a task matches its description.

Can I use Architecture Decision Records in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add affaan-m/ECC --skill architecture-decision-records -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/architecture-decision-records, .gemini/skills/architecture-decision-records, .github/skills/architecture-decision-records and .opencode/skills/architecture-decision-records in your project.

What does Architecture Decision Records need to run?

SKILL.md names no scripts, command-line tools or credentials: Architecture Decision Records is instructions for the agent only.

Does Architecture Decision Records access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Architecture Decision Records safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Architecture Decision Records use?

Architecture Decision Records is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Architecture Decision Records use?

About 863 tokens (SKILL.md is roughly 3.5k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Architecture Decision Records?

Skills that share tags, products or a category with Architecture Decision Records: PR Design Doc (OpenHands/OpenHands, 91k stars), Cto Advisor (Ibrahim-3d/orchestrator-supaconductor, 381 stars), Domain Modeling (brim-borium/spotify_sdk, 166 stars) and Architecture Decision (Donchitos/Claude-Code-Game-Studios, 26k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Architecture Decision Records?

affaan-m (a GitHub user) maintains it in affaan-m/ECC, which has 276,673 GitHub stars. The repository holds 683 skills in this directory. The repository was last updated on October 11, 2026.

Source: affaan-m/ECC on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.