From d64afd51b66f6dfe6d0fd5ff3be072888e54f6ca Mon Sep 17 00:00:00 2001 From: shinpr Date: Wed, 20 Aug 2025 10:20:36 +0900 Subject: [PATCH 1/3] =?UTF-8?q?fix:=20=E6=97=A2=E5=AD=98=E3=82=B3=E3=83=BC?= =?UTF-8?q?=E3=83=89=E8=AA=BF=E6=9F=BB=E3=83=97=E3=83=AD=E3=82=BB=E3=82=B9?= =?UTF-8?q?=E3=81=AE=E6=98=8E=E7=A2=BA=E5=8C=96=E3=81=A8AI=E5=AE=9F?= =?UTF-8?q?=E8=A1=8C=E7=B2=BE=E5=BA=A6=E3=81=AE=E5=90=91=E4=B8=8A?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 変更内容 - ai-development-guide.md: パターン5（既存コード調査不足）の表現を明確化 - 曖昧な「検討」「視野に」を「使用する」「行わない」等の明確な動詞に変更 - 判断と行動を明確に分離（if-then形式） - technical-designer.md: 類似機能調査プロセスを強化 - ルールとの関連を明示（パターン5対策） - Design Docへの記載義務を明確化 - task-executor.md: 実装前確認を追加 - Design Docとの連携強化 - パターン5準拠の明記 - code-reviewer.md: 検証項目を追加 - 重複実装チェックの追加 - work-planner.md: タスク定義に既存調査を含める - rules-index.yaml: typical-useを「実装時のベストプラクティス」に更新 ## 改善効果 - AIの判断迷いを排除（明確な行動指示） - ルールとエージェントの連携強化（明示的参照） - responseMimeType問題のような見落としを構造的に防止 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .claude/agents-ja/code-reviewer.md | 4 +++- .claude/agents-ja/task-executor.md | 9 ++++++++- .claude/agents-ja/technical-designer.md | 17 +++++++++++++---- .claude/agents-ja/work-planner.md | 4 ++-- docs/rules-ja/ai-development-guide.md | 10 ++++++++++ docs/rules-ja/rules-index.yaml | 4 ++-- 6 files changed, 38 insertions(+), 10 deletions(-) diff --git a/.claude/agents-ja/code-reviewer.md b/.claude/agents-ja/code-reviewer.md index 840bb9d..3e03bfa 100644 --- a/.claude/agents-ja/code-reviewer.md +++ b/.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） ### 品質検証 - [ ] エラーハンドリングが網羅的か diff --git a/.claude/agents-ja/task-executor.md b/.claude/agents-ja/task-executor.md index b71a106..11cb273 100644 --- a/.claude/agents-ja/task-executor.md +++ b/.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ツールでチェックボックスを更新: diff --git a/.claude/agents-ja/technical-designer.md b/.claude/agents-ja/technical-designer.md index 93fabb2..55b0a56 100644 --- a/.claude/agents-ja/technical-designer.md +++ b/.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作成の最初に必ず実施： diff --git a/.claude/agents-ja/work-planner.md b/.claude/agents-ja/work-planner.md index e14a3a1..ac806f0 100644 --- a/.claude/agents-ja/work-planner.md +++ b/.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. **統合完了**: 他コンポーネントとの連携確認 diff --git a/docs/rules-ja/ai-development-guide.md b/docs/rules-ja/ai-development-guide.md index da8f2fa..d31fedb 100644 --- a/docs/rules-ja/ai-development-guide.md +++ b/docs/rules-ja/ai-development-guide.md @@ -90,6 +90,16 @@ function validateEmail(email: string, context: 'user' | 'contact' | 'admin') { / - 確実性lowの場合、最初に最小限の動作確認コードを作成 - 動作確認できたら本実装、できなければフォールバック実行 +### パターン5: 既存コード調査不足 +**症状**: 重複実装、アーキテクチャ不整合、結合時の障害 +**原因**: 実装前の既存コード理解不足 +**回避方法**: +- 実装前に類似機能の存在を必ず検索（同じドメイン、責務、設定パターンをキーワードに） +- 類似機能を発見 → その実装を使用する（新規実装は行わない） +- 類似機能が技術的負債 → ADRで改善提案を作成してから実装 +- 類似機能が存在しない → 既存の設計思想に沿って新規実装 +- すべての判断と根拠をDesign Docの「既存コードベース分析」セクションに記録 + ## デバッグ手法 ### 1. エラー分析手順 diff --git a/docs/rules-ja/rules-index.yaml b/docs/rules-ja/rules-index.yaml index ae4b1af..2c31047 100644 --- a/docs/rules-ja/rules-index.yaml +++ b/docs/rules-ja/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: "技術的判断基準、アンチパターン検出、デバッグ手法、品質チェックコマンド、実装時の失敗回避" + tags: [anti-patterns, technical-judgment, debugging, quality-commands, rule-of-three, implementation, type-safety, refactoring, code-reading, best-practices] + typical-use: "技術的判断基準、アンチパターン検出、デバッグ手法、品質チェックコマンド、実装時のベストプラクティス" size: medium key-references: - "Rule of Three - Martin Fowler" From dba64f5df12282c21f81f8784021a881b7d7df74 Mon Sep 17 00:00:00 2001 From: shinpr Date: Wed, 20 Aug 2025 10:31:31 +0900 Subject: [PATCH 2/3] fix: Add Pattern 5 (Insufficient Existing Code Investigation) to English rules MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Added Pattern 5 to ai-development-guide.md for preventing duplicate implementations - Updated all agent descriptions to reference pre-implementation code investigation process - Enhanced technical-designer.md with similar functionality search and decision workflow - Added pre-implementation verification steps to task-executor.md - Strengthened architecture validation checklist in code-reviewer.md - Added 'code-reading' and 'best-practices' tags to rules-index.yaml This ensures English documentation maintains parity with Japanese improvements for AI execution accuracy. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .claude/agents-en/code-reviewer.md | 4 +++- .claude/agents-en/task-executor.md | 7 ++++++- .claude/agents-en/technical-designer.md | 17 +++++++++++++---- .claude/agents-en/work-planner.md | 4 ++-- docs/rules-en/ai-development-guide.md | 10 ++++++++++ docs/rules-en/rules-index.yaml | 4 ++-- 6 files changed, 36 insertions(+), 10 deletions(-) diff --git a/.claude/agents-en/code-reviewer.md b/.claude/agents-en/code-reviewer.md index 02a065e..4b88eee 100644 --- a/.claude/agents-en/code-reviewer.md +++ b/.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 diff --git a/.claude/agents-en/task-executor.md b/.claude/agents-en/task-executor.md index 4ccbafd..0d859c8 100644 --- a/.claude/agents-en/task-executor.md +++ b/.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: diff --git a/.claude/agents-en/technical-designer.md b/.claude/agents-en/technical-designer.md index 56aff85..1ee6daf 100644 --- a/.claude/agents-en/technical-designer.md +++ b/.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: diff --git a/.claude/agents-en/work-planner.md b/.claude/agents-en/work-planner.md index 8ed4095..5375f26 100644 --- a/.claude/agents-en/work-planner.md +++ b/.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 diff --git a/docs/rules-en/ai-development-guide.md b/docs/rules-en/ai-development-guide.md index f9d5c30..c247219 100644 --- a/docs/rules-en/ai-development-guide.md +++ b/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 diff --git a/docs/rules-en/rules-index.yaml b/docs/rules-en/rules-index.yaml index b60f6cb..f41f7f7 100644 --- a/docs/rules-en/rules-index.yaml +++ b/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" From 403c7dbd948471a72042297b3aa2d91b8f10f439 Mon Sep 17 00:00:00 2001 From: shinpr Date: Wed, 20 Aug 2025 10:35:56 +0900 Subject: [PATCH 3/3] chore: Bump version to 1.6.7 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- package-lock.json | 4 ++-- package.json | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/package-lock.json b/package-lock.json index de1bc8f..490e08e 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "ai-coding-project-boilerplate", - "version": "1.6.6", + "version": "1.6.7", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "ai-coding-project-boilerplate", - "version": "1.6.6", + "version": "1.6.7", "hasInstallScript": true, "license": "MIT", "bin": { diff --git a/package.json b/package.json index d0d585e..b5a9293 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "ai-coding-project-boilerplate", - "version": "1.6.6", + "version": "1.6.7", "description": "TypeScript project boilerplate optimized for Claude Code development with comprehensive development rules, architecture patterns, and quality assurance tools", "main": "dist/index.js", "keywords": [