Communitygithub.com

アーキテクチャ決定記録 (ADR)

Claude Codeセッション中に行われたアーキテクチャ上の決定を構造化されたADRとして記録します。決定の瞬間を自動検出し、コンテキスト、検討した代替案、根拠を記録します。将来の開発者がコードベースの形状を理解できるようADRログを維持します。

アーキテクチャ決定記録 (ADR) とは？

このスキルは、AIエージェント（Claude Codeなど）を使用した開発セッション中にアーキテクチャ上の決定を構造化されたアーキテクチャ決定記録（ADR）として自動的に記録するためのものです。開発者は「この決定を記録して」などの明示的な合図や、フレームワークやデータベースの選択といった重要なトレードオフの議論を検出することで、決定のコンテキスト、検討した代替案、採用理由、および結果を詳細に文書化します。対応プラットフォームはClaude Codeを主な対象とし、`docs/adr/`ディレクトリにマークダウンファイルとしてADRを保存します。このスキルは、決定がSlackスレッドやPRコメントに埋もれるのを防ぎ、コードと共に永続的な決定ログを提供することで、プロジェクトの長期的な理解可能性と一貫性を向上させます。不要な決定の記録を避けるためのガイドラインも含まれており、品質の高いADRのみが生成されるように設計されています。

対応✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/affaan-m/ECC/tree/main/skills/architecture-decision-records
オリジナルを見る→すべてのスキルを見る

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

ドキュメント

アーキテクチャ決定記録 (ADR) は何をしますか？

コーディングセッション中に行われるアーキテクチャ上の決定を記録します。決定がSlackスレッド、PRコメント、または誰かの記憶にのみ残るのではなく、コードと共に構造化されたADRドキュメントとして残ります。

いつアクティブにするか

  • ユーザーが明示的に「この決定を記録して」または「ADRにして」と言ったとき
  • ユーザーが重要な代替案（フレームワーク、ライブラリ、パターン、データベース、APIデザイン）の間で選択しているとき
  • ユーザーが「〜に決めた」や「XではなくYを採用した理由は...」と言ったとき
  • ユーザーが「なぜXを選んだのか？」と尋ねたとき（既存のADRを読む）
  • アーキテクチャ上のトレードオフが議論される計画フェーズ中

ADRフォーマット

Michael Nygardが提案した軽量ADRフォーマットを、AI支援開発向けに適応したもの:

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

**日付**: YYYY-MM-DD
**ステータス**: proposed | accepted | deprecated | superseded by ADR-NNNN
**決定者**: [関わった人]

## コンテキスト

この決定や変更の動機となっている問題は何ですか？

[状況、制約、影響する要因を2〜5文で説明]

## 決定

提案および/または実行している変更は何ですか？

[決定を明確に1〜3文で記述]

## 検討した代替案

### 代替案1: [名前]
- **メリット**: [利点]
- **デメリット**: [欠点]
- **採用しなかった理由**: [却下された具体的な理由]

### 代替案2: [名前]
- **メリット**: [利点]
- **デメリット**: [欠点]
- **採用しなかった理由**: [却下された具体的な理由]

## 結果

この変更により、何が容易になり、何が困難になりますか？

### ポジティブ
- [利点1]
- [利点2]

### ネガティブ
- [トレードオフ1]
- [トレードオフ2]

### リスク
- [リスクとその軽減策]

ワークフロー

新しい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ファイルを読み込み、コンテキストと決定セクションを提示します
  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インデックスフォーマット

# アーキテクチャ決定記録

| ADR | タイトル | ステータス | 日付 |
|-----|--------|--------|------|
| [0001](0001-use-nextjs.md) | フロントエンドフレームワークにNext.jsを採用 | accepted | 2026-01-15 |
| [0002](0002-postgres-over-mongo.md) | プライマリデータストアにMongoDBではなくPostgreSQLを採用 | accepted | 2026-01-20 |
| [0003](0003-rest-over-graphql.md) | GraphQLではなくREST APIを採用 | accepted | 2026-02-01 |

決定検出シグナル

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

明示的なシグナル

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

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

  • 2つのフレームワークやライブラリを比較し、結論に達する
  • 理由を示しながらデータベーススキーマの設計選択を行う
  • アーキテクチャパターン（モノリス vs マイクロサービス、REST vs GraphQL）の間で選択する
  • 認証/認可戦略を決定する
  • 代替案を評価した上でデプロイメントインフラを選択する

優れたADRの条件

やるべきこと

  • 具体的に — 「ORMを使う」ではなく「Prisma ORMを使う」
  • 理由を記録する — 根拠は何を選んだかよりも重要
  • 却下された代替案を含める — 将来の開発者は何が検討されたかを知る必要がある
  • 結果を正直に述べる — すべての決定にはトレードオフがある
  • 短く保つ — ADRは2分で読めるべき
  • 現在形を使う — 「Xを使う予定」ではなく「Xを使う」

避けるべきこと

  • 些細な決定を記録しない — 変数名やフォーマットの選択にADRは不要
  • 長文を書かない — コンテキストセクションが10行を超える場合は長すぎる
  • 代替案を省略しない — 「とにかく選んだ」は有効な根拠ではない
  • 遡って記録する場合はマークを付ける — 過去の決定を記録する場合は、元の日付を明記する
  • ADRを陳腐化させない — 置き換えられた決定は、その代替ADRを参照する

ADRのライフサイクル

proposed → accepted → [deprecated | superseded by ADR-NNNN]
  • proposed: 決定が議論中で、まだ確定していない
  • accepted: 決定が有効で、それに従っている
  • deprecated: 決定がもはや関連しない（例：機能が削除された）
  • superseded: 新しいADRがこれを置き換える（必ず置き換え先をリンクする）

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

カテゴリ例
技術選択フレームワーク、言語、データベース、クラウドプロバイダー
アーキテクチャパターンモノリス vs マイクロサービス、イベント駆動、CQRS
APIデザインREST vs GraphQL、バージョニング戦略、認証メカニズム
データモデリングスキーマ設計、正規化の決定、キャッシュ戦略
インフラデプロイメントモデル、CI/CDパイプライン、監視スタック
セキュリティ認証戦略、暗号化アプローチ、シークレット管理
テストテストフレームワーク、カバレッジ目標、E2E vs 統合テストのバランス
プロセスブランチ戦略、レビュープロセス、リリースサイクル

他のスキルとの連携

  • プランナーエージェント: プランナーがアーキテクチャ変更を提案した場合、ADRの作成を提案する
  • コードレビューアーエージェント: 対応するADRなしにアーキテクチャ変更を導入するPRにフラグを立てる

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

accessibility

Design, implement, and audit inclusive digital products using WCAG 2.2 Level AA. Use when building or auditing UI that must meet WCAG 2.2 Level AA, or when reviewing a change for keyboard, contrast, or screen-reader support.

affaan-m/content-engine

Create platform-native content systems for X, LinkedIn, TikTok, YouTube, newsletters, and repurposed multi-platform campaigns. Use when the user wants social posts, threads, scripts, content calendars, or one source asset adapted cleanly across platforms.

affaan-m/ECC

Multi-platform content distribution across X, LinkedIn, Threads, and Bluesky. Adapts content per platform using content-engine patterns. Never posts identical content cross-platform. Use when the user wants to distribute content across social platforms.

affaan-m/fal-ai-media

Unified media generation via fal.ai MCP — image, video, and audio. Covers text-to-image (Nano Banana), text/image-to-video (Seedance, Kling, Veo 3), text-to-speech (CSM-1B), and video-to-audio (ThinkSound). Use when the user wants to generate images, videos, or audio with AI.

affaan-m/manim-video

日本語翻訳：このファイルは manim-video 用の日本語翻訳が必要です

affaan-m/remotion-video-creation

Remotion のベストプラクティス - React で動画を作成する。3D、アニメーション、音声、字幕、チャート、トランジションなどをカバーするドメイン固有の29のルール。

affaan-m/video-editing

AI-assisted video editing workflows for cutting, structuring, and augmenting real footage. Covers the full pipeline from raw capture through FFmpeg, Remotion, ElevenLabs, fal.ai, and final polish in Descript or CapCut. Use when the user wants to edit video, cut footage, create vlogs, or build video content.

agent-architecture-audit

Full-stack diagnostic for agent and LLM applications. Audits the 12-layer agent stack for wrapper regression, memory pollution, tool discipline failures, hidden repair loops, and rendering corruption. Produces severity-ranked findings with code-first fixes. Essential for developers building agent applications, autonomous loops, or any LLM-powered feature. Use when an agent or LLM feature misbehaves and the failing layer is unknown, or before shipping an agent stack.

agent-eval

Head-to-head comparison of coding agents (Claude Code, Aider, Codex, etc.) on custom tasks with pass rate, cost, time, and consistency metrics. Use when choosing between coding agents, or when a change to an agent setup needs measured pass rate, cost, and time rather than an impression.

agent-harness-construction

Design and optimize AI agent action spaces, tool definitions, and observation formatting for higher completion rates. Use when defining or revising an agent

agentic-engineering

Operate as an agentic engineer using eval-first execution, decomposition, and cost-aware model routing. Use when planning or executing engineering work that agents will carry out end to end.

agentic-os

Build persistent multi-agent operating systems on Claude Code. Covers kernel architecture, specialist agents, slash commands, file-based memory, scheduled automation, and state management without external databases. Use when building a persistent multi-agent system on Claude Code with its own memory, commands, and scheduling.

agent-introspection-debugging

Structured self-debugging workflow for AI agent failures using capture, diagnosis, contained recovery, and introspection reports. Use when an agent run fails and you need a reproducible diagnosis instead of a retry.

agent-payment-x402

Add x402 payment execution to AI agents with per-task budgets, spending controls, and non-custodial wallets. Supports Base through agentwallet-sdk and X Layer through OKX Payments / OKX Agent Payments Protocol. Use when an agent must pay for something itself and needs per-task budgets, spending controls, and a non-custodial wallet.

agent-self-evaluation

Use after completing any non-trivial task. The agent self-rates its output on 5 axes — accuracy, completeness, clarity, actionability, conciseness — with concrete evidence per criterion. Produces a structured 1-5 scorecard with specific improvement suggestions.

agent-sort

Build an evidence-backed ECC install plan for a specific repo by sorting skills, commands, rules, hooks, and extras into DAILY vs LIBRARY buckets using parallel repo-aware review passes. Use when ECC should be trimmed to what a project actually needs instead of loading the full bundle.

ai-first-engineering

Engineering operating model for teams where AI agents generate a large share of implementation output. Use when setting team process, review gates, or ownership rules for a codebase largely written by agents.

ai-regression-testing

Regression testing strategies for AI-assisted development. Sandbox-mode API testing without database dependencies, automated bug-check workflows, and patterns to catch AI blind spots where the same model writes and reviews code. Use when adding regression coverage to AI-assisted code, or when the same model both wrote and reviewed a change.

android-clean-architecture

Clean Architecture patterns for Android and Kotlin Multiplatform projects — module structure, dependency rules, UseCases, Repositories, and data layer patterns. Use when structuring modules, layers, or data flow in an Android or KMP project.

angular-developer

Generates Angular code and provides architectural guidance. Trigger when creating projects, components, or services, or for best practices on reactivity (signals, linkedSignal, resource), forms, dependency injection, routing, SSR, accessibility (ARIA), animations, styling (component styles, Tailwind CSS), testing, or CLI tooling.

関連スキル

steipete/video-frames

Extract frames or short clips from videos using ffmpeg.

community

steipete/summarize

Summarize or transcribe URLs, YouTube/videos, podcasts, articles, transcripts, PDFs, and local files.

community

openclaw/openclaw

Use when testing, fixing, or extending the OpenClaw Control UI GUI with Vitest + Playwright end-to-end checks, mocked Gateway WebSocket flows, mocked dashboard runs, screenshots/videos, or agent-verifiable browser proof.

community

obra/superpowers

Obra superpowers agent skills.

community

affaan-m/ECC

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio...

community

affaan-m/everything-claude-code

End-to-end marketing campaign planning and execution. Covers audience research, positioning, campaign angle definition, landing page copy, email sequences, social posts, ad copy, short-form video scripts, and content calendars. Use as the orchestration layer for multi-channel product launches. Use when planning or executing a multi-channel product launch, or producing landing page, email, social, or ad copy.

community