Merge pull request #48 from shinpr/fix/code-reading-clarity

fix: Improve code investigation process clarity and AI execution accuracy

Author: shinpr

.claude/agents-en/code-reviewer.md

@@ -9,7 +9,7 @@ You are a code review AI assistant specializing in Design Doc compliance validat
 ## Initial Required Tasks
 
 Load and follow these rule files before starting:
-- @docs/rules/ai-development-guide.md - AI Development Guide
+- @docs/rules/ai-development-guide.md - AI Development Guide, pre-implementation existing code investigation process
 - @docs/rules/technical-spec.md - Technical Specifications
 - @docs/rules/typescript.md - TypeScript Development Rules
 - @docs/rules/project-context.md - Project Context
@@ -93,6 +93,8 @@ Load and follow these rule files before starting:
 - [ ] Data flow follows design
 - [ ] Component dependencies correct
 - [ ] Responsibilities properly separated
+- [ ] Existing codebase analysis section includes similar functionality investigation results
+- [ ] No unnecessary duplicate implementations (Pattern 5 from @docs/rules/ai-development-guide.md)
 
 ### Quality Validation
 - [ ] Comprehensive error handling

.claude/agents-en/task-executor.md

@@ -27,7 +27,7 @@ You are a specialized AI assistant for reliably executing individual tasks.
 ## Mandatory Rules
 
 Load and follow these rule files before starting:
-- @docs/rules/ai-development-guide.md - AI Development Guide
+- @docs/rules/ai-development-guide.md - AI Development Guide, pre-implementation existing code investigation process
   ✅ **Follow**: All rules for implementation, testing, and code quality
   ⚠️ **Exception**: Quality assurance process (Phase1-6) and commits are out of scope
 - @docs/rules/typescript-testing.md - Testing Rules
@@ -62,8 +62,13 @@ ls docs/plans/tasks/*.md | grep -E "task-[0-9]{2}\.md$" | head -1
 - Complete understanding of task file
 - Confirm overall design document (_overview-*.md)
 - Grasp impact scope and common processing points
+- Check "Existing Codebase Analysis" section in Design Doc
 
 ### 3. Implementation Execution
+#### Pre-implementation Verification (Following @docs/rules/ai-development-guide.md Pattern 5)
+- Re-confirm no existing implementations of similar functionality exist
+- Follow decisions recorded in Design Doc (use existing/new implementation)
+- If new similar functionality discovered, pause implementation and report
 - If all checkboxes are `[x]`, report "already completed" and end
 - Staged implementation with incremental verification
 - Upon each step completion【Required】Update checkboxes using Edit tool:

.claude/agents-en/technical-designer.md

@@ -12,7 +12,7 @@ Before starting work, be sure to read and follow these rule files:
 - @docs/rules/documentation-criteria.md - Documentation creation criteria
 - @docs/rules/technical-spec.md - Project technical specifications
 - @docs/rules/typescript.md - TypeScript development rules
-- @docs/rules/ai-development-guide.md - AI development guide
+- @docs/rules/ai-development-guide.md - AI development guide, pre-implementation existing code investigation process
 - @docs/rules/project-context.md - Project context
 - @docs/rules/architecture/implementation-approach.md - Metacognitive strategy selection process (used for implementation approach decisions)
 - @docs/rules/architecture/ architecture rule files (if exist)
@@ -50,7 +50,7 @@ Details of documentation creation criteria follow @docs/rules/documentation-crit
 ### Existing Code Investigation【Required】
 Must be performed before Design Doc creation:
 
-1. **Implementation Path Verification**
+1. **Implementation File Path Verification**
    - First grasp overall structure with `Glob: src/**/*.ts`
    - Then identify target files with `Grep: "class.*Service" --type ts` or feature names
    - Record and distinguish between existing implementation locations and planned new locations
@@ -59,9 +59,18 @@ Must be performed before Design Doc creation:
    - List major public methods of target service (about 5 important ones if over 10)
    - Identify call sites with `Grep: "ServiceName\." --type ts`
 
-3. **Include in Design Doc**
+3. **Similar Functionality Search and Decision** (Pattern 5 prevention from @docs/rules/ai-development-guide.md)
+   - Search existing code for keywords related to planned functionality
+   - Look for implementations with same domain, responsibilities, or configuration patterns
+   - Decision and action:
+     - Similar functionality found → Use that implementation (do not create new implementation)
+     - Similar functionality is technical debt → Create ADR improvement proposal before implementation
+     - No similar functionality → Proceed with new implementation
+
+4. **Include in Design Doc**
    - Always include investigation results in "## Existing Codebase Analysis" section
-   - If planned path differs from actual path, clearly state the reason
+   - Clearly document similar functionality search results (found implementations or "none")
+   - Record adopted decision (use existing/improvement proposal/new implementation) and rationale
 
 ### Agreement Checklist【Most Important】
 Must be performed at the beginning of Design Doc creation:

.claude/agents-en/work-planner.md

@@ -9,7 +9,7 @@ You are a specialized AI assistant for creating work plan documents.
 ## Initial Mandatory Tasks
 
 Before starting work, be sure to read and follow these rule files:
-- @docs/rules/ai-development-guide.md - AI development guide (task management principles)
+- @docs/rules/ai-development-guide.md - AI development guide, pre-implementation existing code investigation process, task management principles
 - @docs/rules/documentation-criteria.md - Documentation creation criteria
 - @docs/rules/technical-spec.md - Technical specifications
 - @docs/rules/typescript-testing.md - Testing rules
@@ -75,7 +75,7 @@ Execute file output immediately (considered approved at execution).
 5. **Design Doc Compliance**: All task completion criteria derived from Design Doc specifications
 
 ### Task Completion Definition: 3 Elements
-1. **Implementation Complete**: Code functions
+1. **Implementation Complete**: Code functions (including existing code investigation)
 2. **Quality Complete**: Tests, type checking, linting pass
 3. **Integration Complete**: Coordination with other components verified
 

.claude/agents-ja/code-reviewer.md

@@ -9,7 +9,7 @@ tools: Read, Grep, Glob, LS
 ## 初回必須タスク
 
 作業開始前に以下のルールファイルを必ず読み込み、厳守してください：
-- @docs/rules/ai-development-guide.md - AI開発ガイド
+- @docs/rules/ai-development-guide.md - AI開発ガイド、実装前の既存コード調査プロセス
 - @docs/rules/technical-spec.md - 技術仕様
 - @docs/rules/typescript.md - TypeScript開発ルール
 - @docs/rules/project-context.md - プロジェクトコンテキスト
@@ -93,6 +93,8 @@ tools: Read, Grep, Glob, LS
 - [ ] データフローが設計通りか
 - [ ] コンポーネント間の依存関係が正しいか
 - [ ] 責務の分離が適切か
+- [ ] 既存コードベース分析セクションに類似機能調査結果が記載されているか
+- [ ] 不必要な重複実装がないか（@docs/rules/ai-development-guide.md パターン5）
 
 ### 品質検証
 - [ ] エラーハンドリングが網羅的か

.claude/agents-ja/task-executor.md

@@ -27,7 +27,7 @@ tools: Read, Edit, Write, MultiEdit, Bash, Grep, Glob, LS, TodoWrite
 ## 必須ルール
 
 作業開始前に以下のルールファイルを必ず読み込み、厳守してください：
-- @docs/rules/ai-development-guide.md - AI開発ガイド
+- @docs/rules/ai-development-guide.md - AI開発ガイド、実装前の既存コード調査プロセス
   ✅ **厳守**: 実装・テスト・コード品質に関するすべてのルール
   ⚠️ **例外**: 品質保証工程（Phase 1-6）・コミット作成は責務範囲外のため適用しない
 - @docs/rules/typescript-testing.md - テストルール
@@ -62,8 +62,15 @@ ls docs/plans/tasks/*.md | grep -E "task-[0-9]{2}\.md$" | head -1
 - タスクファイルの完全理解
 - 全体設計書（_overview-*.md）確認
 - 影響範囲と共通化ポイントの把握
+- Design Docの「既存コードベース分析」セクションを確認
 
 ### 3. 実装実行
+#### 実装前の確認（@docs/rules/ai-development-guide.md パターン5準拠）
+- 類似機能の既存実装がないか再確認
+- Design Docに記載された判断（既存使用/新規実装）に従う
+- 新たな類似機能を発見した場合は実装を中断し報告
+
+#### 実装の進行
 - 全チェックボックスが`[x]`の場合は「既に完了」と報告して終了
 - 段階的実装と逐次確認
 - 各ステップ完了時に【必須】Editツールでチェックボックスを更新:

.claude/agents-ja/technical-designer.md

@@ -12,7 +12,7 @@ tools: Read, Write, Edit, MultiEdit, Glob, LS, TodoWrite, WebSearch
 - @docs/rules/documentation-criteria.md - ドキュメント作成基準
 - @docs/rules/technical-spec.md - プロジェクトの技術仕様
 - @docs/rules/typescript.md - TypeScript開発ルール
-- @docs/rules/ai-development-guide.md - AI開発ガイド
+- @docs/rules/ai-development-guide.md - AI開発ガイド、実装前の既存コード調査プロセス
 - @docs/rules/project-context.md - プロジェクトコンテキスト
 - @docs/rules/architecture/implementation-approach.md - メタ認知的戦略選択プロセス（実装アプローチ決定で使用）
 - @docs/rules/architecture/ 配下のアーキテクチャルールファイル（存在する場合）
@@ -50,7 +50,7 @@ tools: Read, Write, Edit, MultiEdit, Glob, LS, TodoWrite, WebSearch
 ### 既存コード調査【必須】
 Design Doc作成前に必ず実施：
 
-1. **実装パスの確認**
+1. **実装ファイルパスの確認**
    - まず `Glob: src/**/*.ts` で全体構造を把握
    - 次に `Grep: "class.*Service" --type ts` や機能名で対象ファイルを特定
    - 既存実装の場所と新規作成予定の場所を区別して記録
@@ -59,9 +59,18 @@ Design Doc作成前に必ず実施：
    - 変更対象サービスの主要publicメソッドを列挙（10個超の場合は重要な5個程度）
    - `Grep: "ServiceName\." --type ts` で呼び出し箇所を特定
 
-3. **Design Docへの記載**
+3. **類似機能の検索と判断**（@docs/rules/ai-development-guide.md パターン5対策）
+   - 実装予定の機能に関連するキーワードで既存コードを検索
+   - 同じドメイン、同じ責務、同じ設定パターンの実装を探索
+   - 判断と行動:
+     - 類似機能を発見 → その実装を使用する（新規実装は行わない）
+     - 類似機能が技術的負債 → ADRで改善提案を作成してから実装
+     - 類似機能なし → 新規実装を進める
+
+4. **Design Docへの記載**
    - 「## 既存コードベース分析」セクションに調査結果を必ず記載
-   - 計画パスと実際のパスが異なる場合は、その理由を明記
+   - 類似機能の検索結果（発見した実装、または「なし」）を明記
+   - 採用した判断（既存使用/改善提案/新規実装）とその根拠を記録
 
 ### 合意事項チェックリスト【最重要】
 Design Doc作成の最初に必ず実施：

.claude/agents-ja/work-planner.md

@@ -9,7 +9,7 @@ tools: Read, Write, Edit, MultiEdit, Glob, LS, TodoWrite
 ## 初回必須タスク
 
 作業開始前に以下のルールファイルを必ず読み込み、厳守してください：
-- @docs/rules/ai-development-guide.md - AI開発ガイド（タスク管理の原則）
+- @docs/rules/ai-development-guide.md - AI開発ガイド、実装前の既存コード調査プロセス、タスク管理の原則
 - @docs/rules/documentation-criteria.md - ドキュメント作成基準
 - @docs/rules/technical-spec.md - 技術仕様
 - @docs/rules/typescript-testing.md - テストルール
@@ -72,7 +72,7 @@ tools: Read, Write, Edit, MultiEdit, Glob, LS, TodoWrite
 5. **Design Doc準拠**: 全タスクの完了条件はDesign Docの仕様から導出
 
 ### タスク完了定義の3要素
-1. **実装完了**: コードが動作する
+1. **実装完了**: コードが動作する（既存コード調査を含む）
 2. **品質完了**: テスト・型チェック・リントがパス
 3. **統合完了**: 他コンポーネントとの連携確認
 

docs/rules-en/ai-development-guide.md

@@ -89,6 +89,16 @@ function validateEmail(email: string, context: 'user' | 'contact' | 'admin') { /
   ```
 - For low certainty cases, create minimal verification code first
 
+### Pattern 5: Insufficient Existing Code Investigation
+**Symptom**: Duplicate implementations, architecture inconsistency, integration failures
+**Cause**: Insufficient understanding of existing code before implementation
+**Avoidance Methods**:
+- Before implementation, always search for similar functionality (using domain, responsibility, configuration patterns as keywords)
+- Similar functionality found → Use that implementation (do not create new implementation)
+- Similar functionality is technical debt → Create ADR improvement proposal before implementation
+- No similar functionality exists → Implement new functionality following existing design philosophy
+- Record all decisions and rationale in "Existing Codebase Analysis" section of Design Doc
+
 ## Debugging Techniques
 
 ### 1. Error Analysis Procedure

docs/rules-en/rules-index.yaml

@@ -46,8 +46,8 @@ rules:
 
   ai-development-guide:
     file: "ai-development-guide.md"
-    tags: [anti-patterns, technical-judgment, debugging, quality-commands, rule-of-three, implementation, type-safety, refactoring]
-    typical-use: "Technical decision criteria, anti-pattern detection, debugging techniques, quality check commands, implementation failure avoidance"
+    tags: [anti-patterns, technical-judgment, debugging, quality-commands, rule-of-three, implementation, type-safety, refactoring, code-reading, best-practices]
+    typical-use: "Technical decision criteria, anti-pattern detection, debugging techniques, quality check commands, implementation best practices"
     size: medium
     key-references:
       - "Rule of Three - Martin Fowler"