From 6f6dd17ccfd017f3ca41af593eae317ce667b214 Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Sun, 29 Mar 2026 19:03:38 +0900 Subject: [PATCH] fix: add dependency existence verification to design workflow Design documents could reference non-existent components as "existing" dependencies without verification, leading to implementation failures. Add verification step to technical-designer agents and realizability check to document-reviewer Gate 1. Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude/agents-en/document-reviewer.md | 2 ++ .claude/agents-en/technical-designer-frontend.md | 10 +++++++++- .claude/agents-en/technical-designer.md | 12 ++++++++++-- .claude/agents-ja/document-reviewer.md | 2 ++ .claude/agents-ja/technical-designer-frontend.md | 10 +++++++++- .claude/agents-ja/technical-designer.md | 12 ++++++++++-- CHANGELOG.md | 10 ++++++++++ package.json | 2 +- 8 files changed, 53 insertions(+), 7 deletions(-) diff --git a/.claude/agents-en/document-reviewer.md b/.claude/agents-en/document-reviewer.md index f11fe31..15dea7a 100644 --- a/.claude/agents-en/document-reviewer.md +++ b/.claude/agents-en/document-reviewer.md @@ -92,6 +92,7 @@ For DesignDoc, additionally verify: - Technical information verification: When sources exist, verify with WebSearch for latest information and validate claim validity - Failure scenario review: Identify failure scenarios across normal usage, high load, and external failures; specify which design element becomes the bottleneck - Code inspection evidence review: Verify inspected files are relevant to design scope; flag if key related files are missing +- Dependency realizability check: For each dependency the Design Doc's Existing Codebase Analysis section describes as "existing", verify its definition exists in the codebase using Grep/Glob. Not found in codebase and no authoritative external source documented → `critical` issue (category: `feasibility`). Found but definition signature (method names, parameter types, return types) diverges from Design Doc description → `important` issue (category: `consistency`) - **As-is implementation document review**: When code verification results are provided and the document describes existing implementation (not future requirements), verify that code-observable behaviors are stated as facts; speculative language about deterministic behavior → `important` issue **Perspective-specific Mode**: @@ -244,6 +245,7 @@ Include in output when `prior_context_count > 0`: - [ ] Gate 0 structural existence checks pass before quality review - [ ] Design decision rationales verified against identified standards/patterns - [ ] Code inspection evidence covers files relevant to design scope +- [ ] Dependencies described as "existing" verified against codebase (Grep/Glob) - [ ] Field propagation map present when fields cross component boundaries ## Review Criteria (for Comprehensive Mode) diff --git a/.claude/agents-en/technical-designer-frontend.md b/.claude/agents-en/technical-designer-frontend.md index d0a0c58..737f92d 100644 --- a/.claude/agents-en/technical-designer-frontend.md +++ b/.claude/agents-en/technical-designer-frontend.md @@ -59,9 +59,17 @@ Must be performed before Design Doc creation: - Similar component is technical debt → Create ADR improvement proposal before implementation - No similar component → Proceed with new implementation -4. **Include in Design Doc** +4. **Dependency Existence Verification** + - For each component the design assumes already exists, search for its definition in the codebase using Grep/Glob + - Typical targets include: components, custom hooks, Context definitions, store/state definitions, API endpoints, type definitions, utility functions + - If found in codebase: record file path and definition location + - If found outside codebase (external API, separate repository, generated artifact): record the authoritative source and mark as "external dependency" + - If not found anywhere: mark as "requires new creation" in the Design Doc and reflect in implementation order dependencies + +5. **Include in Design Doc** - Always include investigation results in "## Existing Codebase Analysis" section - Clearly document similar component search results (found components or "none") + - Include dependency existence verification results (verified existing / requires new creation) - Record adopted decision (use existing/improvement proposal/new implementation) and rationale ### Integration Point Analysis【Important】 diff --git a/.claude/agents-en/technical-designer.md b/.claude/agents-en/technical-designer.md index e79eff8..22494f6 100644 --- a/.claude/agents-en/technical-designer.md +++ b/.claude/agents-en/technical-designer.md @@ -73,12 +73,20 @@ Must be performed before Design Doc creation: - Similar functionality is technical debt → Create ADR improvement proposal before implementation - No similar functionality → Proceed with new implementation -4. **Include in Design Doc** +4. **Dependency Existence Verification** + - For each component the design assumes already exists, search for its definition in the codebase using Grep/Glob + - Typical targets include: interfaces, classes, repositories, service methods, API endpoints, DB tables/columns, configuration keys, enum values, type definitions + - If found in codebase: record file path and definition location + - If found outside codebase (external API, separate repository, generated artifact): record the authoritative source and mark as "external dependency" + - If not found anywhere: mark as "requires new creation" in the Design Doc and reflect in implementation order dependencies + +5. **Include in Design Doc** - Always include investigation results in "## Existing Codebase Analysis" section - Clearly document similar functionality search results (found implementations or "none") + - Include dependency existence verification results (verified existing / requires new creation) - Record adopted decision (use existing/improvement proposal/new implementation) and rationale -5. **Code Inspection Evidence** +6. **Code Inspection Evidence** - Record all inspected files and key functions in "Code Inspection Evidence" section of Design Doc - Each entry must state relevance (similar functionality / integration point / pattern reference) diff --git a/.claude/agents-ja/document-reviewer.md b/.claude/agents-ja/document-reviewer.md index 8255648..f587e3f 100644 --- a/.claude/agents-ja/document-reviewer.md +++ b/.claude/agents-ja/document-reviewer.md @@ -92,6 +92,7 @@ DesignDocの場合、追加で以下を確認: - 技術情報検証：出典がある場合はWebSearchで最新情報を確認、主張の妥当性を検証 - 失敗シナリオ検証：正常系・高負荷・外部障害の失敗シナリオを特定し、どの設計要素がボトルネックになるか指摘 - コード調査エビデンス検証：調査ファイルが設計スコープに関連するか確認、主要な関連ファイルの漏れを指摘 +- 依存先の実在性検証：Design Docの「既存コードベース分析」セクションが「既存」と記述する依存先について、Grep/Globでコードベース内の定義を確認。コードベースに見つからず公式の外部出典の記載もない → `critical`（カテゴリ: `feasibility`）。存在するが定義のシグネチャ（メソッド名、パラメータ型、戻り値型）がDesign Docの記述と乖離 → `important`（カテゴリ: `consistency`） - **既存実装ドキュメント検証**: コード検証結果が提供され、ドキュメントが既存実装を記述している場合（将来の要件ではなく）、コードから観察可能な振る舞いが事実として記述されていることを検証する。確定的な振る舞いに対する推測的な表現 → `important` **観点特化モード**: @@ -244,6 +245,7 @@ DesignDocの場合、追加で以下を確認: - [ ] Gate 0の存在チェックが品質レビュー前に通過していること - [ ] 設計判断の根拠が特定された基準/パターンに照合されていること - [ ] コード調査エビデンスが設計スコープに関連するファイルを網羅していること +- [ ] 「既存」と記述された依存先がコードベースに対して検証されていること（Grep/Glob） - [ ] フィールドが境界を越える場合にフィールド伝播マップが存在すること ## レビュー基準（総合モード用） diff --git a/.claude/agents-ja/technical-designer-frontend.md b/.claude/agents-ja/technical-designer-frontend.md index e0732b8..9edc929 100644 --- a/.claude/agents-ja/technical-designer-frontend.md +++ b/.claude/agents-ja/technical-designer-frontend.md @@ -69,9 +69,17 @@ Design Doc作成前に必ず実施： - 類似コンポーネントが技術的負債 → ADRで改善提案を作成してから実装 - 類似コンポーネントなし → 新規実装を進める -4. **Design Docへの記載** +4. **依存先の存在検証** + - 設計が「既存」と想定するコンポーネントについて、Grep/Globでコードベース内の定義を検索 + - 典型的な対象: コンポーネント、カスタムフック、Context定義、ストア/状態定義、APIエンドポイント、型定義、ユーティリティ関数 + - コードベースに存在 → ファイルパスと定義箇所を記録 + - コードベース外に存在（外部API、別リポジトリ、生成物など） → 公式の出典を記録し「外部依存」としてマーク + - どこにも見つからない → Design Docで「新規作成が必要」とマークし、実装順序の依存関係に反映 + +5. **Design Docへの記載** - 「## 既存コードベース分析」セクションに調査結果を必ず記載 - 類似コンポーネントの検索結果（発見したコンポーネント、または「なし」）を明記 + - 依存先の存在検証結果（既存確認済み / 新規作成が必要）を記載 - 採用した判断（既存使用/改善提案/新規実装）とその根拠を記録 ### 統合ポイント分析【重要】 diff --git a/.claude/agents-ja/technical-designer.md b/.claude/agents-ja/technical-designer.md index ba6e680..2caf2a0 100644 --- a/.claude/agents-ja/technical-designer.md +++ b/.claude/agents-ja/technical-designer.md @@ -73,12 +73,20 @@ Design Doc作成前に必ず実施： - 類似機能が技術的負債 → ADRで改善提案を作成してから実装 - 類似機能なし → 新規実装を進める -4. **Design Docへの記載** +4. **依存先の存在検証** + - 設計が「既存」と想定するコンポーネントについて、Grep/Globでコードベース内の定義を検索 + - 典型的な対象: インターフェース、クラス、リポジトリ、サービスメソッド、APIエンドポイント、DBテーブル/カラム、設定キー、enum値、型定義 + - コードベースに存在 → ファイルパスと定義箇所を記録 + - コードベース外に存在（外部API、別リポジトリ、生成物など） → 公式の出典を記録し「外部依存」としてマーク + - どこにも見つからない → Design Docで「新規作成が必要」とマークし、実装順序の依存関係に反映 + +5. **Design Docへの記載** - 「## 既存コードベース分析」セクションに調査結果を必ず記載 - 類似機能の検索結果（発見した実装、または「なし」）を明記 + - 依存先の存在検証結果（既存確認済み / 新規作成が必要）を記載 - 採用した判断（既存使用/改善提案/新規実装）とその根拠を記録 -5. **コード調査エビデンス** +6. **コード調査エビデンス** - 調査したすべてのファイルと主要関数をDesign Docの「コード調査エビデンス」セクションに記録 - 各エントリの関連性（類似機能 / 統合点 / パターン参照）を明記 diff --git a/CHANGELOG.md b/CHANGELOG.md index 52229cc..b1875b0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,16 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [1.18.5] - 2026-03-29 + +### Fixed + +#### Dependency Existence Verification in Design Workflow +Design documents could describe components as "existing" without verification, causing implementation failures when those dependencies turned out to be missing or mismatched. + +- `technical-designer` / `technical-designer-frontend`: Add **Dependency Existence Verification** step to Existing Code Investigation — each assumed dependency is now verified via Grep/Glob before design proceeds, with three-way classification (found in codebase / external dependency / requires new creation) +- `document-reviewer`: Add **dependency realizability check** to Gate 1 — cross-checks claimed "existing" dependencies against the codebase during review. Missing dependency with no external source → `critical` (feasibility). Signature mismatch (method names, parameter types, return types) → `important` (consistency) + ## [1.18.4] - 2026-03-28 ### Fixed diff --git a/package.json b/package.json index be41b09..b3d01ef 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "create-ai-project", - "version": "1.18.4", + "version": "1.18.5", "packageManager": "npm@10.8.2", "description": "TypeScript boilerplate with skills and sub-agents for Claude Code. Prevents context exhaustion through role-based task splitting.", "keywords": [