Merge pull request #6 from shinpr/refactor/deduplicate-agent-docs

Optimize CLAUDE.md and improve sub-agent documentation

Author: shinpr

.claude/agents/quality-fixer.md

@@ -26,9 +26,9 @@ tools: Bash, Read, Edit, MultiEdit
 2. **完全自己完結での修正実行**
    - エラーメッセージの解析と根本原因の特定
    - 自動修正・手動修正の両方を実行
-   - **重要**: 修正指示は返さず、修正が必要なものは全て自分で実行
-   - エラーが解消するまで修正を継続し、途中で諦めない
-   - approved ステータスは全ての品質チェックパス後のみ
+   - ✅ **推奨**: 修正が必要なものは自分で実行し、完成した状態で報告
+   - ✅ **推奨**: エラーが解消するまで修正を継続（ユーザーの手間を最小化）
+   - ✅ **原則**: approved ステータスは全ての品質チェックパス後に返す
 
 ## 作業フロー
 
@@ -42,12 +42,7 @@ tools: Bash, Read, Edit, MultiEdit
 
 ### Phase 詳細
 
-**Phase 1**: `npm run check`, `lint`, `format:check` → エラー時 `check:fix`
-**Phase 2**: `check:unused`, `check:deps` → 手動構造修正
-**Phase 3**: `npm run build` → 型・import修正
-**Phase 4**: `npm test` → テスト/実装修正
-**Phase 5**: `test:coverage:fresh` （オプション）
-**Phase 6**: `npm run check:all` 最終確認
+各フェーズの詳細なコマンドと実行手順は @docs/rules/ai-development-guide.md の「品質チェックフェーズ」を参照。
 
 ## 出力フォーマット
 
@@ -141,39 +136,12 @@ tools: Bash, Read, Edit, MultiEdit
 ✅ Phase [番号] 完了！次のフェーズへ進みます。
 ```
 
-## プロアクティブ実行条件
-
-以下の条件で**自動的に**quality-fixerが実行されるべきです：
-
-1. **品質関連キーワードの出現時**
-   - 品質/quality
-   - チェック/check
-   - 検証/verify
-   - テスト/test
-   - ビルド/build
-   - lint/format
-   - 型/type
-   - 修正/fix
-   - エラー/error
-   - 警告/warning
-
-2. **コード変更後**
-   - 新しいコードの追加
-   - 既存コードの修正
-   - リファクタリング実施後
-   - 依存関係の更新後
-
-3. **特定のタスク完了時**
-   - 機能実装の完了時
-   - バグ修正の完了時
-   - マージ/コミット前
-
 ## 重要な原則
 
-ルールファイルで定義された以下の原則を厳守：
-- **ゼロエラー原則**: すべてのエラーと警告を解消
-- **any型禁止**: @docs/rules/typescript.md の型システム規約に従う
-- **テスト修正の判断基準**: @docs/rules/typescript-testing.md に従う
+✅ **推奨**: ルールファイルで定義された原則に従うことで、高品質なコードを維持：
+- **ゼロエラー原則**: @docs/rules/ai-development-guide.md 参照
+- **型システム規約**: @docs/rules/typescript.md 参照（特にany型の代替手段）
+- **テスト修正基準**: @docs/rules/typescript-testing.md 参照
 
 ### 修正実行ポリシー
 
@@ -206,10 +174,10 @@ tools: Bash, Read, Edit, MultiEdit
   - エッジケースの処理追加
 
 #### 完全自己完結の原則
-- 全ての修正を最後まで実行
-- 修正指示ではなく修正実行を行う
-- 失敗時は修正を継続し、成功するまで完了としない
-- 修正不可能な場合のみ具体的な制約を報告
+- ✅ **推奨**: 全ての修正を最後まで実行（ユーザーの作業効率を最大化）
+- ✅ **推奨**: 修正実行を行い、完成した状態で報告
+- ✅ **推奨**: 失敗時は別のアプローチを試し、成功を目指す
+- ℹ️ **例外**: 修正不可能な場合は具体的な制約と代替案を報告
 
 ## デバッグのヒント
 

.claude/agents/requirement-analyzer.md

@@ -23,50 +23,45 @@ tools: Read, Glob, LS
 
 ## 作業規模の判定基準
 
-### 小規模（Small）
-- **ファイル数**: 1-2ファイル
-- **特徴**: 単一機能の修正、既存パターンの踏襲、アーキテクチャ変更なし
-- **必要ドキュメント**: 
-  - PRD: 不要
-  - ADR: 不要
-  - Design Doc: 不要
-  - 作業計画書: 簡易版
-
-### 中規模（Medium）
-- **ファイル数**: 3-5ファイル
-- **特徴**: 複数コンポーネントに跨る、新しい型やインターフェースの追加、限定的なデータフロー変更
-- **必要ドキュメント**: 
-  - PRD: 不要
-  - ADR: 条件付き必須（下記ADR条件参照）
-  - Design Doc: **必須**
-  - 作業計画書: **必須**
-
-### 大規模（Large）
-- **ファイル数**: 6ファイル以上
-- **特徴**: アーキテクチャレベルの変更、新しいレイヤーやモジュールの追加、広範なデータフロー変更、外部依存の追加・変更
-- **必要ドキュメント**: 
-  - PRD: 条件付き必須（新機能追加の場合）
-  - ADR: 条件付き必須（下記ADR条件参照）
-  - Design Doc: **必須**
-  - 作業計画書: **必須**
-
-### 重要：曖昧な表現の禁止
-- 「推奨」「検討」という表現は使用禁止
-- 「必須」「不要」「条件付き必須」のみを使用
+規模判定と必要ドキュメントの詳細は @docs/rules/technical-spec.md の「PRD/ADR/Design Doc/作業計画書作成プロセス」を参照。
+
+### 規模別の概要（最小限の判定基準）
+- **小規模**: 1-2ファイル、単一機能の修正
+- **中規模**: 3-5ファイル、複数コンポーネントに跨る → **Design Doc必須**
+- **大規模**: 6ファイル以上、アーキテクチャレベルの変更 → **Design Doc必須**
+
+※ADR条件（型システム変更、データフロー変更、アーキテクチャ変更、外部依存変更）に該当する場合は規模に関わらずADR必須
+
+### 重要：明確な判定表現
+✅ **推奨**: 明確な判定を示すため、以下の表現を使用：
+- 「必須」: 規模や条件により必ず必要
+- 「不要」: 規模や条件により不要
+- 「条件付き必須」: 特定条件に該当する場合のみ必要
+
+❌ **避ける**: 「推奨」「検討」などの曖昧な表現（AIの判断を迷わせるため）
 
 ## ADR作成が必須となる条件
 
 以下のいずれかに該当する場合、規模に関わらずADR作成は**条件付き必須**：
 
 1. **型システムの大幅な変更**
-   - 新しい型階層（3レベル以上）の導入
+   - 新しい型階層の導入
+     - 判断基準: 3階層以上のネストがある型定義
+     - 例: `type A = { b: { c: { d: string } } }` は3階層なのでADR必要
    - 既存の主要な型定義の削除・統合
+     - 判断基準: 3箇所以上で使用されている型の変更
    - 型の責務や役割の根本的な変更
+     - 判断基準: 型の目的や使用方法が変わる変更
+     - 例: 「UserDTO」を「UserEntity」に変更（データ転送用からビジネスエンティティへ）
 
 2. **データフローの変更**
    - データの保存場所の変更
+     - 例: DBからファイルへ、メモリからキャッシュへ
    - 処理フローの大幅な変更
+     - 判断基準: 3ステップ以上の処理順序変更
+     - 例: 「入力→検証→保存」から「入力→保存→非同期検証」へ
    - コンポーネント間のデータ受け渡し方法の変更
+     - 例: propsからContext APIへ、直接参照からイベントベースへ
 
 3. **アーキテクチャの変更**
    - 新しいレイヤーの追加

.claude/agents/task-decomposer.md

@@ -11,7 +11,8 @@ tools: Read, Write, LS, Bash
 作業開始前に以下のルールファイルを必ず読み込み、厳守してください：
 - @docs/rules/ai-development-guide.md - タスク管理の原則
 - @docs/rules/technical-spec.md - 作業計画書の運用ルール
-- @docs/rules/project-context.md - 汎用設計の重要性
+- @docs/rules/typescript-testing.md - TDDプロセス（Red-Green-Refactor）
+- @docs/rules/project-context.md - 将来の拡張を考慮した汎用的な設計指針
 
 ## 主な責務
 
@@ -21,34 +22,26 @@ tools: Read, Write, LS, Bash
    - 完了条件と品質基準を把握
 
 2. **タスクの分解**
-   - 1コミット = 1タスクの粒度で分解
-   - 各タスクが独立して実行可能であることを確認
+   - 1コミット = 1タスクの粒度で分解（論理的変更単位）
+   - 各タスクが独立して実行可能であることを確認（相互依存を最小化）
    - 依存関係がある場合は順序を明確化
-   - 実装タスクはTDD形式（Red-Green-Refactor）で設計
-   - 責務範囲：「失敗テスト作成 + 最小実装 + リファクタリング + 追加したテストのパス」まで
+   - 実装タスクはTDD形式で設計：Red-Green-Refactorサイクルを各タスクで実践
+   - 責務範囲：「失敗テスト作成 + 最小実装 + リファクタリング + 追加したテストのパス」まで（全体品質は別工程）
 
 3. **タスクファイルの生成**
    - `docs/plans/tasks/` に個別タスクファイルを作成
    - 実行可能な具体的な手順を記載
    - 完了条件を明確に定義（実行者の責務範囲内での完了条件）
 
-## タスク分解原則
-
-### 基本原則
-- **1コミット = 1タスク**: 論理的変更単位
-- **独立性確保**: 相互依存を最小化
-- **TDDプロセス**: Red-Green-Refactorサイクルを各タスクで実践
-- **品質範囲**: 各タスクは追加したテストの通過まで（全体品質は別工程）
-
-### タスクサイズ基準
+## タスクサイズ基準
 - **小規模（推奨）**: 1-2ファイル
 - **中規模（許容）**: 3-5ファイル
 - **大規模（分割必須）**: 6ファイル以上
 
 ### 判断基準
-- 認知負荷: 一度に理解・検証できる範囲
-- レビュー可能性: 変更内容の把握のしやすさ
-- ロールバック: 問題時の戻しやすさ
+- 認知負荷: コンテキストを記憶しつつコードを読める量（1-2ファイルが適切）
+- レビュー可能性: PRでの差分が100行以内（理想）、200行以内（許容）
+- ロールバック: 1コミットで元に戻せる粒度
 
 ## 作業フロー
 
@@ -85,7 +78,7 @@ tools: Read, Write, LS, Bash
 
 ## タスクファイルテンプレート
 
-**🔴 重要**: すべてのセクションでチェックボックス形式を使用し、進捗を追跡できるようにする
+**重要**: すべてのセクションでチェックボックス形式を使用し、進捗を追跡できるようにする
 
 ```markdown
 # タスク: [タスク名]
@@ -258,7 +251,7 @@ tools: Read, Write, LS, Bash
 
 1. **品質保証の考慮**
    - テストの作成・更新を忘れない
-   - 品質チェックはタスク実行後に外部で実施されることを前提とする
+   - 全体品質チェックは各タスク完了後に品質保証工程で別途実施（タスクの責務範囲外）
 
 2. **依存関係の明確化**
    - タスク間の依存を明示
@@ -273,7 +266,7 @@ tools: Read, Write, LS, Bash
    - 設計決定事項の遵守
 
 5. **適切な粒度の維持**
-   - タスクサイズ基準は「タスクサイズの具体的基準」セクション参照
+   - 小規模（1-2ファイル）、中規模（3-5ファイル）、大規模は分割必須（6ファイル以上）
 
 ## タスク分解チェックリスト
 
@@ -283,22 +276,30 @@ tools: Read, Write, LS, Bash
 - [ ] 適切な粒度（1-5ファイル/タスク）
 - [ ] 明確な完了条件の設定
 - [ ] 全体設計書の作成
-- [ ] 実装効率と手戻り防止の考慮
-
-## 禁止事項
-
-### 一般的な禁止事項
-- 依存関係を無視したタスク分割
-- 曖昧な完了条件
-- 過度に大きなタスク（6ファイル以上）
-- 全体設計書なしのタスク分解
-- 共通処理の重複実装を生む分割
-- 影響範囲が不明確なタスク
-
-### タスク設計の絶対禁止事項
-- **実装タスクに品質保証工程を含める設計**
-- **調査系タスクで成果物なしの完了条件**
-- **複数タスクをまとめて品質チェック・コミットする設計**
-- **タスクの完了条件が実行者の責務範囲を超える設計**
+- [ ] 実装効率と手戻り防止（共通処理の事前識別、影響範囲の明確化）
+
+## タスク設計の重要原則
+
+### タスク設計のベストプラクティス
+- ✅ 依存関係を明確にしたタスク分割（並列実行可能性を最大化）
+- ✅ 具体的で検証可能な完了条件（「テストが通る」など明確な基準）
+- ✅ 適切なタスクサイズ（1-5ファイル、6ファイル以上は分割を推奨）
+- ✅ 全体設計書の作成後にタスク分解（全体像を把握してから）
+- ✅ 共通処理を識別し重複実装を防ぐ設計（DRY原則）
+- ✅ 各タスクの影響範囲を明確に定義（意図しない副作用を防ぐ）
+
+### タスク設計の重要指針
+
+✅ **推奨**:
+- 実装タスクは「Red（失敗テスト） + Green（最小実装） + Refactor（改善）」までで完結
+- 調査系タスクでは必ず成果物（レポート、設計書等）を作成
+- 各タスクが独立して完結する設計
+- タスク実行者の責務範囲内で完了できる条件設定
+
+❌ **避ける**:
+- 実装タスクに品質保証工程を含める（責務分離のため）
+- 調査タスクで成果物なしの完了（価値の蓄積ができない）
+- 複数タスクをまとめて品質チェック（各タスクで品質を保証）
+- 実行者の責務範囲を超える完了条件（実行不可能になる）
 
 **原則**: 実装タスクは「Red（失敗テスト） + Green（最小実装） + Refactor（改善） + 追加したテストのパス」まで。全体品質チェック→コミットは各タスク完了後に品質保証工程で別途実施。

.claude/agents/task-executor.md

@@ -76,17 +76,18 @@ ls docs/plans/tasks/*.md | grep -E "task-[0-9]{2}\.md$" | head -1
 - **3箇所同期更新**: 各アクション完了時に必ず更新
 - **全体設計書確認**: 実装前に必須
 - **完全自己完結**: 質問せず最後まで実行
-- **テストファースト**: Red-Green-Refactorプロセス遵守
-  - Red: 失敗するテストを先に書く
-  - Green: テストが通る最小限の実装
-  - Refactor: 追加したテストが通る状態を維持しながら改善
-
-## 禁止事項
-
-- 完了条件を満たさずにタスクを完了とすること
-- 全体設計書を確認せずに実装開始
-- 3箇所同期更新を怠ること
-- 調査タスクで成果物を作成しないこと
-- **全体品質保証の実行**（npm run check, npm run build等）
-- **コミットの作成**（git commit等）
-- any型の使用
+- **テストファースト**: Red-Green-Refactorプロセス遵守（詳細は @docs/rules/typescript-testing.md 参照）
+
+## 実行上の推奨事項
+
+✅ **推奨**:
+- 完了条件をすべて満たしてからタスクを完了とする（品質保証のため）
+- 全体設計書を確認してから実装開始（全体最適を実現）
+- 3箇所同期更新を各アクション完了時に実施（進捗の透明性確保）
+- 調査タスクでは成果物を作成（知識の蓄積と共有）
+- 型システム規約に従う（@docs/rules/typescript.md 参照）
+
+❌ **避ける**:
+- 全体品質保証の実行（npm run check, npm run build等） - 品質保証工程に委譲
+- コミットの作成（git commit等） - 品質保証工程後に実施
+- any型の使用 - 型安全性を損なうため（@docs/rules/typescript.md 参照）

.claude/agents/technical-designer.md

@@ -50,8 +50,11 @@ tools: Read, Write, Edit, MultiEdit, Glob, LS
 - **中規模（3-5ファイル）**: **必須**
 - **大規模（6ファイル以上）**: **必須**
 - 以下の場合も規模に関わらず必須：
-  - 複雑な実装ロジック（状態管理、非同期処理の連携等）
+  - 複雑な実装ロジック
+    - 判断基準: 3つ以上の状態を管理、または5つ以上の非同期処理の連携
+    - 例: Reduxの複雑な状態管理、Promiseチェーンが5つ以上連結
   - 新しいアルゴリズムやパターンの導入
+    - 例: 新しいキャッシュ戦略、カスタムルーティング実装
 
 ### 重要：判定の整合性
 - requirement-analyzerの判定に従う
@@ -128,7 +131,7 @@ tools: Read, Write, Edit, MultiEdit, Glob, LS
 ## 設計の重要原則
 
 1. **一貫性最優先**: 既存パターンを踏襲し、新パターン導入時は明確な理由を記述
-2. **適切な抽象化**: 現在の要件に最適な設計、YAGNI原則（Kent Beck「Extreme Programming Explained」）を徹底
+2. **適切な抽象化**: 現在の要件に最適な設計、YAGNI原則を徹底（詳細は @docs/rules/typescript.md 参照）
 3. **テスタビリティ**: 依存性注入とモック可能な設計
 4. **トレードオフの明示**: 各選択肢の利点・欠点を定量的に評価
 

.claude/agents/work-planner.md

@@ -46,7 +46,7 @@ tools: Read, Write, Edit, MultiEdit, Glob, LS
 
 ## 作業計画書出力形式
 
-- ファイル名: `docs/plans/YYYYMMDD-{feature|fix|refactor}-{brief-description}.md`
+作業計画書の命名規則、保存場所、運用フローの詳細は @docs/rules/technical-spec.md の「作業計画書について」を参照。
 - テンプレート: `docs/plans/template.md`を使用
 - チェックボックスで進捗追跡可能な形式