blueprint-derive-adr

既存プロジェクトのコード構造、依存関係、ドキュメントを分析して、アーキテクチャ決定記録（ADR）を生成します。

このスキルを使用するタイミング

次の場合はこのスキルを使用してください...	次の場合は代わりに blueprint-derive-prd を使用してください...
コードから暗黙のアーキテクチャ上の決定を遡って文書化する場合	決定ではなく、README から要件やペルソナを抽出したい場合
フレームワーク、データベース、状態管理の選択を ADR として記録する必要がある場合	PRD＋ADR＋PRP をまとめて導出するには、代わりに blueprint-derive-plans を使用してください
既存プロジェクトのオンボーディングを行い、決定を記録に残したい場合	単一の ADR を作成または検証する場合は、代わりに adr-relationships を使用してください

ユースケース：既存プロジェクトを Blueprint Development システムに導入し、暗黙のアーキテクチャ上の決定を文書化します。

前提条件：

• Blueprint Development が初期化済みであること（docs/blueprint/ が存在する）
• PRD が存在することが望ましい（先に /blueprint:derive-prd を実行してください）

手順：

フェーズ 1：調査

1.1 前提条件の確認

ls docs/blueprint/manifest.json
ls docs/prds/

Blueprint が初期化されていない場合 → /blueprint:init を提案 PRD がない場合 → まず /blueprint:derive-prd を提案（推奨ですが、必須ではありません）

1.2 ADR ディレクトリの作成

mkdir -p docs/adrs

1.3 プロジェクト構造の分析

コードベースを調査して、アーキテクチャのパターンを特定します。

Explore エージェントを使用します：

<Task subagent_type="Explore" prompt="Analyze project architecture: directory structure, major components, frameworks used, design patterns">

調査する主な領域：

• ディレクトリ構造：コードの構成方法
• エントリーポイント：メインファイル、インデックスファイル
• 設定：設定ファイル、環境の処理
• 依存関係：パッケージマニフェスト、インポート
• データレイヤー：データベース、ORM、データモデル
• API レイヤー：ルート、コントローラー、ハンドラー
• テスト：テストの構成とフレームワーク

フェーズ 1.5：競合の分析

新しい ADR を生成する前に、競合する可能性のある既存の決定や、関連する決定がないか確認します。

1.5.1 既存の ADR の確認

ls docs/adrs/*.md 2>/dev/null | wc -l

ADR が存在する場合は、文書化しようとしている決定との競合の可能性を分析します。

1.5.2 新しい ADR のドメインの決定

決定カテゴリをドメインに対応付けます。

決定カテゴリ	ドメインタグ
状態管理	state-management
データベース／ORM	data-layer
フレームワークの選択	frontend-framework
API 設計	api-design
認証	authentication
テスト戦略	testing
スタイリングの方針	styling
ビルドツール	build-tooling
デプロイ	deployment

1.5.3 同じドメインに属する既存の ADR のスキャン

文書化する各ドメインについて：

grep -l "^domain: {domain}" docs/adrs/*.md

status: Accepted の一致する ADR ごとに：

• ADR 番号とタイトルを抽出する
• 決定の結果（選択された案）を抽出する
• 競合スコアを計算する：
  • 同じドメイン：+0.3
  • 両方とも Accepted：+0.2
  • 結果が反対または異なる：+0.4
  • 経過期間が 6 か月超：+0.1

1.5.4 競合の可能性を提示する

競合スコアが 0.7 以上の場合、ユーザーに確認します。

question: "Found existing ADR in same domain: ADR-{XXXX} - {title}. How should the new decision relate?"
options:
  - label: "Supersede ADR-{XXXX}"
    description: "New ADR replaces the existing decision"
  - label: "Extend ADR-{XXXX}"
    description: "New ADR builds on the existing decision"
  - label: "Mark as related"
    description: "Decisions are connected but independent"
  - label: "No relationship"
    description: "Continue without linking"

関係性の選択を保存し、生成する ADR のフロントマターに含めます。

1.5.5 複数の競合への対応

同じドメインに競合の可能性が複数ある場合：

• それぞれについてユーザーに判断を求める
• 古くなった複数の決定を置き換えるための「すべてを置き換える」一括オプションを用意する

フェーズ 2：アーキテクチャ上の決定の特定

2.1 よくある決定カテゴリ

カテゴリ	確認する内容	決定例
フレームワーク	package.json、インポート	React と Vue、Express と Fastify
言語	ファイル拡張子、tsconfig	TypeScript と JavaScript
状態管理	ストアのパターン、コンテキスト	Redux と Zustand と Context
スタイリング	CSS ファイル、スタイル付きインポート	Tailwind と CSS-in-JS と SCSS
テスト	テストファイル、テスト設定	Vitest と Jest、Playwright と Cypress
ビルド	ビルド設定、バンドラー	Vite と Webpack、esbuild
データベース	ORM 設定、マイグレーション	PostgreSQL と MongoDB、Prisma と Drizzle
API スタイル	ルートのパターン、スキーマ	REST と GraphQL、tRPC
デプロイ	Docker、CI 設定	コンテナーとサーバーレス
モノレポ	ワークスペース設定	Turborepo と Nx となし

2.2 コードから決定を推測する

特定した技術選択ごとに、次の手順を行います。

1. 現在の実装を記録します
2. よくある代替案を検討します
3. コンテキストやコメントから根拠を推測します

2.3 ユーザーに確認する

重要な決定については AskUserQuestion を使用します。

question: "I found the project uses {technology}. Why was this chosen over alternatives?"
options:
  - "Performance requirements" → document performance rationale
  - "Team familiarity" → document team expertise factor
  - "Ecosystem/community" → document ecosystem benefits
  - "Specific feature needs" → ask for details
  - "Legacy/inherited decision" → document as inherited
  - "Other" → custom rationale

question: "Are there any architecture decisions you'd like to document that aren't visible in the code?"
options:
  - "Yes, let me describe" → capture additional decisions
  - "No, the inferred decisions are sufficient" → proceed

フェーズ 3：ADR の生成

3.1 ADR テンプレート（MADR 形式）

重要な決定ごとに ADR を作成します。

---
id: ADR-{NNNN}                          # Derived from filename (0003-*.md → ADR-0003)
date: {YYYY-MM-DD}
status: Accepted | Superseded | Deprecated | Proposed
deciders: {who made the decision}
domain: {domain-tag}                    # Optional: state-management, data-layer, etc.
supersedes: ADR-{XXXX}                  # Optional: if superseding another ADR
extends: ADR-{XXXX}                     # Optional: if extending another ADR
relates-to:                             # Cross-document references
  - PRD-{NNN}                           # Related PRDs
  - ADR-{YYYY}                          # Related ADRs
github-issues: []                       # Linked GitHub issues
name: blueprint-derive-adr
---

# ADR-{number}: {Title}

## Context

{Describe the issue motivating this decision}
{What is the problem we're trying to solve?}
{What constraints exist?}

## Decision Drivers

- {driver 1, e.g., "Performance under high load"}
- {driver 2, e.g., "Developer experience"}
- {driver 3, e.g., "Maintainability"}

## Considered Options

1. **{Option 1}** - {brief description}
2. **{Option 2}** - {brief description}
3. **{Option 3}** - {brief description}

## Decision Outcome

**Chosen option**: "{Option X}" because {justification}.

### Positive Consequences

- {positive outcome 1}
- {positive outcome 2}

### Negative Consequences

- {negative outcome / tradeoff 1}
- {negative outcome / tradeoff 2}

## Pros and Cons of Options

### {Option 1}

- ✅ {pro 1}
- ✅ {pro 2}
- ❌ {con 1}

### {Option 2}

- ✅ {pro 1}
- ❌ {con 1}
- ❌ {con 2}

## Links

- {Related ADRs}
- {External documentation}
- {Discussion threads}

---
*Generated from project analysis via /blueprint:derive-adr*

3.2 生成する標準 ADR

該当する場合、次のよくある決定について ADR を生成します。

ADR	作成するタイミング
0001-project-language.md	言語／ランタイムの選択
0002-framework-choice.md	メインフレームワークの選択
0003-testing-strategy.md	テストフレームワークとアプローチ
0004-styling-approach.md	CSS／スタイリングの手法
0005-state-management.md	状態の管理方法（該当する場合）
0006-database-choice.md	データベースと ORM（該当する場合）
0007-api-design.md	API のスタイルとパターン
0008-deployment-strategy.md	デプロイのアプローチ

3.3 ADR README を作成する

blueprint-plugin/templates/adr-readme.md のテンプレートを使って、ADR README テンプレートを docs/adrs/README.md に書き込みます。

README は自己文書化されています。必要に応じて ADR インデックスを生成するプログラムによる fd + awk コマンドが含まれているため、同期がずれていく静的な表は不要になります。

書き込む際のカスタマイズ：

• フェーズ 2 の分析で文書化されていない決定を特定し、ユーザーが完全な ADR を作成しないことを選んだ場合は、それらを Proposed ADRs セクションに追加します。

  ## Proposed ADRs
  
  Decisions identified but not yet documented as full ADRs:
  
  - [ ] {Decision topic} — {brief context} (identified {YYYY-MM-DD})
  - [ ] {Decision topic} — {brief context} (identified {YYYY-MM-DD})
  

• プログラムによる一覧表示コマンドはそのまま残します。静的なインデックスの代わりとなります。

フェーズ 4：関連性の更新と検証

4.0 廃止された ADR を更新する（双方向の整合性）

新しい ADR が既存の ADR に取って代わる場合：

1. 廃止される ADR ファイルを読み取ります

2. フロントマターを更新します：

   • status: Accepted を status: Superseded に変更します
   • superseded_by: ADR-{new_number} を追加します

3. Links セクションを更新します（ない場合は追加します）：

   ## Links
   - Superseded by [ADR-{number}](./{filename}.md)
   

4. 更新内容を報告します：

   Updated ADR-{old_number}:
   - Status: Accepted → Superseded
   - Added: superseded_by: ADR-{new_number}
   - Updated Links section
   

例：ADR-0012 が ADR-0003 に取って代わる場合：

• ADR-0012 内：supersedes: ADR-0003
• ADR-0003 内：
  • status: Superseded
  • superseded_by: ADR-0012
  • Links セクションで ADR-0012 を参照

4.1 マニフェストを更新する

各 ADR について、docs/blueprint/manifest.json の ID レジストリを更新します。

{
  "id_registry": {
    "documents": {
      "ADR-0003": {
        "path": "docs/adrs/0003-database-choice.md",
        "title": "Database Choice",
        "status": "Accepted",
        "domain": "data-layer",
        "relates_to": ["PRD-001"],
        "github_issues": [],
        "created": "{date}"
      }
    }
  }
}

4.2 概要を提示する

✅ ADRs Generated: {count} records

**Location**: `docs/adrs/`

**Decisions documented**:
- ADR-0001: {title} - {status} [{domain}]
- ADR-0002: {title} - {status} [{domain}]
...

**Relationships established**:
- ADR-{new} supersedes ADR-{old} (status updated)
- ADR-{new} extends ADR-{existing}
- ADR-{new} related to ADR-{other}

**ADRs updated** (bidirectional consistency):
- ADR-{old}: status → Superseded, superseded_by → ADR-{new}

**Sources analyzed**:
- {list of analyzed files/patterns}

**Confidence levels**:
- High confidence: {list - clear from code}
- Inferred: {list - reasonable assumptions}
- Needs review: {list - uncertain}

**Recommended next steps**:
1. Review generated ADRs for accuracy
2. Add rationale where marked as "inferred"
3. Run `/blueprint:derive-adr-validate` to check relationship consistency
4. Run `/blueprint:prp-create` for feature implementation
5. Run `/blueprint:generate-skills` for project skills

4.2 次のステップを提案する

• PRD がない場合 → /blueprint:derive-prd を提案します
• 実装の準備ができている場合 → /blueprint:prp-create を提案します
• アーキテクチャが進化している場合 → 新しい ADR の追加方法を説明します

フェーズ 5：マニフェストを更新する

docs/blueprint/manifest.json を更新します。

• structure に has_adrs: true を追加します
• generated_artifacts に ADR を追加します
• updated_at タイムスタンプを更新します

ヒント：

• 実際に代替案がある決定に焦点を当てます（自明な選択は対象外です）
• 継承した決定やレガシーの決定は、その旨を記録します
• 根拠が不確かな場合は、ユーザーによる確認が必要であることを明記します
• ADR は簡潔に保ち、実装の詳細ではなく「理由」に焦点を当てます
• 決定同士に関連がある場合は、関連する ADR を参照します

4.3 次のアクションのプロンプト（AskUserQuestion を使用）：

question: "ADRs generated. What would you like to do next?"
options:
  - label: "Create a PRP for feature work (Recommended)"
    description: "Start implementing a specific feature with /blueprint:prp-create"
  - label: "Generate project skills"
    description: "Create skills from PRDs for Claude context"
  - label: "Review and add rationale"
    description: "Edit ADRs marked as 'inferred' or 'needs rationale'"
  - label: "Document another architecture decision"
    description: "Manually add a new ADR"
  - label: "I'm done for now"
    description: "Exit - ADRs are saved"

選択に基づくアクション：

• 「PRP を作成」→ /blueprint:prp-create を実行します（機能名を尋ねます）
• 「プロジェクトスキルを生成」→ /blueprint:generate-skills を実行します
• 「レビューして根拠を追加」→ 対応が必要な ADR ファイルを表示します
• 「別の決定を文書化」→ 特定の決定についてフェーズ 2 を再開します
• 「完了」→ 終了します

エラー処理：

• コードベースが最小限の場合 → 数を減らし、より広範な ADR を作成します
• パターンが競合する場合 → どちらが意図されたものかをユーザーに尋ねます
• 根拠が不明確な場合 → ユーザーの入力が必要なものとして「根拠が必要」とマークします