create-ai-project 1.19.0 → 1.20.0

package/.claude/skills-ja/subagents-orchestration-guide/SKILL.md

@@ -54,13 +54,15 @@ graph TD
 
 ### ドキュメント作成エージェント
 6. **requirement-analyzer**: 要件分析と作業規模判定（WebSearch対応、最新技術情報の調査）
-7. **prd-creator**: Product Requirements Document作成（WebSearch対応、市場動向調査）
-8. **ui-spec-designer**: PRDとプロトタイプコード（任意）からUI Spec作成（フロントエンド/フルスタック機能）
-9. **technical-designer**: ADR/Design Doc作成（最新技術情報の調査、Property注釈付与）
-10. **work-planner**: 作業計画書作成（テストスケルトンからメタ情報を抽出・反映）
-11. **document-reviewer**: 単一ドキュメントの品質・完成度・ルール準拠チェック
-12. **design-sync**: Design Doc間の整合性検証（明示的矛盾のみ検出）
-13. **acceptance-test-generator**: Design DocのACとUI Spec（任意）から統合テストとE2Eテストのスケルトン生成
+7. **codebase-analyzer**: 既存コードベースを分析し技術設計への重点的なガイダンスを生成
+8. **prd-creator**: Product Requirements Document作成（WebSearch対応、市場動向調査）
+9. **ui-spec-designer**: PRDとプロトタイプコード（任意）からUI Spec作成（フロントエンド/フルスタック機能）
+10. **technical-designer**: ADR/Design Doc作成（最新技術情報の調査、Property注釈付与）
+11. **work-planner**: 作業計画書作成（テストスケルトンからメタ情報を抽出・反映）
+12. **document-reviewer**: 単一ドキュメントの品質・完成度・ルール準拠チェック
+13. **code-verifier**: Design Docの主張を既存コードベースに対して検証（設計フローでレビュー前に使用）
+14. **design-sync**: Design Doc間の整合性検証（明示的矛盾のみ検出）
+15. **acceptance-test-generator**: Design DocのACとUI Spec（任意）から統合テストとE2Eテストのスケルトン生成
 
 ## オーケストレーション原則
 
@@ -104,8 +106,10 @@ graph TD
 
 サブエージェントはJSON形式で応答。オーケストレーター判断に必要なフィールド：
 - **requirement-analyzer**: scale, confidence, adrRequired, crossLayerScope, scopeDependencies, questions
-- **task-executor**: status (escalation_needed/blocked/completed), testsAdded, requiresTestReview
-- **quality-fixer**: approved (true/false)
+- **codebase-analyzer**: analysisScope.categoriesDetected, dataModel.detected, focusAreas[], existingElements count, limitations
+- **code-verifier**:（設計フロー時）consistencyScore, discrepancies[], reverseCoverage（dataOperationsInCode, testBoundariesSectionPresent含む）
+- **task-executor**: status (escalation_needed/completed), escalation_type (design_compliance_violation/similar_function_found/similar_component_found/investigation_target_not_found/out_of_scope_file), testsAdded, requiresTestReview
+- **quality-fixer**: status (approved/blocked)。blockedタイプは`reason`フィールドで判別: `"Cannot determine due to unclear specification"` → `blockingIssues[]`で仕様詳細を参照; `"Execution prerequisites not met"` → `missingPrerequisites[]`の`resolutionSteps`を参照し、ユーザーにアクション可能なステップとして提示
 - **document-reviewer**: approvalReady (true/false)
 - **design-sync**: sync_status (synced/conflicts_found)
 - **integration-test-reviewer**: status (approved/needs_revision/blocked), requiredFixes
@@ -114,7 +118,7 @@ graph TD
 
 ## 作業計画時の基本フロー
 
-### 大規模（6ファイル以上） - 11ステップ（バックエンド） / 13ステップ（フロントエンド/フルスタック）
+### 大規模（6ファイル以上） - 13ステップ（バックエンド） / 15ステップ（フロントエンド/フルスタック）
 
 1. requirement-analyzer → 要件分析 + 既存PRD確認 **[停止]**
 2. prd-creator → PRD作成
@@ -123,24 +127,28 @@ graph TD
 5. **（フロントエンド/フルスタックのみ）** document-reviewer → UI Specレビュー **[停止: UI Spec承認]**
 6. technical-designer → ADR作成（アーキテクチャ/技術/データフロー変更がある場合）
 7. document-reviewer → ADRレビュー（ADR作成時） **[停止: ADR承認]**
-8. technical-designer → Design Doc作成（レイヤー横断時: レイヤー別に作成、レイヤー横断オーケストレーション参照）
-9. document-reviewer → Design Docレビュー（レイヤー横断時: Design Doc毎に実行）
-10. design-sync → 整合性検証 **[停止: Design Doc承認]**
-11. acceptance-test-generator → テストスケルトン生成、work-plannerに渡す (*1)
-12. work-planner → 作業計画書作成 **[停止: 一括承認]**
-13. task-decomposer → 自律実行 → 完了報告
+8. codebase-analyzer → コードベース分析（要件分析結果 + PRDパスを入力）
+9. technical-designer → Design Doc作成（codebase-analyzer出力を追加コンテキストとして入力。レイヤー横断時: レイヤー別に作成、レイヤー横断オーケストレーション参照）
+10. code-verifier → Design Docを既存コードに対して検証（doc_type: design-doc）
+11. document-reviewer → Design Docレビュー（code-verifier結果をcode_verificationとして入力。レイヤー横断時: Design Doc毎に実行）
+12. design-sync → 整合性検証 **[停止: Design Doc承認]**
+13. acceptance-test-generator → テストスケルトン生成、work-plannerに渡す (*1)
+14. work-planner → 作業計画書作成 **[停止: 一括承認]**
+15. task-decomposer → 自律実行 → 完了報告
 
-### 中規模（3-5ファイル） - 7ステップ（バックエンド） / 9ステップ（フロントエンド/フルスタック）
+### 中規模（3-5ファイル） - 9ステップ（バックエンド） / 11ステップ（フロントエンド/フルスタック）
 
 1. requirement-analyzer → 要件分析 **[停止]**
-2. **（フロントエンド/フルスタックのみ）** プロトタイプコードの有無を確認 → ui-spec-designer → UI Spec作成
-3. **（フロントエンド/フルスタックのみ）** document-reviewer → UI Specレビュー **[停止: UI Spec承認]**
-4. technical-designer → Design Doc作成（レイヤー横断時: レイヤー別に作成、レイヤー横断オーケストレーション参照）
-5. document-reviewer → Design Docレビュー（レイヤー横断時: Design Doc毎に実行）
-6. design-sync → 整合性検証 **[停止: Design Doc承認]**
-7. acceptance-test-generator → テストスケルトン生成、work-plannerに渡す (*1)
-8. work-planner → 作業計画書作成 **[停止: 一括承認]**
-9. task-decomposer → 自律実行 → 完了報告
+2. codebase-analyzer → コードベース分析（要件分析結果を入力）
+3. **（フロントエンド/フルスタックのみ）** プロトタイプコードの有無を確認 → ui-spec-designer → UI Spec作成
+4. **（フロントエンド/フルスタックのみ）** document-reviewer → UI Specレビュー **[停止: UI Spec承認]**
+5. technical-designer → Design Doc作成（codebase-analyzer出力を追加コンテキストとして入力。レイヤー横断時: レイヤー別に作成、レイヤー横断オーケストレーション参照）
+6. code-verifier → Design Docを既存コードに対して検証（doc_type: design-doc）
+7. document-reviewer → Design Docレビュー（code-verifier結果をcode_verificationとして入力。レイヤー横断時: Design Doc毎に実行）
+8. design-sync → 整合性検証 **[停止: Design Doc承認]**
+9. acceptance-test-generator → テストスケルトン生成、work-plannerに渡す (*1)
+10. work-planner → 作業計画書作成 **[停止: 一括承認]**
+11. task-decomposer → 自律実行 → 完了報告
 
 ### 小規模（1-2ファイル） - 2ステップ
 
@@ -157,14 +165,18 @@ requirement-analyzerが複数レイヤー（backend + frontend）にまたがる
 
 | ステップ | エージェント | 目的 |
 |---------|-----------|------|
-| 6a | technical-designer | バックエンドDesign Doc |
-| 6b | technical-designer-frontend | フロントエンドDesign Doc |
-| 7 | document-reviewer ×2 | 各Design Docを個別にレビュー |
-| 8 | design-sync | レイヤー間整合性検証 **[停止]** |
+| 8 | codebase-analyzer ×2 | レイヤー別コードベース分析（要件分析結果をレイヤーでフィルタして入力） |
+| 9a | technical-designer | バックエンドDesign Doc（バックエンドcodebase-analyzerコンテキスト付き） |
+| 9b | technical-designer-frontend | フロントエンドDesign Doc（フロントエンドcodebase-analyzerコンテキスト + バックエンドIntegration Points付き） |
+| 10 | code-verifier ×2 | 各Design Docを既存コードに対して検証 |
+| 11 | document-reviewer ×2 | 各Design Docをレビュー（code-verifier結果をcode_verificationとして入力） |
+| 12 | design-sync | レイヤー間整合性検証 **[停止]** |
+
+×2のステップはレイヤー毎に1回ずつ呼び出す。各呼び出しは独立しており、オーケストレーターが並列Agent呼び出しをサポートする場合は並列実行可能。
 
 **Design Doc作成時のレイヤーコンテキスト指定**:
-- **バックエンド**: 「[path]のPRDからバックエンドDesign Docを作成。対象: APIコントラクト、データ層、ビジネスロジック、サービスアーキテクチャ。」
-- **フロントエンド**: 「[path]のPRDからフロントエンドDesign Docを作成。[path]のバックエンドDesign DocのAPIコントラクトとIntegration Pointsを参照。対象: コンポーネント階層、状態管理、UI操作、データ取得。」
+- **バックエンド**: 「PRD [パス] からバックエンドDesign Docを作成。コードベース分析: [バックエンドレイヤー用codebase-analyzerのJSON]。対象: APIコントラクト、データ層、ビジネスロジック、サービスアーキテクチャ。」
+- **フロントエンド**: 「PRD [パス] からフロントエンドDesign Docを作成。コードベース分析: [フロントエンドレイヤー用codebase-analyzerのJSON]。バックエンドDesign Doc [パス] のAPIコントラクトとIntegration Pointsを参照。対象: コンポーネント階層、状態管理、UI操作、データ取得。」
 
 **design-sync**: フロントエンドDesign Docをソースとして使用。`docs/design/`内の他のDesign Docを自動検出して比較。
 
@@ -224,6 +236,16 @@ requirement-analyzerが複数レイヤー（backend + frontend）にまたがる
 
 エージェントのInput Parametersセクションと、フロー内のその時点で利用可能な成果物からプロンプトを構成する。
 
+### Call Example (codebase-analyzer)
+- subagent_type: "codebase-analyzer"
+- description: "コードベース分析"
+- prompt: "requirement_analysis: [要件分析のJSON]. prd_path: [存在する場合はパス]. requirements: [元のユーザー要件]. 既存コードベースを分析し設計ガイダンスを生成してください。"
+
+### Call Example (code-verifier — 設計フロー)
+- subagent_type: "code-verifier"
+- description: "Design Doc検証"
+- prompt: "doc_type: design-doc document_path: [Design Docパス] Design Docを既存コードに対して検証してください。"
+
 ## オーケストレーターの主な役割
 
 1. **状態管理**: 現在のフェーズ、各サブエージェントの状態、次のアクションを把握
@@ -234,6 +256,16 @@ requirement-analyzerが複数レイヤー（backend + frontend）にまたがる
    - changeSummaryからコミットメッセージを作成 → **Bashでgit commit実行**
    - 要件変更時は初期要件と追加要件を明示的に統合
 
+   #### codebase-analyzer → technical-designer
+
+   **codebase-analyzerへの入力**: 要件分析JSON出力、PRDパス（存在する場合）、元のユーザー要件
+   **technical-designerへの入力**: codebase-analyzerのJSON出力をDesign Doc作成プロンプトの追加コンテキストとして渡す。designerは`focusAreas`と`dataModel`を「既存コードベース分析」セクションに反映する。
+
+   #### code-verifier → document-reviewer（Design Docレビュー）
+
+   **code-verifierへの入力**: Design Docパス（doc_type: design-doc）。`code_paths`は意図的に未指定 — verifierがドキュメントからコードスコープを独自に発見する。
+   **document-reviewerへの入力**: code-verifierのJSON出力を`code_verification`パラメータとして渡す。
+
    #### *1 acceptance-test-generator → work-planner
 
    **acceptance-test-generatorへの入力**:
@@ -249,7 +281,7 @@ requirement-analyzerが複数レイヤー（backend + frontend）にまたがる
    - E2Eテストファイル: [パス]（最終フェーズでのみ実行）
 
    **エラー時**: ファイルが生成されない場合はユーザーにエスカレーション
-3. **品質保証とコミット実行**: approved=true確認後、即座にgit commit実行
+3. **品質保証とコミット実行**: `status: "approved"`確認後、即座にgit commit実行
 4. **自律実行モード管理**: 承認後の自律実行開始・停止・エスカレーション判断
 5. **ADRステータス管理**: ユーザー判断後のADRステータス更新（Accepted/Rejected）
 

package/.claude/skills-ja/task-analyzer/references/skills-index.yaml

@@ -60,6 +60,7 @@ skills:
       - "テストの実装規約"
       - "テスト品質基準"
       - "モックの型安全性"
+      - "データ層テスト"
       - "Vitestの基本例"
 
   technical-spec:
@@ -138,6 +139,7 @@ skills:
       - "Node.js Testing Best Practices - Yoni Goldberg"
       - "Property-Based Testing - 2025 Practices"
       - "references/e2e-design.md - E2Eテスト設計原則"
+      - "references/e2e-environment-prerequisites.md - E2E環境前提条件"
     sections:
       - "References"
       - "テスト種別と上限"

package/.claude/skills-ja/typescript-testing/SKILL.md

@@ -135,6 +135,45 @@ const sdkMock = {
 } as unknown as ExternalSDK // 外部SDKの複雑な型のため
 ```
 
+## データ層テスト
+
+### データ層に対するモックの限界
+
+モックは呼び出しパターンを検証するが、データ層の正確性は検証できない。モックのみのテストでは以下が検出されずに通過する:
+- スキーマの不一致（テーブル名、カラム名、データ型）
+- クエリの正確性（JOIN、フィルタ、集約、グルーピング）
+- データベース制約（NOT NULL、UNIQUE、外部キー）
+- マイグレーションの乖離（スキーマ変更によるコードとの不整合）
+
+### データアクセスにモックが適切な場合
+
+- データ層からデータを受け取るビジネスロジックのテスト（repositoryをモック、serviceをテスト）
+- エラーハンドリングパスのテスト（接続失敗、タイムアウトのシミュレーション）
+- データアクセスがテスト対象ではなく依存先であるユニットテスト
+
+### データアクセスにモックが不十分な場合
+
+- repositoryやデータアクセス実装自体のテスト
+- クエリの正確性の検証（JOIN、フィルタ、集約、グルーピング）
+- データ整合性制約のテスト
+- マイグレーション互換性のテスト
+
+### 実データベーステスト（環境依存）
+
+実データベースエンジンに対するデータ層の正確性を検証するオプション:
+- CI環境向けの**コンテナ化されたデータベース**
+- 高速フィードバック用の**インメモリデータベース**（注: dialect差異が問題を隠す場合がある）
+- seed data付きの**専用テストデータベース**
+
+適切なアプローチはプロジェクト環境とCI/CD構成に依存する。
+
+### AI生成コードとスキーマ認識
+
+- AI生成のデータアクセスコードはスキーマのhallucinationリスクが高い
+- 生成されたクエリは正しい構文でも、存在しないスキーマ要素を参照する場合がある
+- モックベースのテストはスキーマの正確性に関わらずパスする
+- 緩和策: Design Docに明示的なスキーマ参照を含めること。逆方向カバレッジ検証でドキュメント化されたスキーマに対するデータ操作を検証する
+
 ## Vitestの基本例
 
 ```typescript

package/CHANGELOG.md

@@ -5,6 +5,56 @@ 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.20.0] - 2026-04-01
+
+### Added
+
+#### Evidence-Based Design Pipeline
+
+Design Docs are now based on explicit codebase evidence before implementation starts, with structured verification before review.
+
+- **codebase-analyzer agent** (new): Analyzes existing codebase before Design Doc creation, producing structured JSON guidance (existing elements, data models, constraints, focus areas) for technical-designer
+- **code-verifier in design flow**: Inserted before document-reviewer so review uses structured verification evidence instead of relying solely on the designer's investigation
+- **Design Doc template: Test Boundaries section**: Mock boundary decisions, data layer testing strategy, and integration verification points — gives downstream test generation explicit mock/real scope
+- **Design flow updated** (all orchestration paths): requirement-analyzer → codebase-analyzer → technical-designer → code-verifier → document-reviewer → design-sync. ADR-only flows skip codebase-analyzer and code-verifier. Step counts updated (Large: 11→13 backend, Medium: 7→9 backend)
+- **Cross-layer orchestration**: codebase-analyzer ×2 and code-verifier ×2 steps added for per-layer analysis in fullstack flows
+
+#### Investigation Targets for Task Execution
+
+Task executors now read and record observations from specified files before implementing, reducing implementations that contradict actual system behavior.
+
+- **task-decomposer**: Generates Investigation Targets per task based on task nature (existing code modification, new feature, test implementation, E2E setup, bug fix)
+- **task-executor / task-executor-frontend**: Phase Entry Gate (4 checkboxes, BLOCKING) and Completion Gate (4 checkboxes, BLOCKING) enforce investigation before implementation. New `investigation_target_not_found` escalation type
+- **Task template**: Investigation Targets section added with observation recording step in Red phase
+
+#### E2E Environment Prerequisites
+
+- **work-planner**: Extracts environment prerequisites from E2E skeletons (2-stage: detect precondition patterns → generate Phase 0 setup tasks for seed data, auth fixtures, service mocks, environment config)
+- **quality-fixer / quality-fixer-frontend**: New `missing_prerequisites` blocked type distinguishes environment failures from specification conflicts, with structured `missingPrerequisites[]` response including concrete resolution steps
+- **E2E environment prerequisites reference** (new): Seed data strategy, authentication fixture patterns, environment checklist
+
+### Changed
+
+- **quality-fixer success contract**: Unified on `status: "approved"` as the primary success indicator. Removed legacy `approved: true` field from JSON examples
+- **quality-fixer blocked contract**: Split into two response formats — `specification conflict` and `missing prerequisites` — discriminated by `reason` field
+- **Annotation syntax**: Made language-agnostic across work-planner, integration-test-reviewer, integration-e2e-testing skill (removed hardcoded `//` prefix from annotation pattern definitions while keeping TypeScript code examples unchanged)
+- **@real-dependency annotation**: Added to skeleton spec (integration-e2e-testing) and work-planner annotation patterns, completing the producer→consumer chain from acceptance-test-generator
+- **document-reviewer**: Added `code_verification` input parameter, data design completeness check (co-occurrence rule for data keywords), and code-verifier integration rules
+- **technical-designer / technical-designer-frontend**: Added Codebase Analysis input parameter for consuming codebase-analyzer output
+- **code-verifier**: Added data layer element enumeration in reverse coverage (dataOperationsInCode, testBoundariesSectionPresent)
+- **orchestration guide**: Updated escalation_type list to include `similar_component_found` (frontend executor alignment). Added Call Examples for codebase-analyzer and code-verifier. Information bridging sections for codebase-analyzer→technical-designer and code-verifier→document-reviewer
+- **typescript-testing skill**: Added Data Layer Testing section (mock limitations, when mocks are appropriate/insufficient, real database testing options, AI schema hallucination awareness)
+- **skills-index.yaml**: Added `Data Layer Testing` section to typescript-testing, added e2e-environment-prerequisites reference to integration-e2e-testing
+- **commands**: design, front-design, implement, reverse-engineer, update-doc updated to include codebase-analyzer and code-verifier in their flows
+
+## [1.19.1] - 2026-03-30
+
+### Changed
+
+- Migrate circular dependency checker from madge to dpdm. madge has stale indirect dependencies with known security vulnerabilities (brace-expansion ReDoS) that are not being addressed upstream. dpdm is actively maintained and uses TypeScript compiler API directly with a shallower dependency tree.
+- Remove `.madgerc` config file (settings migrated to dpdm CLI options)
+- Remove unused `check:deps:graph` script
+
 ## [1.19.0] - 2026-03-30
 
 ### Changed

package/README.ja.md

@@ -3,7 +3,7 @@
 *他の言語で読む: [English](README.md)*
 
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue?logo=typescript)](https://www.typescriptlang.org/)
-[![Node.js](https://img.shields.io/badge/Node.js-20%2B-green?logo=node.js)](https://nodejs.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-22%2B-green?logo=node.js)](https://nodejs.org/)
 [![Claude Code](https://img.shields.io/badge/Claude%20Code-Optimized-purple)](https://claude.ai/code)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/shinpr/ai-coding-project-boilerplate/pulls)

package/README.md

@@ -3,7 +3,7 @@
 *Read this in other languages: [日本語](README.ja.md)*
 
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue?logo=typescript)](https://www.typescriptlang.org/)
-[![Node.js](https://img.shields.io/badge/Node.js-20%2B-green?logo=node.js)](https://nodejs.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-22%2B-green?logo=node.js)](https://nodejs.org/)
 [![Claude Code](https://img.shields.io/badge/Claude%20Code-Optimized-purple)](https://claude.ai/code)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/shinpr/ai-coding-project-boilerplate/pulls)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ai-project",
-  "version": "1.19.0",
+  "version": "1.20.0",
   "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": [
@@ -50,8 +50,7 @@
     "check": "biome check src",
     "check:fix": "biome check --write src",
     "check:unused": "knip --include exports",
-    "check:deps": "madge --circular --extensions ts src",
-    "check:deps:graph": "madge --extensions ts --image graph.svg src",
+    "check:deps": "dpdm --no-warning --no-tree --exit-code circular:1 --ext .ts --exclude \"__tests__|.test.ts$|.spec.ts$\" --tsconfig ./tsconfig.json -T \"src/**/*.ts\"",
     "check:code": "npm run check && npm run check:unused && npm run check:deps && npm run build",
     "check:all": "npm run check:code && npm run test",
     "cleanup:processes": "bash ./scripts/cleanup-test-processes.sh",
@@ -71,7 +70,7 @@
     "husky": "^9.1.7",
     "knip": "^5.0.0",
     "lint-staged": "^16.1.0",
-    "madge": "^8.0.0",
+    "dpdm": "^4.0.0",
     "tsc-alias": "^1.8.7",
     "tsx": "^4.19.4",
     "typescript": "^5.0.0",

package/.madgerc

@@ -1,14 +0,0 @@
-{
-  "fileExtensions": ["ts"],
-  "excludeRegExp": [
-    "__tests__",
-    "\\.test\\.ts$",
-    "\\.spec\\.ts$"
-  ],
-  "detectiveOptions": {
-    "ts": {
-      "skipTypeImports": true
-    }
-  },
-  "tsConfig": "./tsconfig.json"
-}