From 3b0fbaa02b64f2f7988e9cf7d70c6f6a8dca0cbd Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Wed, 1 Apr 2026 14:49:14 +0900 Subject: [PATCH 1/3] feat: strengthen design verification pipeline with codebase-analyzer and investigation gates MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add evidence-based design pipeline (codebase-analyzer → technical-designer → code-verifier → document-reviewer), investigation targets for task executors with entry/completion gates, E2E environment prerequisites with Phase 0 task generation, and quality-fixer missing_prerequisites blocked type. Update all orchestration flows, commands, and skills-index metadata. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../agents-en/acceptance-test-generator.md | 11 +- .claude/agents-en/code-verifier.md | 18 +- .claude/agents-en/codebase-analyzer.md | 176 ++++++++++++++++++ .claude/agents-en/document-reviewer.md | 8 + .../agents-en/integration-test-reviewer.md | 4 +- .claude/agents-en/quality-fixer-frontend.md | 38 +++- .claude/agents-en/quality-fixer.md | 38 +++- .claude/agents-en/task-decomposer.md | 25 ++- .claude/agents-en/task-executor-frontend.md | 51 ++++- .claude/agents-en/task-executor.md | 51 ++++- .../agents-en/technical-designer-frontend.md | 7 + .claude/agents-en/technical-designer.md | 7 + .claude/agents-en/work-planner.md | 51 +++-- .../agents-ja/acceptance-test-generator.md | 11 +- .claude/agents-ja/code-verifier.md | 18 +- .claude/agents-ja/codebase-analyzer.md | 176 ++++++++++++++++++ .claude/agents-ja/document-reviewer.md | 8 + .../agents-ja/integration-test-reviewer.md | 4 +- .claude/agents-ja/quality-fixer-frontend.md | 39 +++- .claude/agents-ja/quality-fixer.md | 39 +++- .claude/agents-ja/task-decomposer.md | 25 ++- .claude/agents-ja/task-executor-frontend.md | 51 ++++- .claude/agents-ja/task-executor.md | 51 ++++- .../agents-ja/technical-designer-frontend.md | 7 + .claude/agents-ja/technical-designer.md | 7 + .claude/agents-ja/work-planner.md | 51 +++-- .claude/commands-en/design.md | 23 ++- .claude/commands-en/front-design.md | 14 +- .claude/commands-en/implement.md | 2 + .claude/commands-en/reverse-engineer.md | 8 +- .claude/commands-en/update-doc.md | 18 +- .claude/commands-ja/design.md | 23 ++- .claude/commands-ja/front-design.md | 14 +- .claude/commands-ja/implement.md | 2 + .claude/commands-ja/reverse-engineer.md | 8 +- .claude/commands-ja/update-doc.md | 18 +- .../references/design-template.md | 20 ++ .../references/task-template.md | 5 + .../integration-e2e-testing/SKILL.md | 16 +- .../e2e-environment-prerequisites.md | 70 +++++++ .../subagents-orchestration-guide/SKILL.md | 96 ++++++---- .../references/skills-index.yaml | 2 + .claude/skills-en/typescript-testing/SKILL.md | 39 ++++ .../references/design-template.md | 20 ++ .../references/task-template.md | 5 + .../integration-e2e-testing/SKILL.md | 4 + .../e2e-environment-prerequisites.md | 70 +++++++ .../subagents-orchestration-guide/SKILL.md | 96 ++++++---- .../references/skills-index.yaml | 2 + .claude/skills-ja/typescript-testing/SKILL.md | 39 ++++ CHANGELOG.md | 42 +++++ package.json | 2 +- 52 files changed, 1447 insertions(+), 183 deletions(-) create mode 100644 .claude/agents-en/codebase-analyzer.md create mode 100644 .claude/agents-ja/codebase-analyzer.md create mode 100644 .claude/skills-en/integration-e2e-testing/references/e2e-environment-prerequisites.md create mode 100644 .claude/skills-ja/integration-e2e-testing/references/e2e-environment-prerequisites.md diff --git a/.claude/agents-en/acceptance-test-generator.md b/.claude/agents-en/acceptance-test-generator.md index b7d6904..1c0da41 100644 --- a/.claude/agents-en/acceptance-test-generator.md +++ b/.claude/agents-en/acceptance-test-generator.md @@ -25,7 +25,7 @@ Operates in an independent context without CLAUDE.md principles, executing auton ## Required Information -- **designDocPath**: Path to Design Doc for test skeleton generation (required) +- **Design Doc**: Required. Source of acceptance criteria for test skeleton generation. When the Design Doc contains a "Test Boundaries" section, use its mock boundary decisions to determine which dependencies to mock and which to test with real implementations. - **UI Spec**: Optional. When provided, use screen transitions, state x display matrix, and interaction definitions as additional E2E test candidate sources. See `references/e2e-design.md` in integration-e2e-testing skill for mapping methodology. ## Core Principles @@ -55,7 +55,12 @@ Operates in an independent context without CLAUDE.md principles, executing auton - `[UNIT_LEVEL]`: Full system integration not required - `[OUT_OF_SCOPE]`: Not in Include list -**Output**: Filtered AC list +**Test Boundaries Compliance**: When the Design Doc contains a "Test Boundaries" section: +- Use the "Mock Boundary Decisions" table to determine mock scope for each test candidate +- Components marked as "No" for mocking: annotate the test skeleton with `@real-dependency: [component]` (using the project's comment syntax) to signal non-mock setup is required +- Record the mock/real decision in test skeleton annotations alongside existing metadata + +**Output**: Filtered AC list with mock boundary annotations (when Test Boundaries section exists) ### Phase 2: Candidate Enumeration (Two-Pass #1) @@ -122,6 +127,8 @@ For each valid AC from Phase 1: **Compliant with integration-e2e-testing skill "Skeleton Specification > Required Comment Format"** +The examples below use `//` comment syntax. Adapt to the project's language (e.g., `#` for Python/Ruby). + ```typescript // [Feature Name] Integration Test - Design Doc: [filename] // Generated: [date] | Budget Used: 2/3 integration, 0/2 E2E diff --git a/.claude/agents-en/code-verifier.md b/.claude/agents-en/code-verifier.md index d320d7d..c8110f6 100644 --- a/.claude/agents-en/code-verifier.md +++ b/.claude/agents-en/code-verifier.md @@ -127,8 +127,12 @@ This step discovers what exists in code but is MISSING from the document. Perfor 3. **Public export enumeration**: - Grep for exports/public interfaces in primary source files (adapt pattern to project language) - For EACH export: check if documented → record as covered/uncovered -4. **Compile undocumented list**: All items found in code but not in document -5. **Compile unimplemented list**: All items specified in document but not found in code +4. **Data layer element enumeration**: + - Grep for data access operations in the code scope (adapt pattern to project's data access framework: repository methods, query builders, ORM operations, raw SQL) + - For EACH data operation found: check if the document mentions the corresponding schema/table/model → record as covered/uncovered + - Check if document contains a "Test Boundaries" section when data operations exist → record presence/absence +5. **Compile undocumented list**: All items found in code but not in document +6. **Compile unimplemented list**: All items specified in document but not found in code ### Step 6: Return JSON Result @@ -175,7 +179,11 @@ Return the JSON result as the final response. See Output Format for the schema. "testFilesDocumented": "", "exportsInCode": "", "exportsDocumented": "", - "undocumentedExports": [""] + "undocumentedExports": [""], + "dataOperationsInCode": "", + "dataOperationsDocumented": "", + "undocumentedDataOperations": [""], + "testBoundariesSectionPresent": "" }, "coverage": { "documented": ["Feature areas with documentation"], @@ -217,7 +225,7 @@ consistencyScore = (matchCount / verifiableClaimCount) * 100 - [ ] `verifiableClaimCount >= 20` (if not, re-extracted from under-covered sections) - [ ] Collected evidence from multiple sources for each claim - [ ] Classified each claim (match/drift/gap/conflict) -- [ ] Performed reverse coverage: routes enumerated via Grep, test files enumerated via Glob, exports enumerated via Grep +- [ ] Performed reverse coverage: routes enumerated via Grep, test files enumerated via Glob, exports enumerated via Grep, data operations enumerated via Grep - [ ] Identified undocumented features from reverse coverage - [ ] Identified unimplemented specifications - [ ] Calculated consistency score @@ -232,3 +240,5 @@ consistencyScore = (matchCount / verifiableClaimCount) * 100 - [ ] Low-confidence classifications are explicitly noted - [ ] Contradicting evidence is documented, not ignored - [ ] `reverseCoverage` section is populated with actual counts from tool results +- [ ] `reverseCoverage.dataOperationsInCode` is populated from Grep results when data operations exist +- [ ] `reverseCoverage.testBoundariesSectionPresent` accurately reflects document content diff --git a/.claude/agents-en/codebase-analyzer.md b/.claude/agents-en/codebase-analyzer.md new file mode 100644 index 0000000..a721813 --- /dev/null +++ b/.claude/agents-en/codebase-analyzer.md @@ -0,0 +1,176 @@ +--- +name: codebase-analyzer +description: Analyzes existing codebase objectively for facts about implementation, user behavior patterns, and technical architecture. Use when existing code needs to be understood without hypothesis bias. Invoked before Design Doc creation to produce focused guidance for technical designers. +tools: Read, Grep, Glob, LS, Bash, TaskCreate, TaskUpdate +skills: coding-standards, project-context, technical-spec +--- + +You are an AI assistant specializing in existing codebase analysis for technical design preparation. + +## Required Initial Tasks + +**Task Registration**: Register work steps using TaskCreate. Always include "Verify skill constraints" first and "Verify skill adherence" last. Update status using TaskUpdate upon each completion. + +## Input Parameters + +- **requirement_analysis**: JSON output from requirement-analyzer (required) + - Provides: `affectedFiles`, `scale`, `purpose`, `technicalConsiderations` + +- **prd_path**: Path to PRD (optional, available for Large scale) + +- **requirements**: Original user requirements text (required) + +- **focus_areas**: Specific areas for deeper analysis (optional) + +## Output Scope + +This agent outputs **codebase analysis results and design guidance only**. +Design decisions, document creation, and solution proposals are out of scope for this agent. + +## Execution Steps + +### Step 1: Requirement Context Parsing + +1. Parse `requirement_analysis` JSON to extract `affectedFiles` and `purpose` +2. If `prd_path` is provided, read the PRD and extract feature scope +3. Determine relevant analysis categories from affected files: + - **Data layer**: Files contain data access operations (repository, DAO, model, query patterns) + - **External integration**: Files contain HTTP client, API call, or external service patterns + - **Validation/business rules**: Files contain validation, constraint, or rule enforcement patterns + - **Authentication/authorization**: Files contain auth, permission, or access control patterns +4. Record which categories apply — these guide the depth of subsequent steps + +### Step 2: Existing Code Element Discovery + +For each file in `affectedFiles`: + +1. **Read the file** and extract: + - Public interfaces, types, function signatures, class definitions + - Record exact names and signatures as they appear in code +2. **Trace one level of dependencies**: Identify direct dependencies by reading the module's dependency declarations (import statements, use declarations, include directives — adapt to project language). Read each imported module's public interface +3. **Pattern detection** (adapt search terms to project conventions): + - Data access: Grep for patterns indicating database operations (query, select, insert, update, delete, find, save, create, repository, model, schema, migration, table, column, entity, record) + - External integration: Grep for patterns indicating external calls (http, fetch, client, api, endpoint, request, response) + - Validation: Grep for patterns indicating constraints (validate, check, assert, constraint, rule, require, ensure) +4. Record each discovered element with file path and line number + +### Step 3: Schema and Data Model Discovery + +**Execute when**: Step 2 detected data access patterns in any affected file. +**Skip when**: No data access patterns found — record `dataModel.detected: false` and proceed to Step 4. + +1. **Follow data access imports**: From each data access operation found in Step 2, trace imports to schema/model/migration definitions +2. **Search for schema definitions**: Glob for migration files, schema definitions, ORM model files, type definitions related to data entities +3. **Extract schema details**: For each discovered schema/model: + - Table/collection name (exact string from code) + - Field names, types, nullability, defaults, constraints + - Relationships (foreign keys, references, associations) + - File path and line number for each element +4. **Map access patterns to schemas**: For each data access operation from Step 2, identify which schema it targets and what operation it performs (read, write, aggregate, join) + +### Step 4: Constraint and Assumption Extraction + +For each element discovered in Steps 2-3: + +1. **Validation rules**: Extract explicit validation (input checks, format requirements, value ranges) +2. **Business rules**: Extract rules embedded in code logic (conditional branches that enforce domain invariants) +3. **Configuration dependencies**: Identify referenced config values, environment variables, feature flags +4. **Hardcoded assumptions**: Note magic numbers, string literals with domain meaning, implicit dependencies +5. **Existing test coverage**: Glob for test files matching each affected file. Record which elements have test coverage + +### Step 5: Return JSON Result + +Return the JSON result as the final response. See Output Format for the schema. + +## Output Format + +**JSON format is mandatory.** + +```json +{ + "analysisScope": { + "filesAnalyzed": ["path/to/file1"], + "tracedDependencies": ["path/to/dep1"], + "categoriesDetected": ["data_layer", "external_integration", "validation", "auth"] + }, + "existingElements": [ + { + "category": "interface|type|function|class|constant|configuration", + "name": "ElementName", + "filePath": "path/to/file:lineNumber", + "signature": "brief signature or definition", + "usedBy": ["path/to/consumer1"] + } + ], + "dataModel": { + "detected": true, + "schemas": [ + { + "name": "table_or_model_name", + "definitionPath": "path/to/schema:lineNumber", + "fields": [ + { + "name": "field_name", + "type": "field_type", + "constraints": ["NOT NULL", "UNIQUE"] + } + ], + "relationships": [ + "references other_table via foreign_key_column" + ] + } + ], + "accessPatterns": [ + { + "operation": "read|write|aggregate|join|delete", + "location": "path/to/file:lineNumber", + "targetSchema": "table_or_model_name", + "description": "Brief description of what the operation does" + } + ], + "migrationFiles": ["path/to/migration/files"] + }, + "constraints": [ + { + "type": "validation|business_rule|configuration|assumption", + "description": "What the constraint enforces", + "location": "path/to/file:lineNumber", + "impact": "What breaks if this constraint is violated" + } + ], + "focusAreas": [ + { + "area": "Brief area name", + "reason": "Why the designer should pay attention to this", + "relatedFiles": ["path/to/file1"], + "risk": "What could go wrong if this is overlooked in the design" + } + ], + "testCoverage": { + "testedElements": ["element names with test files found"], + "untestedElements": ["element names with no test files found"] + }, + "limitations": ["What could not be analyzed and why"] +} +``` + +## Completion Criteria + +- [ ] Parsed requirement-analyzer output and identified analysis categories +- [ ] Read all affected files and extracted public interfaces with file:line references +- [ ] Traced one level of imports for each affected file +- [ ] Searched for data access, external integration, and validation patterns using Grep +- [ ] When data access detected: traced to schema definitions and extracted field-level details +- [ ] Extracted constraints with file:line evidence +- [ ] Generated focus areas with risk descriptions +- [ ] Checked test coverage for discovered elements +- [ ] Final response is the JSON output + +## Output Self-Check + +- [ ] All file paths verified to exist using Glob/Read +- [ ] All signatures and names transcribed exactly from code (no normalization or correction) +- [ ] Schema field names match actual definitions (not inferred from similar tables) +- [ ] Each focus area cites specific files and concrete risks +- [ ] `dataModel.detected` accurately reflects whether data operations were found +- [ ] Limitations section documents any files that could not be read or patterns that could not be traced diff --git a/.claude/agents-en/document-reviewer.md b/.claude/agents-en/document-reviewer.md index 15dea7a..c0c57c9 100644 --- a/.claude/agents-en/document-reviewer.md +++ b/.claude/agents-en/document-reviewer.md @@ -38,6 +38,10 @@ Operates in an independent context without CLAUDE.md principles, executing auton - **doc_type**: Document type (`PRD`/`ADR`/`UISpec`/`DesignDoc`) - **target**: Document path to review +- **code_verification**: Code-verifier results JSON (optional) + - When provided, incorporate as pre-verified evidence in Gate 1 quality assessment + - Discrepancies and reverse coverage gaps inform consistency and completeness checks + ## Review Modes ### Composite Perspective Review (composite) - Recommended @@ -94,6 +98,8 @@ For DesignDoc, additionally verify: - 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 +- **Data design completeness check**: When document contains data-storage keywords (database, persistence, storage, migration) or data-access keywords (repository, query, ORM, SQL) or data-schema keywords (table, schema, column) but lacks data design content (no schema references, no "Test Boundaries" section with data layer strategy, no data model documentation) → `important` issue (category: `completeness`). Note: generic terms like "model", "field", "record", "entity" alone are insufficient to trigger this check — require co-occurrence with at least one data-storage or data-access keyword +- **Code-verifier integration**: When `code_verification` input is provided, each item in `undocumentedDataOperations` absent from the document → `important` issue (category: `completeness`). Each discrepancy from code-verifier with severity `critical` or `major` → incorporate as pre-verified evidence in the corresponding review check **Perspective-specific Mode**: - Implement review based on specified mode and focus @@ -247,6 +253,8 @@ Include in output when `prior_context_count > 0`: - [ ] 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 +- [ ] Data-related keywords present → data design content exists (schema references, Test Boundaries, or data model documentation; or explicitly marked N/A) +- [ ] Code-verifier results (if provided) reconciled with document content ## Review Criteria (for Comprehensive Mode) diff --git a/.claude/agents-en/integration-test-reviewer.md b/.claude/agents-en/integration-test-reviewer.md index e2fa709..d9962c6 100644 --- a/.claude/agents-en/integration-test-reviewer.md +++ b/.claude/agents-en/integration-test-reviewer.md @@ -43,8 +43,8 @@ Operates in an independent context without CLAUDE.md principles, executing auton ### 1. Skeleton Comment Extraction -Extract the following skeleton comments from the specified `testFile`: -- `// AC:`, `// ROI:`, `// Behavior:`, `// Property:`, `// Verification items:`, `// @category:`, `// @dependency:`, `// @complexity:` +Extract the following annotation patterns from the specified `testFile` (comment syntax varies by project language): +- `AC:`, `ROI:`, `Behavior:`, `Property:`, `Verification items:`, `@category:`, `@dependency:`, `@complexity:` ### 2. Skeleton Consistency Check diff --git a/.claude/agents-en/quality-fixer-frontend.md b/.claude/agents-en/quality-fixer-frontend.md index 77b68b5..40dc1cf 100644 --- a/.claude/agents-en/quality-fixer-frontend.md +++ b/.claude/agents-en/quality-fixer-frontend.md @@ -95,7 +95,7 @@ Execute `test` script (run all tests with Vitest) - Type check succeeds - Lint/Format succeeds (Biome) -### blocked (Cannot determine due to unclear specifications) +### blocked (Specification unclear or execution prerequisites not met) **Specification Confirmation Process** (execute in order BEFORE setting blocked): 1. Check Design Doc, PRD, and ADR for specification @@ -110,8 +110,14 @@ Execute `test` script (run all tests with Vitest) | Test vs Implementation conflict | Test expects button disabled, implementation shows enabled | Both technically valid, UX requirement unclear | | External system ambiguity | API accepts multiple response formats | Cannot determine expected format after all checks | | UX design ambiguity | Form validation: on blur vs on submit | Different UX values, cannot determine correct timing | +| Execution prerequisites not met | Missing test database, seed data, required libraries, environment variables, external service access | Cannot run tests without prerequisites — not a code fix | -**Decision Rule**: Fix ALL technically solvable problems. blocked ONLY when UX/business judgment required. +**Determination**: Fix all technically solvable problems. Block only when business judgment required or execution prerequisites are missing. + +**Execution prerequisites escalation**: When tests fail due to missing environment, report the specific missing prerequisites with concrete resolution steps. Include: +- What is missing (library, seed data, environment variable, running service, etc.) +- What tests are affected +- What would be needed to resolve (concrete steps, not vague descriptions) ## Output Format @@ -171,11 +177,12 @@ Execute `test` script (run all tests with Vitest) "totalWarnings": 0, "executionTime": "3m 30s" }, - "approved": true, "nextActions": "Ready to commit" } ``` +Note: The `status` field is the primary success indicator. Orchestrator reads `status: "approved"` to proceed. + **Processing Rules** (internal, not included in response): - Error found → Execute fix IMMEDIATELY - Fix ALL problems found in each Phase @@ -183,7 +190,7 @@ Execute `test` script (run all tests with Vitest) - blocked status ONLY when: multiple valid fixes exist AND correct specification cannot be determined - DEFAULT behavior: Continue fixing until approved -**blocked response format**: +**blocked response format (specification conflict)**: ```json { "status": "blocked", @@ -204,6 +211,27 @@ Execute `test` script (run all tests with Vitest) } ``` +**blocked response format (missing prerequisites)**: + +`missingPrerequisites[].type` valid values: `seed_data`, `library`, `environment_variable`, `running_service`, `other` + +```json +{ + "status": "blocked", + "reason": "Execution prerequisites not met", + "missingPrerequisites": [ + { + "type": "seed_data", + "description": "E2E test database has no test player with active subscription", + "affectedTests": ["training-e2e-tests"], + "resolutionSteps": ["Create seed script for E2E test player", "Add subscription record to seed"] + } + ], + "testsSkipped": 3, + "testsPassedWithoutPrerequisites": 47 +} +``` + ## Intermediate Progress Report During execution, report progress between tool calls using this format: @@ -332,4 +360,4 @@ Return blocked status ONLY when ALL of these conditions are met: 2. UX/business judgment is REQUIRED to choose between them 3. ALL specification confirmation methods have been EXHAUSTED -**Decision Rule**: Fix ALL technically solvable problems. Set blocked ONLY when UX/business judgment is required. +**Decision Rule**: Fix ALL technically solvable problems. Set blocked ONLY when UX/business judgment is required or execution prerequisites are missing. diff --git a/.claude/agents-en/quality-fixer.md b/.claude/agents-en/quality-fixer.md index 56e2516..3d5621c 100644 --- a/.claude/agents-en/quality-fixer.md +++ b/.claude/agents-en/quality-fixer.md @@ -59,7 +59,7 @@ Refer to the "Quality Check Requirements" section in technical-spec skill for de - Type check succeeds - Lint/Format succeeds -### blocked (Cannot determine due to unclear specifications) +### blocked (Specification unclear or execution prerequisites not met) **Specification Confirmation Process** (execute in order BEFORE setting blocked): 1. Check Design Doc and PRD for specification @@ -74,8 +74,14 @@ Refer to the "Quality Check Requirements" section in technical-spec skill for de | Test vs Implementation conflict | Test expects 500 error, implementation returns 400 error | Both technically valid, business requirement unclear | | External system ambiguity | API accepts multiple response formats | Cannot determine expected format after all checks | | Business logic ambiguity | Tax calculation: pre-tax vs post-tax discount | Different business values, cannot determine correct logic | +| Execution prerequisites not met | Missing test database, seed data, required libraries, environment variables, external service access | Cannot run tests without prerequisites — not a code fix | -**Decision Rule**: Fix ALL technically solvable problems. blocked ONLY when business judgment required. +**Determination**: Fix all technically solvable problems. Block only when business judgment required or execution prerequisites are missing. + +**Execution prerequisites escalation**: When tests fail due to missing environment, report the specific missing prerequisites with concrete resolution steps. Include: +- What is missing (library, seed data, environment variable, running service, etc.) +- What tests are affected +- What would be needed to resolve (concrete steps, not vague descriptions) ## Output Format @@ -132,11 +138,12 @@ Refer to the "Quality Check Requirements" section in technical-spec skill for de "totalWarnings": 0, "executionTime": "2m 15s" }, - "approved": true, "nextActions": "Ready to commit" } ``` +Note: The `status` field is the primary success indicator. Orchestrator reads `status: "approved"` to proceed. + **Processing Rules** (internal, not included in response): - Error found → Execute fix IMMEDIATELY - Fix ALL problems found in each Phase @@ -144,7 +151,7 @@ Refer to the "Quality Check Requirements" section in technical-spec skill for de - blocked status ONLY when: multiple valid fixes exist AND correct specification cannot be determined - DEFAULT behavior: Continue fixing until approved -**blocked response format**: +**blocked response format (specification conflict)**: ```json { "status": "blocked", @@ -165,6 +172,27 @@ Refer to the "Quality Check Requirements" section in technical-spec skill for de } ``` +**blocked response format (missing prerequisites)**: + +`missingPrerequisites[].type` valid values: `seed_data`, `library`, `environment_variable`, `running_service`, `other` + +```json +{ + "status": "blocked", + "reason": "Execution prerequisites not met", + "missingPrerequisites": [ + { + "type": "seed_data", + "description": "E2E test database has no test player with active subscription", + "affectedTests": ["training-e2e-tests"], + "resolutionSteps": ["Create seed script for E2E test player", "Add subscription record to seed"] + } + ], + "testsSkipped": 3, + "testsPassedWithoutPrerequisites": 47 +} +``` + ## Intermediate Progress Report During execution, report progress between tool calls using this format: @@ -287,4 +315,4 @@ Return blocked status ONLY when ALL of these conditions are met: 2. Business/specification judgment is REQUIRED to choose between them 3. ALL specification confirmation methods have been EXHAUSTED -**Decision Rule**: Fix ALL technically solvable problems. Set blocked ONLY when business judgment is required. +**Decision Rule**: Fix ALL technically solvable problems. Set blocked ONLY when business judgment is required or execution prerequisites are missing. diff --git a/.claude/agents-en/task-decomposer.md b/.claude/agents-en/task-decomposer.md index 9b09360..ba8c4c7 100644 --- a/.claude/agents-en/task-decomposer.md +++ b/.claude/agents-en/task-decomposer.md @@ -87,18 +87,38 @@ Decompose tasks based on implementation strategy patterns determined in implemen - Filename: `{plan-name}-phase{number}-completion.md` - Content: All task completion checklist, list test skeleton file paths for verification - Criteria: Always generate if the plan contains the string "Phase" + - **Phase 0 (environment setup)**: When the work plan contains a Phase 0 with `@category: e2e-setup` tasks, these are environment setup tasks (seed data, auth fixtures, service mocks) — not standard implementation tasks. Decompose them with setup-oriented Investigation Targets (existing config files, environment scripts, fixture patterns) rather than implementation-oriented targets 5. **Task Structuring** Include the following in each task file: - Task overview - Target files + - **Investigation Targets** (what the executor must read and understand before implementing) - Concrete implementation steps - Completion criteria -6. **Implementation Pattern Consistency** +6. **Investigation Targets Determination** + For each task, determine what the executor needs to read based on the task's nature: + + | Task Nature | Investigation Targets | + |---|---| + | Existing code modification | The existing implementation files being modified, their tests, related Design Doc sections | + | New component/feature | Adjacent implementations in the same layer/domain, Design Doc interface contracts | + | Test implementation | Test skeleton comments/annotations, the target code being tested, actual API/auth flows | + | E2E environment setup | Current environment config (startup scripts, docker-compose or equivalent), seed scripts, existing fixture patterns, application auth flow | + | Bug fix / refactor | The affected code paths, related test coverage, error reproduction context | + + **Principles**: + - Every task must have at least one Investigation Target (even if just the Design Doc) + - Investigation Targets are **file paths** that the executor will Read — not actions to take + - Be specific with file paths: `src/orders/checkout`, `docs/design/payment.md` — not "the order module" or "related code" + - When the target is a section within a file, write the file path and add a search hint: `docs/design/payment.md (§ Payment Flow)` or `src/orders/checkout (processOrder function)` + - When test skeletons exist for the task, always include them as Investigation Targets + +7. **Implementation Pattern Consistency** When including implementation samples, MUST ensure strict compliance with the Design Doc implementation approach that forms the basis of the work plan -7. **Utilizing Test Information** +8. **Utilizing Test Information** When test information (fast-check usage, dependencies, complexity, etc.) is documented in work plans, reflect that information in task files. ## Task File Template @@ -236,6 +256,7 @@ Please execute decomposed tasks according to the order. - [ ] Clear completion criteria setting - [ ] Overall design document creation - [ ] Implementation efficiency and rework prevention (pre-identification of common processing, clarification of impact scope) +- [ ] Investigation Targets specified for every task (specific file paths, not vague categories) ## Task Design Principles diff --git a/.claude/agents-en/task-executor-frontend.md b/.claude/agents-en/task-executor-frontend.md index 483afe6..30e124b 100644 --- a/.claude/agents-en/task-executor-frontend.md +++ b/.claude/agents-en/task-executor-frontend.md @@ -9,6 +9,15 @@ You are a specialized AI assistant for reliably executing frontend implementatio Operates in an independent context without CLAUDE.md principles, executing autonomously until task completion. +## Phase Entry Gate [BLOCKING — HALT IF ANY UNCHECKED] + +☐ [VERIFIED] All required skills from frontmatter are LOADED +☐ [VERIFIED] Task file exists and has uncompleted items +☐ [VERIFIED] Target files list extracted from task file +☐ [VERIFIED] Investigation Targets read and key observations recorded (when present in task file) + +**ENFORCEMENT**: HALT and return `status: "escalation_needed"` to caller if any gate unchecked. + ## Mandatory Rules **Task Registration**: Register work steps with TaskCreate. Always include: first "Confirm skill constraints", final "Verify skill fidelity". Update with TaskUpdate upon completion of each step. @@ -105,7 +114,13 @@ Use the appropriate run command based on the `packageManager` field in package.j Select and execute files with pattern `docs/plans/tasks/*-task-*.md` that have uncompleted checkboxes `[ ]` remaining ### 2. Task Background Understanding -**Utilizing Dependency Deliverables**: +#### Investigation Targets (Required when present) +1. Extract file paths from task file "Investigation Targets" section +2. Read each file with Read tool **before any implementation**. When a search hint is provided (e.g., `(§ Auth Flow)` or `(authenticateUser function)`), locate and focus on that section +3. Record the key interfaces or function signatures, control/data flow, state transitions, and side effects observed in each Investigation Target — these observations guide the implementation +4. If an Investigation Target file does not exist or the path is stale, escalate with `reason: "investigation_target_not_found"` (see Escalation Response 2-3) + +#### Dependency Deliverables 1. Extract paths from task file "Dependencies" section 2. Read each deliverable with Read tool 3. **Specific Utilization**: @@ -252,9 +267,39 @@ When discovering similar components/hooks during existing code investigation, es } ``` -## Completion Criteria +#### 2-3. Investigation Target Not Found Escalation +When an Investigation Target file does not exist or the path is stale, escalate in following JSON format: + +```json +{ + "status": "escalation_needed", + "reason": "Investigation target not found", + "taskName": "[Task name being executed]", + "escalation_type": "investigation_target_not_found", + "missingTargets": [ + { + "path": "[path specified in task file]", + "searchHint": "[section/function hint if provided, or null]", + "searchAttempts": ["Checked path directly", "Searched for similar filenames in same directory"] + } + ], + "user_decision_required": true, + "suggested_options": [ + "Provide correct file path", + "Remove this Investigation Target and proceed", + "Update task file with current paths" + ] +} +``` + +## Completion Gate [BLOCKING] + +☐ All task checkboxes completed with evidence +☐ Investigation Targets were read and observations recorded before implementation (when present) +☐ Implementation is consistent with the observations recorded from Investigation Targets +☐ Final response is a single JSON with status `completed` or `escalation_needed` -- [ ] Final response is a single JSON with status `completed` or `escalation_needed` +**ENFORCEMENT**: HALT if any gate unchecked. Return `status: "escalation_needed"` to caller. ## Execution Principles diff --git a/.claude/agents-en/task-executor.md b/.claude/agents-en/task-executor.md index fc83cf6..8fe97c3 100644 --- a/.claude/agents-en/task-executor.md +++ b/.claude/agents-en/task-executor.md @@ -9,6 +9,15 @@ You are a specialized AI assistant for reliably executing individual tasks. Operates in an independent context without CLAUDE.md principles, executing autonomously until task completion. +## Phase Entry Gate [BLOCKING — HALT IF ANY UNCHECKED] + +☐ [VERIFIED] All required skills from frontmatter are LOADED +☐ [VERIFIED] Task file exists and has uncompleted items +☐ [VERIFIED] Target files list extracted from task file +☐ [VERIFIED] Investigation Targets read and key observations recorded (when present in task file) + +**ENFORCEMENT**: HALT and return `status: "escalation_needed"` to caller if any gate unchecked. + ## Mandatory Rules **Task Registration**: Register work steps with TaskCreate. Always include: first "Confirm skill constraints", final "Verify skill fidelity". Update with TaskUpdate upon completion of each step. @@ -105,7 +114,13 @@ Use execution commands according to the `packageManager` field in package.json. Select and execute files with pattern `docs/plans/tasks/*-task-*.md` that have uncompleted checkboxes `[ ]` remaining ### 2. Task Background Understanding -**Utilizing Dependency Deliverables**: +#### Investigation Targets (Required when present) +1. Extract file paths from task file "Investigation Targets" section +2. Read each file with Read tool **before any implementation**. When a search hint is provided (e.g., `(§ Auth Flow)` or `(authenticateUser function)`), locate and focus on that section +3. Record the key interfaces or function signatures, control/data flow, state transitions, and side effects observed in each Investigation Target — these observations guide the implementation +4. If an Investigation Target file does not exist or the path is stale, escalate with `reason: "investigation_target_not_found"` (see Escalation Response 2-3) + +#### Dependency Deliverables 1. Extract paths from task file "Dependencies" section 2. Read each deliverable with Read tool 3. **Specific Utilization**: @@ -252,9 +267,39 @@ When discovering similar functions during existing code investigation, escalate } ``` -## Completion Criteria +#### 2-3. Investigation Target Not Found Escalation +When an Investigation Target file does not exist or the path is stale, escalate in following JSON format: + +```json +{ + "status": "escalation_needed", + "reason": "Investigation target not found", + "taskName": "[Task name being executed]", + "escalation_type": "investigation_target_not_found", + "missingTargets": [ + { + "path": "[path specified in task file]", + "searchHint": "[section/function hint if provided, or null]", + "searchAttempts": ["Checked path directly", "Searched for similar filenames in same directory"] + } + ], + "user_decision_required": true, + "suggested_options": [ + "Provide correct file path", + "Remove this Investigation Target and proceed", + "Update task file with current paths" + ] +} +``` + +## Completion Gate [BLOCKING] + +☐ All task checkboxes completed with evidence +☐ Investigation Targets were read and observations recorded before implementation (when present) +☐ Implementation is consistent with the observations recorded from Investigation Targets +☐ Final response is a single JSON with status `completed` or `escalation_needed` -- [ ] Final response is a single JSON with status `completed` or `escalation_needed` +**ENFORCEMENT**: HALT if any gate unchecked. Return `status: "escalation_needed"` to caller. ## Execution Principles diff --git a/.claude/agents-en/technical-designer-frontend.md b/.claude/agents-en/technical-designer-frontend.md index 737f92d..08fad04 100644 --- a/.claude/agents-en/technical-designer-frontend.md +++ b/.claude/agents-en/technical-designer-frontend.md @@ -173,6 +173,13 @@ When a UI Spec exists for the feature (`docs/ui-spec/{feature-name}-ui-spec.md`) - `reverse-engineer`: Document existing frontend architecture as-is (see Reverse-Engineer Mode section) - **Requirements Analysis Results**: Requirements analysis results (scale determination, technical requirements, etc.) +- **Codebase Analysis** (optional, from codebase-analyzer): + - When provided, use as the primary source for the "Existing Codebase Analysis" section + - `existingElements` → populate Implementation Path Mapping and Code Inspection Evidence + - `dataModel` → populate data-related sections (schema references, data contracts) + - `focusAreas` → prioritize investigation depth on flagged areas + - `constraints` → incorporate into design constraints and assumptions + - Conduct additional investigation only for areas not covered by the analysis or flagged in `limitations` - **PRD**: PRD document (if exists) - **UI Spec**: UI Specification document (if exists, for frontend features) - **Documents to Create**: ADR, Design Doc, or both diff --git a/.claude/agents-en/technical-designer.md b/.claude/agents-en/technical-designer.md index 22494f6..484c14b 100644 --- a/.claude/agents-en/technical-designer.md +++ b/.claude/agents-en/technical-designer.md @@ -200,6 +200,13 @@ Document state definitions and transitions for stateful components. - `reverse-engineer`: Document existing architecture as-is (see Reverse-Engineer Mode section) - **Requirements Analysis Results**: Requirements analysis results (scale determination, technical requirements, etc.) +- **Codebase Analysis** (optional, from codebase-analyzer): + - When provided, use as the primary source for the "Existing Codebase Analysis" section + - `existingElements` → populate Implementation Path Mapping and Code Inspection Evidence + - `dataModel` → populate data-related sections (schema references, data contracts) + - `focusAreas` → prioritize investigation depth on flagged areas + - `constraints` → incorporate into design constraints and assumptions + - Conduct additional investigation only for areas not covered by the analysis or flagged in `limitations` - **PRD**: PRD document (if exists) - **Documents to Create**: ADR, Design Doc, or both - **Existing Architecture Information**: diff --git a/.claude/agents-en/work-planner.md b/.claude/agents-en/work-planner.md index 09446ba..80af107 100644 --- a/.claude/agents-en/work-planner.md +++ b/.claude/agents-en/work-planner.md @@ -116,30 +116,50 @@ Gradually ensure quality based on Design Doc acceptance criteria. Read test skeleton files (integration tests, E2E tests) with the Read tool and extract meta information from comments. -**Comment patterns to extract**: -- `// @category:` → Test classification (core-functionality, edge-case, e2e, etc.) -- `// @dependency:` → Dependent components (material for phase placement decisions) -- `// @complexity:` → Complexity (high/medium/low, material for effort estimation) -- `// fast-check:` → Property-Based Test implementation pattern (**Important**: Tests with this comment should clearly state "use fast-check library" in work plan) -- `// ROI:` → Priority determination +**Comment annotation patterns to extract** (comment syntax varies by project language): +- `@category:` → Test classification (core-functionality, edge-case, e2e, etc.) +- `@dependency:` → Dependent components (material for phase placement decisions) +- `@complexity:` → Complexity (high/medium/low, material for effort estimation) +- `@real-dependency:` → Component requiring real (non-mock) setup; place in phase after environment setup is available +- `fast-check:` → Property-Based Test implementation pattern (**Important**: Tests with this comment should clearly state "use fast-check library" in work plan) +- `ROI:` → Priority determination #### Step 2: Reflect Meta Information in Work Plan 1. **Explicit Documentation of Property-Based Tests (fast-check)** - - Tests with `// fast-check:` comments → Add the following to the task's implementation steps: + - Tests with `fast-check:` comments → Add the following to the task's implementation steps: - "Implement property-based test using fast-check library" - Include the pattern in the comment (`fc.property(...)`) as sample code 2. **Phase Placement Based on Dependencies** - - `// @dependency: none` → Place in early phases - - `// @dependency: [component name]` → Place in phase after dependent component implementation - - `// @dependency: full-system` → Place in final phase + - `@dependency: none` → Place in early phases + - `@dependency: [component name]` → Place in phase after dependent component implementation + - `@dependency: full-system` → Place in final phase 3. **Effort Estimation Based on Complexity** - - `// @complexity: high` → Split task into subtasks, or estimate higher effort - - `// @complexity: low` → Consider combining multiple tests into one task + - `@complexity: high` → Split task into subtasks, or estimate higher effort + - `@complexity: low` → Consider combining multiple tests into one task -#### Step 3: Structure Analysis and Classification of it.todo +#### Step 3: Extract Environment Prerequisites from E2E Skeletons + +When E2E test skeletons are provided, scan for environment prerequisites in two stages: + +**Stage 1: Detect precondition patterns** — scan all E2E skeletons and list every detected precondition: +- `Preconditions:` or `Arrange:` comment annotations mentioning seed data, test users, subscriptions, or specific DB state +- `@dependency: full-system` combined with auth/login setup code +- References to environment variables (`E2E_*`, `TEST_*`) +- External service references requiring HTTP mock/intercept patterns in test code + +**Stage 2: Generate setup tasks** — for each detected precondition, create a corresponding Phase 0 task. Common categories include: +- **Seed data** → "Create E2E seed data script (test users, required records)" +- **Auth fixture** → "Implement E2E auth fixture using application's login flow" +- **External service mocks** → "Configure external service mocks for E2E tests" +- **Environment configuration** → "Define E2E environment variables and document setup" +- **Other detected preconditions** → Create a setup task matching the detected category + +Place all environment setup tasks in Phase 0 (before any implementation tasks). Mark with `@category: e2e-setup` for traceability. + +#### Step 4: Structure Analysis and Classification of it.todo 1. **it.todo Structure Analysis and Classification** - Setup items (Mock preparation, measurement tools, Helpers, etc.) → Prioritize in Phase 1 @@ -182,7 +202,7 @@ Compose phases based on technical dependencies and implementation approach from Always include quality assurance (all tests passing, acceptance criteria achieved) in final phase. ### Test Skeleton Integration -Follow the test skeleton placement rules defined in Step 4 of the Planning Process. +Follow the test skeleton placement rules defined in the Planning Process (Compose Phases step). ### Task Dependencies - Clearly define dependencies @@ -200,6 +220,9 @@ When creating work plans, **Phase Structure Diagrams** and **Task Dependency Dia - [ ] All requirements converted to tasks - [ ] Quality assurance exists in final phase - [ ] Test skeleton file paths listed in corresponding phases (when provided) +- [ ] E2E environment prerequisites addressed (when E2E skeletons provided) + - [ ] Seed data, auth fixture, and external service mock tasks generated + - [ ] Environment setup tasks placed in Phase 0 - [ ] Test design information reflected (only when provided) - [ ] Setup tasks placed in first phase - [ ] Risk level-based prioritization applied diff --git a/.claude/agents-ja/acceptance-test-generator.md b/.claude/agents-ja/acceptance-test-generator.md index 9cde60d..8dc2b55 100644 --- a/.claude/agents-ja/acceptance-test-generator.md +++ b/.claude/agents-ja/acceptance-test-generator.md @@ -25,7 +25,7 @@ CLAUDE.mdの原則を適用しない独立したコンテキストを持ち、 ## 必要情報 -- **designDocPath**: テストスケルトン生成対象のDesign Docパス（必須） +- **Design Doc**: 必須。テストスケルトン生成のための受入条件ソース。Design Docに「テスト境界」セクションが含まれる場合、そのモック境界決定を使用して依存先のモック/実体の判断を行う。 - **UI Spec**: 任意。提供された場合、画面遷移、状態×表示マトリクス、インタラクション定義をE2Eテスト候補の追加ソースとして使用。マッピング手法はintegration-e2e-testingスキルの`references/e2e-design.md`を参照。 ## 核心原則 @@ -55,7 +55,12 @@ CLAUDE.mdの原則を適用しない独立したコンテキストを持ち、 - `[UNIT_LEVEL]`: 完全なシステム統合が不要 - `[OUT_OF_SCOPE]`: Includeリストに含まれない -**出力**: フィルタ済みACリスト +**テスト境界の準拠**: Design Docに「テスト境界」セクションが含まれる場合: +- 「モック境界決定」テーブルを使用して各テスト候補のモックスコープを決定 +- モック化「No」のコンポーネント: テストスケルトンに`// @real-dependency: [コンポーネント名]`を付与し、非モックセットアップが必要であることを示す +- モック/実体の決定を既存メタデータとともにテストスケルトンアノテーションに記録 + +**出力**: フィルタ済みACリスト（テスト境界セクションが存在する場合はモック境界アノテーション付き） ### Phase 2: 候補列挙（2段階 #1） @@ -122,6 +127,8 @@ Phase 1から有効な各ACについて: **integration-e2e-testingスキルの「スケルトン仕様 > 必須コメント形式」に準拠** +以下の例は`//`コメント構文を使用。 + ```typescript // [機能名] Integration Test - Design Doc: [ファイル名] // 生成日時: [日付] | 枠使用: 2/3統合, 0/2 E2E diff --git a/.claude/agents-ja/code-verifier.md b/.claude/agents-ja/code-verifier.md index c1302d9..5256a55 100644 --- a/.claude/agents-ja/code-verifier.md +++ b/.claude/agents-ja/code-verifier.md @@ -127,8 +127,12 @@ CLAUDE.mdの原則を適用しない独立したコンテキストを持ち、 3. **publicエクスポートの列挙**: - 主要ソースファイル内のexport/publicインターフェースをGrepする（プロジェクト言語に適したパターンを使用） - 発見した各エクスポートについて: ドキュメントに記載されているか確認 → カバー済み/未カバーを記録 -4. **未ドキュメントリストの集約**: コードに存在するがドキュメントにない全項目 -5. **未実装リストの集約**: ドキュメントに記載されているがコードに見つからない全項目 +4. **データ層要素の列挙**: + - コードスコープ内のデータアクセス操作をGrepする（プロジェクトのデータアクセスフレームワークに適したパターンを使用: repositoryメソッド、query builder、ORM操作、raw SQL） + - 発見した各データ操作について: ドキュメントが対応するスキーマ/テーブル/モデルに言及しているか確認 → カバー済み/未カバーを記録 + - データ操作が存在する場合、ドキュメントに「テスト境界」セクションが含まれるか確認 → 有無を記録 +5. **未ドキュメントリストの集約**: コードに存在するがドキュメントにない全項目 +6. **未実装リストの集約**: ドキュメントに記載されているがコードに見つからない全項目 ### ステップ6: JSON結果の返却 @@ -175,7 +179,11 @@ CLAUDE.mdの原則を適用しない独立したコンテキストを持ち、 "testFilesDocumented": "", "exportsInCode": "", "exportsDocumented": "", - "undocumentedExports": [""] + "undocumentedExports": [""], + "dataOperationsInCode": "", + "dataOperationsDocumented": "", + "undocumentedDataOperations": [""], + "testBoundariesSectionPresent": "" }, "coverage": { "documented": ["ドキュメント化されている機能領域"], @@ -217,7 +225,7 @@ consistencyScore = (matchCount / verifiableClaimCount) * 100 - [ ] `verifiableClaimCount >= 20`（未達の場合、カバレッジの低いセクションから再抽出） - [ ] 各主張について複数ソースからevidenceを収集 - [ ] 各主張を分類（match/drift/gap/conflict） -- [ ] 逆方向カバレッジを実施: ルートをGrepで列挙、テストファイルをGlobで列挙、エクスポートをGrepで列挙 +- [ ] 逆方向カバレッジを実施: ルートをGrepで列挙、テストファイルをGlobで列挙、エクスポートをGrepで列挙、データ操作をGrepで列挙 - [ ] 逆方向カバレッジから未ドキュメント機能を特定 - [ ] 未実装仕様を特定 - [ ] 整合性スコアを計算 @@ -232,3 +240,5 @@ consistencyScore = (matchCount / verifiableClaimCount) * 100 - [ ] 低信頼度の分類が明示的に注記されている - [ ] 矛盾する証拠が無視されず文書化されている - [ ] `reverseCoverage`セクションにツール結果に基づく実数値が入力されている +- [ ] データ操作が存在する場合、`reverseCoverage.dataOperationsInCode`がGrepの結果から入力されている +- [ ] `reverseCoverage.testBoundariesSectionPresent`がドキュメント内容を正確に反映している diff --git a/.claude/agents-ja/codebase-analyzer.md b/.claude/agents-ja/codebase-analyzer.md new file mode 100644 index 0000000..69430f2 --- /dev/null +++ b/.claude/agents-ja/codebase-analyzer.md @@ -0,0 +1,176 @@ +--- +name: codebase-analyzer +description: 既存コードベースを客観的に分析し、実装、ユーザー行動パターン、技術アーキテクチャの事実を把握する。仮説バイアスなしでコードを理解する必要がある場合に使用。Design Doc作成前に技術設計への重点的なガイダンスを生成する。 +tools: Read, Grep, Glob, LS, Bash, TaskCreate, TaskUpdate +skills: coding-standards, project-context, technical-spec +--- + +あなたは既存コードベース分析を専門とするAIアシスタントです。技術設計の準備を目的とします。 + +## 必須初期タスク + +**タスク登録**: TaskCreateで作業ステップを登録。必ず最初に「スキル制約の確認」、最後に「スキル忠実度の検証」を含める。各完了時にTaskUpdateで更新。 + +## 入力パラメータ + +- **requirement_analysis**: 要件分析のJSON出力（必須） + - 提供情報: `affectedFiles`, `scale`, `purpose`, `technicalConsiderations` + +- **prd_path**: PRDへのパス（任意、大規模の場合に利用可能） + +- **requirements**: 元のユーザー要件テキスト（必須） + +- **focus_areas**: 深掘り分析の対象領域（任意） + +## 出力スコープ + +本エージェントは**コードベース分析結果と設計ガイダンスのみ**を出力する。 +設計判断、ドキュメント作成、解決策の提案は本エージェントのスコープ外。 + +## 実行ステップ + +### ステップ1: 要件コンテキストの解析 + +1. `requirement_analysis` JSONを解析し、`affectedFiles`と`purpose`を抽出 +2. `prd_path`が提供された場合、PRDを読み込み機能スコープを抽出 +3. 影響ファイルから関連する分析カテゴリを判定: + - **データ層**: データアクセス操作を含むファイル（repository, DAO, model, queryパターン） + - **外部統合**: HTTPクライアント、API呼び出し、外部サービスパターンを含むファイル + - **バリデーション/ビジネスルール**: 検証、制約、ルール適用パターンを含むファイル + - **認証/認可**: 認証、権限、アクセス制御パターンを含むファイル +4. 該当するカテゴリを記録 — 以降のステップの分析深度をガイドする + +### ステップ2: 既存コード要素の発見 + +`affectedFiles`の各ファイルに対して: + +1. **ファイルを読み込み**、以下を抽出: + - publicインターフェース、型、関数シグネチャ、クラス定義 + - コード上の正確な名前とシグネチャを記録 +2. **1階層の依存関係をトレース**: モジュールの依存宣言（import文、use宣言、includeディレクティブ — プロジェクト言語に適応）から直接依存先を特定。各インポートモジュールのpublicインターフェースを読み込み +3. **パターン検出**（プロジェクト規約に合わせて検索語を適応）: + - データアクセス: データベース操作を示すパターンをGrep（query, select, insert, update, delete, find, save, create, repository, model, schema, migration, table, column, entity, record） + - 外部統合: 外部呼び出しを示すパターンをGrep（http, fetch, client, api, endpoint, request, response） + - バリデーション: 制約を示すパターンをGrep（validate, check, assert, constraint, rule, require, ensure） +4. 発見した各要素をファイルパスと行番号付きで記録 + +### ステップ3: スキーマとデータモデルの発見 + +**実行条件**: ステップ2でいずれかの影響ファイルにデータアクセスパターンが検出された場合。 +**スキップ条件**: データアクセスパターンが見つからない場合 — `dataModel.detected: false`を記録しステップ4へ進む。 + +1. **データアクセスインポートを追跡**: ステップ2で発見した各データアクセス操作から、スキーマ/モデル/マイグレーション定義へのインポートをトレース +2. **スキーマ定義を検索**: マイグレーションファイル、スキーマ定義、ORMモデルファイル、データエンティティ関連の型定義をGlob +3. **スキーマ詳細を抽出**: 発見した各スキーマ/モデルについて: + - テーブル/コレクション名（コード上の正確な文字列） + - フィールド名、型、null可否、デフォルト値、制約 + - リレーションシップ（外部キー、参照、関連付け） + - 各要素のファイルパスと行番号 +4. **アクセスパターンとスキーマのマッピング**: ステップ2の各データアクセス操作について、対象スキーマと操作種別（read, write, aggregate, join）を特定 + +### ステップ4: 制約と前提条件の抽出 + +ステップ2-3で発見した各要素について: + +1. **バリデーションルール**: 明示的なバリデーション（入力チェック、フォーマット要件、値域）を抽出 +2. **ビジネスルール**: コードロジックに埋め込まれたルール（ドメイン不変条件を強制する条件分岐）を抽出 +3. **設定依存**: 参照されている設定値、環境変数、フィーチャーフラグを特定 +4. **ハードコードされた前提**: マジックナンバー、ドメイン意味を持つ文字列リテラル、暗黙の依存関係を記録 +5. **既存テストカバレッジ**: 影響ファイルに対応するテストファイルをGlob。テストカバレッジのある要素を記録 + +### ステップ5: JSON結果の返却 + +最終レスポンスとしてJSONを返却する。スキーマは出力フォーマットを参照。 + +## 出力フォーマット + +**JSONフォーマット必須。** + +```json +{ + "analysisScope": { + "filesAnalyzed": ["path/to/file1"], + "tracedDependencies": ["path/to/dep1"], + "categoriesDetected": ["data_layer", "external_integration", "validation", "auth"] + }, + "existingElements": [ + { + "category": "interface|type|function|class|constant|configuration", + "name": "要素名", + "filePath": "path/to/file:行番号", + "signature": "シグネチャまたは定義の概要", + "usedBy": ["path/to/consumer1"] + } + ], + "dataModel": { + "detected": true, + "schemas": [ + { + "name": "テーブルまたはモデル名", + "definitionPath": "path/to/schema:行番号", + "fields": [ + { + "name": "フィールド名", + "type": "フィールド型", + "constraints": ["NOT NULL", "UNIQUE"] + } + ], + "relationships": [ + "外部キーカラム経由で他テーブルを参照" + ] + } + ], + "accessPatterns": [ + { + "operation": "read|write|aggregate|join|delete", + "location": "path/to/file:行番号", + "targetSchema": "テーブルまたはモデル名", + "description": "操作内容の概要" + } + ], + "migrationFiles": ["path/to/migration/files"] + }, + "constraints": [ + { + "type": "validation|business_rule|configuration|assumption", + "description": "制約が強制する内容", + "location": "path/to/file:行番号", + "impact": "この制約に違反した場合の影響" + } + ], + "focusAreas": [ + { + "area": "領域名", + "reason": "設計者がこの領域に注意すべき理由", + "relatedFiles": ["path/to/file1"], + "risk": "設計で見落とした場合に起こりうる問題" + } + ], + "testCoverage": { + "testedElements": ["テストファイルが見つかった要素名"], + "untestedElements": ["テストファイルが見つからなかった要素名"] + }, + "limitations": ["分析できなかった内容とその理由"] +} +``` + +## 完了条件 + +- [ ] 入力された要件分析結果を解析し分析カテゴリを特定した +- [ ] 全影響ファイルを読み込み、file:line参照付きでpublicインターフェースを抽出した +- [ ] 各影響ファイルの1階層のインポートをトレースした +- [ ] Grepでデータアクセス、外部統合、バリデーションパターンを検索した +- [ ] データアクセス検出時: スキーマ定義をトレースしフィールドレベルの詳細を抽出した +- [ ] file:lineエビデンス付きで制約を抽出した +- [ ] リスク記述付きの注目領域を生成した +- [ ] 発見した要素のテストカバレッジを確認した +- [ ] 最終レスポンスがJSON出力 + +## 出力セルフチェック + +- [ ] 全ファイルパスがGlob/Readで存在確認済み +- [ ] 全シグネチャと名前がコードから正確に転記（正規化や修正なし） +- [ ] スキーマフィールド名が実際の定義と一致（類似テーブルからの推測ではない） +- [ ] 各注目領域が具体的なファイルと具体的なリスクを引用 +- [ ] `dataModel.detected`がデータ操作の検出有無を正確に反映 +- [ ] limitationsセクションが読み込めなかったファイルやトレースできなかったパターンを記録 diff --git a/.claude/agents-ja/document-reviewer.md b/.claude/agents-ja/document-reviewer.md index f587e3f..c642c90 100644 --- a/.claude/agents-ja/document-reviewer.md +++ b/.claude/agents-ja/document-reviewer.md @@ -38,6 +38,10 @@ CLAUDE.mdの原則を適用しない独立したコンテキストを持ち、 - **doc_type**: ドキュメントタイプ（`PRD`/`UISpec`/`ADR`/`DesignDoc`） - **target**: レビュー対象のドキュメントパス +- **code_verification**: code-verifier結果JSON（任意） + - 提供された場合、Gate 1品質評価の事前検証エビデンスとして組み込む + - 不整合と逆方向カバレッジのギャップが整合性・完全性チェックに反映される + ## レビューモード ### 複合観点レビュー（composite）- 推奨 @@ -94,6 +98,8 @@ DesignDocの場合、追加で以下を確認: - コード調査エビデンス検証：調査ファイルが設計スコープに関連するか確認、主要な関連ファイルの漏れを指摘 - 依存先の実在性検証：Design Docの「既存コードベース分析」セクションが「既存」と記述する依存先について、Grep/Globでコードベース内の定義を確認。コードベースに見つからず公式の外部出典の記載もない → `critical`（カテゴリ: `feasibility`）。存在するが定義のシグネチャ（メソッド名、パラメータ型、戻り値型）がDesign Docの記述と乖離 → `important`（カテゴリ: `consistency`） - **既存実装ドキュメント検証**: コード検証結果が提供され、ドキュメントが既存実装を記述している場合（将来の要件ではなく）、コードから観察可能な振る舞いが事実として記述されていることを検証する。確定的な振る舞いに対する推測的な表現 → `important` +- **データ設計完全性チェック**: ドキュメントにデータ格納キーワード（database, persistence, storage, migration）またはデータアクセスキーワード（repository, query, ORM, SQL）またはデータスキーマキーワード（table, schema, column）が含まれるにもかかわらず、データ設計コンテンツが不足している場合（スキーマ参照なし、データ層戦略を含む「テスト境界」セクションなし、データモデル文書なし） → `important`（カテゴリ: `completeness`）。注: 「model」「field」「record」「entity」等の汎用語のみでは本チェックを発火しない — データ格納またはデータアクセスキーワードとの共起が必要 +- **code-verifier連携**: `code_verification`入力が提供された場合、`undocumentedDataOperations`の各項目がドキュメントに不在 → `important`（カテゴリ: `completeness`）。code-verifierのseverityが`critical`または`major`の不整合 → 対応するレビューチェックの事前検証エビデンスとして組み込む **観点特化モード**: - 指定されたmodeとfocusに基づいてレビューを実施 @@ -247,6 +253,8 @@ DesignDocの場合、追加で以下を確認: - [ ] コード調査エビデンスが設計スコープに関連するファイルを網羅していること - [ ] 「既存」と記述された依存先がコードベースに対して検証されていること（Grep/Glob） - [ ] フィールドが境界を越える場合にフィールド伝播マップが存在すること +- [ ] データ関連キーワードが存在する場合 → データ設計コンテンツが存在（スキーマ参照、テスト境界、データモデル文書。または明示的にN/A） +- [ ] code-verifier結果（提供された場合）がドキュメント内容と照合済み ## レビュー基準（総合モード用） diff --git a/.claude/agents-ja/integration-test-reviewer.md b/.claude/agents-ja/integration-test-reviewer.md index 88fd002..0bcdd06 100644 --- a/.claude/agents-ja/integration-test-reviewer.md +++ b/.claude/agents-ja/integration-test-reviewer.md @@ -43,8 +43,8 @@ CLAUDE.mdの原則を適用しない独立したコンテキストを持ち、 ### 1. スケルトンコメントの抽出 -指定された`testFile`から以下のスケルトンコメントを抽出: -- `// AC:`, `// ROI:`, `// 振る舞い:`, `// Property:`, `// 検証項目:`, `// @category:`, `// @dependency:`, `// @complexity:` +指定された`testFile`から以下のアノテーションパターンを抽出（コメント構文はプロジェクト言語に依存）: +- `AC:`, `ROI:`, `振る舞い:`, `Property:`, `検証項目:`, `@category:`, `@dependency:`, `@complexity:` ### 2. スケルトン整合性チェック diff --git a/.claude/agents-ja/quality-fixer-frontend.md b/.claude/agents-ja/quality-fixer-frontend.md index 3369c78..8300f48 100644 --- a/.claude/agents-ja/quality-fixer-frontend.md +++ b/.claude/agents-ja/quality-fixer-frontend.md @@ -95,7 +95,7 @@ package.jsonからフロントエンドビルドコマンドを自動検出し - 型チェック成功 - Lint/Format成功（Biome） -### blocked（仕様不明確で判断不能） +### blocked（仕様不明確または実行前提条件の不足で判断不能） **仕様確認プロセス**: blockedにする前に、以下の順序で仕様を確認： @@ -111,8 +111,14 @@ blockedにする前に、以下の順序で仕様を確認： | テストと実装が矛盾し、両方とも技術的には妥当 | テスト「ボタン無効化」、実装「ボタン有効」 | 正しいUX要件が判断不能 | | 外部システムの期待値が特定できない | 外部APIが複数のレスポンス形式に対応可能 | 全確認手段を試しても判断不能 | | 複数の実装方法があり、UX価値が異なる | バリデーション「blur時」vs「submit時」 | 正しいUX設計が判断不能 | +| 実行前提条件の不足 | テストDB、seed data、必要なライブラリ、環境変数、外部サービスへのアクセスが未準備 | 前提条件なしではテスト実行不可 — コード修正では解決しない | -**判定ロジック**: 技術的に解決可能な問題は全て修正。ビジネス/UX判断が必要な場合のみblocked。 +**判定ロジック**: 技術的に解決可能な問題は全て修正。ビジネス/UX判断が必要な場合、または実行前提条件が不足している場合のみblocked。 + +**実行前提条件のエスカレーション**: 環境の不足によりテストが失敗する場合、不足している前提条件を具体的な解決ステップとともに報告する。以下を含めること: +- 何が不足しているか（ライブラリ、seed data、環境変数、実行中のサービス等） +- どのテストが影響を受けるか +- 解決に何が必要か（具体的なステップ、曖昧な記述は不可） ## 出力フォーマット @@ -172,10 +178,10 @@ blockedにする前に、以下の順序で仕様を確認： "totalWarnings": 0, "executionTime": "3m 30s" }, - "approved": true, "nextActions": "コミット準備完了" } ``` +Note: `status`フィールドが成功の主要指標。オーケストレーターは`status: "approved"`で次に進む。 **品質チェック処理中（内部利用のみ、レスポンスに含めない）**: - エラー発見 → 即座に修正実行 @@ -184,11 +190,11 @@ blockedにする前に、以下の順序で仕様を確認： - blocked条件 → 複数の修正アプローチがあり、正しい仕様が判断不能な場合のみ - デフォルト動作 → approvedになるまで修正継続 -**blocked レスポンス形式**: +**blockedレスポンス形式（specification conflict）**: ```json { "status": "blocked", - "reason": "仕様不明確で判断不能", + "reason": "Cannot determine due to unclear specification", "blockingIssues": [{ "type": "ux_specification_conflict", "details": "ユーザーインタラクション動作についてテスト期待値と実装が矛盾", @@ -205,6 +211,27 @@ blockedにする前に、以下の順序で仕様を確認： } ``` +**blockedレスポンス形式（missing prerequisites）**: + +`missingPrerequisites[].type` の有効値: `seed_data`, `library`, `environment_variable`, `running_service`, `other` + +```json +{ + "status": "blocked", + "reason": "Execution prerequisites not met", + "missingPrerequisites": [ + { + "type": "seed_data", + "description": "E2Eテスト用DBにアクティブなサブスクリプションを持つテストプレイヤーが存在しない", + "affectedTests": ["training-e2e-tests"], + "resolutionSteps": ["E2Eテストプレイヤー用seed scriptの作成", "サブスクリプションレコードをseedに追加"] + } + ], + "testsSkipped": 3, + "testsPassedWithoutPrerequisites": 47 +} +``` + ## 中間進捗レポート 実行中、ツール呼び出しの間に以下のフォーマットで進捗を報告する: @@ -333,4 +360,4 @@ graph TD - 外部システムの期待値を特定できず、全確認手段を試しても判断できない - 実装方法でUX/ビジネス価値が異なり、正しい選択を判断できない -**判定ロジック**: 技術的に解決可能な問題は全て修正；UX/ビジネス判断が必要な場合のみblocked。 +**判定ルール**: 技術的に解決可能な問題は全て修正。UX/ビジネス判断が必要な場合、または実行前提条件が不足している場合のみblocked。 diff --git a/.claude/agents-ja/quality-fixer.md b/.claude/agents-ja/quality-fixer.md index 72e7869..695efdf 100644 --- a/.claude/agents-ja/quality-fixer.md +++ b/.claude/agents-ja/quality-fixer.md @@ -59,7 +59,7 @@ package.jsonの`packageManager`フィールドに応じた実行コマンドを - 型チェック成功 - Lint/Format成功 -### blocked（仕様不明確で判断不能） +### blocked（仕様不明確または実行前提条件の不足で判断不能） **仕様確認プロセス**： blockedにする前に、以下の順序で仕様を確認： @@ -75,8 +75,14 @@ blockedにする前に、以下の順序で仕様を確認： | テストと実装が矛盾し、両方とも技術的には妥当 | テスト「500エラー」、実装「400エラー」 | ビジネス要件として正しい方が判断不能 | | 外部システムの期待値が特定できない | 外部APIが複数のレスポンス形式に対応可能 | 全確認手段を試しても判断不能 | | 複数の実装方法があり、ビジネス価値が異なる | 割引計算で「税込から割引」vs「税抜から割引」 | 正しいビジネスロジックが判断不能 | +| 実行前提条件の不足 | テストDB、seed data、必要なライブラリ、環境変数、外部サービスへのアクセスが未準備 | 前提条件なしではテスト実行不可 — コード修正では解決しない | -**判定ロジック**: 技術的に解決可能な問題は全て修正。ビジネス判断が必要な場合のみblocked。 +**判定ロジック**: 技術的に解決可能な問題は全て修正。ビジネス判断が必要な場合、または実行前提条件が不足している場合のみblocked。 + +**実行前提条件のエスカレーション**: 環境の不足によりテストが失敗する場合、不足している前提条件を具体的な解決ステップとともに報告する。以下を含めること: +- 何が不足しているか（ライブラリ、seed data、環境変数、実行中のサービス等） +- どのテストが影響を受けるか +- 解決に何が必要か（具体的なステップ、曖昧な記述は不可） ## 出力フォーマット @@ -133,10 +139,10 @@ blockedにする前に、以下の順序で仕様を確認： "totalWarnings": 0, "executionTime": "2m 15s" }, - "approved": true, "nextActions": "コミット可能です" } ``` +Note: `status`フィールドが成功の主要指標。オーケストレーターは`status: "approved"`で次に進む。 **品質チェック処理中（内部のみ使用、レスポンスには含めない）**: - エラー発見 → 即座に修正を実行 @@ -145,11 +151,11 @@ blockedにする前に、以下の順序で仕様を確認： - blocked条件 → 複数の修正アプローチが存在し、正しい仕様が判断不能な場合のみ - デフォルト動作 → approvedまで修正を継続 -**blockedレスポンス形式**: +**blockedレスポンス形式（specification conflict）**: ```json { "status": "blocked", - "reason": "仕様不明確により判断不能", + "reason": "Cannot determine due to unclear specification", "blockingIssues": [{ "type": "specification_conflict", "details": "テスト期待値と実装が矛盾", @@ -166,6 +172,27 @@ blockedにする前に、以下の順序で仕様を確認： } ``` +**blockedレスポンス形式（missing prerequisites）**: + +`missingPrerequisites[].type` の有効値: `seed_data`, `library`, `environment_variable`, `running_service`, `other` + +```json +{ + "status": "blocked", + "reason": "Execution prerequisites not met", + "missingPrerequisites": [ + { + "type": "seed_data", + "description": "E2Eテスト用DBにアクティブなサブスクリプションを持つテストプレイヤーが存在しない", + "affectedTests": ["training-e2e-tests"], + "resolutionSteps": ["E2Eテストプレイヤー用seed scriptの作成", "サブスクリプションレコードをseedに追加"] + } + ], + "testsSkipped": 3, + "testsPassedWithoutPrerequisites": 47 +} +``` + ## 中間進捗レポート 実行中、ツール呼び出しの間に以下のフォーマットで進捗を報告する: @@ -288,4 +315,4 @@ graph TD - 外部システムの期待値が特定できず、全ての確認手段を試しても判断不能 - 実装方法によってビジネス価値が異なり、正しい選択が判断不能 -**判定ロジック**: 技術的に解決可能な問題は全て修正し、ビジネス判断が必要な場合のみblocked。 +**判定ルール**: 技術的に解決可能な問題は全て修正。ビジネス判断が必要な場合、または実行前提条件が不足している場合のみblocked。 diff --git a/.claude/agents-ja/task-decomposer.md b/.claude/agents-ja/task-decomposer.md index b954150..65dbcbf 100644 --- a/.claude/agents-ja/task-decomposer.md +++ b/.claude/agents-ja/task-decomposer.md @@ -87,18 +87,38 @@ implementation-approachスキルで決定された実装戦略パターンに基 - ファイル名: `{計画書名}-phase{番号}-completion.md` - 内容: 全タスク完了チェックリスト、テストスケルトンファイルパスを検証用に記載 - 判断基準: 計画書に「Phase」という文字列があれば必ず生成 + - **Phase 0（環境セットアップ）**: 作業計画にPhase 0の`@category: e2e-setup`タスクが含まれる場合、これらは環境セットアップタスク（seed data、auth fixture、serviceモック）であり、通常の実装タスクとは異なる。実装指向ではなくセットアップ指向の調査対象（既存の設定ファイル、環境スクリプト、fixtureパターン）で分解する 5. **タスクの構造化** 各タスクファイルに以下を含める： - タスク概要 - 対象ファイル + - **調査対象**（executorが実装前に読んで理解すべきもの） - 具体的な実装手順 - 完了条件 -6. **実装方針の一貫性** +6. **調査対象の決定** + 各タスクについて、タスクの性質に基づきexecutorが読むべき内容を決定する: + + | タスクの性質 | 調査対象 | + |---|---| + | 既存コードの修正 | 修正対象の既存実装ファイル、そのテスト、関連するDesign Docセクション | + | 新規コンポーネント/機能 | 同一レイヤー/ドメインの隣接実装、Design Docのインターフェース契約 | + | テスト実装 | テストスケルトンのコメント/アノテーション、テスト対象コード、実際のAPI/認証フロー | + | E2E環境セットアップ | 現在の環境設定（起動スクリプト、docker-compose等）、seed scripts、既存のfixtureパターン、アプリケーション認証フロー | + | バグ修正 / リファクタリング | 影響を受けるコードパス、関連テストカバレッジ、エラー再現コンテキスト | + + **原則**: + - 全タスクに最低1つの調査対象を設定する（Design Docのみでも可） + - 調査対象は**ファイルパス**で指定する — 実行すべきアクションではない + - ファイルパスは具体的に: `src/orders/checkout`, `docs/design/payment.md` — 「注文モジュール」「関連コード」ではなく + - ファイル内の特定セクションが対象の場合はサーチヒントを付与: `docs/design/payment.md (§ Payment Flow)` or `src/orders/checkout (processOrder関数)` + - タスクにテストスケルトンが存在する場合は必ず調査対象に含める + +7. **実装方針の一貫性** 実装サンプルを含める場合は、作業計画書の元となったDesign Docの実装方針に完全準拠すること -7. **テスト情報の活用** +8. **テスト情報の活用** 作業計画書にテスト情報（fast-check使用、依存関係、複雑度等）が記載されている場合、その情報をタスクファイルに反映する。 ## タスクファイルテンプレート @@ -236,6 +256,7 @@ implementation-approachスキルで決定された実装戦略パターンに基 - [ ] 明確な完了条件の設定 - [ ] 全体設計書の作成 - [ ] 実装効率と手戻り防止（共通処理の事前識別、影響範囲の明確化） +- [ ] 全タスクに調査対象が指定されている（具体的なファイルパス、曖昧なカテゴリではない） ## タスク設計の原則 diff --git a/.claude/agents-ja/task-executor-frontend.md b/.claude/agents-ja/task-executor-frontend.md index fcee275..3fcfc3e 100644 --- a/.claude/agents-ja/task-executor-frontend.md +++ b/.claude/agents-ja/task-executor-frontend.md @@ -9,6 +9,15 @@ skills: frontend-typescript-rules, frontend-typescript-testing, coding-standards CLAUDE.mdの原則を適用しない独立したコンテキストを持ち、タスク完了まで独立した判断で実行します。 +## フェーズ開始ゲート [BLOCKING — 未チェック項目があればHALT] + +☐ [確認済] frontmatterの全必須スキルがロード済み +☐ [確認済] タスクファイルが存在し未完了項目がある +☐ [確認済] タスクファイルから対象ファイルリストを抽出済み +☐ [確認済] 調査対象を読み込み主要な所見を記録済み（タスクファイルに記載がある場合） + +**強制**: いずれかが未チェックの場合はHALTし、`status: "escalation_needed"`を返却。 + ## 必須ルール **タスク登録**: TaskCreateで作業ステップを登録。必ず最初に「スキル制約の確認」、最後に「スキル忠実度の検証」を含める。各完了時にTaskUpdateで更新。 @@ -105,7 +114,13 @@ package.jsonの`packageManager`フィールドに応じた実行コマンドを `docs/plans/tasks/*-task-*.md` パターンのファイルで、未完了チェックボックス `[ ]` が残っているものを選択して実行 ### 2. タスク背景理解 -**依存成果物の活用**: +#### 調査対象（タスクファイルに記載がある場合は必須） +1. タスクファイル「調査対象」セクションからファイルパスを抽出 +2. **実装前に**各ファイルをReadツールで読み込む。サーチヒントが付与されている場合（例: `(§ Auth Flow)` や `(authenticateUser関数)`）、そのセクションを特定して重点的に確認 +3. 各調査対象で観察した主要なインターフェース・関数シグネチャ、制御/データフロー、状態遷移、副作用を記録する — これらの所見が実装をガイドする +4. 調査対象のファイルが存在しない、またはパスが古い場合は `reason: "investigation_target_not_found"` でエスカレーション（エスカレーションレスポンス2-3参照） + +#### 依存成果物 1. タスクファイル「Dependencies」セクションからパスを抽出 2. 各成果物をReadツールで読み込み 3. **具体的な活用方法**: @@ -252,9 +267,39 @@ Design Doc通りに実装できない場合、以下のJSON形式でエスカレ } ``` -## 完了条件 +#### 2-3. 調査対象未発見エスカレーション +調査対象のファイルが存在しない、またはパスが古い場合、以下のJSON形式でエスカレーション: + +```json +{ + "status": "escalation_needed", + "reason": "Investigation target not found", + "taskName": "[実行中のタスク名]", + "escalation_type": "investigation_target_not_found", + "missingTargets": [ + { + "path": "[タスクファイルで指定されたパス]", + "searchHint": "[セクション/関数ヒントがある場合はそれ、なければnull]", + "searchAttempts": ["パスを直接確認", "同一ディレクトリ内で類似ファイル名を検索"] + } + ], + "user_decision_required": true, + "suggested_options": [ + "正しいファイルパスを提供", + "この調査対象を除外して続行", + "タスクファイルを現在のパスで更新" + ] +} +``` + +## 完了ゲート [BLOCKING] + +☐ 全タスクチェックボックスがエビデンス付きで完了 +☐ 調査対象を読み込み、実装前に所見を記録した（タスクファイルに記載がある場合） +☐ 実装が調査対象から記録した所見と整合している +☐ 最終レスポンスが`completed`または`escalation_needed`ステータスの単一JSON -- [ ] 最終レスポンスが`completed`または`escalation_needed`ステータスの単一JSON +**強制**: いずれかが未チェックの場合はHALT。`status: "escalation_needed"`を返却。 ## 実行原則 diff --git a/.claude/agents-ja/task-executor.md b/.claude/agents-ja/task-executor.md index d3f67b7..0365571 100644 --- a/.claude/agents-ja/task-executor.md +++ b/.claude/agents-ja/task-executor.md @@ -9,6 +9,15 @@ skills: typescript-rules, typescript-testing, coding-standards, project-context, CLAUDE.mdの原則を適用しない独立したコンテキストを持ち、タスク完了まで独立した判断で実行します。 +## フェーズ開始ゲート [BLOCKING — 未チェック項目があればHALT] + +☐ [確認済] frontmatterの全必須スキルがロード済み +☐ [確認済] タスクファイルが存在し未完了項目がある +☐ [確認済] タスクファイルから対象ファイルリストを抽出済み +☐ [確認済] 調査対象を読み込み主要な所見を記録済み（タスクファイルに記載がある場合） + +**強制**: いずれかが未チェックの場合はHALTし、`status: "escalation_needed"`を返却。 + ## 必須ルール **タスク登録**: TaskCreateで作業ステップを登録。必ず最初に「スキル制約の確認」、最後に「スキル忠実度の検証」を含める。各完了時にTaskUpdateで更新。 @@ -102,7 +111,13 @@ CLAUDE.mdの原則を適用しない独立したコンテキストを持ち、 `docs/plans/tasks/*-task-*.md` パターンのファイルから、未完了のチェックボックス `[ ]` が残っているものを選択して実行 ### 2. タスク背景理解 -**依存成果物の活用**： +#### 調査対象（タスクファイルに記載がある場合は必須） +1. タスクファイル「調査対象」セクションからファイルパスを抽出 +2. **実装前に**各ファイルをReadツールで読み込む。サーチヒントが付与されている場合（例: `(§ Auth Flow)` や `(authenticateUser関数)`）、そのセクションを特定して重点的に確認 +3. 各調査対象で観察した主要なインターフェース・関数シグネチャ、制御/データフロー、状態遷移、副作用を記録する — これらの所見が実装をガイドする +4. 調査対象のファイルが存在しない、またはパスが古い場合は `reason: "investigation_target_not_found"` でエスカレーション（エスカレーションレスポンス2-3参照） + +#### 依存成果物 1. タスクファイルの「依存」セクションからパスを取得 2. 各成果物をReadツールで読み込み 3. **具体的活用**： @@ -249,9 +264,39 @@ Design Doc通りに実装できない場合は以下のJSON形式でエスカレ } ``` -## 完了条件 +#### 2-3. 調査対象未発見エスカレーション +調査対象のファイルが存在しない、またはパスが古い場合、以下のJSON形式でエスカレーション: + +```json +{ + "status": "escalation_needed", + "reason": "Investigation target not found", + "taskName": "[実行中のタスク名]", + "escalation_type": "investigation_target_not_found", + "missingTargets": [ + { + "path": "[タスクファイルで指定されたパス]", + "searchHint": "[セクション/関数ヒントがある場合はそれ、なければnull]", + "searchAttempts": ["パスを直接確認", "同一ディレクトリ内で類似ファイル名を検索"] + } + ], + "user_decision_required": true, + "suggested_options": [ + "正しいファイルパスを提供", + "この調査対象を除外して続行", + "タスクファイルを現在のパスで更新" + ] +} +``` + +## 完了ゲート [BLOCKING] + +☐ 全タスクチェックボックスがエビデンス付きで完了 +☐ 調査対象を読み込み、実装前に所見を記録した（タスクファイルに記載がある場合） +☐ 実装が調査対象から記録した所見と整合している +☐ 最終レスポンスが`completed`または`escalation_needed`ステータスの単一JSON -- [ ] 最終レスポンスが`completed`または`escalation_needed`ステータスの単一JSON +**強制**: いずれかが未チェックの場合はHALT。`status: "escalation_needed"`を返却。 ## 実行原則 diff --git a/.claude/agents-ja/technical-designer-frontend.md b/.claude/agents-ja/technical-designer-frontend.md index 9edc929..cefd5ef 100644 --- a/.claude/agents-ja/technical-designer-frontend.md +++ b/.claude/agents-ja/technical-designer-frontend.md @@ -173,6 +173,13 @@ Design Doc作成前に実施： - `reverse-engineer`: 既存フロントエンドアーキテクチャの現状ドキュメント化（reverse-engineerモードセクション参照） - **要件分析結果**: 要件分析の結果（規模判定、技術要件等） +- **コードベース分析**（任意、コードベース分析エージェントから提供）: + - 提供された場合、「既存コードベース分析」セクションの主要ソースとして使用 + - `existingElements` → Implementation Path MappingとCode Inspection Evidenceに反映 + - `dataModel` → データ関連セクション（スキーマ参照、データ契約）に反映 + - `focusAreas` → フラグされた領域の調査深度を優先 + - `constraints` → 設計上の制約と前提条件に組み込む + - 分析でカバーされていない領域、または`limitations`でフラグされた領域についてのみ追加調査を実施 - **PRD**: PRDドキュメント（存在する場合） - **UI Spec**: UI Specパス（存在する場合、コンポーネント構造と状態設計を継承） - **作成対象ドキュメント**: ADR、Design Doc、または両方 diff --git a/.claude/agents-ja/technical-designer.md b/.claude/agents-ja/technical-designer.md index 2caf2a0..bc50004 100644 --- a/.claude/agents-ja/technical-designer.md +++ b/.claude/agents-ja/technical-designer.md @@ -200,6 +200,13 @@ Design Doc作成前に実施： - `reverse-engineer`: 既存アーキテクチャの現状ドキュメント化（reverse-engineerモードセクション参照） - **要件分析結果**: 要件分析の結果（規模判定、技術要件等） +- **コードベース分析**（任意、コードベース分析エージェントから提供）: + - 提供された場合、「既存コードベース分析」セクションの主要ソースとして使用 + - `existingElements` → Implementation Path MappingとCode Inspection Evidenceに反映 + - `dataModel` → データ関連セクション（スキーマ参照、データ契約）に反映 + - `focusAreas` → フラグされた領域の調査深度を優先 + - `constraints` → 設計上の制約と前提条件に組み込む + - 分析でカバーされていない領域、または`limitations`でフラグされた領域についてのみ追加調査を実施 - **PRD**: PRDドキュメント（存在する場合） - **作成するドキュメント**: ADR、Design Doc、または両方 - **既存アーキテクチャ情報**: diff --git a/.claude/agents-ja/work-planner.md b/.claude/agents-ja/work-planner.md index 203a4f2..3da5040 100644 --- a/.claude/agents-ja/work-planner.md +++ b/.claude/agents-ja/work-planner.md @@ -115,30 +115,50 @@ Design Docの受入条件を基に、段階的に品質を確保。 テストスケルトンファイル（統合テスト、E2Eテスト）をReadツールで読み込み、コメントからメタ情報を抽出する。 -**抽出対象のコメントパターン**: -- `// @category:` → テスト分類（core-functionality, edge-case, e2e等） -- `// @dependency:` → 依存コンポーネント（フェーズ配置の判断材料） -- `// @complexity:` → 複雑度（high/medium/low、工数見積もりの判断材料） -- `// fast-check:` → Property-Based Test実装パターン（**重要**: このコメントがあるテストは「fast-checkライブラリ使用」と作業計画に明記） -- `// ROI:` → 優先度判断 +**抽出対象のアノテーションパターン**（コメント構文はプロジェクト言語に依存）: +- `@category:` → テスト分類（core-functionality, edge-case, e2e等） +- `@dependency:` → 依存コンポーネント（フェーズ配置の判断材料） +- `@complexity:` → 複雑度（high/medium/low、工数見積もりの判断材料） +- `@real-dependency:` → 非モックセットアップが必要なコンポーネント。環境セットアップ完了後のフェーズに配置 +- `fast-check:` → Property-Based Test実装パターン（**重要**: このコメントがあるテストは「fast-checkライブラリ使用」と作業計画に明記） +- `ROI:` → 優先度判断 #### Step 2: メタ情報の作業計画への反映 1. **Property-Based Test（fast-check）の明記** - - `// fast-check:` コメントがあるテスト → 該当タスクの実装手順に以下を追加: + - `fast-check:` コメントがあるテスト → 該当タスクの実装手順に以下を追加: - 「fast-checkライブラリを使用したproperty-based testを実装」 - コメント内のパターン（`fc.property(...)`）をサンプルコードとして記載 2. **依存関係に基づくフェーズ配置** - - `// @dependency: none` → 早いフェーズに配置 - - `// @dependency: [コンポーネント名]` → 依存コンポーネント実装後のフェーズに配置 - - `// @dependency: full-system` → 最終フェーズに配置 + - `@dependency: none` → 早いフェーズに配置 + - `@dependency: [コンポーネント名]` → 依存コンポーネント実装後のフェーズに配置 + - `@dependency: full-system` → 最終フェーズに配置 3. **複雑度に基づく工数見積もり** - - `// @complexity: high` → タスクを細分化、または工数を多めに見積もる - - `// @complexity: low` → 複数テストを1タスクにまとめることを検討 + - `@complexity: high` → タスクを細分化、または工数を多めに見積もる + - `@complexity: low` → 複数テストを1タスクにまとめることを検討 -#### Step 3: it.todoの構造分析と分類 +#### Step 3: E2EスケルトンからのEnvironment Prerequisites抽出 + +E2Eテストスケルトンが提供された場合、2段階で環境前提条件をスキャンする: + +**Stage 1: 前提条件パターンの検出** — 全E2Eスケルトンをスキャンし、検出した全前提条件を列挙: +- seed data、テストユーザー、サブスクリプション、特定のDB状態に言及する`Preconditions:`または`Arrange:`コメントアノテーション +- auth/loginセットアップコードと組み合わされた`@dependency: full-system` +- 環境変数への参照（`E2E_*`, `TEST_*`） +- テストコード内のHTTP mock/interceptパターンを必要とする外部サービス参照 + +**Stage 2: セットアップタスクの生成** — 検出した各前提条件に対応するPhase 0タスクを作成。一般的なカテゴリ: +- **Seed data** → 「E2E seed data scriptの作成（テストユーザー、必要なレコード）」 +- **Auth fixture** → 「アプリケーションのログインフローを使用したE2E auth fixtureの実装」 +- **外部サービスモック** → 「E2Eテスト用の外部サービスモック設定」 +- **環境設定** → 「E2E環境変数の定義とセットアップ手順の文書化」 +- **その他の検出された前提条件** → 検出カテゴリに合わせたセットアップタスクを作成 + +全環境セットアップタスクをPhase 0（実装タスクより前）に配置する。トレーサビリティのため`@category: e2e-setup`を付与。 + +#### Step 4: it.todoの構造分析と分類 1. **it.todoの構造分析と分類** - セットアップ系（Mock準備、測定ツール、Helper等）→ Phase 1に最優先配置 @@ -181,7 +201,7 @@ Design Docの技術的依存関係と実装アプローチに基づいてフェ 最終フェーズには必ず品質保証（全テスト通過、受入条件達成）を含める。 ### テストスケルトンの統合 -計画プロセスのステップ4で定義したテストスケルトン配置ルールに従う。 +計画プロセス（フェーズ構成ステップ）で定義したテストスケルトン配置ルールに従う。 ### タスクの依存関係 - 依存関係を明確に定義 @@ -199,6 +219,9 @@ Design Docの技術的依存関係と実装アプローチに基づいてフェ - [ ] 全要件のタスク化 - [ ] 最終フェーズに品質保証の存在 - [ ] テストスケルトンファイルパスを対応するフェーズに記載（提供時） +- [ ] E2E環境前提条件に対応済み（E2Eスケルトンが提供された場合） + - [ ] seed data、auth fixture、外部サービスモックのタスクを生成 + - [ ] 環境セットアップタスクをPhase 0に配置 - [ ] テスト設計情報の反映（提供された場合のみ） - [ ] セットアップタスクが最初のフェーズに配置されている - [ ] リスクレベルに基づく優先順位付けが適用されている diff --git a/.claude/commands-en/design.md b/.claude/commands-en/design.md index c963731..0bd6387 100644 --- a/.claude/commands-en/design.md +++ b/.claude/commands-en/design.md @@ -11,7 +11,8 @@ description: Execute from requirement analysis to design document creation **Execution Protocol**: 1. **Delegate all work through Agent tool** — invoke sub-agents, pass data between them, and report results (permitted tools: see subagents-orchestration-guide "Orchestrator's Permitted Tools") 2. **Follow subagents-orchestration-guide skill design flow exactly**: - - Execute: requirement-analyzer → technical-designer → document-reviewer → design-sync + - Execute: requirement-analyzer → codebase-analyzer → technical-designer → code-verifier → document-reviewer → design-sync + - **ADR-only**: Skip codebase-analyzer and code-verifier (these apply to Design Doc only) - **Stop at every `[Stop: ...]` marker** → Wait for user approval before proceeding 3. **Scope**: Complete when design documents receive approval @@ -22,7 +23,9 @@ description: Execute from requirement analysis to design document creation ``` Requirements → requirement-analyzer → [Stop: Scale determination] ↓ - technical-designer → document-reviewer + codebase-analyzer → technical-designer + ↓ + code-verifier → document-reviewer ↓ design-sync → [Stop: Design approval] ``` @@ -38,12 +41,16 @@ Once requirements are moderately clarified, analyze with requirement-analyzer an Clearly present design alternatives and trade-offs. +Execute the process below within design scope. Follow subagents-orchestration-guide Call Examples for codebase-analyzer and code-verifier invocations. + ## Scope Boundaries **Included in this command**: - Requirement analysis with requirement-analyzer +- Codebase analysis with codebase-analyzer (before technical design) - ADR creation (if architecture changes, new technology, or data flow changes) - Design Doc creation with technical-designer +- Design Doc verification with code-verifier (before document review) - Document review with document-reviewer - Design Doc consistency verification with design-sync @@ -52,17 +59,21 @@ Clearly present design alternatives and trade-offs. ## Execution Flow 1. requirement-analyzer → Requirement analysis -2. technical-designer → Design Doc creation -3. document-reviewer → Single document quality check -4. User approval (WAIT for approval) -5. design-sync → Design Doc consistency verification +2. codebase-analyzer → Codebase analysis (pass requirement-analyzer output) +3. technical-designer → Design Doc creation (pass codebase-analyzer output) +4. code-verifier → Verify Design Doc against existing code +5. document-reviewer → Single document quality check (pass code-verifier results) +6. User approval (WAIT for approval) +7. design-sync → Design Doc consistency verification - IF conflicts found → Report to user → Wait for fix instructions → Fix with technical-designer(update) - IF no conflicts → End ## Completion Criteria - [ ] Executed requirement-analyzer and determined scale +- [ ] Executed codebase-analyzer and passed results to technical-designer - [ ] Created appropriate design document (ADR or Design Doc) with technical-designer +- [ ] Executed code-verifier on Design Doc and passed results to document-reviewer (skip for ADR-only) - [ ] Executed document-reviewer and addressed feedback - [ ] Executed design-sync for consistency verification - [ ] Obtained user approval for design document diff --git a/.claude/commands-en/front-design.md b/.claude/commands-en/front-design.md index 99faaae..4da3735 100644 --- a/.claude/commands-en/front-design.md +++ b/.claude/commands-en/front-design.md @@ -20,9 +20,11 @@ Orchestrator invokes sub-agents and passes structured JSON between them. **Included in this command**: - Requirement analysis with requirement-analyzer +- Codebase analysis with codebase-analyzer (before Design Doc creation) - UI Specification creation with ui-spec-designer (prototype code inquiry included) - ADR creation (if architecture changes, new technology, or data flow changes) - Design Doc creation with technical-designer-frontend +- Design Doc verification with code-verifier (before document review) - Document review with document-reviewer **Responsibility Boundary**: This command completes with frontend design document (UI Spec/ADR/Design Doc) approval. Work planning and beyond are outside scope. @@ -63,12 +65,18 @@ Then create the UI Specification: - **[STOP]**: Present UI Spec for user approval ### Step 3: Design Document Creation Phase +First, analyze the existing codebase: +- Invoke **codebase-analyzer** using Agent tool + - `subagent_type: "codebase-analyzer"`, `description: "Codebase analysis"`, `prompt: "requirement_analysis: [JSON from Step 1]. requirements: [user requirements]. Analyze existing codebase for frontend design guidance."` + Create appropriate design documents according to scale determination: - Invoke **technical-designer-frontend** using Agent tool - For ADR: `subagent_type: "technical-designer-frontend"`, `description: "ADR creation"`, `prompt: "Create ADR for [technical decision]"` - - For Design Doc: `subagent_type: "technical-designer-frontend"`, `description: "Design Doc creation"`, `prompt: "Create Design Doc based on requirements. UI Spec is at [ui-spec path]. Inherit component structure and state design from UI Spec."` -- Invoke **document-reviewer** to verify consistency - - `subagent_type: "document-reviewer"`, `description: "Document review"`, `prompt: "Review [document path] for consistency and completeness"` + - For Design Doc: `subagent_type: "technical-designer-frontend"`, `description: "Design Doc creation"`, `prompt: "Create Design Doc based on requirements. Codebase analysis: [JSON from codebase-analyzer]. UI Spec is at [ui-spec path]. Inherit component structure and state design from UI Spec."` +- **(Design Doc only)** Invoke **code-verifier** to verify Design Doc against existing code. Skip for ADR. + - `subagent_type: "code-verifier"`, `description: "Design Doc verification"`, `prompt: "doc_type: design-doc document_path: [Design Doc path] Verify Design Doc against existing code."` +- Invoke **document-reviewer** to verify consistency (pass code-verifier results for Design Doc; omit for ADR) + - `subagent_type: "document-reviewer"`, `description: "Document review"`, `prompt: "doc_type: DesignDoc target: [document path] mode: composite code_verification: [JSON from code-verifier] (Design Doc only) Review for consistency and completeness."` - **[STOP]**: Present design alternatives and trade-offs, obtain user approval ## Output Example diff --git a/.claude/commands-en/implement.md b/.claude/commands-en/implement.md index 42692f5..1f0a30c 100644 --- a/.claude/commands-en/implement.md +++ b/.claude/commands-en/implement.md @@ -52,6 +52,8 @@ After scale determination, **register all steps of the applicable subagents-orch - [ ] Identified current progress position - [ ] Clarified next step - [ ] Recognized stopping points → **Use AskUserQuestion for confirmation at all Stop points** +- [ ] codebase-analyzer included before each Design Doc creation +- [ ] code-verifier included before document-reviewer for each Design Doc - [ ] Understood the 4-step cycle after task execution (task-executor → escalation judgment/follow-up → quality-fixer → commit) **Flow Adherence**: Follow "Autonomous Execution Task Management" in subagents-orchestration-guide skill, managing 4 steps with TaskCreate/TaskUpdate diff --git a/.claude/commands-en/reverse-engineer.md b/.claude/commands-en/reverse-engineer.md index 02a0d12..33dbeb4 100644 --- a/.claude/commands-en/reverse-engineer.md +++ b/.claude/commands-en/reverse-engineer.md @@ -142,9 +142,7 @@ prompt: | doc_type: PRD target: $STEP_2_OUTPUT mode: composite - - ## Code Verification Results - $STEP_3_OUTPUT + code_verification: $STEP_3_OUTPUT ## Additional Review Focus - Alignment between PRD claims and verification evidence @@ -308,9 +306,7 @@ prompt: | doc_type: DesignDoc target: $STEP_7_OUTPUT or $STEP_7_FRONTEND_OUTPUT mode: composite - - ## Code Verification Results - $STEP_8_OUTPUT + code_verification: $STEP_8_OUTPUT ## Parent PRD $APPROVED_PRD_PATH diff --git a/.claude/commands-en/update-doc.md b/.claude/commands-en/update-doc.md index 10cae1d..e4fcc13 100644 --- a/.claude/commands-en/update-doc.md +++ b/.claude/commands-en/update-doc.md @@ -25,8 +25,8 @@ description: Update existing design documents (Design Doc / PRD / ADR) with revi Target document → [Stop: Confirm changes] ↓ technical-designer / technical-designer-frontend / prd-creator (update mode) - ↓ - document-reviewer → [Stop: Review approval] + ↓ (Design Doc only) + code-verifier → document-reviewer → [Stop: Review approval] ↓ (Design Doc only) design-sync → [Stop: Final approval] ``` @@ -113,6 +113,18 @@ prompt: | ### Step 5: Document Review [Stop] +**For Design Doc updates only**: Before document-reviewer, invoke code-verifier: +``` +subagent_type: code-verifier +description: "Verify updated Design Doc" +prompt: | + doc_type: design-doc + document_path: [path from Step 1] + Verify the updated Design Doc against current codebase. +``` + +**Store output as**: `$CODE_VERIFICATION_OUTPUT` + Invoke document-reviewer: ``` subagent_type: document-reviewer @@ -123,6 +135,7 @@ prompt: | doc_type: [Design Doc / PRD / ADR] target: [path from Step 1] mode: standard + code_verification: $CODE_VERIFICATION_OUTPUT (Design Doc only, omit for PRD/ADR) Focus on: - Consistency of updated sections with rest of document @@ -191,6 +204,7 @@ prompt: | - [ ] Identified target document - [ ] Clarified change content with user - [ ] Updated document with appropriate agent (update mode) +- [ ] Executed code-verifier before document-reviewer (Design Doc only) - [ ] Executed document-reviewer and addressed feedback - [ ] Executed design-sync for consistency verification (Design Doc only) - [ ] Obtained user approval for updated document diff --git a/.claude/commands-ja/design.md b/.claude/commands-ja/design.md index 632379b..2166e05 100644 --- a/.claude/commands-ja/design.md +++ b/.claude/commands-ja/design.md @@ -11,7 +11,8 @@ description: 要件分析から設計書作成まで実行 **実行プロトコル**: 1. **全作業をAgentツールでサブエージェントに委譲** — サブエージェントの呼び出し、データの受け渡し、結果の報告（許可ツール: subagents-orchestration-guideスキル「オーケストレーターの許可ツール」参照） 2. **subagents-orchestration-guideスキルの設計フローに厳密に従う**: - - 実行: requirement-analyzer → technical-designer → document-reviewer → design-sync + - 実行: requirement-analyzer → codebase-analyzer → technical-designer → code-verifier → document-reviewer → design-sync + - **ADRのみの場合**: codebase-analyzerとcode-verifierはスキップ（Design Docにのみ適用） - **`[停止: ...]`マーカーで必ず停止** → 次に進む前にユーザー承認を待つ 3. **スコープ**: 設計書が承認されたら完了 @@ -22,7 +23,9 @@ description: 要件分析から設計書作成まで実行 ``` 要件 → requirement-analyzer → [停止: 規模判定] ↓ - technical-designer → document-reviewer + codebase-analyzer → technical-designer + ↓ + code-verifier → document-reviewer ↓ design-sync → [停止: 設計承認] ``` @@ -38,12 +41,16 @@ description: 要件分析から設計書作成まで実行 設計の代替案とトレードオフを明確に提示します。 +subagents-orchestration-guideのCall Examplesに従い、codebase-analyzerとcode-verifierを呼び出す。 + ## スコープ境界 **実行内容**: - requirement-analyzerによる要件分析 +- codebase-analyzerによるコードベース分析（技術設計の前に実施） - ADR作成（アーキテクチャ変更、新技術、データフロー変更がある場合） - technical-designerによるDesign Doc作成 +- code-verifierによるDesign Doc検証（ドキュメントレビューの前に実施） - document-reviewerによるドキュメントレビュー - design-syncによるDesign Doc間整合性検証 @@ -52,17 +59,21 @@ description: 要件分析から設計書作成まで実行 ## 実行フロー 1. requirement-analyzer → 要件分析 -2. technical-designer → Design Doc作成 -3. document-reviewer → 単一ドキュメント品質チェック -4. ユーザー承認（承認を待つ） -5. design-sync → Design Doc間整合性検証 +2. codebase-analyzer → コードベース分析（要件分析結果を入力） +3. technical-designer → Design Doc作成（codebase-analyzer出力を入力） +4. code-verifier → Design Docを既存コードに対して検証 +5. document-reviewer → 単一ドキュメント品質チェック（code-verifier結果を入力） +6. ユーザー承認（承認を待つ） +7. design-sync → Design Doc間整合性検証 - 矛盾あり → ユーザーに報告 → 修正指示待ち → technical-designer(update)で修正 - 矛盾なし → 終了 ## 完了条件 - [ ] requirement-analyzerを実行し規模を判定した +- [ ] codebase-analyzerを実行し結果をtechnical-designerに渡した - [ ] technical-designerで適切な設計書（ADRまたはDesign Doc）を作成した +- [ ] code-verifierでDesign Docを検証し結果をdocument-reviewerに渡した（ADRのみの場合はスキップ） - [ ] document-reviewerを実行しフィードバックに対応した - [ ] design-syncで整合性検証を実行した - [ ] ユーザーから設計書の承認を取得した diff --git a/.claude/commands-ja/front-design.md b/.claude/commands-ja/front-design.md index ef41500..ae65d46 100644 --- a/.claude/commands-ja/front-design.md +++ b/.claude/commands-ja/front-design.md @@ -20,9 +20,11 @@ description: 要件分析からフロントエンド設計ドキュメント作 **実行内容**: - requirement-analyzerによる要件分析 +- codebase-analyzerによるコードベース分析（Design Doc作成前に実施） - ui-spec-designerによるUI Spec作成（プロトタイプコード確認を含む） - ADR作成（アーキテクチャ変更、新技術、データフロー変更がある場合） - technical-designer-frontendによるDesign Doc作成 +- code-verifierによるDesign Doc検証（ドキュメントレビューの前に実施） - document-reviewerによるドキュメントレビュー **責務境界**: このコマンドはフロントエンド設計ドキュメント（UI Spec/ADR/Design Doc）の承認で責務完了。作業計画以降はスコープ外。 @@ -63,12 +65,18 @@ UI Specを作成: - **[停止]**: UI Specをユーザーに提示し承認を取得 ### Step 3: 設計ドキュメント作成フェーズ +まず既存コードベースを分析: +- Agentツールで**codebase-analyzer**を呼び出す + - `subagent_type: "codebase-analyzer"`, `description: "コードベース分析"`, `prompt: "requirement_analysis: [Step 1のJSON]. requirements: [ユーザー要件]. フロントエンド設計ガイダンスのため既存コードベースを分析。"` + 規模判定に応じて適切な設計ドキュメントを作成: - Agentツールで**technical-designer-frontend**を呼び出す - ADRの場合: `subagent_type: "technical-designer-frontend"`, `description: "ADR作成"`, `prompt: "[技術決定]のADRを作成"` - - Design Docの場合: `subagent_type: "technical-designer-frontend"`, `description: "Design Doc作成"`, `prompt: "要件に基づいてDesign Docを作成。UI Specは[ui-specパス]。UI Specのコンポーネント構造と状態設計を継承。"` -- **document-reviewer**で整合性検証 - - `subagent_type: "document-reviewer"`, `description: "ドキュメントレビュー"`, `prompt: "[ドキュメントパス]の整合性と完成度をレビュー"` + - Design Docの場合: `subagent_type: "technical-designer-frontend"`, `description: "Design Doc作成"`, `prompt: "要件に基づいてDesign Docを作成。コードベース分析: [codebase-analyzerのJSON]。UI Specは[ui-specパス]。UI Specのコンポーネント構造と状態設計を継承。"` +- **（Design Docのみ）** **code-verifier**でDesign Docを既存コードに対して検証。ADRの場合はスキップ。 + - `subagent_type: "code-verifier"`, `description: "Design Doc検証"`, `prompt: "doc_type: design-doc document_path: [Design Docパス] Design Docを既存コードに対して検証。"` +- **document-reviewer**で整合性検証（Design Docの場合はcode-verifier結果を渡す。ADRの場合は省略） + - `subagent_type: "document-reviewer"`, `description: "ドキュメントレビュー"`, `prompt: "doc_type: DesignDoc target: [ドキュメントパス] mode: composite code_verification: [code-verifierのJSON]（Design Docのみ） 整合性と完成度をレビュー。"` - **[停止]**: 設計の選択肢とトレードオフを提示し、ユーザー承認を取得 ## 出力例 diff --git a/.claude/commands-ja/implement.md b/.claude/commands-ja/implement.md index 2aaedcc..01f0f54 100644 --- a/.claude/commands-ja/implement.md +++ b/.claude/commands-ja/implement.md @@ -52,6 +52,8 @@ requirement-analyzerの`crossLayerScope`がレイヤー横断（backend + fronte - [ ] 現在の進捗位置を特定した - [ ] 次のステップを明確にした - [ ] 停止ポイントを認識した → **全ての停止ポイントでAskUserQuestionを使用** +- [ ] 各Design Doc作成前にcodebase-analyzerを含めた +- [ ] 各Design DocレビューでDesign Doc前にcode-verifierを含めた - [ ] タスク実行後の4ステップサイクル（task-executor → エスカレーション判定・フォローアップ → quality-fixer → commit）を理解した **フロー厳守**: subagents-orchestration-guideスキルの「自律実行中のタスク管理」に従い、TaskCreate/TaskUpdateで4ステップを管理する diff --git a/.claude/commands-ja/reverse-engineer.md b/.claude/commands-ja/reverse-engineer.md index 24ad699..e891210 100644 --- a/.claude/commands-ja/reverse-engineer.md +++ b/.claude/commands-ja/reverse-engineer.md @@ -142,9 +142,7 @@ prompt: | doc_type: PRD target: $STEP_2_OUTPUT mode: composite - - ## コード検証結果 - $STEP_3_OUTPUT + code_verification: $STEP_3_OUTPUT ## 追加レビュー観点 - PRD主張と検証evidenceの整合性 @@ -308,9 +306,7 @@ prompt: | doc_type: DesignDoc target: $STEP_7_OUTPUT または $STEP_7_FRONTEND_OUTPUT mode: composite - - ## コード検証結果 - $STEP_8_OUTPUT + code_verification: $STEP_8_OUTPUT ## 親PRD $APPROVED_PRD_PATH diff --git a/.claude/commands-ja/update-doc.md b/.claude/commands-ja/update-doc.md index 2fdd7b4..d0ab724 100644 --- a/.claude/commands-ja/update-doc.md +++ b/.claude/commands-ja/update-doc.md @@ -25,8 +25,8 @@ description: 既存設計ドキュメント（Design Doc / PRD / ADR）をレビ 対象ドキュメント → [停止: 変更内容確認] ↓ technical-designer / technical-designer-frontend / prd-creator（updateモード） - ↓ - document-reviewer → [停止: レビュー承認] + ↓（Design Docのみ） + code-verifier → document-reviewer → [停止: レビュー承認] ↓（Design Docのみ） design-sync → [停止: 最終承認] ``` @@ -113,6 +113,18 @@ prompt: | ### ステップ5: ドキュメントレビュー [停止] +**Design Doc更新時のみ**: document-reviewerの前にcode-verifierを呼び出す: +``` +subagent_type: code-verifier +description: "更新されたDesign Docを検証" +prompt: | + doc_type: design-doc + document_path: [ステップ1のパス] + 更新されたDesign Docを現在のコードベースに対して検証する。 +``` + +**出力を保存**: `$CODE_VERIFICATION_OUTPUT` + document-reviewerを呼び出す: ``` subagent_type: document-reviewer @@ -123,6 +135,7 @@ prompt: | doc_type: [Design Doc / PRD / ADR] target: [ステップ1のパス] mode: standard + code_verification: $CODE_VERIFICATION_OUTPUT（Design Docのみ、PRD/ADRでは省略） 注力ポイント: - 更新セクションとドキュメント全体の整合性 @@ -191,6 +204,7 @@ prompt: | - [ ] 対象ドキュメントを特定した - [ ] ユーザーと変更内容を確認した - [ ] 適切なエージェントでドキュメントを更新した（updateモード） +- [ ] code-verifierをdocument-reviewerの前に実行した（Design Docのみ） - [ ] document-reviewerを実行しフィードバックに対応した - [ ] design-syncで整合性検証を実行した（Design Docのみ） - [ ] 更新されたドキュメントのユーザー承認を取得した diff --git a/.claude/skills-en/documentation-criteria/references/design-template.md b/.claude/skills-en/documentation-criteria/references/design-template.md index 101fe13..71325db 100644 --- a/.claude/skills-en/documentation-criteria/references/design-template.md +++ b/.claude/skills-en/documentation-criteria/references/design-template.md @@ -266,6 +266,26 @@ Evaluate the following for this feature's trust boundaries and data flow: Mark items as N/A with brief rationale when the feature has no relevant trust boundary. +## Test Boundaries + +### Mock Boundary Decisions + +| Component/Dependency | Mock? | Rationale | +|---------------------|-------|-----------| +| [External API / DB / File system / etc.] | [Yes/No] | [Why this boundary was chosen] | + +### Data Layer Testing Strategy + +- **Schema dependencies**: [List tables/models this feature reads from or writes to, with paths to their definitions] +- **Test data approach**: [How test data is provided — fixtures, factories, seed scripts, or real database] +- **Mock limitations acknowledged**: [What cannot be reliably tested with mocks alone for this feature] + +Mark as N/A with brief rationale when the feature has no data layer dependencies. + +### Integration Verification Points + +- [List critical integration points that require testing beyond unit-level mocks] + ## Alternative Solutions ### Alternative 1 diff --git a/.claude/skills-en/documentation-criteria/references/task-template.md b/.claude/skills-en/documentation-criteria/references/task-template.md index 3b3310e..eaef819 100644 --- a/.claude/skills-en/documentation-criteria/references/task-template.md +++ b/.claude/skills-en/documentation-criteria/references/task-template.md @@ -13,8 +13,13 @@ Metadata: - [ ] [Implementation file path] - [ ] [Test file path] +## Investigation Targets +Files to read before starting implementation (file path, with optional search hint): +- [e.g., src/orders/checkout (processOrder function) — determined by task-decomposer based on task nature] + ## Implementation Steps (TDD: Red-Green-Refactor) ### 1. Red Phase +- [ ] Read all Investigation Targets and record key observations - [ ] Review dependency deliverables (if any) - [ ] Verify/create contract definitions - [ ] Write failing tests diff --git a/.claude/skills-en/integration-e2e-testing/SKILL.md b/.claude/skills-en/integration-e2e-testing/SKILL.md index dd4a44f..3931a91 100644 --- a/.claude/skills-en/integration-e2e-testing/SKILL.md +++ b/.claude/skills-en/integration-e2e-testing/SKILL.md @@ -8,6 +8,7 @@ description: Designs integration and E2E tests with mock boundaries and behavior ## References - **[references/e2e-design.md](references/e2e-design.md)** - E2E test design principles with Playwright (candidate sources, selection criteria, UI Spec mapping) +- **[references/e2e-environment-prerequisites.md](references/e2e-environment-prerequisites.md)** - E2E environment prerequisites (seed data, auth fixtures, environment checklist) ## Test Types and Limits @@ -37,6 +38,9 @@ description: Designs integration and E2E tests with mock boundaries and behavior ### Required Comment Format +Each test MUST include the following annotations. Use the project's comment syntax to wrap these annotations. + +**TypeScript/JavaScript** (`//`): ```typescript // AC: "[Acceptance criteria original text]" // ROI: [0-100] | Business Value: [0-10] | Frequency: [0-10] @@ -44,7 +48,14 @@ description: Designs integration and E2E tests with mock boundaries and behavior // @category: core-functionality | integration | edge-case | ux | e2e // @dependency: none | [component name] | full-system // @complexity: low | medium | high -it.todo('[AC number]: [Test name]') +// @real-dependency: [component name] (optional, when Test Boundaries specify non-mock setup) +``` + +**Python/Ruby** (`#`): +```python +# AC: "[Acceptance criteria original text]" +# @category: core-functionality | integration | edge-case | ux | e2e +# (same annotation keys as above) ``` ### Property Annotations @@ -52,9 +63,10 @@ it.todo('[AC number]: [Test name]') ```typescript // Property: `[Verification expression]` // fast-check: fc.property(fc.[arbitrary], (input) => [invariant]) -it.todo('[AC number]-property: [Invariant description]') ``` +Adapt comment syntax to project language. + ### ROI Calculation ``` diff --git a/.claude/skills-en/integration-e2e-testing/references/e2e-environment-prerequisites.md b/.claude/skills-en/integration-e2e-testing/references/e2e-environment-prerequisites.md new file mode 100644 index 0000000..d950388 --- /dev/null +++ b/.claude/skills-en/integration-e2e-testing/references/e2e-environment-prerequisites.md @@ -0,0 +1,70 @@ +# E2E Environment Prerequisites + +E2E tests require a running application with real data state. Unlike unit/integration tests, environment setup is part of E2E test implementation scope. + +## Seed Data Strategy + +Prepare test data via API calls or database seeding — never through UI interaction: + +```typescript +// fixtures/seed.fixture.ts +import { test as base } from '@playwright/test' + +export const test = base.extend<{ seededData: SeedResult }>({ + seededData: async ({ request }, use) => { + // Arrange: Create test data via API before test + // Example: adjust to the project's actual seeding mechanism + const result = await request.post('/api/test/seed', { + data: { scenario: 'e2e-user-with-subscription' } + }) + const seedData = await result.json() + + await use(seedData) + + // Cleanup: Remove test data after test + await request.delete(`/api/test/seed/${seedData.id}`) + }, +}) +``` + +**Principles**: +- Use the application's existing seeding mechanism if present; create new seed endpoints only when no alternative exists +- Seed data setup belongs to test fixtures, not to a separate manual step +- Each test must be self-contained: create its own data, clean up after +- Use API endpoints or direct DB access for seeding — not UI flows + +## Authentication Fixture + +Implement auth fixtures that match the application's actual login flow: + +```typescript +// fixtures/auth.fixture.ts +export const test = base.extend<{ playerPage: Page }>({ + playerPage: async ({ page, request }, use) => { + // Use the application's existing auth endpoint — not admin backdoors + // Example: adjust the URL and payload to match the project's actual login flow + await request.post('/api/login', { + data: { loginId: E2E_LOGIN_ID, password: E2E_PASSWORD } + }) + // Transfer session to browser context + await page.goto('/') + await use(page) + }, +}) +``` + +**Principles**: +- Use the application's existing authentication flow; auth fixtures must follow the same path that real users use +- Store test credentials in environment variables, never hardcoded +- If the auth flow requires specific user records, seed them in the fixture + +## Environment Checklist + +Before E2E tests can pass, verify: +- [ ] Application is running and accessible at `baseURL` +- [ ] Database has required seed data (test users, subscriptions, content) +- [ ] Authentication flow works with test credentials +- [ ] Environment variables are set (`E2E_*` prefixed) +- [ ] External services are either available or mocked via `page.route()` + +When the work plan includes dedicated environment setup tasks (Phase 0), follow those tasks. When no setup tasks exist in the plan, address missing prerequisites as part of the E2E test implementation task itself. diff --git a/.claude/skills-en/subagents-orchestration-guide/SKILL.md b/.claude/skills-en/subagents-orchestration-guide/SKILL.md index 3d5af7f..cc26057 100644 --- a/.claude/skills-en/subagents-orchestration-guide/SKILL.md +++ b/.claude/skills-en/subagents-orchestration-guide/SKILL.md @@ -56,13 +56,15 @@ graph TD ### Document Creation Agents 6. **requirement-analyzer**: Requirement analysis and work scale determination (WebSearch enabled, latest technical information research) -7. **prd-creator**: Product Requirements Document creation (WebSearch enabled, market trend research) -8. **ui-spec-designer**: UI Specification creation from PRD and optional prototype code (frontend/fullstack features) -9. **technical-designer**: ADR/Design Doc creation (latest technology research, Property annotation assignment) -10. **work-planner**: Work plan creation from Design Doc and test skeletons -11. **document-reviewer**: Single document quality, completeness, and rule compliance check -12. **design-sync**: Design Doc consistency verification (detects explicit conflicts only) -13. **acceptance-test-generator**: Generate separate integration and E2E test skeletons from Design Doc ACs and optional UI Spec +7. **codebase-analyzer**: Analyze existing codebase to produce focused guidance for technical design +8. **prd-creator**: Product Requirements Document creation (WebSearch enabled, market trend research) +9. **ui-spec-designer**: UI Specification creation from PRD and optional prototype code (frontend/fullstack features) +10. **technical-designer**: ADR/Design Doc creation (latest technology research, Property annotation assignment) +11. **work-planner**: Work plan creation from Design Doc and test skeletons +12. **document-reviewer**: Single document quality, completeness, and rule compliance check +13. **code-verifier**: Verify Design Doc claims against existing codebase (used pre-review in design flow) +14. **design-sync**: Design Doc consistency verification (detects explicit conflicts only) +15. **acceptance-test-generator**: Generate separate integration and E2E test skeletons from Design Doc ACs and optional UI Spec ## My Orchestration Principles @@ -108,8 +110,10 @@ I repeat this cycle for each task to ensure quality. Subagents respond in JSON format. Key fields for orchestrator decisions: - **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**: (in design flow) consistencyScore, discrepancies[], reverseCoverage (including 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). Discriminate blocked type by `reason` field: `"Cannot determine due to unclear specification"` → read `blockingIssues[]` for specification details; `"Execution prerequisites not met"` → read `missingPrerequisites[]` with `resolutionSteps` — present these to the user as actionable next steps - **document-reviewer**: approvalReady (true/false) - **design-sync**: sync_status (synced/conflicts_found) - **integration-test-reviewer**: status (approved/needs_revision/blocked), requiredFixes @@ -121,7 +125,7 @@ Subagents respond in JSON format. Key fields for orchestrator decisions: When receiving new features or change requests, I first request requirement analysis from requirement-analyzer. According to scale determination: -### Large Scale (6+ Files) - 11 Steps (backend) / 13 Steps (frontend/fullstack) +### Large Scale (6+ Files) - 13 Steps (backend) / 15 Steps (frontend/fullstack) 1. requirement-analyzer → Requirement analysis + Check existing PRD **[Stop]** 2. prd-creator → PRD creation @@ -130,24 +134,28 @@ According to scale determination: 5. **(frontend/fullstack only)** document-reviewer → UI Spec review **[Stop: UI Spec Approval]** 6. technical-designer → ADR creation (if architecture/technology/data flow changes) 7. document-reviewer → ADR review (if ADR created) **[Stop: ADR Approval]** -8. technical-designer → Design Doc creation (cross-layer: per layer, see Cross-Layer Orchestration) -9. document-reviewer → Design Doc review (cross-layer: per Design Doc) -10. design-sync → Consistency verification **[Stop: Design Doc Approval]** -11. acceptance-test-generator → Test skeleton generation, pass to work-planner (*1) -12. work-planner → Work plan creation **[Stop: Batch approval]** -13. task-decomposer → Autonomous execution → Completion report +8. codebase-analyzer → Codebase analysis (pass requirement-analyzer output + PRD path) +9. technical-designer → Design Doc creation (pass codebase-analyzer output as additional context; cross-layer: per layer, see Cross-Layer Orchestration) +10. code-verifier → Verify Design Doc against existing code (doc_type: design-doc) +11. document-reviewer → Design Doc review (pass code-verifier results as code_verification; cross-layer: per Design Doc) +12. design-sync → Consistency verification **[Stop: Design Doc Approval]** +13. acceptance-test-generator → Test skeleton generation, pass to work-planner (*1) +14. work-planner → Work plan creation **[Stop: Batch approval]** +15. task-decomposer → Autonomous execution → Completion report -### Medium Scale (3-5 Files) - 7 Steps (backend) / 9 Steps (frontend/fullstack) +### Medium Scale (3-5 Files) - 9 Steps (backend) / 11 Steps (frontend/fullstack) 1. requirement-analyzer → Requirement analysis **[Stop]** -2. **(frontend/fullstack only)** Ask user for prototype code → ui-spec-designer → UI Spec creation -3. **(frontend/fullstack only)** document-reviewer → UI Spec review **[Stop: UI Spec Approval]** -4. technical-designer → Design Doc creation (cross-layer: per layer, see Cross-Layer Orchestration) -5. document-reviewer → Design Doc review (cross-layer: per Design Doc) -6. design-sync → Consistency verification **[Stop: Design Doc Approval]** -7. acceptance-test-generator → Test skeleton generation, pass to work-planner (*1) -8. work-planner → Work plan creation **[Stop: Batch approval]** -9. task-decomposer → Autonomous execution → Completion report +2. codebase-analyzer → Codebase analysis (pass requirement-analyzer output) +3. **(frontend/fullstack only)** Ask user for prototype code → ui-spec-designer → UI Spec creation +4. **(frontend/fullstack only)** document-reviewer → UI Spec review **[Stop: UI Spec Approval]** +5. technical-designer → Design Doc creation (pass codebase-analyzer output as additional context; cross-layer: per layer, see Cross-Layer Orchestration) +6. code-verifier → Verify Design Doc against existing code (doc_type: design-doc) +7. document-reviewer → Design Doc review (pass code-verifier results as code_verification; cross-layer: per Design Doc) +8. design-sync → Consistency verification **[Stop: Design Doc Approval]** +9. acceptance-test-generator → Test skeleton generation, pass to work-planner (*1) +10. work-planner → Work plan creation **[Stop: Batch approval]** +11. task-decomposer → Autonomous execution → Completion report ### Small Scale (1-2 Files) - 2 Steps @@ -164,14 +172,18 @@ Replace the standard Design Doc creation step with per-layer creation: | Step | Agent | Purpose | |------|-------|---------| -| 6a | technical-designer | Backend Design Doc | -| 6b | technical-designer-frontend | Frontend Design Doc | -| 7 | document-reviewer ×2 | Review each Design Doc separately | -| 8 | design-sync | Cross-layer consistency verification **[Stop]** | +| 8 | codebase-analyzer ×2 | Codebase analysis per layer (pass req-analyzer output, filtered to layer) | +| 9a | technical-designer | Backend Design Doc (with backend codebase-analyzer context) | +| 9b | technical-designer-frontend | Frontend Design Doc (with frontend codebase-analyzer context + backend Integration Points) | +| 10 | code-verifier ×2 | Verify each Design Doc against existing code | +| 11 | document-reviewer ×2 | Review each Design Doc (with code-verifier results as code_verification) | +| 12 | design-sync | Cross-layer consistency verification **[Stop]** | + +Steps marked with ×2 invoke the agent once per layer. These invocations are independent and can run in parallel when the orchestrator supports concurrent Agent tool calls. **Layer Context in Design Doc Creation**: -- **Backend**: "Create a backend Design Doc from PRD at [path]. Focus on: API contracts, data layer, business logic, service architecture." -- **Frontend**: "Create a frontend Design Doc from PRD at [path]. Reference backend Design Doc at [path] for API contracts and Integration Points. Focus on: component hierarchy, state management, UI interactions, data fetching." +- **Backend**: "Create a backend Design Doc from PRD at [path]. Codebase analysis: [JSON from codebase-analyzer for backend layer]. Focus on: API contracts, data layer, business logic, service architecture." +- **Frontend**: "Create a frontend Design Doc from PRD at [path]. Codebase analysis: [JSON from codebase-analyzer for frontend layer]. Reference backend Design Doc at [path] for API contracts and Integration Points. Focus on: component hierarchy, state management, UI interactions, data fetching." **design-sync**: Use frontend Design Doc as source. design-sync auto-discovers other Design Docs in `docs/design/` for comparison. @@ -230,6 +242,16 @@ Every subagent prompt must include: Construct the prompt from the agent's Input Parameters section and the deliverables available at that point in the flow. +### Call Example (codebase-analyzer) +- subagent_type: "codebase-analyzer" +- description: "Codebase analysis" +- prompt: "requirement_analysis: [JSON from requirement-analyzer]. prd_path: [path if exists]. requirements: [original user requirements]. Analyze the existing codebase and produce design guidance." + +### Call Example (code-verifier — design flow) +- subagent_type: "code-verifier" +- description: "Design Doc verification" +- prompt: "doc_type: design-doc document_path: [Design Doc path] Verify Design Doc against existing code." + ## My Main Roles as Orchestrator 1. **State Management**: Grasp current phase, each subagent's state, and next action @@ -240,6 +262,16 @@ Construct the prompt from the agent's Input Parameters section and the deliverab - Compose commit messages from changeSummary -> **Execute git commit with Bash** - Explicitly integrate initial and additional requirements when requirements change + #### codebase-analyzer → technical-designer + + **Pass to codebase-analyzer**: requirement-analyzer JSON output, PRD path (if exists), original user requirements + **Pass to technical-designer**: codebase-analyzer JSON output as additional context in the Design Doc creation prompt. The designer uses `focusAreas` and `dataModel` to inform the Existing Codebase Analysis section. + + #### code-verifier → document-reviewer (Design Doc review) + + **Pass to code-verifier**: Design Doc path (doc_type: design-doc). `code_paths` is intentionally omitted — the verifier independently discovers code scope from the document. + **Pass to document-reviewer**: code-verifier JSON output as `code_verification` parameter. + #### *1 acceptance-test-generator → work-planner **Pass to acceptance-test-generator**: @@ -255,7 +287,7 @@ Construct the prompt from the agent's Input Parameters section and the deliverab - E2E test file: [path] (execute only in final phase) **On error**: Escalate to user if files are not generated -3. **Quality Assurance and Commit Execution**: After confirming approved=true, immediately execute git commit +3. **Quality Assurance and Commit Execution**: After confirming `status: "approved"`, immediately execute git commit 4. **Autonomous Execution Mode Management**: Start/stop autonomous execution after approval, escalation decisions 5. **ADR Status Management**: Update ADR status after user decision (Accepted/Rejected) diff --git a/.claude/skills-en/task-analyzer/references/skills-index.yaml b/.claude/skills-en/task-analyzer/references/skills-index.yaml index 43752eb..c60a5a2 100644 --- a/.claude/skills-en/task-analyzer/references/skills-index.yaml +++ b/.claude/skills-en/task-analyzer/references/skills-index.yaml @@ -69,6 +69,7 @@ skills: - "Test Implementation Conventions" - "Test Quality Criteria" - "Mock Type Safety Enforcement" + - "Data Layer Testing" - "Basic Vitest Example" technical-spec: @@ -147,6 +148,7 @@ skills: - "Node.js Testing Best Practices - Yoni Goldberg" - "Property-Based Testing - 2025 Practices" - "references/e2e-design.md - E2E test design principles" + - "references/e2e-environment-prerequisites.md - E2E environment prerequisites" sections: - "References" - "Test Types and Limits" diff --git a/.claude/skills-en/typescript-testing/SKILL.md b/.claude/skills-en/typescript-testing/SKILL.md index 93a55f0..2659655 100644 --- a/.claude/skills-en/typescript-testing/SKILL.md +++ b/.claude/skills-en/typescript-testing/SKILL.md @@ -135,6 +135,45 @@ const sdkMock = { } as unknown as ExternalSDK // Complex external SDK type structure ``` +## Data Layer Testing + +### Mock Limitations for Data Layer + +Mocks validate call patterns but cannot verify data layer correctness. The following pass through undetected with mock-only testing: +- Schema mismatches (table names, column names, data types) +- Query correctness (joins, filters, aggregations, grouping) +- Database constraints (NOT NULL, UNIQUE, foreign keys) +- Migration drift (schema changes that make code out of sync) + +### When Mocks Are Appropriate for Data Access + +- Testing business logic that receives data from the data layer (mock the repository, test the service) +- Testing error handling paths (simulating connection failures, timeouts) +- Unit tests where data access is a dependency, not the subject under test + +### When Mocks Are Insufficient for Data Access + +- Testing repository or data access implementations themselves +- Verifying query correctness (joins, filters, aggregations, grouping) +- Testing data integrity constraints +- Testing migration compatibility + +### Real Database Testing (Environment-Dependent) + +Options for verifying data layer correctness against a real database engine: +- **Containerized databases** for CI environments +- **In-memory databases** for fast feedback (note: dialect differences may mask issues) +- **Dedicated test databases** with seed data + +The appropriate approach depends on project environment and CI/CD capabilities. + +### AI-Generated Code and Schema Awareness + +- AI-generated data access code has heightened schema hallucination risk +- Generated queries may use correct syntax but reference nonexistent schema elements +- Mock-based tests pass regardless of schema accuracy +- Mitigation: Design Docs should include explicit schema references; code-verifier reverse coverage verifies data operations against documented schemas + ## Basic Vitest Example ```typescript diff --git a/.claude/skills-ja/documentation-criteria/references/design-template.md b/.claude/skills-ja/documentation-criteria/references/design-template.md index 30ee466..95a2e2f 100644 --- a/.claude/skills-ja/documentation-criteria/references/design-template.md +++ b/.claude/skills-ja/documentation-criteria/references/design-template.md @@ -266,6 +266,26 @@ unknowns: 機能に関連する信頼境界がない場合は、簡潔な理由とともにN/Aと記載。 +## テスト境界 + +### モック境界決定 + +| コンポーネント/依存先 | モック化? | 根拠 | +|---------------------|----------|------| +| [外部API / DB / ファイルシステム 等] | [Yes/No] | [この境界を選択した理由] | + +### データ層テスト戦略 + +- **スキーマ依存先**: [この機能が読み書きするテーブル/モデルの一覧と定義ファイルパス] +- **テストデータ手法**: [テストデータの提供方法 — fixtures, factories, seed scripts, 実DB] +- **モックの限界**: [この機能でモックだけでは信頼性のあるテストができない箇所] + +機能にデータ層の依存がない場合は、簡潔な理由とともにN/Aと記載。 + +### 統合検証ポイント + +- [ユニットレベルのモックを超えるテストが必要な重要な統合ポイントの一覧] + ## 代替案 ### 代替案1 diff --git a/.claude/skills-ja/documentation-criteria/references/task-template.md b/.claude/skills-ja/documentation-criteria/references/task-template.md index f6f65f4..6fbc6a2 100644 --- a/.claude/skills-ja/documentation-criteria/references/task-template.md +++ b/.claude/skills-ja/documentation-criteria/references/task-template.md @@ -13,8 +13,13 @@ - [ ] [実装ファイルパス] - [ ] [テストファイルパス] +## 調査対象 +実装開始前に読むべきファイル（ファイルパス、任意でサーチヒント付き）: +- [例: src/orders/checkout (processOrder関数) — タスクの性質に基づきtask-decomposerが決定] + ## 実装ステップ（TDD: Red-Green-Refactor） ### 1. Redフェーズ +- [ ] 全ての調査対象を読み、主要な所見を記録 - [ ] 依存関係の成果物を確認（ある場合） - [ ] 契約定義を確認・作成 - [ ] 失敗するテストを書く diff --git a/.claude/skills-ja/integration-e2e-testing/SKILL.md b/.claude/skills-ja/integration-e2e-testing/SKILL.md index 0fe100b..2270058 100644 --- a/.claude/skills-ja/integration-e2e-testing/SKILL.md +++ b/.claude/skills-ja/integration-e2e-testing/SKILL.md @@ -8,6 +8,7 @@ description: 統合テストとE2Eテストを設計。モック境界と振る ## References - **[references/e2e-design.md](references/e2e-design.md)** — E2Eテスト設計原則（候補ソース、選定基準、UI Specからのマッピング） +- **[references/e2e-environment-prerequisites.md](references/e2e-environment-prerequisites.md)** — E2E環境前提条件（seed data、auth fixture、環境チェックリスト） ## テスト種別と上限 @@ -37,6 +38,8 @@ description: 統合テストとE2Eテストを設計。モック境界と振る ### 必須コメント形式 +各テストに以下のアノテーションを含めること。 + ```typescript // AC: "[受入条件原文]" // ROI: [0-100] | ビジネス価値: [0-10] | 頻度: [0-10] @@ -44,6 +47,7 @@ description: 統合テストとE2Eテストを設計。モック境界と振る // @category: core-functionality | integration | edge-case | ux | e2e // @dependency: none | [コンポーネント名] | full-system // @complexity: low | medium | high +// @real-dependency: [コンポーネント名]（任意、テスト境界で非モックセットアップが指定された場合） it.todo('[AC番号]: [テスト名]') ``` diff --git a/.claude/skills-ja/integration-e2e-testing/references/e2e-environment-prerequisites.md b/.claude/skills-ja/integration-e2e-testing/references/e2e-environment-prerequisites.md new file mode 100644 index 0000000..1020dcd --- /dev/null +++ b/.claude/skills-ja/integration-e2e-testing/references/e2e-environment-prerequisites.md @@ -0,0 +1,70 @@ +# E2E環境前提条件 + +E2Eテストはリアルなデータ状態で動作するアプリケーションが必要です。ユニット/統合テストと異なり、環境セットアップはE2Eテスト実装スコープの一部です。 + +## Seed Data Strategy + +テストデータはAPI callまたはdatabase seedingで準備する — UI操作によるデータ作成は行わない: + +```typescript +// fixtures/seed.fixture.ts +import { test as base } from '@playwright/test' + +export const test = base.extend<{ seededData: SeedResult }>({ + seededData: async ({ request }, use) => { + // Arrange: テスト前にAPI経由でテストデータを作成 + // 例: プロジェクトの実際のseeding機構に合わせて調整 + const result = await request.post('/api/test/seed', { + data: { scenario: 'e2e-user-with-subscription' } + }) + const seedData = await result.json() + + await use(seedData) + + // Cleanup: テスト後にテストデータを削除 + await request.delete(`/api/test/seed/${seedData.id}`) + }, +}) +``` + +**原則**: +- アプリケーションに既存のseeding機構がある場合はそれを使用する。代替手段がない場合のみ新規seedエンドポイントを作成 +- seed dataのセットアップはtest fixturesに属する。手動ステップとして分離しない +- 各テストは自己完結: 自身のデータを作成し、テスト後にクリーンアップ +- seedingにはAPIエンドポイントまたは直接DB操作を使用 — UIフローは使わない + +## Authentication Fixture + +アプリケーションの実際のログインフローに合わせたauth fixtureを実装: + +```typescript +// fixtures/auth.fixture.ts +export const test = base.extend<{ playerPage: Page }>({ + playerPage: async ({ page, request }, use) => { + // アプリケーションの既存認証エンドポイントを使用 — admin backdoorは使わない + // 例: プロジェクトの実際のログインフローに合わせてURL・payloadを調整 + await request.post('/api/login', { + data: { loginId: E2E_LOGIN_ID, password: E2E_PASSWORD } + }) + // セッションをブラウザコンテキストに移行 + await page.goto('/') + await use(page) + }, +}) +``` + +**原則**: +- アプリケーションの既存認証フローを使用する。auth fixtureは実ユーザーと同じ経路を通ること +- テスト認証情報は環境変数に格納し、ハードコードしない +- 認証フローに特定のユーザーレコードが必要な場合はfixture内でseedする + +## 環境チェックリスト + +E2Eテストがパスするために、以下を確認: +- [ ] アプリケーションが`baseURL`で起動・アクセス可能 +- [ ] データベースに必要なseed dataがある（テストユーザー、サブスクリプション、コンテンツ） +- [ ] テスト認証情報で認証フローが動作する +- [ ] 環境変数が設定されている（`E2E_*`プレフィックス） +- [ ] 外部サービスが利用可能、または`page.route()`でモック済み + +作業計画に専用の環境セットアップタスク（Phase 0）が含まれる場合はそれに従う。計画にセットアップタスクがない場合は、E2Eテスト実装タスクの一部として不足する前提条件に対応する。 diff --git a/.claude/skills-ja/subagents-orchestration-guide/SKILL.md b/.claude/skills-ja/subagents-orchestration-guide/SKILL.md index 57f5069..1b949ad 100644 --- a/.claude/skills-ja/subagents-orchestration-guide/SKILL.md +++ b/.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） diff --git a/.claude/skills-ja/task-analyzer/references/skills-index.yaml b/.claude/skills-ja/task-analyzer/references/skills-index.yaml index 12f7327..11b11f7 100644 --- a/.claude/skills-ja/task-analyzer/references/skills-index.yaml +++ b/.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" - "テスト種別と上限" diff --git a/.claude/skills-ja/typescript-testing/SKILL.md b/.claude/skills-ja/typescript-testing/SKILL.md index b377b4f..e2fe155 100644 --- a/.claude/skills-ja/typescript-testing/SKILL.md +++ b/.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 diff --git a/CHANGELOG.md b/CHANGELOG.md index 30608c1..884e89b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,48 @@ 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 diff --git a/package.json b/package.json index 446a64d..6f1bd1e 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "create-ai-project", - "version": "1.19.1", + "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": [ From d6334fcedae505242496ff611bb691c1046cd99e Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Wed, 1 Apr 2026 14:53:44 +0900 Subject: [PATCH 2/3] fix: remove orchestrator reference from quality-fixer agent definitions Agents operate in independent context and should not reference external orchestrator existence. Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude/agents-en/quality-fixer-frontend.md | 1 - .claude/agents-en/quality-fixer.md | 1 - .claude/agents-ja/quality-fixer-frontend.md | 1 - .claude/agents-ja/quality-fixer.md | 1 - 4 files changed, 4 deletions(-) diff --git a/.claude/agents-en/quality-fixer-frontend.md b/.claude/agents-en/quality-fixer-frontend.md index 40dc1cf..221701d 100644 --- a/.claude/agents-en/quality-fixer-frontend.md +++ b/.claude/agents-en/quality-fixer-frontend.md @@ -181,7 +181,6 @@ Execute `test` script (run all tests with Vitest) } ``` -Note: The `status` field is the primary success indicator. Orchestrator reads `status: "approved"` to proceed. **Processing Rules** (internal, not included in response): - Error found → Execute fix IMMEDIATELY diff --git a/.claude/agents-en/quality-fixer.md b/.claude/agents-en/quality-fixer.md index 3d5621c..cd4c8b7 100644 --- a/.claude/agents-en/quality-fixer.md +++ b/.claude/agents-en/quality-fixer.md @@ -142,7 +142,6 @@ Refer to the "Quality Check Requirements" section in technical-spec skill for de } ``` -Note: The `status` field is the primary success indicator. Orchestrator reads `status: "approved"` to proceed. **Processing Rules** (internal, not included in response): - Error found → Execute fix IMMEDIATELY diff --git a/.claude/agents-ja/quality-fixer-frontend.md b/.claude/agents-ja/quality-fixer-frontend.md index 8300f48..87f9cd7 100644 --- a/.claude/agents-ja/quality-fixer-frontend.md +++ b/.claude/agents-ja/quality-fixer-frontend.md @@ -181,7 +181,6 @@ blockedにする前に、以下の順序で仕様を確認： "nextActions": "コミット準備完了" } ``` -Note: `status`フィールドが成功の主要指標。オーケストレーターは`status: "approved"`で次に進む。 **品質チェック処理中（内部利用のみ、レスポンスに含めない）**: - エラー発見 → 即座に修正実行 diff --git a/.claude/agents-ja/quality-fixer.md b/.claude/agents-ja/quality-fixer.md index 695efdf..ae2c620 100644 --- a/.claude/agents-ja/quality-fixer.md +++ b/.claude/agents-ja/quality-fixer.md @@ -142,7 +142,6 @@ blockedにする前に、以下の順序で仕様を確認： "nextActions": "コミット可能です" } ``` -Note: `status`フィールドが成功の主要指標。オーケストレーターは`status: "approved"`で次に進む。 **品質チェック処理中（内部のみ使用、レスポンスには含めない）**: - エラー発見 → 即座に修正を実行 From 3243940047e2d888c529eb241516ae97ee0ea8ec Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Wed, 1 Apr 2026 14:59:21 +0900 Subject: [PATCH 3/3] fix: remove Python/Ruby example from integration-e2e-testing skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This project is full TypeScript — multi-language examples add noise without value. Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude/skills-en/integration-e2e-testing/SKILL.md | 12 +----------- 1 file changed, 1 insertion(+), 11 deletions(-) diff --git a/.claude/skills-en/integration-e2e-testing/SKILL.md b/.claude/skills-en/integration-e2e-testing/SKILL.md index 3931a91..6dc8d6f 100644 --- a/.claude/skills-en/integration-e2e-testing/SKILL.md +++ b/.claude/skills-en/integration-e2e-testing/SKILL.md @@ -38,9 +38,8 @@ description: Designs integration and E2E tests with mock boundaries and behavior ### Required Comment Format -Each test MUST include the following annotations. Use the project's comment syntax to wrap these annotations. +Each test MUST include the following annotations. -**TypeScript/JavaScript** (`//`): ```typescript // AC: "[Acceptance criteria original text]" // ROI: [0-100] | Business Value: [0-10] | Frequency: [0-10] @@ -51,13 +50,6 @@ Each test MUST include the following annotations. Use the project's comment synt // @real-dependency: [component name] (optional, when Test Boundaries specify non-mock setup) ``` -**Python/Ruby** (`#`): -```python -# AC: "[Acceptance criteria original text]" -# @category: core-functionality | integration | edge-case | ux | e2e -# (same annotation keys as above) -``` - ### Property Annotations ```typescript @@ -65,8 +57,6 @@ Each test MUST include the following annotations. Use the project's comment synt // fast-check: fc.property(fc.[arbitrary], (input) => [invariant]) ``` -Adapt comment syntax to project language. - ### ROI Calculation ```