create-ai-project 1.11.2 → 1.12.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude/agents-en/acceptance-test-generator.md +13 -13
- package/.claude/agents-en/code-reviewer.md +8 -10
- package/.claude/agents-en/design-sync.md +6 -5
- package/.claude/agents-en/document-reviewer.md +8 -7
- package/.claude/agents-en/integration-test-reviewer.md +5 -4
- package/.claude/agents-en/prd-creator.md +7 -6
- package/.claude/agents-en/quality-fixer-frontend.md +3 -14
- package/.claude/agents-en/quality-fixer.md +9 -20
- package/.claude/agents-en/requirement-analyzer.md +8 -7
- package/.claude/agents-en/rule-advisor.md +57 -128
- package/.claude/agents-en/task-decomposer.md +4 -10
- package/.claude/agents-en/task-executor-frontend.md +4 -16
- package/.claude/agents-en/task-executor.md +5 -16
- package/.claude/agents-en/technical-designer-frontend.md +17 -15
- package/.claude/agents-en/technical-designer.md +13 -15
- package/.claude/agents-en/work-planner.md +9 -14
- package/.claude/agents-ja/acceptance-test-generator.md +9 -15
- package/.claude/agents-ja/code-reviewer.md +3 -11
- package/.claude/agents-ja/design-sync.md +2 -6
- package/.claude/agents-ja/document-reviewer.md +4 -9
- package/.claude/agents-ja/integration-test-reviewer.md +2 -5
- package/.claude/agents-ja/prd-creator.md +3 -7
- package/.claude/agents-ja/quality-fixer-frontend.md +2 -13
- package/.claude/agents-ja/quality-fixer.md +7 -18
- package/.claude/agents-ja/requirement-analyzer.md +5 -8
- package/.claude/agents-ja/rule-advisor.md +57 -128
- package/.claude/agents-ja/task-decomposer.md +4 -10
- package/.claude/agents-ja/task-executor-frontend.md +3 -15
- package/.claude/agents-ja/task-executor.md +3 -17
- package/.claude/agents-ja/technical-designer-frontend.md +17 -15
- package/.claude/agents-ja/technical-designer.md +13 -15
- package/.claude/agents-ja/work-planner.md +9 -14
- package/.claude/commands-en/build.md +2 -2
- package/.claude/commands-en/design.md +1 -1
- package/.claude/commands-en/implement.md +8 -8
- package/.claude/commands-en/plan.md +3 -3
- package/.claude/commands-en/project-inject.md +4 -4
- package/.claude/commands-en/{refine-rule.md → refine-skill.md} +47 -48
- package/.claude/commands-en/{sync-rules.md → sync-skills.md} +29 -29
- package/.claude/commands-ja/build.md +2 -2
- package/.claude/commands-ja/design.md +1 -1
- package/.claude/commands-ja/implement.md +8 -8
- package/.claude/commands-ja/plan.md +3 -3
- package/.claude/commands-ja/project-inject.md +4 -4
- package/.claude/{commands/refine-rule.md → commands-ja/refine-skill.md} +25 -25
- package/.claude/{commands/sync-rules.md → commands-ja/sync-skills.md} +28 -28
- package/{docs/rules-en/coding-standards.md → .claude/skills-en/coding-standards/SKILL.md} +21 -108
- package/{docs/rules-en/documentation-criteria.md → .claude/skills-en/documentation-criteria/SKILL.md} +40 -42
- package/{docs/adr/template-en.md → .claude/skills-en/documentation-criteria/references/adr-template.md} +1 -1
- package/{docs/design/template-en.md → .claude/skills-en/documentation-criteria/references/design-template.md} +11 -31
- package/{docs/plans/template-en.md → .claude/skills-en/documentation-criteria/references/plan-template.md} +4 -4
- package/{docs/prd/template-en.md → .claude/skills-en/documentation-criteria/references/prd-template.md} +1 -1
- package/{docs/rules-en/frontend/technical-spec.md → .claude/skills-en/frontend/technical-spec/SKILL.md} +17 -13
- package/{docs/rules-en/frontend/typescript.md → .claude/skills-en/frontend/typescript-rules/SKILL.md} +17 -12
- package/{docs/rules-en/frontend/typescript-testing.md → .claude/skills-en/frontend/typescript-testing/SKILL.md} +11 -6
- package/{docs/rules-en/architecture/implementation-approach.md → .claude/skills-en/implementation-approach/SKILL.md} +7 -2
- package/{docs/rules-en/integration-e2e-testing.md → .claude/skills-en/integration-e2e-testing/SKILL.md} +15 -18
- package/{docs/rules-en/project-context.md → .claude/skills-en/project-context/SKILL.md} +7 -3
- package/.claude/skills-en/subagents-orchestration-guide/SKILL.md +224 -0
- package/.claude/skills-en/task-analyzer/SKILL.md +131 -0
- package/{docs/rules-en/rules-index.yaml → .claude/skills-en/task-analyzer/references/skills-index.yaml} +34 -20
- package/{docs/rules-en/technical-spec.md → .claude/skills-en/technical-spec/SKILL.md} +6 -6
- package/{docs/rules-en/typescript.md → .claude/skills-en/typescript-rules/SKILL.md} +15 -10
- package/{docs/rules-en/typescript-testing.md → .claude/skills-en/typescript-testing/SKILL.md} +10 -4
- package/{docs/rules-ja/coding-standards.md → .claude/skills-ja/coding-standards/SKILL.md} +12 -99
- package/{docs/rules-ja/documentation-criteria.md → .claude/skills-ja/documentation-criteria/SKILL.md} +18 -5
- package/.claude/skills-ja/documentation-criteria/references/adr-template.md +64 -0
- package/.claude/skills-ja/documentation-criteria/references/design-template.md +261 -0
- package/{docs/plans/template-ja.md → .claude/skills-ja/documentation-criteria/references/plan-template.md} +38 -38
- package/{docs/prd/template-ja.md → .claude/skills-ja/documentation-criteria/references/prd-template.md} +33 -33
- package/{docs/rules-ja/frontend/technical-spec.md → .claude/skills-ja/frontend/technical-spec/SKILL.md} +13 -9
- package/.claude/skills-ja/frontend/typescript-rules/SKILL.md +315 -0
- package/{docs/rules-ja/frontend/typescript-testing.md → .claude/skills-ja/frontend/typescript-testing/SKILL.md} +93 -5
- package/{docs/rules/architecture/implementation-approach.md → .claude/skills-ja/implementation-approach/SKILL.md} +10 -5
- package/{docs/rules-ja/integration-e2e-testing.md → .claude/skills-ja/integration-e2e-testing/SKILL.md} +5 -8
- package/{docs/rules-ja/project-context.md → .claude/skills-ja/project-context/SKILL.md} +7 -3
- package/.claude/skills-ja/subagents-orchestration-guide/SKILL.md +212 -0
- package/.claude/skills-ja/task-analyzer/SKILL.md +131 -0
- package/{docs/rules-ja/rules-index.yaml → .claude/skills-ja/task-analyzer/references/skills-index.yaml} +34 -19
- package/{docs/rules-ja/technical-spec.md → .claude/skills-ja/technical-spec/SKILL.md} +6 -6
- package/{docs/rules-ja/typescript.md → .claude/skills-ja/typescript-rules/SKILL.md} +16 -11
- package/{docs/rules-ja/typescript-testing.md → .claude/skills-ja/typescript-testing/SKILL.md} +11 -5
- package/CLAUDE.en.md +6 -6
- package/CLAUDE.ja.md +6 -6
- package/CLAUDE.md +19 -28
- package/README.ja.md +39 -10
- package/README.md +39 -10
- package/package.json +1 -1
- package/scripts/set-language.js +35 -53
- package/scripts/setup-project.js +4 -1
- package/.claude/agents/acceptance-test-generator.md +0 -316
- package/.claude/agents/code-reviewer.md +0 -193
- package/.claude/agents/document-reviewer.md +0 -182
- package/.claude/agents/prd-creator.md +0 -186
- package/.claude/agents/quality-fixer.md +0 -295
- package/.claude/agents/requirement-analyzer.md +0 -161
- package/.claude/agents/rule-advisor.md +0 -194
- package/.claude/agents/task-decomposer.md +0 -291
- package/.claude/agents/task-executor.md +0 -270
- package/.claude/agents/technical-designer.md +0 -343
- package/.claude/agents/work-planner.md +0 -181
- package/.claude/commands/build.md +0 -78
- package/.claude/commands/design.md +0 -27
- package/.claude/commands/implement.md +0 -79
- package/.claude/commands/plan.md +0 -43
- package/.claude/commands/project-inject.md +0 -76
- package/.claude/commands/review.md +0 -78
- package/.claude/commands/task.md +0 -13
- package/.claude/commands-ja/refine-rule.md +0 -206
- package/.claude/commands-ja/sync-rules.md +0 -116
- package/.claude/settings.local.json +0 -74
- package/docs/adr/template-ja.md +0 -64
- package/docs/design/template-ja.md +0 -285
- package/docs/guides/en/sub-agents.md +0 -343
- package/docs/guides/ja/sub-agents.md +0 -343
- package/docs/guides/sub-agents.md +0 -306
- package/docs/plans/20250123-integration-test-improvement.md +0 -993
- package/docs/rules/ai-development-guide.md +0 -260
- package/docs/rules/documentation-criteria.md +0 -180
- package/docs/rules/project-context.md +0 -38
- package/docs/rules/rules-index.yaml +0 -137
- package/docs/rules/technical-spec.md +0 -47
- package/docs/rules/typescript-testing.md +0 -188
- package/docs/rules/typescript.md +0 -166
- package/docs/rules-ja/architecture/implementation-approach.md +0 -136
- package/docs/rules-ja/frontend/typescript.md +0 -131
|
@@ -1,3 +1,8 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: frontend/technical-spec
|
|
3
|
+
description: Frontend technical design rules including environment variables, architecture design, data flow, and build/testing commands.
|
|
4
|
+
---
|
|
5
|
+
|
|
1
6
|
# Technical Design Rules (Frontend)
|
|
2
7
|
|
|
3
8
|
## Basic Technology Stack Policy
|
|
@@ -12,13 +17,13 @@ TypeScript-based React application implementation. Architecture patterns should
|
|
|
12
17
|
- Properly implement default value settings and mandatory checks
|
|
13
18
|
|
|
14
19
|
```typescript
|
|
15
|
-
//
|
|
20
|
+
// Build tool environment variables (public values only)
|
|
16
21
|
const config = {
|
|
17
22
|
apiUrl: import.meta.env.API_URL || 'http://localhost:3000',
|
|
18
23
|
appName: import.meta.env.APP_NAME || 'My App'
|
|
19
24
|
}
|
|
20
25
|
|
|
21
|
-
//
|
|
26
|
+
// Does not work in frontend
|
|
22
27
|
const apiUrl = process.env.API_URL
|
|
23
28
|
```
|
|
24
29
|
|
|
@@ -31,23 +36,22 @@ const apiUrl = process.env.API_URL
|
|
|
31
36
|
|
|
32
37
|
**Correct Approach for Secrets**:
|
|
33
38
|
```typescript
|
|
34
|
-
//
|
|
39
|
+
// Security risk: API key exposed in browser
|
|
35
40
|
const apiKey = import.meta.env.API_KEY
|
|
36
41
|
const response = await fetch(`https://api.example.com/data?key=${apiKey}`)
|
|
37
42
|
|
|
38
|
-
//
|
|
43
|
+
// Correct: Backend manages secrets, frontend accesses via proxy
|
|
39
44
|
const response = await fetch('/api/data') // Backend handles API key authentication
|
|
40
45
|
```
|
|
41
46
|
|
|
42
47
|
## Architecture Design
|
|
43
48
|
|
|
44
49
|
### Frontend Architecture Patterns
|
|
45
|
-
Strictly adhere to selected project patterns. Project-specific details reference `docs/rules/architecture/`.
|
|
46
50
|
|
|
47
51
|
**React Component Architecture**:
|
|
48
52
|
- **Function Components**: Mandatory, class components deprecated
|
|
49
53
|
- **Custom Hooks**: For logic reuse and dependency injection
|
|
50
|
-
- **Component Hierarchy**: Atoms
|
|
54
|
+
- **Component Hierarchy**: Atoms -> Molecules -> Organisms -> Templates -> Pages
|
|
51
55
|
- **Props-driven**: Components receive all necessary data via props
|
|
52
56
|
- **Co-location**: Place tests, styles, and related files alongside components
|
|
53
57
|
|
|
@@ -69,26 +73,26 @@ Maintain consistent data flow throughout the React application:
|
|
|
69
73
|
|
|
70
74
|
- **Unidirectional Flow**: Data flows top-down via props
|
|
71
75
|
```
|
|
72
|
-
API Response
|
|
73
|
-
User Input
|
|
76
|
+
API Response -> State -> Props -> Render -> UI
|
|
77
|
+
User Input -> Event Handler -> State Update -> Re-render
|
|
74
78
|
```
|
|
75
79
|
|
|
76
80
|
- **Immutable Updates**: Use immutable patterns for state updates
|
|
77
81
|
```typescript
|
|
78
|
-
//
|
|
82
|
+
// Immutable state update
|
|
79
83
|
setUsers(prev => [...prev, newUser])
|
|
80
84
|
|
|
81
|
-
//
|
|
85
|
+
// Mutable state update (avoid)
|
|
82
86
|
users.push(newUser)
|
|
83
87
|
setUsers(users)
|
|
84
88
|
```
|
|
85
89
|
|
|
86
90
|
### Type Safety in Data Flow
|
|
87
|
-
- **Frontend
|
|
88
|
-
- **Backend
|
|
91
|
+
- **Frontend -> Backend**: Props/State (Type Guaranteed) -> API Request (Serialization)
|
|
92
|
+
- **Backend -> Frontend**: API Response (`unknown`) -> Type Guard -> State (Type Guaranteed)
|
|
89
93
|
|
|
90
94
|
```typescript
|
|
91
|
-
//
|
|
95
|
+
// Type-safe data flow
|
|
92
96
|
async function fetchUser(id: string): Promise<User> {
|
|
93
97
|
const response = await fetch(`/api/users/${id}`)
|
|
94
98
|
const data: unknown = await response.json()
|
|
@@ -1,8 +1,13 @@
|
|
|
1
|
-
|
|
1
|
+
---
|
|
2
|
+
name: frontend/typescript-rules
|
|
3
|
+
description: React/TypeScript frontend development rules including type safety, component design, state management, and error handling.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# TypeScript Development Rules (Frontend)
|
|
2
7
|
|
|
3
8
|
## Frontend-Specific Anti-patterns
|
|
4
9
|
|
|
5
|
-
In addition to universal anti-patterns in coding-standards
|
|
10
|
+
In addition to universal anti-patterns in coding-standards skill, watch for these Frontend-specific issues:
|
|
6
11
|
|
|
7
12
|
- **Prop drilling through 3+ levels** - Should use Context API or state management
|
|
8
13
|
- **Massive components (300+ lines)** - Split into smaller components
|
|
@@ -10,8 +15,8 @@ In addition to universal anti-patterns in coding-standards.md, watch for these F
|
|
|
10
15
|
## Type Safety in Frontend Implementation
|
|
11
16
|
|
|
12
17
|
**Type Safety in Data Flow**
|
|
13
|
-
- **Frontend
|
|
14
|
-
- **Backend
|
|
18
|
+
- **Frontend -> Backend**: Props/State (Type Guaranteed) -> API Request (Serialization)
|
|
19
|
+
- **Backend -> Frontend**: API Response (`unknown`) -> Type Guard -> State (Type Guaranteed)
|
|
15
20
|
|
|
16
21
|
**Frontend-Specific Type Scenarios**:
|
|
17
22
|
- **React Props/State**: TypeScript manages types, unknown unnecessary
|
|
@@ -38,7 +43,7 @@ In addition to universal anti-patterns in coding-standards.md, watch for these F
|
|
|
38
43
|
**Function Design**
|
|
39
44
|
- **0-2 parameters maximum**: Use object for 3+ parameters
|
|
40
45
|
```typescript
|
|
41
|
-
//
|
|
46
|
+
// Object parameter
|
|
42
47
|
function createUser({ name, email, role }: CreateUserParams) {}
|
|
43
48
|
```
|
|
44
49
|
|
|
@@ -65,10 +70,10 @@ In addition to universal anti-patterns in coding-standards.md, watch for these F
|
|
|
65
70
|
- Imports use absolute paths (`src/`)
|
|
66
71
|
|
|
67
72
|
**Clean Code Principles**
|
|
68
|
-
-
|
|
69
|
-
-
|
|
70
|
-
-
|
|
71
|
-
-
|
|
73
|
+
- Delete unused code immediately
|
|
74
|
+
- Delete debug `console.log()`
|
|
75
|
+
- No commented-out code (manage history with version control)
|
|
76
|
+
- Comments explain "why" (not "what")
|
|
72
77
|
|
|
73
78
|
## Error Handling
|
|
74
79
|
|
|
@@ -76,12 +81,12 @@ In addition to universal anti-patterns in coding-standards.md, watch for these F
|
|
|
76
81
|
|
|
77
82
|
**Fail-Fast Principle**: Fail quickly on errors to prevent continued processing in invalid states
|
|
78
83
|
```typescript
|
|
79
|
-
//
|
|
84
|
+
// Prohibited: Unconditional fallback
|
|
80
85
|
catch (error) {
|
|
81
86
|
return defaultValue // Hides error
|
|
82
87
|
}
|
|
83
88
|
|
|
84
|
-
//
|
|
89
|
+
// Required: Explicit failure
|
|
85
90
|
catch (error) {
|
|
86
91
|
logger.error('Processing failed', error)
|
|
87
92
|
throw error // Handle with Error Boundary or higher layer
|
|
@@ -128,4 +133,4 @@ Never include sensitive information (password, token, apiKey, secret, creditCard
|
|
|
128
133
|
- Component Memoization: Use React.memo for expensive components
|
|
129
134
|
- State Optimization: Minimize re-renders with proper state structure
|
|
130
135
|
- Lazy Loading: Use React.lazy and Suspense for code splitting
|
|
131
|
-
- Bundle Size: Monitor with the `build` script
|
|
136
|
+
- Bundle Size: Monitor with the `build` script and keep under 500KB
|
|
@@ -1,4 +1,9 @@
|
|
|
1
|
-
|
|
1
|
+
---
|
|
2
|
+
name: frontend/typescript-testing
|
|
3
|
+
description: Frontend testing rules with Vitest, React Testing Library, and MSW. Includes coverage requirements, test design principles, and quality criteria.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# TypeScript Testing Rules (Frontend)
|
|
2
7
|
|
|
3
8
|
## Test Framework
|
|
4
9
|
- **Vitest**: This project uses Vitest
|
|
@@ -43,7 +48,7 @@
|
|
|
43
48
|
3. **Cross-functional Verification in E2E Tests**
|
|
44
49
|
- Mandatory verification of impact on existing features when adding new features
|
|
45
50
|
- Cover integration points with "High" and "Medium" impact levels from Design Doc's "Integration Point Map"
|
|
46
|
-
- Verification pattern: Existing feature operation
|
|
51
|
+
- Verification pattern: Existing feature operation -> Enable new feature -> Verify continuity of existing features
|
|
47
52
|
- Success criteria: No change in displayed content, rendering time within 5 seconds
|
|
48
53
|
- Designed for automatic execution in CI/CD pipelines
|
|
49
54
|
|
|
@@ -72,11 +77,11 @@ src/
|
|
|
72
77
|
|
|
73
78
|
### Test Code Quality Rules
|
|
74
79
|
|
|
75
|
-
|
|
80
|
+
**Recommended: Keep all tests always active**
|
|
76
81
|
- Merit: Guarantees test suite completeness
|
|
77
82
|
- Practice: Fix problematic tests and activate them
|
|
78
83
|
|
|
79
|
-
|
|
84
|
+
**Avoid: test.skip() or commenting out**
|
|
80
85
|
- Reason: Creates test gaps and incomplete quality checks
|
|
81
86
|
- Solution: Completely delete unnecessary tests
|
|
82
87
|
|
|
@@ -84,7 +89,7 @@ src/
|
|
|
84
89
|
|
|
85
90
|
### MSW (Mock Service Worker) Setup
|
|
86
91
|
```typescript
|
|
87
|
-
//
|
|
92
|
+
// Type-safe MSW handler
|
|
88
93
|
import { rest } from 'msw'
|
|
89
94
|
|
|
90
95
|
const handlers = [
|
|
@@ -96,7 +101,7 @@ const handlers = [
|
|
|
96
101
|
|
|
97
102
|
### Component Mock Type Safety
|
|
98
103
|
```typescript
|
|
99
|
-
//
|
|
104
|
+
// Only required parts
|
|
100
105
|
type TestProps = Pick<ButtonProps, 'label' | 'onClick'>
|
|
101
106
|
const mockProps: TestProps = { label: 'Click', onClick: vi.fn() }
|
|
102
107
|
|
|
@@ -1,3 +1,8 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: implementation-approach
|
|
3
|
+
description: Implementation strategy selection framework with meta-cognitive approach, verification levels, and integration point definitions.
|
|
4
|
+
---
|
|
5
|
+
|
|
1
6
|
# Implementation Strategy Selection Framework (Meta-cognitive Approach)
|
|
2
7
|
|
|
3
8
|
## Meta-cognitive Strategy Selection Process
|
|
@@ -21,7 +26,7 @@ Historical Context Understanding: Current form rationale, past decision validity
|
|
|
21
26
|
|
|
22
27
|
### Phase 2: Strategy Exploration and Creation
|
|
23
28
|
|
|
24
|
-
**Core Question**: "When determining before
|
|
29
|
+
**Core Question**: "When determining before -> after, what implementation patterns or strategies should be referenced?"
|
|
25
30
|
|
|
26
31
|
#### Strategy Discovery Process
|
|
27
32
|
```yaml
|
|
@@ -133,4 +138,4 @@ Define integration points according to selected strategy:
|
|
|
133
138
|
3. **Apply 5 Whys**: Pursue root causes to grasp essence
|
|
134
139
|
4. **Multi-perspective Evaluation**: Comprehensively evaluate from each Phase 1-4 perspective
|
|
135
140
|
5. **Creative Thinking**: Consider sequential application of multiple strategies and designs leveraging project-specific constraints
|
|
136
|
-
6. **Clarify Decision Rationale**: Make strategy selection rationale explicit in design documents
|
|
141
|
+
6. **Clarify Decision Rationale**: Make strategy selection rationale explicit in design documents
|
|
@@ -1,3 +1,8 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: integration-e2e-testing
|
|
3
|
+
description: Integration and E2E test design principles, ROI calculation, test skeleton specification, and review criteria.
|
|
4
|
+
---
|
|
5
|
+
|
|
1
6
|
# Integration Test & E2E Test Design/Implementation Rules
|
|
2
7
|
|
|
3
8
|
## Test Types and Limits
|
|
@@ -31,7 +36,7 @@
|
|
|
31
36
|
```typescript
|
|
32
37
|
// AC: "[Acceptance criteria original text]"
|
|
33
38
|
// ROI: [0-100] | Business Value: [0-10] | Frequency: [0-10]
|
|
34
|
-
// Behavior: [Trigger]
|
|
39
|
+
// Behavior: [Trigger] -> [Process] -> [Observable Result]
|
|
35
40
|
// @category: core-functionality | integration | edge-case | ux | e2e
|
|
36
41
|
// @dependency: none | [component name] | full-system
|
|
37
42
|
// @complexity: low | medium | high
|
|
@@ -49,7 +54,7 @@ it.todo('[AC number]-property: [Invariant description]')
|
|
|
49
54
|
### ROI Calculation
|
|
50
55
|
|
|
51
56
|
```
|
|
52
|
-
ROI = (Business Value
|
|
57
|
+
ROI = (Business Value x Frequency + Legal Requirement x 10 + Defect Detection) / Total Cost
|
|
53
58
|
```
|
|
54
59
|
|
|
55
60
|
| Type | Total Cost | E2E Generation Condition |
|
|
@@ -87,7 +92,7 @@ it('AC2-property: Model name is always gemini-3-pro-image-preview', () => {
|
|
|
87
92
|
|
|
88
93
|
| Step Type | Verification Target | Example |
|
|
89
94
|
|-----------|--------------------| --------|
|
|
90
|
-
| Trigger | Reproduce in Arrange | API failure
|
|
95
|
+
| Trigger | Reproduce in Arrange | API failure -> mockResolvedValue({ ok: false }) |
|
|
91
96
|
| Process | Intermediate state or call | Function call, state change |
|
|
92
97
|
| Observable Result | Final output value | Return value, error message, log output |
|
|
93
98
|
|
|
@@ -101,27 +106,19 @@ it('AC2-property: Model name is always gemini-3-pro-image-preview', () => {
|
|
|
101
106
|
| No `// Verification items:` | Derive from "observable result" in "Behavior" description |
|
|
102
107
|
| Both present | Prioritize verification items, use behavior as supplement |
|
|
103
108
|
|
|
104
|
-
**Derivation Example from Behavior**:
|
|
105
|
-
```
|
|
106
|
-
// Behavior: User completes payment → Order created in DB → Order confirmation screen displayed
|
|
107
|
-
↓ Derived
|
|
108
|
-
- Order is created in DB (or creation function is called)
|
|
109
|
-
- Order confirmation screen data is returned
|
|
110
|
-
```
|
|
111
|
-
|
|
112
109
|
### Integration Test Mock Boundaries
|
|
113
110
|
|
|
114
111
|
| Judgment Criteria | Mock | Actual |
|
|
115
112
|
|-------------------|------|--------|
|
|
116
|
-
| Part of test target? | No
|
|
117
|
-
| Is call verification target of test? | No
|
|
118
|
-
| External network communication? | Yes
|
|
113
|
+
| Part of test target? | No -> Can mock | Yes -> Actual required |
|
|
114
|
+
| Is call verification target of test? | No -> Can mock | Yes -> Actual or verifiable mock |
|
|
115
|
+
| External network communication? | Yes -> Mock required | No -> Actual recommended |
|
|
119
116
|
|
|
120
117
|
**Judgment Flow**:
|
|
121
|
-
1. External API (HTTP communication)
|
|
122
|
-
2. Component interaction under test
|
|
123
|
-
3. Log output verification needed
|
|
124
|
-
4. Log output verification not needed
|
|
118
|
+
1. External API (HTTP communication) -> Mock required
|
|
119
|
+
2. Component interaction under test -> Actual required
|
|
120
|
+
3. Log output verification needed -> Use verifiable mock (vi.fn())
|
|
121
|
+
4. Log output verification not needed -> Actual or ignore
|
|
125
122
|
|
|
126
123
|
### E2E Test Execution Conditions
|
|
127
124
|
|
|
@@ -1,3 +1,8 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: project-context
|
|
3
|
+
description: Project-specific context including project nature, technology stack, and implementation principles. Customize for each project.
|
|
4
|
+
---
|
|
5
|
+
|
|
1
6
|
# Project Context
|
|
2
7
|
|
|
3
8
|
## Basic Configuration
|
|
@@ -30,9 +35,8 @@ When using this template for new projects:
|
|
|
30
35
|
- Technical constraint conditions
|
|
31
36
|
|
|
32
37
|
2. **Architecture Selection**
|
|
33
|
-
- Select appropriate patterns from
|
|
34
|
-
- Place project-specific designs in `docs/rules/architecture/`
|
|
38
|
+
- Select appropriate patterns from architecture skills
|
|
35
39
|
|
|
36
40
|
3. **Environment Configuration**
|
|
37
41
|
- Implement environment variable management methods suitable for the project
|
|
38
|
-
- Add project-specific configuration files
|
|
42
|
+
- Add project-specific configuration files
|
|
@@ -0,0 +1,224 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: subagents-orchestration-guide
|
|
3
|
+
description: Orchestration guide for coordinating subagents through implementation workflows. Defines scale determination, document requirements, stop points, and autonomous execution mode.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Sub-agents Practical Guide - Orchestration Guidelines for Claude (Me)
|
|
7
|
+
|
|
8
|
+
This document provides practical behavioral guidelines for me (Claude) to efficiently process tasks by utilizing subagents.
|
|
9
|
+
|
|
10
|
+
## Core Principle: I Am an Orchestrator
|
|
11
|
+
|
|
12
|
+
**Role Definition**: I am an orchestrator, not an executor.
|
|
13
|
+
|
|
14
|
+
### Required Actions
|
|
15
|
+
- **New tasks**: ALWAYS start with requirement-analyzer
|
|
16
|
+
- **During flow execution**: STRICTLY follow scale-based flow
|
|
17
|
+
- **Each phase**: DELEGATE to appropriate subagent
|
|
18
|
+
- **Stop points**: ALWAYS wait for user approval
|
|
19
|
+
|
|
20
|
+
### Prohibited Actions
|
|
21
|
+
- Executing investigation directly with Grep/Glob/Read
|
|
22
|
+
- Performing analysis or design without subagent delegation
|
|
23
|
+
- Saying "Let me first investigate" then starting work directly
|
|
24
|
+
- Skipping or postponing requirement-analyzer
|
|
25
|
+
|
|
26
|
+
**Execution Rule**: New tasks -> requirement-analyzer FIRST. After flow starts -> follow scale determination.
|
|
27
|
+
|
|
28
|
+
## Decision Flow When Receiving Tasks
|
|
29
|
+
|
|
30
|
+
```mermaid
|
|
31
|
+
graph TD
|
|
32
|
+
Start[Receive New Task] --> RA[Analyze requirements with requirement-analyzer]
|
|
33
|
+
RA --> Scale[Scale assessment]
|
|
34
|
+
Scale --> Flow[Execute flow based on scale]
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
**During flow execution, determine next subagent according to scale determination table**
|
|
38
|
+
|
|
39
|
+
### Requirement Change Detection During Flow
|
|
40
|
+
|
|
41
|
+
**During flow execution**, if detecting the following in user response, stop flow and go to requirement-analyzer:
|
|
42
|
+
- Mentions of new features/behaviors (additional operation methods, display on different screens, etc.)
|
|
43
|
+
- Additions of constraints/conditions (data volume limits, permission controls, etc.)
|
|
44
|
+
- Changes in technical requirements (processing methods, output format changes, etc.)
|
|
45
|
+
|
|
46
|
+
**If any one applies -> Restart from requirement-analyzer with integrated requirements**
|
|
47
|
+
|
|
48
|
+
## Subagents I Can Utilize
|
|
49
|
+
|
|
50
|
+
### Implementation Support Agents
|
|
51
|
+
1. **quality-fixer**: Self-contained processing for overall quality assurance and fixes until completion
|
|
52
|
+
2. **task-decomposer**: Appropriate task decomposition of work plans
|
|
53
|
+
3. **task-executor**: Individual task execution and structured response
|
|
54
|
+
4. **integration-test-reviewer**: Review integration/E2E tests for skeleton compliance
|
|
55
|
+
|
|
56
|
+
### Document Creation Agents
|
|
57
|
+
5. **requirement-analyzer**: Requirement analysis and work scale determination (WebSearch enabled, latest technical information research)
|
|
58
|
+
6. **prd-creator**: Product Requirements Document creation (WebSearch enabled, market trend research)
|
|
59
|
+
7. **technical-designer**: ADR/Design Doc creation (latest technology research, Property annotation assignment)
|
|
60
|
+
8. **work-planner**: Work plan creation (extracts and reflects meta information from test skeletons)
|
|
61
|
+
9. **document-reviewer**: Single document quality, completeness, and rule compliance check
|
|
62
|
+
10. **design-sync**: Design Doc consistency verification (detects explicit conflicts only)
|
|
63
|
+
11. **acceptance-test-generator**: Generate separate integration and E2E test skeletons from Design Doc ACs (EARS format, Property annotations, fast-check support)
|
|
64
|
+
|
|
65
|
+
## My Orchestration Principles
|
|
66
|
+
|
|
67
|
+
### Task Assignment with Responsibility Separation
|
|
68
|
+
|
|
69
|
+
I understand each subagent's responsibilities and assign work appropriately:
|
|
70
|
+
|
|
71
|
+
**task-executor Responsibilities** (DELEGATE these):
|
|
72
|
+
- Implementation work and test addition
|
|
73
|
+
- Confirmation that ONLY added tests pass (existing tests are NOT in scope)
|
|
74
|
+
- DO NOT delegate quality assurance to task-executor
|
|
75
|
+
|
|
76
|
+
**quality-fixer Responsibilities** (DELEGATE these):
|
|
77
|
+
- Overall quality assurance (type check, lint, ALL test execution)
|
|
78
|
+
- Complete execution of quality error fixes
|
|
79
|
+
- Self-contained processing until fix completion
|
|
80
|
+
- Final approved judgment (ONLY after all fixes are complete)
|
|
81
|
+
|
|
82
|
+
### Standard Flow I Manage
|
|
83
|
+
|
|
84
|
+
**Basic Cycle**: I manage the 4-step cycle of `task-executor -> escalation judgment/follow-up -> quality-fixer -> commit`.
|
|
85
|
+
I repeat this cycle for each task to ensure quality.
|
|
86
|
+
|
|
87
|
+
## Constraints Between Subagents
|
|
88
|
+
|
|
89
|
+
**Important**: Subagents cannot directly call other subagents. When coordinating multiple subagents, the main AI (Claude) operates as the orchestrator.
|
|
90
|
+
|
|
91
|
+
## Scale Determination and Document Requirements
|
|
92
|
+
|
|
93
|
+
| Scale | File Count | PRD | ADR | Design Doc | Work Plan |
|
|
94
|
+
|-------|------------|-----|-----|------------|-----------|
|
|
95
|
+
| Small | 1-2 | Update[^1] | Not needed | Not needed | Simplified (inline comments only) |
|
|
96
|
+
| Medium | 3-5 | Update[^1] | Conditional[^2] | **Required** | **Required** |
|
|
97
|
+
| Large | 6+ | **Required**[^3] | Conditional[^2] | **Required** | **Required** |
|
|
98
|
+
|
|
99
|
+
[^1]: Update existing PRD if one exists for the relevant feature
|
|
100
|
+
[^2]: Required when: architecture changes, new technology introduction, OR data flow changes
|
|
101
|
+
[^3]: Create new PRD, update existing PRD, or create reverse PRD (when no existing PRD)
|
|
102
|
+
|
|
103
|
+
## My Basic Flow for Work Planning
|
|
104
|
+
|
|
105
|
+
When receiving new features or change requests, I first request requirement analysis from requirement-analyzer.
|
|
106
|
+
According to scale determination:
|
|
107
|
+
|
|
108
|
+
### Large Scale (6+ Files)
|
|
109
|
+
1. requirement-analyzer -> Requirement analysis + Check existing PRD **[Stop: Requirement confirmation/question handling]**
|
|
110
|
+
2. prd-creator -> PRD creation (update if existing, new creation with thorough investigation if not) -> Execute document-reviewer **[Stop: Requirement confirmation]**
|
|
111
|
+
3. technical-designer -> ADR creation (if needed) -> Execute document-reviewer **[Stop: Technical direction decision]**
|
|
112
|
+
4. technical-designer -> Design Doc creation -> Execute document-reviewer -> Execute design-sync **[Stop: Design content confirmation]**
|
|
113
|
+
5. acceptance-test-generator -> Integration and E2E test skeleton generation
|
|
114
|
+
-> Main AI: Verify generation, then pass information to work-planner
|
|
115
|
+
6. work-planner -> Work plan creation (including integration and E2E test information) **[Stop: Batch approval for entire implementation phase]**
|
|
116
|
+
7. **Start autonomous execution mode**: task-decomposer -> Execute all tasks -> Completion report
|
|
117
|
+
|
|
118
|
+
### Medium Scale (3-5 Files)
|
|
119
|
+
1. requirement-analyzer -> Requirement analysis **[Stop: Requirement confirmation/question handling]**
|
|
120
|
+
2. technical-designer -> Design Doc creation -> Execute document-reviewer -> Execute design-sync **[Stop: Technical direction decision]**
|
|
121
|
+
3. acceptance-test-generator -> Integration and E2E test skeleton generation
|
|
122
|
+
-> Main AI: Verify generation, then pass information to work-planner
|
|
123
|
+
4. work-planner -> Work plan creation (including integration and E2E test information) **[Stop: Batch approval for entire implementation phase]**
|
|
124
|
+
5. **Start autonomous execution mode**: task-decomposer -> Execute all tasks -> Completion report
|
|
125
|
+
|
|
126
|
+
### Small Scale (1-2 Files)
|
|
127
|
+
1. Create simplified plan **[Stop: Batch approval for entire implementation phase]**
|
|
128
|
+
2. **Start autonomous execution mode**: Direct implementation -> Completion report
|
|
129
|
+
|
|
130
|
+
## Autonomous Execution Mode
|
|
131
|
+
|
|
132
|
+
### Authority Delegation
|
|
133
|
+
|
|
134
|
+
**After starting autonomous execution mode**:
|
|
135
|
+
- Batch approval for entire implementation phase delegates authority to subagents
|
|
136
|
+
- task-executor: Implementation authority (can use Edit/Write)
|
|
137
|
+
- quality-fixer: Fix authority (automatic quality error fixes)
|
|
138
|
+
|
|
139
|
+
### Definition of Autonomous Execution Mode
|
|
140
|
+
After "batch approval for entire implementation phase" with work-planner, autonomously execute the following processes without human approval:
|
|
141
|
+
|
|
142
|
+
```mermaid
|
|
143
|
+
graph TD
|
|
144
|
+
START[Batch approval for entire implementation phase] --> AUTO[Start autonomous execution mode]
|
|
145
|
+
AUTO --> TD[task-decomposer: Task decomposition]
|
|
146
|
+
TD --> PHASE[Register phase management Todo]
|
|
147
|
+
PHASE --> PSTART[Phase start: Expand task Todo]
|
|
148
|
+
PSTART --> TE[task-executor: Implementation]
|
|
149
|
+
TE --> ESC{Escalation judgment}
|
|
150
|
+
ESC -->|No issue| FOLLOW[Follow-up processing]
|
|
151
|
+
ESC -->|Issue found| STOP[Escalate to user]
|
|
152
|
+
FOLLOW --> QF[quality-fixer: Quality check and fixes]
|
|
153
|
+
QF --> COMMIT[Execute git commit]
|
|
154
|
+
COMMIT --> TCHECK{Tasks remaining?}
|
|
155
|
+
TCHECK -->|Yes| TE
|
|
156
|
+
TCHECK -->|No| PCHECK{Phases remaining?}
|
|
157
|
+
PCHECK -->|Yes| PSTART
|
|
158
|
+
PCHECK -->|No| REPORT[Completion report]
|
|
159
|
+
|
|
160
|
+
TE --> INTERRUPT{User input?}
|
|
161
|
+
INTERRUPT -->|Requirement change| STOP2[Stop autonomous execution]
|
|
162
|
+
STOP2 --> RA[Re-analyze with requirement-analyzer]
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
### Conditions for Stopping Autonomous Execution
|
|
166
|
+
Stop autonomous execution and escalate to user in the following cases:
|
|
167
|
+
|
|
168
|
+
1. **Escalation from subagent**
|
|
169
|
+
- When receiving response with `status: "escalation_needed"`
|
|
170
|
+
- When receiving response with `status: "blocked"`
|
|
171
|
+
|
|
172
|
+
2. **When requirement change detected**
|
|
173
|
+
- Any match in requirement change detection checklist
|
|
174
|
+
- Stop autonomous execution and re-analyze with integrated requirements in requirement-analyzer
|
|
175
|
+
|
|
176
|
+
3. **When work-planner update restriction is violated**
|
|
177
|
+
- Requirement changes after task-decomposer starts require overall redesign
|
|
178
|
+
- Restart entire flow from requirement-analyzer
|
|
179
|
+
|
|
180
|
+
4. **When user explicitly stops**
|
|
181
|
+
- Direct stop instruction or interruption
|
|
182
|
+
|
|
183
|
+
## My Main Roles as Orchestrator
|
|
184
|
+
|
|
185
|
+
1. **State Management**: Grasp current phase, each subagent's state, and next action
|
|
186
|
+
2. **Information Bridging**: Data conversion and transmission between subagents
|
|
187
|
+
- Convert each subagent's output to next subagent's input format
|
|
188
|
+
- **Always pass deliverables from previous process to next agent**
|
|
189
|
+
- Extract necessary information from structured responses
|
|
190
|
+
- Compose commit messages from changeSummary -> **Execute git commit with Bash**
|
|
191
|
+
- Explicitly integrate initial and additional requirements when requirements change
|
|
192
|
+
3. **Quality Assurance and Commit Execution**: After confirming approved=true, immediately execute git commit
|
|
193
|
+
4. **Autonomous Execution Mode Management**: Start/stop autonomous execution after approval, escalation decisions
|
|
194
|
+
5. **ADR Status Management**: Update ADR status after user decision (Accepted/Rejected)
|
|
195
|
+
|
|
196
|
+
## Important Constraints
|
|
197
|
+
|
|
198
|
+
- **Quality check is MANDATORY**: quality-fixer approval REQUIRED before commit
|
|
199
|
+
- **Structured response is MANDATORY**: Information transmission between subagents MUST use JSON format
|
|
200
|
+
- **Approval management**: Document creation -> Execute document-reviewer -> Get user approval BEFORE proceeding
|
|
201
|
+
- **Flow confirmation**: After getting approval, ALWAYS check next step with work planning flow (large/medium/small scale)
|
|
202
|
+
- **Consistency verification**: IF subagent determinations contradict -> prioritize these guidelines
|
|
203
|
+
|
|
204
|
+
## Required Dialogue Points with Humans
|
|
205
|
+
|
|
206
|
+
### Basic Principles
|
|
207
|
+
- **Stopping is mandatory**: Always wait for human response at the following timings
|
|
208
|
+
- **Confirmation -> Agreement cycle**: After document generation, proceed to next step after agreement or fix instructions in update mode
|
|
209
|
+
- **Specific questions**: Make decisions easy with options (A/B/C) or comparison tables
|
|
210
|
+
- **Dialogue over efficiency**: Get confirmation at early stages to prevent rework
|
|
211
|
+
|
|
212
|
+
### Main Stop Points
|
|
213
|
+
- **After requirement-analyzer completion**: Confirm requirement analysis results and questions
|
|
214
|
+
- **After PRD creation -> document-reviewer execution**: Confirm requirement understanding and consistency (confirm with question list)
|
|
215
|
+
- **After ADR creation -> document-reviewer execution**: Confirm technical direction and consistency (present multiple options with comparison table)
|
|
216
|
+
- On user approval: Main AI (me) updates Status to Accepted
|
|
217
|
+
- On user rejection: Main AI (me) updates Status to Rejected
|
|
218
|
+
- **After Design Doc creation -> document-reviewer execution**: Confirm design content and consistency
|
|
219
|
+
- **After work plan creation**: Batch approval for entire implementation phase (confirm with plan summary)
|
|
220
|
+
|
|
221
|
+
### Stop Points During Autonomous Execution
|
|
222
|
+
- **When requirement change detected**: Match in requirement change checklist -> Return to requirement-analyzer
|
|
223
|
+
- **When critical error occurs**: Report error content -> Wait for response instructions
|
|
224
|
+
- **When user interrupts**: Explicit stop instruction -> Confirm situation
|