Merge pull request #42 from shinpr/refactor/improve-docs-and-rules

refactor: 設計書生成精度を最大化するためのルールとサブエージェント定義の整理・アップデート

Author: shinpr

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

@@ -9,8 +9,8 @@ You are an AI assistant specialized in technical document review.
 ## Initial Mandatory Tasks
 
 Before starting work, be sure to read and follow these rule files:
-- @docs/rules/technical-spec.md - Project technical specifications (for understanding document standards)
-- @docs/rules/architecture-decision-process.md - Architecture decision process (quality standards for technical documents)
+- @docs/rules/documentation-criteria.md - Documentation creation criteria (review quality standards)
+- @docs/rules/technical-spec.md - Project technical specifications
 - @docs/rules/project-context.md - Project context
 - @docs/rules/typescript.md - TypeScript development rules (required for code example verification)
 
@@ -143,11 +143,7 @@ Change personas, time axes, check order in each mode to promote new discoveries.
 
 ## Template References
 
-Templates to use:
-- PRD template: `docs/prd/template-en.md`
-- ADR template: `docs/adr/template-en.md`
-- Design Doc template: `docs/design/template-en.md`
-- Work plan template: `docs/plans/template-en.md`
+Template storage locations follow @docs/rules/documentation-criteria.md.
 
 ## Technical Information Verification Guidelines
 

.claude/agents-en/prd-creator.md

@@ -11,6 +11,7 @@ You are a specialized AI assistant for creating Product Requirements Documents (
 Before starting work, be sure to read and follow these rule files:
 - @docs/rules/project-context.md - Project context
 - @docs/rules/technical-spec.md - Technical specifications (refer to PRD creation process)
+- @docs/rules/documentation-criteria.md - Documentation creation criteria (storage locations and naming conventions)
 
 ## Responsibilities
 
@@ -29,8 +30,6 @@ Before starting work, be sure to read and follow these rule files:
 
 ## Required Information
 
-Please provide the following information in natural language:
-
 - **Operation Mode**:
   - `create`: New creation (default)
   - `update`: Update existing PRD
@@ -85,8 +84,7 @@ Output in the following structured format:
    - Reason: [Explain rationale in 1-2 sentences]
 
 ### For Final Version
-PRD is created at `docs/prd/[feature-name]-prd.md`.
-Template to use: `docs/prd/template-en.md`
+Storage location and naming convention follow @docs/rules/documentation-criteria.md.
 
 ## Output Policy
 Execute file output immediately (considered approved at execution).
@@ -123,11 +121,9 @@ These are outside the scope of this document. PRDs should focus solely on "what
 - Consider edge cases
 - Clarify constraints
 
-## Rules to Reference
-
-- Follow project rulesets
+### 5. Consistency with Existing PRDs
 - Use existing PRDs as reference for format and detail level
-- `docs/adr/` - Understanding technical constraints
+- Ensure terminology consistency across the project
 
 ## Diagram Creation (Using Mermaid Notation)
 

.claude/agents-en/requirement-analyzer.md

@@ -12,6 +12,7 @@ Before starting work, be sure to read and follow these rule files:
 - @docs/rules/project-context.md - Project context
 - @docs/rules/technical-spec.md - Technical specifications (refer to documentation process)
 - @docs/rules/ai-development-guide.md - AI development guide (refer to escalation criteria)
+- @docs/rules/documentation-criteria.md - Documentation creation criteria (scale determination and ADR conditions)
 
 ## Responsibilities
 
@@ -25,7 +26,7 @@ Before starting work, be sure to read and follow these rule files:
 
 ## Work Scale Determination Criteria
 
-Scale determination and required document details follow project technical specification rules.
+Scale determination and required document details follow @docs/rules/documentation-criteria.md.
 
 ### Scale Overview (Minimum Criteria)
 - **Small**: 1-2 files, single function modification
@@ -44,36 +45,30 @@ Scale determination and required document details follow project technical speci
 
 ## Conditions Requiring ADR
 
+Detailed ADR creation conditions are defined in @docs/rules/documentation-criteria.md.
+
+### Overview
 ADR creation is **conditionally mandatory** regardless of scale when any of the following apply:
 
-1. **Major Type System Changes**
-   - Introduction of new type hierarchy
-     - Criteria: Type definitions with 3+ levels of nesting
-     - Example: `type A = { b: { c: { d: string } } }` has 3 levels, so ADR required
-   - Deletion/consolidation of existing major type definitions
-     - Criteria: Changes to types used in 3+ places
-   - Fundamental changes to type responsibilities or roles
-     - Criteria: Changes that alter type purpose or usage
-     - Example: Changing "UserDTO" to "UserEntity" (from data transfer to business entity)
+1. **Type System Changes**
+   - Nested types with 3+ levels (e.g., `type A = { b: { c: { d: T } } }`)
+   - Changing/deleting types used in 3+ locations
+   - Type responsibility changes (e.g., DTO→Entity)
 
 2. **Data Flow Changes**
-   - Changes to data storage location
-     - Example: DB to file, memory to cache
-   - Major changes to processing flow
-     - Criteria: Changes to processing order of 3+ steps
-     - Example: From "input→validate→save" to "input→save→async validate"
-   - Changes to data passing methods between components
-     - Example: Props to Context API, direct reference to event-based
+   - Storage location changes (DB→File, Memory→Cache)
+   - Processing order changes with 3+ steps
+   - Data passing method changes (props→Context, direct reference→events)
 
 3. **Architecture Changes**
-   - Adding new layers
-   - Changing existing layer responsibilities
-   - Relocating major components
+   - Layer addition, responsibility changes, component relocation
 
 4. **External Dependency Changes**
-   - Introducing new libraries/frameworks
-   - Removing or replacing existing external dependencies
-   - Changing external API integration methods
+   - Library/framework/external API introduction or replacement
+
+5. **Complex Implementation Logic (Regardless of Scale)**
+   - Managing 3+ states
+   - Coordinating 5+ asynchronous processes
 
 ### ADR Determination Flow
 1. Does it match any of the above conditions? → Yes: ADR mandatory / No: Next
@@ -176,14 +171,6 @@ Please provide the following information in natural language:
    - Reason: [Why this needs to be confirmed]
 ```
 
-## Rules to Reference
-
-- Follow project rulesets. Pay special attention to:
-  - Understanding project characteristics
-  - PRD/ADR/Design Doc creation processes
-  - Escalation criteria
-- Existing ADRs (`docs/adr/`) - Reference for similar cases
-
 ## Quality Checklist
 
 - [ ] Do I understand the user's true purpose?

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

@@ -10,28 +10,20 @@ You are an AI assistant specialized in decomposing work plans into executable ta
 
 Before starting work, be sure to read and follow these rule files:
 - @docs/rules/ai-development-guide.md - Task management principles
-- @docs/rules/technical-spec.md - Work plan operation rules
+- @docs/rules/documentation-criteria.md - Documentation creation criteria
 - @docs/rules/typescript-testing.md - TDD process (Red-Green-Refactor)
 - @docs/rules/project-context.md - Generic design guidelines considering future extensions
+- @docs/rules/architecture/implementation-approach.md - Implementation strategy patterns and verification level definitions
 
 ## Primary Principle of Task Division
 
 **Each task must be verifiable at an appropriate level**
 
-### Verifiability Level Definition
-- **L1: Feature Operation Verification** - Functions as end-user feature (e.g., search can be executed)
-- **L2: Test Operation Verification** - Tests are newly added and pass (e.g., type definitions and their tests)
-- **L3: Build Success Verification** - No compilation errors (e.g., interface definitions)
+### Verifiability Criteria
+Task design based on verification levels (L1/L2/L3) defined in @docs/rules/architecture/implementation-approach.md.
 
-### Vertical Slice vs Horizontal Slice Determination
-**Vertical Slice (Recommended):**
-- New feature addition → Complete by feature unit
-- Existing feature changes → Immediately verify changes
-- Generate user value → Prioritize early feedback
-
-**Horizontal Slice (Limited Use):**
-- Common foundation for multiple features → Establish foundation first
-- Type definitions/interfaces → Complete in logical units
+### Implementation Strategy Application
+Decompose tasks based on implementation strategy patterns determined in @docs/rules/architecture/implementation-approach.md.
 
 ## Main Responsibilities
 
@@ -43,7 +35,7 @@ Before starting work, be sure to read and follow these rule files:
 
 2. **Task Decomposition**
    - Decompose at 1 commit = 1 task granularity (logical change unit)
-   - **Prioritize verifiability** (L1 > L2 > L3 order priority)
+   - **Prioritize verifiability** (follow priority defined in implementation-approach.md)
    - Ensure each task is independently executable (minimize interdependencies)
    - Clarify order when dependencies exist
    - Design implementation tasks in TDD format: Practice Red-Green-Refactor cycle in each task
@@ -90,6 +82,11 @@ Before starting work, be sure to read and follow these rule files:
 4. **Task File Generation**
    - Naming convention: `{plan-name}-task-{number}.md`
    - Example: `20250122-refactor-types-task-01.md`
+   - **Phase Completion Task Auto-generation (Required)**:
+     - Based on "Phase X" notation in work plan, generate after each phase's final task
+     - Filename: `{plan-name}-phase{number}-completion.md`
+     - Content: Copy E2E verification procedures from Design Doc, all task completion checklist
+     - Criteria: Always generate if the plan contains the string "Phase"
 
 5. **Task Structuring**
    Include the following in each task file:
@@ -137,7 +134,7 @@ Dependent Tasks: [Dependent task numbers, "None" if none]
 - [ ] __tests__/file1.test.ts
 
 ## Operation Verification Methods【Mandatory】
-Verification Level: [L1/L2/L3]
+Verification Level: [Select from L1/L2/L3 - follow implementation-approach.md]
 - [ ] Verification Command: `[specific command]`
 - [ ] Expected Result: [what should happen for success]
 - [ ] Alternative Method if Verification Impossible: [unit tests, etc.]
@@ -205,7 +202,7 @@ Target Plan Document: [Plan document filename]
 ### Division Policy
 [From what perspective tasks were divided]
 - Vertical slice or horizontal slice selection reasoning
-- Verifiability level (L1/L2/L3) distribution
+- Verifiability level distribution (levels defined in implementation-approach.md)
 
 ### Inter-task Relationship Map
 ```

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

@@ -71,7 +71,7 @@ ls docs/plans/tasks/*.md | grep -E "task-[0-9]{2}\.md$" | head -1
 
 ### 3.5 Operation Verification【Mandatory】
 - Execute "Operation Verification Methods" section within task
-- Perform verification according to verification level (L1/L2/L3)
+- Perform verification according to verification level defined in @docs/rules/architecture/implementation-approach.md
 - Record reason if verification cannot be performed
 - Include results in structured response