Architecture Decision Records

Name: Architecture Decision Records
Author: affaan-m

affaan-m/everything-claude-code

5.5k installs
238k repo stars
Updated August 5, 2026
affaan-m/everything-claude-code

architecture-decision-records captures coding-session architecture choices as structured ADR markdown with context, alternatives, rationale, and consequences.

About

The architecture-decision-records skill records architecture choices as structured ADR documents alongside code instead of leaving rationale in Slack threads, PR comments, or memory. It activates when users ask to record a decision, pick among frameworks, libraries, databases, or API designs, explain why X over Y, or review why a past choice was made. New ADRs follow a Michael Nygard template adapted for AI-assisted development with Context, Decision, Alternatives Considered, and Consequences including risks. The workflow initializes docs/adr/ only with user consent, extracts the core choice, documents rejected options, assigns incremental numbers, presents a draft for explicit approval before writing docs/adr/NNNN-decision-title.md, and updates README.md index. Reading mode scans the index and surfaces Context and Decision sections or offers to create a missing record. Decision signals include explicit record requests and implicit framework or auth strategy comparisons. Good ADRs stay specific, cite rationale, list rejected alternatives, note tradeoffs, and remain readable in about two minutes. Lifecycle states are proposed, accepted, deprecated, or superseded.

Captures architecture decisions as numbered ADR markdown files.
Uses Michael Nygard format with context, alternatives, and consequences.
Writes files only after explicit user approval of the draft.
Maintains docs/adr/README.md index with status and date.
Reads existing ADRs when users ask why a choice was made.

Architecture Decision Records by the numbers

5,493 all-time installs (skills.sh)
+235 installs in the week ending Aug 5, 2026 (Skillselion tracking)
Ranked #71 of 1,879 Documentation skills by installs in the Skillselion catalog
Security screen: LOW risk (skills.sh audit)
Data as of Aug 5, 2026 (Skillselion catalog sync)

At a glance

architecture-decision-records capabilities & compatibility

Capabilities: detect explicit and implicit architecture decisi · draft adr with context, decision, alternatives, · initialize docs/adr/ with readme index and templ · assign incremental adr numbers from existing fil · read and summarize matching adrs from the index
Use cases: documentation · planning · project management
Runs: Runs locally
Pricing: Free

From the docs

What architecture-decision-records says it does

決定がSlackスレッド、PRコメント、または誰かの記憶にのみ存在する代わりに、このスキルはコードと並行して存在する構造化ADRドキュメントを生成します。

SKILL.md

ADRは2分で読めるべき

SKILL.md

npx skills add https://github.com/affaan-m/everything-claude-code --skill architecture-decision-records

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/affaan-m/everything-claude-code/architecture-decision-records.svg)](https://skillselion.com/skills/affaan-m/everything-claude-code/architecture-decision-records)

Installs	5.5k
repo stars	★ 238k
Security audit	3 / 3 scanners passed
Last updated	August 5, 2026
Repository	affaan-m/everything-claude-code ↗

What it does

Capture architecture decisions as numbered ADR markdown files with context, alternatives, and consequences during coding sessions.

Who is it for?

Teams documenting framework, database, API, security, or infrastructure tradeoffs during active development.

Skip if: Trivial naming or formatting choices that do not affect system architecture.

When should I use this skill?

User records an ADR, compares architectural options, asks why X was chosen, or plans tradeoff-heavy design work.

What you get

A maintained docs/adr/ log with numbered ADRs, an index README, and readable Context and Decision sections for past choices.

Numbered ADR markdown file
Updated docs/adr/README.md index
Optional template.md for manual use

By the numbers

Eight-step new ADR capture workflow
Four ADR lifecycle states: proposed, accepted, deprecated, superseded
Eight decision categories in documentation table

Files

SKILL.mdMarkdownGitHub ↗

アーキテクチャ決定記録

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

アクティベーション時期

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

ADR形式

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

# 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インデックス形式

# 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がこれを置き換える（常に置き換えをリンク）

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

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