Agent skill

Architecture Decision Records

by affaan-m in affaan-m/ECC

コーディングセッション中にアーキテクチャ決定を構造化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/ja-JP/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
276k
Token cost
~1.1k tokens
SKILL.md length
132 words
Files
1
Skills in repo
683
Repo updated
First seen
Licence
MIT

At a glance

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

  • Works in 8 steps: 初期化(初回のみ) —… → 決定を特定する — 行われている中核的なアーキテクチャの選択を抽出する → コンテキストを収集する — この問題を起こした背景は?存在する制約条件は? → …
  • 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. コーディングセッション中にアーキテクチャ決定を構造化ADRとして記録し、自動的に決定の瞬間を検出し、コンテキスト、検討された代替案、根拠を記録します。今後の開発者がコードベースの形成理由を理解するためのADRログを維持します。

Its SKILL.md is about 1.1k 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/が存在しない場合、ユーザーの確認を得た上でディレクトリ、インデックステーブルヘッダーでシードされたREADME.md(下記のADRインデックス形式を参照)、手動使用用の空白の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 4eb71d9. 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 1.1k tokens when it runs. Until then it costs about 36 tokens; SKILL.md has 132 words of instructions outside code blocks.

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

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 4eb71d9, republished under its MIT licence (© affaan-m). 132 words, ~1,103 tokens.

Download SKILL.mdSave it as .claude/skills/architecture-decision-records/SKILL.md (or your agent's skills folder).
name
architecture-decision-records
description
コーディングセッション中にアーキテクチャ決定を構造化ADRとして記録し、自動的に決定の瞬間を検出し、コンテキスト、検討された代替案、根拠を記録します。今後の開発者がコードベースの形成理由を理解するためのADRログを維持します。
origin
ECC

アーキテクチャ決定記録

コーディングセッション中にアーキテクチャ決定を構造化ドキュメントとして記録します。決定がSlackスレッド、PRコメント、または誰かの記憶にのみ存在する代わりに、このスキルはコードと並行して存在する構造化ADRドキュメントを生成します。

アクティベーション時期

  • ユーザーが明示的に「この決定を記録しよう」または「このADRを作成しよう」と言う
  • 重要な代替案の選択(フレームワーク、ライブラリ、パターン、データベース、API設計)
  • ユーザーが「私たちは...を選択した」または「YではなくXをしている理由は...です」と言う
  • ユーザーが「なぜXを選んだのか」と尋ねる(既存のADRを読む)
  • アーキテクチャ上のトレードオフが検討される計画段階

ADR形式

Michael Nygardによって提案されたADR形式を、AI支援開発向けに調整したものを使用します:

markdown
# ADR-NNNN: [決定タイトル]

**Date**: YYYY-MM-DD
**Status**: proposed | accepted | deprecated | superseded by ADR-NNNN
**Deciders**: [関係者]

## Context

この決定または変更を促すどのような問題や状況が見られるのか?

[2~5文で状況、制約条件、作用する力について説明]

## Decision

提案または実施する変更は何か?

[決定を明確に述べる1~3文]

## Alternatives Considered(検討された代替案)

### Alternative 1: [名前]
- **Pros**: [利点]
- **Cons**: [欠点]
- **Why not**: [この選択肢が拒否された特定の理由]

### Alternative 2: [名前]
- **Pros**: [利点]
- **Cons**: [欠点]
- **Why not**: [この選択肢が拒否された特定の理由]

## Consequences(結果)

この変更により、何がより簡単になり、何がより難しくなるか?

### Positive
- [利点1]
- [利点2]

### Negative
- [トレードオフ1]
- [トレードオフ2]

### Risks
- [リスクと軽減策]

ワークフロー

新しいADRをキャプチャする

決定の瞬間が検出されたとき:

  1. 初期化(初回のみ) — docs/adr/が存在しない場合、ユーザーの確認を得た上でディレクトリ、インデックステーブルヘッダーでシードされたREADME.md(下記のADRインデックス形式を参照)、手動使用用の空白の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ファイルを読み、ContextとDecisionセクションを表示
  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
# Architecture Decision Records

| ADR | Title | Status | Date |
|-----|-------|--------|------|
| [0001](0001-use-nextjs.md) | Use Next.js as frontend framework | accepted | 2026-01-15 |
| [0002](0002-postgres-over-mongo.md) | PostgreSQL over MongoDB for primary datastore | accepted | 2026-01-20 |
| [0003](0003-rest-over-graphql.md) | REST API over GraphQL | accepted | 2026-02-01 |

決定検出シグナル

会話の中でアーキテクチャ決定を示すこれらのパターンに注意:

明示的なシグナル

  • 「Xにしよう」
  • 「YではなくXを使うべき」
  • 「トレードオフは...だから価値がある」
  • 「このをADRとして記録して」

暗黙的なシグナル(ADRの記録を提案する — ユーザーの確認なしに自動作成しない)

  • 2つのフレームワークまたはライブラリを比較して結論に達する
  • 述べられた根拠を持つデータベーススキーマ設計の選択をする
  • アーキテクチャパターン(モノリス対マイクロサービス、REST対GraphQL)の間で選択する
  • 認証/認可戦略を決定する
  • 代替案を評価した後、デプロイインフラストラクチャを選択する

良いADRとは

すること
  • 具体的に — 「ORMを使う」ではなく「Prisma ORMを使う」
  • 根拠を記録する — 根拠は何よりも重要です
  • 拒否された代替案を含める — 将来の開発者は何が検討されたかを知る必要があります
  • 結果を正直に述べる — すべての決定にはトレードオフがあります
  • 短く保つ — ADRは2分で読めるべき
  • 現在時制を使う — 「Xを使う」ではなく「私たちはXを使う」
しないこと
  • 些細な決定を記録する — 変数名またはフォーマット選択はADRを必要としません
  • エッセイを書く — contextセクションが10行を超える場合は長すぎます
  • 代替案を省略する — 「単に選んだ」は有効な根拠ではありません
  • マーキングなしでバックフィルする — 過去の決定を記録する場合は元の日付を注記
  • ADRを古い状態にする — 置き換えられた決定は置き換えを参照する必要があります

ADRライフサイクル

proposed → accepted → [deprecated | superseded by ADR-NNNN]
  • proposed: 決定が検討中であり、まだコミットされていない
  • accepted: 決定が有効であり、フォローされている
  • deprecated: 決定は関連性がなくなった(例:機能が削除された)
  • superseded: 新しいADRがこれを置き換える(常に置き換えをリンク)

記録する価値のある決定カテゴリ

CategoryExamples
Technology choicesフレームワーク、言語、データベース、クラウドプロバイダ
Architecture patternsモノリス対マイクロサービス、イベント駆動、CQRS
API designREST対GraphQL、バージョニング戦略、auth機構
Data modelingスキーマ設計、正規化決定、キャッシング戦略
Infrastructureデプロイメントモデル、CI/CDパイプライン、監視スタック
SecurityAuth戦略、暗号化アプローチ、シークレット管理
Testingテストフレームワーク、カバレッジ対象、E2E対統合のバランス
Processブランチング戦略、レビュープロセス、リリースケーデンス

他のスキルとの統合

  • Planner エージェント: プランナーがアーキテクチャ変更を提案するとき、ADRの作成を提案
  • Code reviewer エージェント: 対応する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/ja-JP/skills/architecture-decision-records of affaan-m/ECC.

Open the folder on GitHubat commit 4eb71d9

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/ECC276k—~1.1kAutomated 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?

コーディングセッション中にアーキテクチャ決定を構造化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/ja-JP/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/ja-JP/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 1.1k tokens (SKILL.md is roughly 4.4k 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,111 GitHub stars. The repository holds 683 skills in this directory. The repository was last updated on October 10, 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.