spec-runner 1.1.7 → 1.1.8

package/spec-runner/templates/.claude/agents/design-reviewer.md

@@ -0,0 +1,65 @@
+---
+name: design-reviewer
+description: 設計書（docs/）と実装コード（src/）の整合性をチェックする。設計書と実装の乖離が心配なときに使用する。
+tools: Read, Grep, Glob
+model: sonnet
+---
+
+# 設計書⇔実装 整合性チェックエージェント
+
+docs/ 配下の設計書と src/ 配下の実装コードを突合し、乖離を報告する。
+
+## 手順
+
+1. docs/ 配下の設計書ファイルを一覧取得する
+2. 各設計書の frontmatter を読み、`spec_runner.node_id` / `kind` / `depends_on` / `maps_to` を確認する
+3. `docs/02_概要設計/**` は上位設計として扱い、ユースケース・責務・外部 IF・非機能方針が実装に反映されているか確認する
+4. `docs/03_詳細設計/src/**` は `maps_to` で対応先コードを特定し、責務・入出力・判断条件・テスト観点を比較する
+5. `docs/03_詳細設計/infrastructure/**` などの例外文書も `maps_to` を起点に IaC / 設定 / DB 定義と比較する
+6. 乖離を報告する
+
+## チェック項目
+
+### frontmatter
+
+- **必須項目**: `node_id` / `kind` / `depends_on` / `maps_to` が存在するか
+- **依存整合**: `depends_on` の参照先が実在するか。依存の向きが明らかに逆転していないか
+- **対応整合**: `maps_to` の実ファイルが存在するか。変更対象が漏れていないか
+
+### 概要設計
+
+- **ユースケース整合**: `ユースケース一覧.md` と個別 UC が実装のエンドポイント・コマンド・画面遷移と一致しているか
+- **全体俯瞰**: `システム全体俯瞰.md` の責務分割・連携フロー・外部 IF が実装構造と一致しているか
+- **ADR 反映**: `docs/02_概要設計/90_ADR/**` の採用方針が概要設計・詳細設計に反映されているか
+
+### 詳細設計
+
+- **責務整合**: `docs/03_詳細設計/src/**` の責務記述が対応コードの責務と一致しているか
+- **入出力整合**: 関数シグネチャ、設定値、エラー処理、外部依存の扱いが設計どおりか
+- **テスト整合**: `maps_to` に含まれる `tests/**` が設計上の主要シナリオをカバーしているか
+- **不足 / 過剰**: 設計書にあるがコードにない、またはコードにあるが設計書にない要素があるか
+
+## 報告フォーマット
+
+```
+## 整合性チェック結果
+
+### frontmatterの問題
+- [ファイル]: [問題内容]
+
+### 一致（問題なし）
+- [ファイルペアの一覧]
+
+### 乖離あり
+#### [設計書ファイル] ⇔ [実装ファイル]
+- 種別: 不足 / 過剰 / 変更
+- 内容: [具体的な差分の説明]
+- 推奨対応: 設計書を更新 / 実装を修正
+```
+
+## 注意事項
+
+- 読み取り専用（コードや設計書の変更は行わない）
+- 日本語で報告する
+- ADR はコードと 1 対 1 の突合対象ではないが、配置先と反映有無は確認する
+- hard code のパス推定より frontmatter の `maps_to` を優先する

package/spec-runner/templates/.claude/agents/test-runner.md

@@ -0,0 +1,34 @@
+---
+name: test-runner
+description: コード変更後にテストを実行し、失敗時は原因分析まで行う。コード修正・機能追加の後に使用する。
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+# テスト実行エージェント
+
+テストをDocker環境で実行し、結果を分析する。
+
+## 手順
+
+1. `git diff --name-only` で変更ファイルを確認する
+2. 変更ファイルに対応するテストファイルを特定する（`tests/` 配下の同構造）
+3. テストを実行する:
+   - 対象テストが明確な場合: `docker compose run --rm test pytest tests/path/to/test_file.py -v`
+   - 全体実行が必要な場合: `docker compose run --rm test pytest -v`
+4. 結果を分析する
+
+## 失敗時の分析
+
+テストが失敗した場合、以下を報告する:
+
+- **失敗したテスト**: テスト名とファイルパス
+- **エラー内容**: アサーションエラーやスタックトレースの要約
+- **原因の推定**: 変更内容との関連性を分析
+- **修正案**: 具体的なコード修正の提案（コード例を含める）
+
+## 注意事項
+
+- テスト実行は必ず `docker compose run --rm test pytest` で行う
+- コードの修正は行わない（分析と提案のみ）
+- 日本語で報告する

package/spec-runner/templates/.claude/rules/coding.md

@@ -0,0 +1,106 @@
+---
+description: コーディング規約（命名規則・型・コメント・テスト構成）
+paths: ["src/**", "tests/**"]
+---
+
+# コーディング規約
+
+## 命名規則
+
+| 対象 | 規則 | 例 |
+|------|------|-----|
+| ファイル名 | snake_case | `domain.py`, `journal_search.py` |
+| クラス名 | PascalCase | `CheckExecution`, `AccountBalance` |
+| 関数・メソッド | snake_case | `aggregate_by_account()`, `determine_severity()` |
+| 変数 | snake_case | `journal_entries`, `diff_amount` |
+| 定数 | UPPER_SNAKE_CASE | `THRESHOLD_ERROR`, `_VALID_SEVERITIES` |
+| モジュール内部定数 | _UPPER_SNAKE_CASE（先頭アンダースコア） | `_THRESHOLD_WARNING` |
+| テストクラス | Test + PascalCase | `TestDetermineSeverity` |
+| テストメソッド | test_ + snake_case（日本語不可） | `test_empty_entries_raises` |
+| ディレクトリ | snake_case | `agents/reconciliation/`, `plugins/tools/` |
+
+## コメント・docstring
+
+- **言語**: 日本語
+- **docstring**: モジュール先頭に1行で概要を書く。関数・クラスには原則不要（名前で意図が伝わる場合）
+- **インラインコメント**: ビジネスロジックの「なぜ」を説明する場合のみ。処理内容の「何」は書かない
+
+```python
+# 良い例
+# 貸方は負の値として扱う（借方 - 貸方 = 残高）
+balances[credit_key] = balances.get(credit_key, 0) - entry.credit_amount
+```
+
+## 型
+
+- Python 3.12+ のビルトイン型を使用（`list[str]`, `dict[str, int]`, `str | None`）
+- `typing` モジュールのインポートは不要（`List`, `Dict`, `Optional` は使わない）
+- dataclass の `frozen=True` を値オブジェクトに使用
+
+## テスト
+
+- テストファイルは実装と同じディレクトリ構造: `tests/agents/reconciliation/test_domain.py`
+- TDDサイクル: RED → GREEN → REFACTOR
+
+### テストコメント規約
+
+- **docstring**: 全テストメソッドにテスト意図を日本語1行で書く（メソッド名の言い換えではなく「なぜそのテストが必要か」を書く）
+- **セクション区切り**: テストクラスが3つ以上あるファイルでは、クラス間に区切りコメントを入れる
+
+```python
+# ============================================================
+# 重要度判定
+# ============================================================
+class TestDetermineSeverity:
+```
+
+- **準備・実行・検証**: セットアップが5行以上のテストでは `# 準備` / `# 実行` / `# 検証` で構造を明示する。`—` で簡潔な意図を添える（推奨）
+
+```python
+def test_full_flow(self):
+    """集計→比較→分析の全フローが動作する"""
+    # 準備 — 仕訳と調書に50K円の差異を作る
+    agent = self._make_agent()
+    entries = [_make_entry("売掛金", "売上高", 1_000_000)]
+    worksheet = [_make_balance("worksheet", "売掛金", 950_000)]
+
+    # 実行
+    results = agent.run_check(entries, worksheet, [])
+
+    # 検証 — 差異がある科目のみ返る
+    assert len(results) == 1
+    assert results[0].severity.value == "error"
+```
+
+- **インラインコメント**: データ構造やモック応答の意図が分かりにくい箇所には積極的にコメントを付ける。特にリスト要素やside_effectの各要素には `# 計画`、`# 1パス目分析` のように役割を明示する
+
+```python
+llm.chat.side_effect = [
+    plan_json,                    # 計画
+    _make_analysis_response(),    # 1パス目分析
+    investigation_needs,          # 調査判断1: 追加調査必要
+    _make_analysis_response(),    # 再分析1
+    # ここで上限到達 → ループ終了
+]
+
+# 1回目: 途中で切れたJSON、2回目: リトライで正しいJSON
+truncated_json = '[{"account_name": "売掛金", ...'
+```
+
+- **英語コメント禁止**: `Arrange` / `Act` / `Assert` 等の英語は使わない
+
+## 検索ルール
+
+- コードの検索・置換は `src/` と `tests/` の両方を対象にする
+- 日本語のキーワード（後方互換、レガシー等）も検索対象に含める
+
+## プロジェクト構造
+
+```
+src/
+  agents/{agent_name}/     # agent.py, domain.py, prompts.py, config.py
+  plugins/tools/{tool}/    # tool.py
+  plugins/skills/{skill}/  # skill.py
+  web/                     # FastAPI + HTMX
+tests/                     # src/ と同じ構造
+```

package/spec-runner/templates/.claude/rules/design-docs.md

@@ -0,0 +1,63 @@
+---
+description: 設計書共通ルール（frontmatter・命名規則・ADR・文書品質）
+paths: ["docs/**"]
+---
+
+# 設計書共通ルール
+
+## フェーズ管理
+
+- **ユーザー承認なしにフェーズを進めない**
+- フェーズは必ず `要件定義 -> 概要設計 -> 詳細設計 -> TDD -> 実装` の順に進める
+
+## テンプレート
+
+- **設計書は必ずテンプレートをコピーして生成する。独自にゼロから作成しない**
+- 手順: テンプレートを読む → 出力先へコピーする → プレースホルダーを埋める
+
+## frontmatter
+
+- **`docs/**` の全設計書に frontmatter を付ける**
+- 正本の必須項目は `spec_runner.node_id` / `spec_runner.kind` / `spec_runner.depends_on` / `spec_runner.maps_to`
+- `depends_on` はまず文字列配列でよい。依存理由が必要な場合のみオブジェクト形式を使う
+- `maps_to` には見直し対象となる `src/` / `tests/` / IaC / 設定ファイルを列挙する
+- `modules` / `source_files` などの拡張項目を足す場合でも、`maps_to` と矛盾させない
+
+```yaml
+---
+spec_runner:
+  node_id: detail.src.agents.reconciliation.agent
+  kind: detailed_design
+  depends_on:
+    - overview.system_context
+    - use_case.reconciliation.list
+  maps_to:
+    - src/agents/reconciliation/agent.py
+    - tests/agents/reconciliation/test_agent.py
+---
+```
+
+## 命名規則
+
+| 対象 | 規則 | 例 |
+|------|------|-----|
+| `docs/01_要件定義` | 日本語 | `要件定義.md` |
+| `docs/02_概要設計` | 日本語 | `ユースケース一覧.md`, `システム全体俯瞰.md` |
+| `docs/02_概要設計/ユースケース` | `UC-{日本語名}.md` | `UC-差異一覧表示.md` |
+| `docs/02_概要設計/90_ADR` | `ADR-0001-{slug}.md` | `ADR-0001-detailed-design-mirrors-src.md` |
+| `docs/03_詳細設計/src/**` | `src/` に合わせた英語 `snake_case` | `agent.md`, `domain.md`, `skill.md` |
+| `docs/03_詳細設計/infrastructure/**` | 対応先に合わせる。例外で置く場合も `maps_to` 必須 | `database.md`, `schema.dbml` |
+
+## ADR
+
+- **ADR は必ず 3 案を比較してから採用案を決める**
+- ADR は原則 `docs/02_概要設計/90_ADR/` に置く
+- ドメインローカル ADR が必要な場合だけ `docs/02_概要設計/<ドメイン>/90_ADR/` を使う
+- ADR は理由の記録であり、詳細設計の代わりにしない
+
+## 文書品質
+
+- **概要設計では「何をするか」を書き、コード片・DDL・クラス定義は持ち込まない**
+- **詳細設計では `src/` に対応する責務・入出力・判断条件・テスト観点を書く**
+- **`docs/03_詳細設計` は原則 `src/` ミラーにする。例外文書は `maps_to` で根拠を残す**
+- **Markdown に HTML タグ（details, summary, br など）を使わない**

package/spec-runner/templates/.claude/skills/architecture-definition/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: architecture-definition
+description: 新規プロジェクトで docs と `.spec-runner/architecture/architecture.yaml` を立ち上げるための初期化フロー。
+---
+
+# architecture-definition
+
+新規プロジェクト向けの初期化フロー。
+要件定義から概要設計、architecture contract の作成までを先に固め、その後に project 専用 skill の開発へ渡す。
+
+## 全体フロー
+
+```
+Phase 1: 要件整理
+Phase 2: 概要設計の骨格作成
+Phase 3: アーキテクチャ判断の明文化
+Phase 4: architecture contract 作成
+Phase 5: 次の skill へ引き渡し
+```
+
+## Phase 1: 要件整理
+
+1. ユーザーから背景、提供価値、制約、スコープ外を確認する
+2. `docs/01_要件定義/要件定義.md` を作る
+3. frontmatter を付ける
+4. ユーザーに確認・承認を得る
+
+## Phase 2: 概要設計の骨格作成
+
+1. `docs/02_概要設計/ユースケース一覧.md` を作る
+2. `docs/02_概要設計/システム全体俯瞰.md` を作る
+3. 必要に応じて `ユースケース/`、`外部IF一覧.md`、`非機能・運用方針.md` を追加する
+4. ユーザーに確認・承認を得る
+
+## Phase 3: アーキテクチャ判断の明文化
+
+1. ドメイン分割、責務境界、実装単位、インフラ方針を整理する
+2. 必要なら `docs/02_概要設計/90_ADR/` に ADR を作る
+3. ユーザーに確認・承認を得る
+
+## Phase 4: architecture contract 作成
+
+1. `.spec-runner/architecture/architecture.yaml` を作る
+2. 最低限、以下を構造化する
+   - domain_structure
+   - runtime_units
+   - design_policy
+   - testing_policy
+3. ユーザーに確認・承認を得る
+
+## Phase 5: 次の skill へ引き渡し
+
+1. `architecture-skill-development` に渡す前提を整理する
+2. project 専用 skill に切り出すべき反復フローを列挙する
+
+## 原則
+
+- docs を先に作る
+- `.spec-runner/` は補助情報として扱う
+- project 専用 skill を作る前にアーキテクチャを固める

package/spec-runner/templates/.claude/skills/architecture-skill-development/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: architecture-skill-development
+description: architecture contract と docs を読み、プロジェクト専用の skill / rule / template を育てるフロー。
+---
+
+# architecture-skill-development
+
+`architecture-definition` または `existing-project-to-docs` の後に使う。
+決まったアーキテクチャから、そのプロジェクト専用の skill / rule / template を作る。
+
+## 全体フロー
+
+```
+Phase 1: 入力の確認
+Phase 2: 反復フローの抽出
+Phase 3: skill / rule / template へ分解
+Phase 4: 基盤 skill のプロジェクト固有化
+Phase 5: Claude / Copilot テンプレートへ反映
+Phase 6: 一貫性の検証
+Phase 7: セットアップ専用 skill のアーカイブ提案
+```
+
+## Phase 1: 入力の確認
+
+1. `docs/01_要件定義/**`, `docs/02_概要設計/**`, `docs/03_詳細設計/**` を読む
+2. `.spec-runner/architecture/architecture.yaml` を読む
+3. 固定化すべき判断と project 固有判断を切り分ける
+
+## Phase 2: 反復フローの抽出
+
+1. よく繰り返す作業を抽出する
+2. どこにユーザー承認が必要かを決める
+3. 影響調査や TDD など共通 skill をどうつなぐか決める
+4. ユーザーに確認・承認を得る
+
+## Phase 3: skill / rule / template へ分解
+
+1. 会話フローは skill にする
+2. 常時守る約束は rule にする
+3. 毎回コピーする設計書は template にする
+
+### plugin-development を種として使う
+
+新規開発フローの skill を作る場合は、`plugin-development` を種として使う。
+`plugin-development` はプラグイン型アーキテクチャ向けの reference workflow であり、
+そのまま使うのではなく、**このプロジェクトのアーキテクチャに合わせて書き換えた project 専用 skill を作る**ことを目的とする。
+
+具体的には:
+- `.claude/skills/plugin-development/SKILL.md` をコピーして、project 専用の開発 skill の土台にする
+- フェーズ構成・テンプレートパス・用語をこのプロジェクトの実態に合わせて書き換える
+- 元の `plugin-development` は書き換え完了後にアーカイブ候補とする（Phase 7 で提案する）
+
+ユーザーに確認・承認を得る
+
+## Phase 4: 基盤 skill のプロジェクト固有化
+
+インストール時に配布された基盤 skill のプレースホルダーを、このプロジェクトの実態に書き換える。
+
+### test-driven-development の書き換え
+
+`architecture.yaml` の `testing_policy` と `language` を参照して、以下を実際の値に置き換える。
+
+1. **テスト実行コマンド** — `<your-test-command>` を実際のコマンドに書き換える
+
+   例:
+   ```bash
+   # 全テスト
+   docker compose run --rm test pytest
+
+   # 特定ファイル
+   docker compose run --rm test pytest tests/path/to/test_file.py
+
+   # カバレッジ計測
+   docker compose run --rm test pytest --cov=. --cov-report=term-missing
+   ```
+
+2. **コード例** — 言語・フレームワークに合わせて RED / GREEN の例を書き直す
+
+3. **fixture / テストデータ** — このプロジェクトの実際のクラス名・DB 接続方法・ヘルパ関数パターンを記述する
+
+4. **モックのルール** — 使用する外部サービスとモック手段（ライブラリ名など）を具体化する
+
+書き換えは `.claude/skills/test-driven-development/SKILL.md` と `.github/skills/test-driven-development/SKILL.md` の両方に反映する。
+
+### その他の基盤 skill
+
+同様のプレースホルダーや汎用記述が他の skill にあれば、同じ要領で書き換える。
+
+ユーザーに確認・承認を得る
+
+## Phase 5: Claude / Copilot テンプレートへ反映
+
+1. `.claude/` と `.github/` の両方へ反映する
+2. path や naming がずれないよう対応ファイルを揃える
+
+## Phase 6: 一貫性の検証
+
+1. 既存 skill / rule / agent と矛盾しないか確認する
+2. `harness-engineering` が必要な改善点を洗い出す
+
+## Phase 7: セットアップ専用 skill のアーカイブ提案
+
+セットアップ時にしか使わない skill は、開発ループに入ると不要になる。
+**ユーザーの承認を得てから** 整理する。絶対に自動で削除・移動しない。
+
+### アーカイブ候補
+
+| skill | 理由 |
+|---|---|
+| `architecture-definition` | 新規プロジェクト初期化専用。アーキテクチャ確定後は不要 |
+| `existing-project-to-docs` | 既存プロジェクト取り込み専用。docs 生成後は不要 |
+| `plugin-development` | Phase 3 で project 専用 skill の種として使い終えたら不要 |
+| `architecture-skill-development`（このファイル自身） | project 専用 skill が安定したら不要。ただしアーキテクチャが大きく変わる場合は再利用する可能性があるため、削除ではなくアーカイブを推奨 |
+
+### 手順
+
+1. 上記の候補をユーザーに提示し、整理してよいか確認する
+2. 承認を得た skill を `.claude/skills/` と `.github/skills/` から削除する
+3. 必要であれば削除前にバックアップ先をユーザーに伝える
+
+## 原則
+
+- 固定の architecture pack を増やしすぎない
+- project 専用 skill を先に考える
+- docs と architecture contract の両方を入力にする
+- **skill の削除・移動はユーザー承認なしに行わない**

package/spec-runner/templates/.claude/skills/commit/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: commit
+description: 変更を Conventional Commits 形式でコミットする。
+---
+
+# commit
+
+変更を Conventional Commits 形式でコミットする。
+
+## 手順
+
+1. `git status` と `git diff --cached`（ステージ済み）または `git diff`（未ステージ）で変更内容を確認する
+2. `git log --oneline -10` で直近のコミット履歴を確認する
+3. 変更内容に基づいてコミットメッセージを生成する
+4. 未ステージの場合は適切なファイルを `git add` する
+5. **機密情報チェック**: `git diff --cached` の内容を確認し、以下のパターンが含まれていないか検査する
+   - API キー、シークレットキー、パスワード、トークン、秘密鍵、接続文字列
+   - `.env` ファイルの内容、認証情報ファイル（`credentials.json` 等）
+   - 検出した場合はコミットを中止し、ユーザーに報告する
+6. コミットを実行する
+
+## コミットメッセージ形式
+
+```
+<type>: <summary>
+
+<body（任意）>
+```
+
+### type（必須）
+
+| type | 用途 |
+|------|------|
+| `feat` | 新機能・新規ファイル追加 |
+| `fix` | バグ修正 |
+| `docs` | ドキュメントのみの変更 |
+| `refactor` | リファクタリング（機能変更なし） |
+| `test` | テストの追加・修正 |
+| `chore` | ビルド・設定・CI 等の変更 |
+| `style` | フォーマット・命名変更（動作変更なし） |
+
+### summary（必須）
+
+- 日本語で書く
+- 末尾に句点（。）をつけない
+- 命令形ではなく体言止め or 「〜を追加」「〜を修正」形式
+- 50 文字以内を目安
+
+### body（任意）
+
+- 変更が大きい場合のみ記載
+- 「なぜ」この変更をしたかを書く（「何を」は diff で分かる）
+- チーム運用で必要な場合のみ `Co-Authored-By` を追加する
+
+## 例
+
+```
+feat: 突合チェックエージェントを追加
+```
+
+```
+docs: 要件定義・概要設計を追加
+```
+
+```
+chore: Docker 構成を追加
+```
+
+```
+feat: スキル 4 種とツール 3 種を追加
+
+売掛金・役員報酬・汎用残高・租税公課チェックスキル、
+科目別集計・仕訳検索・3 ソース比較ツール
+```
+
+```
+fix: 科目名正規化で建設業科目が漏れていた問題を修正
+```
+
+## 原則
+
+- `git add .` や `git add -A` は使わない（ファイル名を明示する）
+- 1 コミットに複数の論理的変更を混ぜない

package/spec-runner/templates/.claude/skills/design-change/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: design-change
+description: 既存機能の変更を docs 正本で進めるフローガイド。軽い影響調査、ADR、概要設計、詳細設計、TDD を順に進める。
+---
+
+# design-change
+
+既存機能の変更・修正を設計書駆動で進めるフローガイド。
+**フェーズを必ず順番通りに進める。ユーザーの承認なしにフェーズを先に進めない。**
+
+影響範囲のチェックリストは `references/影響範囲チェックリスト.md` を参照する。
+ADR テンプレートは `templates/90_ADR/ADRテンプレート.md` を使用する。
+
+## 全体フロー
+
+```
+Phase 1: 変更要求の整理と軽い影響調査
+Phase 2: ADR 作成（必要時）
+Phase 3: 影響ドキュメントの確定
+Phase 4: 概要設計の修正
+Phase 5: 詳細設計の修正
+Phase 6: TDD → 実装 → 検証
+```
+
+## Phase 1: 変更要求の整理と軽い影響調査
+
+1. 以下をユーザーにヒアリングする
+   - 変更の背景・課題
+   - 変更の目的・期待する結果
+   - 影響を受ける機能カテゴリ
+   - 技術的・ビジネス的制約
+2. 変更起点となる docs を特定する
+3. frontmatter の `depends_on` / `maps_to` を使って影響候補を軽く洗う
+4. 変更が影響するドメインと成果物を一覧化する
+5. ユーザーに確認・承認を得る
+
+## Phase 2: ADR 作成（必要時）
+
+1. アーキテクチャ、責務境界、保存方式、外部 IF などの意思決定が必要か判定する
+2. 必要な場合は **3 案を提示する**
+3. 各案について概要・メリット・デメリット・適合性を示す
+4. ユーザーが案を決定する
+5. テンプレート `templates/90_ADR/ADRテンプレート.md` をコピーして生成する
+6. ファイル名は `ADR-0001-{slug}.md` 形式にする
+
+### ADR 配置ルール
+
+| 変更スコープ | 配置先 |
+|------------|--------|
+| 横断的な決定 | `docs/02_概要設計/90_ADR/` |
+| 特定ドメイン寄りの決定 | `docs/02_概要設計/<ドメイン>/90_ADR/` |
+
+MVP では `docs/02_概要設計/90_ADR/` に集約する。
+
+## Phase 3: 影響ドキュメントの確定
+
+1. `references/影響範囲チェックリスト.md` を読み、変更に応じた影響ドキュメントを網羅的に洗い出す
+2. frontmatter の `depends_on` / `maps_to` を使って候補を絞る
+3. 修正が必要なファイルをチェックリスト形式で提示する
+4. `@design-reviewer` エージェントに委任して、現時点の設計書⇔実装の乖離も合わせて確認する
+5. ユーザーに確認・承認を得る
+
+## Phase 4: 概要設計の修正
+
+1. `ユースケース一覧.md` / `システム全体俯瞰.md` / UC 個別文書 / ADR を必要順に修正する
+2. 修正完了ごとにチェックリストを更新する
+3. 全概要設計の修正完了後、ユーザーに確認・承認を得る
+
+### 修正時の注意
+
+- 変更理由は ADR または本文で追えるようにする
+- 概要設計では「何をするか」に留める
+
+## Phase 5: 詳細設計の修正
+
+1. `docs/03_詳細設計/src/**` を `src/` ミラーで修正する
+2. 補助設計が必要な場合だけ `docs/03_詳細設計/infrastructure/**` を修正する
+3. frontmatter の `depends_on` / `maps_to` を更新する
+4. ユーザーに最終確認を得る
+
+## Phase 6: TDD → 実装 → 検証
+
+設計書修正が承認されたら `test-driven-development` スキルへ移行する。
+
+### 実装完了後のレビュー
+
+- `@design-reviewer` — frontmatter と `maps_to` を起点に設計書⇔実装の整合性チェック
+- `@code-reviewer` — コーディング規約への適合チェック
+
+## 原則
+
+- **影響候補の洗い出しを ADR より先に行う**
+- **概要設計を先に直し、そのあと詳細設計を直す**
+- **frontmatter の更新を後回しにしない**