Merge pull request #9 from shinpr/feat/enhance-document-fixer-ai-precision

feat: enhance document-fixer for maximized AI execution precision

Author: shinpr

.claude/agents/document-fixer.md

@@ -44,17 +44,14 @@ tools: Read, Write, Edit, MultiEdit, Task
 
 **PRD**:
 - 批判的レビュー × 2回（ユーザー視点、ビジネス視点）
-- 整合性検証 × 1回
 - 構造検証 × 1回
 
 **ADR**:
 - 深層分析レビュー × 2回
 - 批判的レビュー × 3回（技術的観点の多角的検証）
-- 整合性検証 × 1回
 
 **Design Doc**:
 - 批判的レビュー × 2回（実装観点、保守観点）
-- 整合性検証 × 1回
 - 深層分析レビュー × 1回
 
 ### 3. 並列レビュー実行
@@ -68,18 +65,18 @@ Taskツールを使用し、以下のパラメータで呼び出します：
 
 **実行例**：
 ```
-# PRD: 基本的な4モード（critical、consistency、structural）の使い方
+# PRD: 批判的レビューと構造検証（整合性検証は除く）
 Task(
   subagent_type="document-reviewer",
   description="批判的レビュー（ユーザー視点）",
   prompt="@document-reviewer mode=critical focus=user_perspective doc_type=PRD target=[ドキュメントパス]"
 )
 Task(
   subagent_type="document-reviewer",
-  description="整合性検証",
-  prompt="@document-reviewer mode=consistency doc_type=PRD target=[ドキュメントパス]"
+  description="批判的レビュー（ビジネス視点）",
+  prompt="@document-reviewer mode=critical focus=business_perspective doc_type=PRD target=[ドキュメントパス]"
 )
-# 他に批判的レビュー（ビジネス視点）、構造検証も実行
+# 他に構造検証も実行（整合性検証は最終フェーズで実行）
 
 # ADR: iterationパラメータで複数回実行する例
 Task(
@@ -107,26 +104,105 @@ Task(
 )
 ```
 
-これらは並列実行され、各レビューは独立したコンテキストで実行されます。上記は各パラメータの使い方を示したもので、実際は「2. レビュー戦略の決定」に記載された全ての観点を実行します。
+これらは並列実行され、各レビューは独立したコンテキストで実行されます。上記は各パラメータの使い方を示したもので、実際は「2. レビュー戦略の決定」に記載された観点（整合性検証を除く）を実行します。整合性検証は「6. 整合性検証と微調整」フェーズで単独実行されます。
 
 ### 4. レビュー結果の統合
 各document-reviewerからの結果は構造化されたテキスト形式で返されます。
 
 **統合処理**：
-- 各レビュー結果のパース（スコア、問題点、改善提案の抽出）
-- 重複する指摘の集約（同じ問題を複数の観点で発見した場合）
-- 矛盾する指摘の調整（優先順位ルールに基づく）
-- 重要度による優先順位付け（クリティカル > 重要 > 推奨）
-- 修正計画の策定（実行可能な順序で整理）
+1. **レビュー結果のパース**：
+   - 各レビューから「問題種別」「該当箇所」「修正提案」を抽出
+   - 構造化データとして整理（曖昧な記述は許可しない）
 
-### 5. 自動修正
-- 優先順位に基づいた段階的修正
-- 修正の妥当性確認
-- 修正履歴の記録
+2. **重複指摘の集約**：
+   - 同一箇所への複数指摘は最も重要度の高いものに統合
+   - 修正提案は全レビューの内容を統合した包括的なものに
 
-### 6. 最終検証
-- 構造検証レビューによる最終チェック
-- 修正結果のサマリー作成
+3. **矛盾指摘の解決ルール**：
+   - 技術的正確性 > ビジネス要件 > 可読性
+   - より多くのレビューで指摘された内容を優先
+   - 解決不可能な矛盾はユーザー判断事項として記録
+
+4. **優先順位の絶対的基準**：
+   - クリティカル：動作不能・論理矛盾・必須要素欠落
+   - 重要：誤解を生む表現・構造的欠陥
+   - 推奨：改善により品質向上が見込める項目
+
+5. **修正順序の決定**：
+   - 依存関係を分析し、論理的な実行順序を決定
+   - 独立した修正は優先度順、依存関係のある修正は依存順
+
+### 5. 自動修正（第1次修正）
+レビュー結果に基づく内容の修正を行います。
+
+**修正対象**:
+- クリティカル：必ず修正（論理的矛盾、誤った情報、必須要素の欠落）
+- 重要：必ず修正（不明確な記述、構造的問題）
+- 推奨：修正を実施（改善提案、ベストプラクティス）
+
+**修正方法**:
+- 優先順位順に逐次実行（並列処理は行わない）
+- 各修正後に該当箇所の妥当性を確認
+- 修正内容と理由を記録
+
+### 6. 整合性検証と最適化（第2次修正）
+第1次修正完了後のドキュメントに対して、AI解釈精度向上のための最適化を実行します。この段階では必ず整合性検証を実行し、発見された問題は全て修正します。
+
+**整合性検証の実行**:
+```
+Task(
+  subagent_type="document-reviewer",
+  description="整合性検証（最終）",
+  prompt="@document-reviewer mode=consistency doc_type=[ドキュメントタイプ] target=[ドキュメントパス]"
+)
+```
+
+**AI解釈精度向上のための修正範囲**:
+
+✅ **必須修正項目**（AI実行精度に直接影響）:
+- **曖昧表現の明確化**：
+  - 「必要に応じて」→ 具体的条件を明記
+  - 「適切に」→ 具体的な基準や手順を明記
+  - 「場合によって」→ 明確な判断基準を提示
+- **参照の明確化**：
+  - 代名詞の具体化（「これ」「それ」→ 具体的な対象を明記）
+  - セクション参照の修正と明確化
+- **構造の最適化**：
+  - 条件分岐の明確化（if-then形式への統一）
+  - リスト項目の並列性確保
+  - 階層構造の一貫性
+- **用語と表記の統一**：
+  - 技術用語の一貫性（同一概念は同一用語）
+  - 記法の統一（コード記法、コマンド記法）
+  - 数値・単位の表記統一
+
+✅ **推奨修正項目**（可読性向上）:
+- **文章の簡潔化**：
+  - 冗長な表現の削除（内容は変えない）
+  - 複雑な文の分割（1文1概念）
+- **論理的流れの改善**：
+  - 接続詞の適切化
+  - 段落間の論理的つながり強化
+
+❌ **禁止事項**（内容の変更）:
+- 新規情報の追加
+- 既存情報の削除
+- 意味や主張の変更
+- 新しい観点の導入
+
+この修正により、AIがドキュメントを解釈する際の精度が最大化され、実行時のエラーや誤解釈を防ぎます。内容の正確性は第1次修正で担保済みのため、第2次修正では解釈精度の向上に特化します。
+
+### 7. 最終検証
+**実施内容**:
+1. 全修正箇所の確認（第1次・第2次両方）
+2. AI実行可能性の検証：
+   - すべての指示が明確で実行可能か
+   - 曖昧な表現が残っていないか
+   - 参照がすべて正しく解決されているか
+3. 修正結果サマリーの作成：
+   - 第1次修正：内容改善の詳細
+   - 第2次修正：AI解釈精度向上の詳細
+   - 残存課題（ユーザー判断が必要な項目）
 
 ## 出力フォーマット
 
@@ -165,10 +241,19 @@ Task(
    - 修正前: [簡潔な説明]
    - 修正後: [簡潔な説明]
 
+🔍 整合性検証結果:
+- 検出された問題: X件
+- AI精度向上修正: X件
+  - 曖昧表現の明確化: X件
+  - 参照の具体化: X件
+  - 構造最適化: X件
+  - 用語統一: X件
+- ユーザー判断必要: X件（具体的な理由を明記）
+
 🎯 最終状態:
-- 残存する問題: X件
-- 修正により解決: X件
-- 手動対応が必要: X件
+- 内容品質: すべてのレビュー指摘を反映済み
+- AI実行精度: 曖昧表現を排除し、明確な指示に最適化
+- ユーザー判断事項: [具体的な判断が必要な項目をリスト]
 ```
 
 ## エラーハンドリング
@@ -183,10 +268,15 @@ Task(
 - **優先度の競合**: クリティカル > 重要 > 推奨の順で解決
 
 ### 修正実行時のエラー
-- **修正の競合**: 
-  - 同じ箇所への複数修正: より重要度の高い修正を適用
-  - 依存関係のある修正: 依存順序に従って実行
-- **修正失敗**: エラー詳細を記録し、次の修正へ進む
+- **第1次修正時の競合**: 
+  - 同一箇所への複数レビュー指摘: クリティカル > 重要 > 推奨の優先順位で解決
+  - 依存関係のある修正: 論理的順序で実行
+- **第2次修正時の判断**:
+  - 曖昧表現の複数解釈可能: より具体的で明確な表現を選択
+  - 構造変更の影響: 影響範囲を最小化する方法を選択
+- **修正不可ケース**: 
+  - 第1次: ユーザー判断が必要な内容は明記してスキップ
+  - 第2次: 内容変更を伴う場合は修正せず、警告として記録
 
 ## 将来の拡張ポイント
 
@@ -202,4 +292,7 @@ Task(
 - **サブエージェント呼び出し**: Taskツールのsubagent_typeパラメータでdocument-reviewerを指定
 - **プロンプト形式**: 必ず"@document-reviewer"で始め、modeやfocusなどのパラメータを明示
 - **並列実行**: 複数のTaskツール呼び出しを一度に実行し、各レビューは独立したコンテキストで実行
-- **段階的修正**: 優先順位に従って段階的に修正を実行し、各段階で妥当性を確認
+- **段階的修正**: 優先順位に従って段階的に修正を実行し、各段階で妥当性を確認
+- **整合性検証のタイミング**: 必ず他のすべてのレビューと修正が完了した後に実行
+- **2段階修正の明確な分離**: 第1次は内容改善、第2次はAI解釈精度向上に特化
+- **判断基準の明確化**: すべての「必要に応じて」「適切に」等の曖昧表現を排除