create-ai-project 1.11.2
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/acceptance-test-generator.md +316 -0
- package/.claude/agents/code-reviewer.md +193 -0
- package/.claude/agents/document-reviewer.md +182 -0
- package/.claude/agents/prd-creator.md +186 -0
- package/.claude/agents/quality-fixer.md +295 -0
- package/.claude/agents/requirement-analyzer.md +161 -0
- package/.claude/agents/rule-advisor.md +194 -0
- package/.claude/agents/task-decomposer.md +291 -0
- package/.claude/agents/task-executor.md +270 -0
- package/.claude/agents/technical-designer.md +343 -0
- package/.claude/agents/work-planner.md +181 -0
- package/.claude/agents-en/acceptance-test-generator.md +256 -0
- package/.claude/agents-en/code-reviewer.md +195 -0
- package/.claude/agents-en/design-sync.md +225 -0
- package/.claude/agents-en/document-reviewer.md +190 -0
- package/.claude/agents-en/integration-test-reviewer.md +195 -0
- package/.claude/agents-en/prd-creator.md +196 -0
- package/.claude/agents-en/quality-fixer-frontend.md +334 -0
- package/.claude/agents-en/quality-fixer.md +291 -0
- package/.claude/agents-en/requirement-analyzer.md +165 -0
- package/.claude/agents-en/rule-advisor.md +194 -0
- package/.claude/agents-en/task-decomposer.md +291 -0
- package/.claude/agents-en/task-executor-frontend.md +276 -0
- package/.claude/agents-en/task-executor.md +272 -0
- package/.claude/agents-en/technical-designer-frontend.md +441 -0
- package/.claude/agents-en/technical-designer.md +371 -0
- package/.claude/agents-en/work-planner.md +216 -0
- package/.claude/agents-ja/acceptance-test-generator.md +256 -0
- package/.claude/agents-ja/code-reviewer.md +195 -0
- package/.claude/agents-ja/design-sync.md +225 -0
- package/.claude/agents-ja/document-reviewer.md +192 -0
- package/.claude/agents-ja/integration-test-reviewer.md +195 -0
- package/.claude/agents-ja/prd-creator.md +194 -0
- package/.claude/agents-ja/quality-fixer-frontend.md +335 -0
- package/.claude/agents-ja/quality-fixer.md +292 -0
- package/.claude/agents-ja/requirement-analyzer.md +164 -0
- package/.claude/agents-ja/rule-advisor.md +194 -0
- package/.claude/agents-ja/task-decomposer.md +291 -0
- package/.claude/agents-ja/task-executor-frontend.md +276 -0
- package/.claude/agents-ja/task-executor.md +272 -0
- package/.claude/agents-ja/technical-designer-frontend.md +442 -0
- package/.claude/agents-ja/technical-designer.md +370 -0
- package/.claude/agents-ja/work-planner.md +213 -0
- package/.claude/commands/build.md +78 -0
- package/.claude/commands/design.md +27 -0
- package/.claude/commands/implement.md +79 -0
- package/.claude/commands/plan.md +43 -0
- package/.claude/commands/project-inject.md +76 -0
- package/.claude/commands/refine-rule.md +206 -0
- package/.claude/commands/review.md +78 -0
- package/.claude/commands/sync-rules.md +116 -0
- package/.claude/commands/task.md +13 -0
- package/.claude/commands-en/build.md +77 -0
- package/.claude/commands-en/design.md +39 -0
- package/.claude/commands-en/front-build.md +103 -0
- package/.claude/commands-en/front-design.md +42 -0
- package/.claude/commands-en/front-plan.md +40 -0
- package/.claude/commands-en/implement.md +75 -0
- package/.claude/commands-en/plan.md +45 -0
- package/.claude/commands-en/project-inject.md +76 -0
- package/.claude/commands-en/refine-rule.md +208 -0
- package/.claude/commands-en/review.md +78 -0
- package/.claude/commands-en/sync-rules.md +116 -0
- package/.claude/commands-en/task.md +13 -0
- package/.claude/commands-ja/build.md +75 -0
- package/.claude/commands-ja/design.md +37 -0
- package/.claude/commands-ja/front-build.md +103 -0
- package/.claude/commands-ja/front-design.md +42 -0
- package/.claude/commands-ja/front-plan.md +40 -0
- package/.claude/commands-ja/implement.md +73 -0
- package/.claude/commands-ja/plan.md +43 -0
- package/.claude/commands-ja/project-inject.md +76 -0
- package/.claude/commands-ja/refine-rule.md +206 -0
- package/.claude/commands-ja/review.md +78 -0
- package/.claude/commands-ja/sync-rules.md +116 -0
- package/.claude/commands-ja/task.md +13 -0
- package/.claude/settings.local.json +74 -0
- package/.husky/pre-commit +1 -0
- package/.husky/pre-push +3 -0
- package/.madgerc +14 -0
- package/.tsprunerc +11 -0
- package/CLAUDE.en.md +102 -0
- package/CLAUDE.ja.md +102 -0
- package/CLAUDE.md +111 -0
- package/LICENSE +21 -0
- package/README.ja.md +233 -0
- package/README.md +243 -0
- package/bin/create-project.js +87 -0
- package/biome.json +51 -0
- package/docs/adr/template-en.md +64 -0
- package/docs/adr/template-ja.md +64 -0
- package/docs/design/template-en.md +281 -0
- package/docs/design/template-ja.md +285 -0
- package/docs/guides/en/quickstart.md +111 -0
- package/docs/guides/en/rule-editing-guide.md +266 -0
- package/docs/guides/en/sub-agents.md +343 -0
- package/docs/guides/en/use-cases.md +308 -0
- package/docs/guides/ja/quickstart.md +112 -0
- package/docs/guides/ja/rule-editing-guide.md +266 -0
- package/docs/guides/ja/sub-agents.md +343 -0
- package/docs/guides/ja/use-cases.md +290 -0
- package/docs/guides/sub-agents.md +306 -0
- package/docs/plans/20250123-integration-test-improvement.md +993 -0
- package/docs/plans/template-en.md +130 -0
- package/docs/plans/template-ja.md +130 -0
- package/docs/prd/template-en.md +109 -0
- package/docs/prd/template-ja.md +109 -0
- package/docs/rules/ai-development-guide.md +260 -0
- package/docs/rules/architecture/implementation-approach.md +136 -0
- package/docs/rules/documentation-criteria.md +180 -0
- package/docs/rules/project-context.md +38 -0
- package/docs/rules/rules-index.yaml +137 -0
- package/docs/rules/technical-spec.md +47 -0
- package/docs/rules/typescript-testing.md +188 -0
- package/docs/rules/typescript.md +166 -0
- package/docs/rules-en/architecture/implementation-approach.md +136 -0
- package/docs/rules-en/coding-standards.md +333 -0
- package/docs/rules-en/documentation-criteria.md +184 -0
- package/docs/rules-en/frontend/technical-spec.md +143 -0
- package/docs/rules-en/frontend/typescript-testing.md +124 -0
- package/docs/rules-en/frontend/typescript.md +131 -0
- package/docs/rules-en/integration-e2e-testing.md +149 -0
- package/docs/rules-en/project-context.md +38 -0
- package/docs/rules-en/rules-index.yaml +211 -0
- package/docs/rules-en/technical-spec.md +86 -0
- package/docs/rules-en/typescript-testing.md +149 -0
- package/docs/rules-en/typescript.md +116 -0
- package/docs/rules-ja/architecture/implementation-approach.md +136 -0
- package/docs/rules-ja/coding-standards.md +333 -0
- package/docs/rules-ja/documentation-criteria.md +180 -0
- package/docs/rules-ja/frontend/technical-spec.md +143 -0
- package/docs/rules-ja/frontend/typescript-testing.md +124 -0
- package/docs/rules-ja/frontend/typescript.md +131 -0
- package/docs/rules-ja/integration-e2e-testing.md +149 -0
- package/docs/rules-ja/project-context.md +38 -0
- package/docs/rules-ja/rules-index.yaml +196 -0
- package/docs/rules-ja/technical-spec.md +86 -0
- package/docs/rules-ja/typescript-testing.md +149 -0
- package/docs/rules-ja/typescript.md +116 -0
- package/package.json +98 -0
- package/scripts/check-unused-exports.js +69 -0
- package/scripts/cleanup-test-processes.sh +32 -0
- package/scripts/post-setup.js +110 -0
- package/scripts/set-language.js +310 -0
- package/scripts/setup-project.js +199 -0
- package/scripts/show-coverage.js +74 -0
- package/src/index.ts +11 -0
- package/templates/.gitignore.template +52 -0
- package/tsconfig.json +50 -0
- package/vitest.config.mjs +47 -0
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
# TypeScript Testing Rules
|
|
2
|
+
|
|
3
|
+
## Test Framework
|
|
4
|
+
- **Vitest**: This project uses Vitest
|
|
5
|
+
- **React Testing Library**: For component testing
|
|
6
|
+
- **MSW (Mock Service Worker)**: For API mocking
|
|
7
|
+
- Test imports: `import { describe, it, expect, beforeEach, vi } from 'vitest'`
|
|
8
|
+
- Component test imports: `import { render, screen, fireEvent } from '@testing-library/react'`
|
|
9
|
+
- Mock creation: Use `vi.mock()`
|
|
10
|
+
|
|
11
|
+
## Basic Testing Policy
|
|
12
|
+
|
|
13
|
+
### Quality Requirements
|
|
14
|
+
- **Coverage**: Unit test coverage must be 60% or higher (Frontend standard 2025)
|
|
15
|
+
- **Independence**: Each test can run independently without depending on other tests
|
|
16
|
+
- **Reproducibility**: Tests are environment-independent and always return the same results
|
|
17
|
+
- **Readability**: Test code maintains the same quality as production code
|
|
18
|
+
|
|
19
|
+
### Coverage Requirements (ADR-0002 Compliant)
|
|
20
|
+
**Mandatory**: Unit test coverage must be 60% or higher
|
|
21
|
+
**Component-specific targets**:
|
|
22
|
+
- Atoms (Button, Text, etc.): 70% or higher
|
|
23
|
+
- Molecules (FormField, etc.): 65% or higher
|
|
24
|
+
- Organisms (Header, Footer, etc.): 60% or higher
|
|
25
|
+
- Custom Hooks: 65% or higher
|
|
26
|
+
- Utils: 70% or higher
|
|
27
|
+
|
|
28
|
+
**Metrics**: Statements, Branches, Functions, Lines
|
|
29
|
+
|
|
30
|
+
### Test Types and Scope
|
|
31
|
+
1. **Unit Tests (React Testing Library)**
|
|
32
|
+
- Verify behavior of individual components or functions
|
|
33
|
+
- Mock all external dependencies
|
|
34
|
+
- Most numerous, implemented with fine granularity
|
|
35
|
+
- Focus on user-observable behavior
|
|
36
|
+
|
|
37
|
+
2. **Integration Tests (React Testing Library + MSW)**
|
|
38
|
+
- Verify coordination between multiple components
|
|
39
|
+
- Mock APIs with MSW (Mock Service Worker)
|
|
40
|
+
- No actual DB connections (backend manages DB)
|
|
41
|
+
- Verify major functional flows
|
|
42
|
+
|
|
43
|
+
3. **Cross-functional Verification in E2E Tests**
|
|
44
|
+
- Mandatory verification of impact on existing features when adding new features
|
|
45
|
+
- Cover integration points with "High" and "Medium" impact levels from Design Doc's "Integration Point Map"
|
|
46
|
+
- Verification pattern: Existing feature operation → Enable new feature → Verify continuity of existing features
|
|
47
|
+
- Success criteria: No change in displayed content, rendering time within 5 seconds
|
|
48
|
+
- Designed for automatic execution in CI/CD pipelines
|
|
49
|
+
|
|
50
|
+
## Test Implementation Conventions
|
|
51
|
+
|
|
52
|
+
### Directory Structure (Co-location Principle)
|
|
53
|
+
```
|
|
54
|
+
src/
|
|
55
|
+
└── components/
|
|
56
|
+
└── Button/
|
|
57
|
+
├── Button.tsx
|
|
58
|
+
├── Button.test.tsx # Co-located with component
|
|
59
|
+
└── index.ts
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
**Rationale**:
|
|
63
|
+
- React Testing Library best practice
|
|
64
|
+
- ADR-0002 Co-location principle
|
|
65
|
+
- Easy to find and maintain tests alongside implementation
|
|
66
|
+
|
|
67
|
+
### Naming Conventions
|
|
68
|
+
- Test files: `{ComponentName}.test.tsx`
|
|
69
|
+
- Integration test files: `{FeatureName}.integration.test.tsx`
|
|
70
|
+
- Test suites: Names describing target components or features
|
|
71
|
+
- Test cases: Names describing expected behavior from user perspective
|
|
72
|
+
|
|
73
|
+
### Test Code Quality Rules
|
|
74
|
+
|
|
75
|
+
✅ **Recommended: Keep all tests always active**
|
|
76
|
+
- Merit: Guarantees test suite completeness
|
|
77
|
+
- Practice: Fix problematic tests and activate them
|
|
78
|
+
|
|
79
|
+
❌ **Avoid: test.skip() or commenting out**
|
|
80
|
+
- Reason: Creates test gaps and incomplete quality checks
|
|
81
|
+
- Solution: Completely delete unnecessary tests
|
|
82
|
+
|
|
83
|
+
## Mock Type Safety Enforcement
|
|
84
|
+
|
|
85
|
+
### MSW (Mock Service Worker) Setup
|
|
86
|
+
```typescript
|
|
87
|
+
// ✅ Type-safe MSW handler
|
|
88
|
+
import { rest } from 'msw'
|
|
89
|
+
|
|
90
|
+
const handlers = [
|
|
91
|
+
rest.get('/api/users/:id', (req, res, ctx) => {
|
|
92
|
+
return res(ctx.json({ id: '1', name: 'John' } satisfies User))
|
|
93
|
+
})
|
|
94
|
+
]
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
### Component Mock Type Safety
|
|
98
|
+
```typescript
|
|
99
|
+
// ✅ Only required parts
|
|
100
|
+
type TestProps = Pick<ButtonProps, 'label' | 'onClick'>
|
|
101
|
+
const mockProps: TestProps = { label: 'Click', onClick: vi.fn() }
|
|
102
|
+
|
|
103
|
+
// Only when absolutely necessary, with clear justification
|
|
104
|
+
const mockRouter = {
|
|
105
|
+
push: vi.fn()
|
|
106
|
+
} as unknown as Router // Complex router type structure
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
## Basic React Testing Library Example
|
|
110
|
+
|
|
111
|
+
```typescript
|
|
112
|
+
import { describe, it, expect, vi } from 'vitest'
|
|
113
|
+
import { render, screen, fireEvent } from '@testing-library/react'
|
|
114
|
+
import { Button } from './Button'
|
|
115
|
+
|
|
116
|
+
describe('Button', () => {
|
|
117
|
+
it('should call onClick when clicked', () => {
|
|
118
|
+
const onClick = vi.fn()
|
|
119
|
+
render(<Button label="Click me" onClick={onClick} />)
|
|
120
|
+
fireEvent.click(screen.getByRole('button', { name: 'Click me' }))
|
|
121
|
+
expect(onClick).toHaveBeenCalledOnce()
|
|
122
|
+
})
|
|
123
|
+
})
|
|
124
|
+
```
|
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
# TypeScript Development Rules
|
|
2
|
+
|
|
3
|
+
## Frontend-Specific Anti-patterns
|
|
4
|
+
|
|
5
|
+
In addition to universal anti-patterns in coding-standards.md, watch for these Frontend-specific issues:
|
|
6
|
+
|
|
7
|
+
- **Prop drilling through 3+ levels** - Should use Context API or state management
|
|
8
|
+
- **Massive components (300+ lines)** - Split into smaller components
|
|
9
|
+
|
|
10
|
+
## Type Safety in Frontend Implementation
|
|
11
|
+
|
|
12
|
+
**Type Safety in Data Flow**
|
|
13
|
+
- **Frontend → Backend**: Props/State (Type Guaranteed) → API Request (Serialization)
|
|
14
|
+
- **Backend → Frontend**: API Response (`unknown`) → Type Guard → State (Type Guaranteed)
|
|
15
|
+
|
|
16
|
+
**Frontend-Specific Type Scenarios**:
|
|
17
|
+
- **React Props/State**: TypeScript manages types, unknown unnecessary
|
|
18
|
+
- **External API Responses**: Always receive as `unknown`, validate with type guards
|
|
19
|
+
- **localStorage/sessionStorage**: Treat as `unknown`, validate
|
|
20
|
+
- **URL Parameters**: Treat as `unknown`, validate
|
|
21
|
+
- **Form Input (Controlled Components)**: Type-safe with React synthetic events
|
|
22
|
+
|
|
23
|
+
**Type Complexity Management (Frontend)**
|
|
24
|
+
- **Props Design**:
|
|
25
|
+
- Props count: 3-7 props ideal (consider component splitting if exceeds 10)
|
|
26
|
+
- Optional Props: 50% or less (consider default values or Context if excessive)
|
|
27
|
+
- Nesting: Up to 2 levels (flatten deeper structures)
|
|
28
|
+
- Type Assertions: Review design if used 3+ times
|
|
29
|
+
- **External API Types**: Relax constraints and define according to reality (convert appropriately internally)
|
|
30
|
+
|
|
31
|
+
## Coding Conventions
|
|
32
|
+
|
|
33
|
+
**Component Design Criteria**
|
|
34
|
+
- **Function Components (Mandatory)**: Official React recommendation, optimizable by modern tooling
|
|
35
|
+
- **Classes Prohibited**: Class components completely deprecated (Exception: Error Boundary)
|
|
36
|
+
- **Custom Hooks**: Standard pattern for logic reuse
|
|
37
|
+
|
|
38
|
+
**Function Design**
|
|
39
|
+
- **0-2 parameters maximum**: Use object for 3+ parameters
|
|
40
|
+
```typescript
|
|
41
|
+
// ✅ Object parameter
|
|
42
|
+
function createUser({ name, email, role }: CreateUserParams) {}
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
**Props Design (Props-driven Approach)**
|
|
46
|
+
- Props are the interface: Define all necessary information as props
|
|
47
|
+
- Avoid implicit dependencies: Do not depend on global state or context without necessity
|
|
48
|
+
- Type-safe: Always define Props type explicitly
|
|
49
|
+
|
|
50
|
+
**Environment Variables**
|
|
51
|
+
- **Use build tool's environment variable system**: `process.env` does not work in browsers
|
|
52
|
+
- **No secrets on client-side**: All frontend code is public, manage secrets in backend
|
|
53
|
+
|
|
54
|
+
**Dependency Injection**
|
|
55
|
+
- **Custom Hooks for dependency injection**: Ensure testability and modularity
|
|
56
|
+
|
|
57
|
+
**Asynchronous Processing**
|
|
58
|
+
- Promise Handling: Always use `async/await`
|
|
59
|
+
- Error Handling: Always handle with `try-catch` or Error Boundary
|
|
60
|
+
- Type Definition: Explicitly define return value types (e.g., `Promise<Result>`)
|
|
61
|
+
|
|
62
|
+
**Format Rules**
|
|
63
|
+
- Semicolon omission (follow Biome settings)
|
|
64
|
+
- Types in `PascalCase`, variables/functions in `camelCase`
|
|
65
|
+
- Imports use absolute paths (`src/`)
|
|
66
|
+
|
|
67
|
+
**Clean Code Principles**
|
|
68
|
+
- ✅ Delete unused code immediately
|
|
69
|
+
- ✅ Delete debug `console.log()`
|
|
70
|
+
- ❌ Commented-out code (manage history with version control)
|
|
71
|
+
- ✅ Comments explain "why" (not "what")
|
|
72
|
+
|
|
73
|
+
## Error Handling
|
|
74
|
+
|
|
75
|
+
**Absolute Rule**: Error suppression prohibited. All errors must have log output and appropriate handling.
|
|
76
|
+
|
|
77
|
+
**Fail-Fast Principle**: Fail quickly on errors to prevent continued processing in invalid states
|
|
78
|
+
```typescript
|
|
79
|
+
// ❌ Prohibited: Unconditional fallback
|
|
80
|
+
catch (error) {
|
|
81
|
+
return defaultValue // Hides error
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
// ✅ Required: Explicit failure
|
|
85
|
+
catch (error) {
|
|
86
|
+
logger.error('Processing failed', error)
|
|
87
|
+
throw error // Handle with Error Boundary or higher layer
|
|
88
|
+
}
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
**Result Type Pattern**: Express errors with types for explicit handling
|
|
92
|
+
```typescript
|
|
93
|
+
type Result<T, E> = { ok: true; value: T } | { ok: false; error: E }
|
|
94
|
+
|
|
95
|
+
// Example: Express error possibility with types
|
|
96
|
+
function parseUser(data: unknown): Result<User, ValidationError> {
|
|
97
|
+
if (!isValid(data)) return { ok: false, error: new ValidationError() }
|
|
98
|
+
return { ok: true, value: data as User }
|
|
99
|
+
}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
**Custom Error Classes**
|
|
103
|
+
```typescript
|
|
104
|
+
export class AppError extends Error {
|
|
105
|
+
constructor(message: string, public readonly code: string, public readonly statusCode = 500) {
|
|
106
|
+
super(message)
|
|
107
|
+
this.name = this.constructor.name
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
// Purpose-specific: ValidationError(400), ApiError(502), NotFoundError(404)
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
**Layer-Specific Error Handling (React)**
|
|
114
|
+
- Error Boundary: Catch React component errors, display fallback UI
|
|
115
|
+
- Custom Hook: Detect business rule violations, propagate AppError as-is
|
|
116
|
+
- API Layer: Convert fetch errors to domain errors
|
|
117
|
+
|
|
118
|
+
**Structured Logging and Sensitive Information Protection**
|
|
119
|
+
Never include sensitive information (password, token, apiKey, secret, creditCard) in logs
|
|
120
|
+
|
|
121
|
+
**Asynchronous Error Handling in React**
|
|
122
|
+
- Error Boundary setup mandatory: Catch rendering errors
|
|
123
|
+
- Use try-catch with all async/await in event handlers
|
|
124
|
+
- Always log and re-throw errors or display error state
|
|
125
|
+
|
|
126
|
+
## Performance Optimization
|
|
127
|
+
|
|
128
|
+
- Component Memoization: Use React.memo for expensive components
|
|
129
|
+
- State Optimization: Minimize re-renders with proper state structure
|
|
130
|
+
- Lazy Loading: Use React.lazy and Suspense for code splitting
|
|
131
|
+
- Bundle Size: Monitor with the `build` script (use the appropriate run command based on the `packageManager` field in package.json) and keep under 500KB
|
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
# Integration Test & E2E Test Design/Implementation Rules
|
|
2
|
+
|
|
3
|
+
## Test Types and Limits
|
|
4
|
+
|
|
5
|
+
| Type | Purpose | File Format | Limit |
|
|
6
|
+
|------|---------|-------------|-------|
|
|
7
|
+
| Integration Test | Component interaction verification | `*.int.test.ts` | 3 per feature |
|
|
8
|
+
| E2E Test | Critical user journey verification | `*.e2e.test.ts` | 1-2 per feature |
|
|
9
|
+
|
|
10
|
+
**Critical User Journey**: Features with revenue impact, legal requirements, or daily use by majority of users
|
|
11
|
+
|
|
12
|
+
## Behavior-First Principle
|
|
13
|
+
|
|
14
|
+
### Observability Check (All YES = Include)
|
|
15
|
+
|
|
16
|
+
| Check | Question | If NO |
|
|
17
|
+
|-------|----------|-------|
|
|
18
|
+
| Observable | Can user observe the result? | Exclude |
|
|
19
|
+
| System Context | Does it require integration of multiple components? | Exclude |
|
|
20
|
+
| Automatable | Can it run stably in CI environment? | Exclude |
|
|
21
|
+
|
|
22
|
+
### Include/Exclude Criteria
|
|
23
|
+
|
|
24
|
+
**Include**: Business logic accuracy, data integrity, user-visible features, error handling
|
|
25
|
+
**Exclude**: External live connections, performance metrics, implementation details, UI layout
|
|
26
|
+
|
|
27
|
+
## Skeleton Specification
|
|
28
|
+
|
|
29
|
+
### Required Comment Format
|
|
30
|
+
|
|
31
|
+
```typescript
|
|
32
|
+
// AC: "[Acceptance criteria original text]"
|
|
33
|
+
// ROI: [0-100] | Business Value: [0-10] | Frequency: [0-10]
|
|
34
|
+
// Behavior: [Trigger] → [Process] → [Observable Result]
|
|
35
|
+
// @category: core-functionality | integration | edge-case | ux | e2e
|
|
36
|
+
// @dependency: none | [component name] | full-system
|
|
37
|
+
// @complexity: low | medium | high
|
|
38
|
+
it.todo('[AC number]: [Test name]')
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
### Property Annotations
|
|
42
|
+
|
|
43
|
+
```typescript
|
|
44
|
+
// Property: `[Verification expression]`
|
|
45
|
+
// fast-check: fc.property(fc.[arbitrary], (input) => [invariant])
|
|
46
|
+
it.todo('[AC number]-property: [Invariant description]')
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
### ROI Calculation
|
|
50
|
+
|
|
51
|
+
```
|
|
52
|
+
ROI = (Business Value × Frequency + Legal Requirement × 10 + Defect Detection) / Total Cost
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
| Type | Total Cost | E2E Generation Condition |
|
|
56
|
+
|------|------------|-------------------------|
|
|
57
|
+
| Integration | 11 | - |
|
|
58
|
+
| E2E | 38 | ROI > 50 |
|
|
59
|
+
|
|
60
|
+
## Implementation Rules
|
|
61
|
+
|
|
62
|
+
### Property-Based Test Implementation
|
|
63
|
+
|
|
64
|
+
When Property annotation exists, fast-check library is required:
|
|
65
|
+
|
|
66
|
+
```typescript
|
|
67
|
+
import fc from 'fast-check'
|
|
68
|
+
|
|
69
|
+
it('AC2-property: Model name is always gemini-3-pro-image-preview', () => {
|
|
70
|
+
fc.assert(
|
|
71
|
+
fc.property(fc.string(), (prompt) => {
|
|
72
|
+
const result = client.generate(prompt)
|
|
73
|
+
return result.model === 'gemini-3-pro-image-preview'
|
|
74
|
+
})
|
|
75
|
+
)
|
|
76
|
+
})
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
**Requirements**:
|
|
80
|
+
- Write in `fc.assert(fc.property(...))` format
|
|
81
|
+
- Reflect skeleton's `// fast-check:` comment directly in implementation
|
|
82
|
+
- When failure case discovered, add as concrete unit test (regression prevention)
|
|
83
|
+
|
|
84
|
+
### Behavior Verification Implementation
|
|
85
|
+
|
|
86
|
+
**Behavior Description Verification Levels**:
|
|
87
|
+
|
|
88
|
+
| Step Type | Verification Target | Example |
|
|
89
|
+
|-----------|--------------------| --------|
|
|
90
|
+
| Trigger | Reproduce in Arrange | API failure → mockResolvedValue({ ok: false }) |
|
|
91
|
+
| Process | Intermediate state or call | Function call, state change |
|
|
92
|
+
| Observable Result | Final output value | Return value, error message, log output |
|
|
93
|
+
|
|
94
|
+
**Pass Criteria**: Pass if "observable result" is verified as **return value or mock call argument** of test target
|
|
95
|
+
|
|
96
|
+
### Verification Item Determination Rules
|
|
97
|
+
|
|
98
|
+
| Skeleton State | Verification Item Determination Method |
|
|
99
|
+
|----------------|---------------------------------------|
|
|
100
|
+
| `// Verification items:` listed | Implement all listed items with expect |
|
|
101
|
+
| No `// Verification items:` | Derive from "observable result" in "Behavior" description |
|
|
102
|
+
| Both present | Prioritize verification items, use behavior as supplement |
|
|
103
|
+
|
|
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
|
+
### Integration Test Mock Boundaries
|
|
113
|
+
|
|
114
|
+
| Judgment Criteria | Mock | Actual |
|
|
115
|
+
|-------------------|------|--------|
|
|
116
|
+
| Part of test target? | No → Can mock | Yes → Actual required |
|
|
117
|
+
| Is call verification target of test? | No → Can mock | Yes → Actual or verifiable mock |
|
|
118
|
+
| External network communication? | Yes → Mock required | No → Actual recommended |
|
|
119
|
+
|
|
120
|
+
**Judgment Flow**:
|
|
121
|
+
1. External API (HTTP communication) → Mock required
|
|
122
|
+
2. Component interaction under test → Actual required
|
|
123
|
+
3. Log output verification needed → Use verifiable mock (vi.fn())
|
|
124
|
+
4. Log output verification not needed → Actual or ignore
|
|
125
|
+
|
|
126
|
+
### E2E Test Execution Conditions
|
|
127
|
+
|
|
128
|
+
- Execute only after all components are implemented
|
|
129
|
+
- Do not use mocks (`@dependency: full-system`)
|
|
130
|
+
|
|
131
|
+
## Review Criteria
|
|
132
|
+
|
|
133
|
+
### Skeleton and Implementation Consistency
|
|
134
|
+
|
|
135
|
+
| Check | Failure Condition |
|
|
136
|
+
|-------|-------------------|
|
|
137
|
+
| Property Verification | Property annotation exists but fast-check not used |
|
|
138
|
+
| Behavior Verification | No expect for "observable result" |
|
|
139
|
+
| Verification Item Coverage | Listed verification items not included in expect |
|
|
140
|
+
| Mock Boundary | Internal components mocked in integration test |
|
|
141
|
+
|
|
142
|
+
### Implementation Quality
|
|
143
|
+
|
|
144
|
+
| Check | Failure Condition |
|
|
145
|
+
|-------|-------------------|
|
|
146
|
+
| AAA Structure | Arrange/Act/Assert separation unclear |
|
|
147
|
+
| Independence | State sharing between tests, execution order dependency |
|
|
148
|
+
| Reproducibility | Depends on date/random, results vary |
|
|
149
|
+
| Readability | Test name and verification content don't match |
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# Project Context
|
|
2
|
+
|
|
3
|
+
## Basic Configuration
|
|
4
|
+
|
|
5
|
+
### Project Nature
|
|
6
|
+
- **Project Type**: Claude Code-specific TypeScript project template
|
|
7
|
+
- **Usage Scope**: Configurable according to project requirements
|
|
8
|
+
- **Implementation Policy**: LLM-driven implementation, quality-focused, strict YAGNI principle adherence
|
|
9
|
+
|
|
10
|
+
### Technology Stack
|
|
11
|
+
- **Foundation Technologies**: TypeScript, Node.js
|
|
12
|
+
- **Test Framework**: Vitest
|
|
13
|
+
- **Quality Management**: Biome, TypeScript strict mode
|
|
14
|
+
|
|
15
|
+
## Implementation Principles
|
|
16
|
+
|
|
17
|
+
### Implementation Policy Characteristics
|
|
18
|
+
- **LLM-Driven Implementation**: Claude Code functions as the primary implementer
|
|
19
|
+
- **Quality-First Culture**: Prioritize quality over speed
|
|
20
|
+
- **YAGNI Principle**: Don't implement until necessary
|
|
21
|
+
- **Systematic Design**: Design process through ADR/Design Doc/work plans
|
|
22
|
+
|
|
23
|
+
## Customization Guide
|
|
24
|
+
|
|
25
|
+
When using this template for new projects:
|
|
26
|
+
|
|
27
|
+
1. **Add Project-Specific Information**
|
|
28
|
+
- Target user characteristics
|
|
29
|
+
- Business requirements and constraints
|
|
30
|
+
- Technical constraint conditions
|
|
31
|
+
|
|
32
|
+
2. **Architecture Selection**
|
|
33
|
+
- Select appropriate patterns from `docs/rules/architecture/`
|
|
34
|
+
- Place project-specific designs in `docs/rules/architecture/`
|
|
35
|
+
|
|
36
|
+
3. **Environment Configuration**
|
|
37
|
+
- Implement environment variable management methods suitable for the project
|
|
38
|
+
- Add project-specific configuration files
|
|
@@ -0,0 +1,211 @@
|
|
|
1
|
+
# Metadata for each rule file
|
|
2
|
+
# Manages overview, tags, typical usage scenarios, and size for each rule
|
|
3
|
+
|
|
4
|
+
rules:
|
|
5
|
+
coding-standards:
|
|
6
|
+
file: "coding-standards.md"
|
|
7
|
+
tags: [universal, anti-patterns, refactoring, type-safety, testing, code-deletion, rule-of-three, fail-fast, impact-analysis]
|
|
8
|
+
typical-use: "Universal coding principles applicable across all domains, foundational standards for all developers"
|
|
9
|
+
size: large
|
|
10
|
+
key-references:
|
|
11
|
+
- "Rule of Three - Martin Fowler"
|
|
12
|
+
- "Single Responsibility Principle - Clean Code"
|
|
13
|
+
- "DRY Principle - The Pragmatic Programmer"
|
|
14
|
+
- "YAGNI Principle - Kent Beck"
|
|
15
|
+
- "5 Whys - Toyota Production System"
|
|
16
|
+
- "Red-Green-Refactor - Kent Beck"
|
|
17
|
+
- "AAA Pattern - Arrange-Act-Assert"
|
|
18
|
+
sections:
|
|
19
|
+
- "Technical Anti-patterns (Red Flag Patterns)"
|
|
20
|
+
- "Basic Principles"
|
|
21
|
+
- "Comment Writing Rules"
|
|
22
|
+
- "Error Handling Fundamentals"
|
|
23
|
+
- "Rule of Three - Criteria for Code Duplication"
|
|
24
|
+
- "Common Failure Patterns and Avoidance Methods"
|
|
25
|
+
- "Debugging Techniques"
|
|
26
|
+
- "Type Safety Fundamentals"
|
|
27
|
+
- "Refactoring Techniques"
|
|
28
|
+
- "Situations Requiring Technical Decisions"
|
|
29
|
+
- "Continuous Improvement Mindset"
|
|
30
|
+
- "Implementation Completeness Assurance"
|
|
31
|
+
- "Red-Green-Refactor Process (Test-First Development)"
|
|
32
|
+
- "Test Design Principles"
|
|
33
|
+
- "Test Helper Utilization Rules"
|
|
34
|
+
- "Test Granularity Principles"
|
|
35
|
+
- "Continuity Test Scope"
|
|
36
|
+
|
|
37
|
+
typescript:
|
|
38
|
+
file: "typescript.md"
|
|
39
|
+
tags: [implementation, type-safety, async, refactoring, coding-style, functional-programming, dependency-injection, branded-types, backend]
|
|
40
|
+
typical-use: "Backend TypeScript code creation, modification, refactoring, modern type features utilization"
|
|
41
|
+
size: small
|
|
42
|
+
key-references:
|
|
43
|
+
- "YAGNI Principle - Kent Beck"
|
|
44
|
+
- "Clean Code - Robert C. Martin"
|
|
45
|
+
- "DRY Principle - The Pragmatic Programmer"
|
|
46
|
+
- "Refactoring - Martin Fowler"
|
|
47
|
+
- "TypeScript 4.9 satisfies Operator - Microsoft"
|
|
48
|
+
- "Branded Types - TypeScript Community"
|
|
49
|
+
- "Effect-TS / fp-ts - Functional Programming"
|
|
50
|
+
- "Dependency Injection - Martin Fowler"
|
|
51
|
+
- "Avoiding fallback in distributed systems - AWS Builders' Library"
|
|
52
|
+
sections:
|
|
53
|
+
- "Type Safety in Backend Implementation"
|
|
54
|
+
- "Coding Conventions"
|
|
55
|
+
- "Error Handling"
|
|
56
|
+
- "Performance Optimization"
|
|
57
|
+
|
|
58
|
+
typescript-testing:
|
|
59
|
+
file: "typescript-testing.md"
|
|
60
|
+
tags: [quality, testing, tdd, coverage, vitest, implementation, debugging, refactoring, backend]
|
|
61
|
+
typical-use: "Backend test creation, quality checks, test quality criteria, development steps for code/bug fixes, refactoring, and new feature implementation"
|
|
62
|
+
size: small
|
|
63
|
+
key-references:
|
|
64
|
+
- "Test-Driven Development - Kent Beck"
|
|
65
|
+
- "Rule of Three - Martin Fowler"
|
|
66
|
+
- "Red-Green-Refactor - Kent Beck"
|
|
67
|
+
- "AAA Pattern - Arrange-Act-Assert"
|
|
68
|
+
sections:
|
|
69
|
+
- "Test Framework"
|
|
70
|
+
- "Basic Testing Policy"
|
|
71
|
+
- "Test Implementation Conventions"
|
|
72
|
+
- "Test Quality Criteria"
|
|
73
|
+
- "Mock Type Safety Enforcement"
|
|
74
|
+
- "Basic Vitest Example"
|
|
75
|
+
|
|
76
|
+
technical-spec:
|
|
77
|
+
file: "technical-spec.md"
|
|
78
|
+
tags: [architecture, design, documentation, environment, data-flow, implementation, quality-commands, testing, build]
|
|
79
|
+
typical-use: "Technical design, environment configuration, documentation creation process, implementation policy decisions, quality check commands, build and test execution"
|
|
80
|
+
size: medium
|
|
81
|
+
key-references:
|
|
82
|
+
- "ADR Format - Michael Nygard"
|
|
83
|
+
- "Single Data Source Principle - Single Source of Truth"
|
|
84
|
+
sections:
|
|
85
|
+
- "Basic Technology Stack Policy"
|
|
86
|
+
- "Environment Variable Management and Security"
|
|
87
|
+
- "Architecture Design"
|
|
88
|
+
- "Architecture Patterns"
|
|
89
|
+
- "Unified Data Flow Principles"
|
|
90
|
+
- "Build and Testing"
|
|
91
|
+
|
|
92
|
+
project-context:
|
|
93
|
+
file: "project-context.md"
|
|
94
|
+
tags: [context, project-specific, implementation]
|
|
95
|
+
typical-use: "Project-specific information, understanding implementation principles"
|
|
96
|
+
size: small
|
|
97
|
+
key-references:
|
|
98
|
+
- "Project-specific (empirical)"
|
|
99
|
+
sections:
|
|
100
|
+
- "Basic Configuration"
|
|
101
|
+
- "Implementation Principles"
|
|
102
|
+
- "Customization Guide"
|
|
103
|
+
|
|
104
|
+
documentation-criteria:
|
|
105
|
+
file: "documentation-criteria.md"
|
|
106
|
+
tags: [documentation, adr, prd, design-doc, work-plan, decision-matrix]
|
|
107
|
+
typical-use: "Implementation start scale assessment, document creation decisions, ADR/PRD/Design Doc/work plan creation criteria"
|
|
108
|
+
size: medium
|
|
109
|
+
key-references:
|
|
110
|
+
- "ADR Methodology - Michael Nygard"
|
|
111
|
+
- "Design Doc Culture - Google Engineering Practices"
|
|
112
|
+
- "Single Source of Truth"
|
|
113
|
+
sections:
|
|
114
|
+
- "Creation Decision Matrix"
|
|
115
|
+
- "ADR Creation Conditions (Required if Any Apply)"
|
|
116
|
+
- "Detailed Document Definitions"
|
|
117
|
+
- "Creation Process"
|
|
118
|
+
- "Storage Locations"
|
|
119
|
+
- "ADR Status"
|
|
120
|
+
- "AI Automation Rules"
|
|
121
|
+
- "Diagram Requirements"
|
|
122
|
+
- "Common ADR Relationships"
|
|
123
|
+
|
|
124
|
+
implementation-approach:
|
|
125
|
+
file: "architecture/implementation-approach.md"
|
|
126
|
+
tags: [architecture, implementation, task-decomposition, strategy-patterns, strangler-pattern, facade-pattern, design, planning, confirmation-levels]
|
|
127
|
+
typical-use: "Implementation strategy selection, task decomposition, design decisions, large-scale change planning"
|
|
128
|
+
size: medium
|
|
129
|
+
key-references:
|
|
130
|
+
- "Strangler Fig Pattern - Martin Fowler"
|
|
131
|
+
- "Feature Slicing - Martin Fowler"
|
|
132
|
+
- "Walking Skeleton - Alistair Cockburn"
|
|
133
|
+
- "Facade Pattern - Gang of Four"
|
|
134
|
+
sections:
|
|
135
|
+
- "Meta-cognitive Strategy Selection Process"
|
|
136
|
+
- "Verification Level Definitions"
|
|
137
|
+
- "Integration Point Definitions"
|
|
138
|
+
- "Anti-patterns"
|
|
139
|
+
- "Guidelines for Meta-cognitive Execution"
|
|
140
|
+
|
|
141
|
+
integration-e2e-testing:
|
|
142
|
+
file: "integration-e2e-testing.md"
|
|
143
|
+
tags: [testing, integration-test, e2e-test, property-based-testing, fast-check, test-skeleton, test-review, quality]
|
|
144
|
+
typical-use: "Integration and E2E test skeleton generation, test implementation, test review, Property-Based Test implementation"
|
|
145
|
+
size: small
|
|
146
|
+
key-references:
|
|
147
|
+
- "fast-check - Property-based testing for TypeScript"
|
|
148
|
+
- "Node.js Testing Best Practices - Yoni Goldberg"
|
|
149
|
+
- "Property-Based Testing - 2025 Practices"
|
|
150
|
+
sections:
|
|
151
|
+
- "Test Types and Limits"
|
|
152
|
+
- "Behavior-First Principle"
|
|
153
|
+
- "Skeleton Specification"
|
|
154
|
+
- "Implementation Rules"
|
|
155
|
+
- "Review Criteria"
|
|
156
|
+
|
|
157
|
+
# Frontend-specific Rules
|
|
158
|
+
frontend-typescript:
|
|
159
|
+
file: "frontend/typescript.md"
|
|
160
|
+
tags: [frontend, react, implementation, type-safety, function-components, props-driven, async, refactoring, coding-style]
|
|
161
|
+
typical-use: "React component creation, Props type definitions, frontend TypeScript development"
|
|
162
|
+
size: small
|
|
163
|
+
key-references:
|
|
164
|
+
- "React Function Components - React Official"
|
|
165
|
+
- "Props-driven Design - React Best Practices"
|
|
166
|
+
- "YAGNI Principle - Kent Beck"
|
|
167
|
+
- "Clean Code - Robert C. Martin"
|
|
168
|
+
- "TypeScript satisfies Operator - Microsoft"
|
|
169
|
+
sections:
|
|
170
|
+
- "Frontend-Specific Anti-patterns"
|
|
171
|
+
- "Type Safety in Frontend Implementation"
|
|
172
|
+
- "Coding Conventions"
|
|
173
|
+
- "Error Handling"
|
|
174
|
+
- "Performance Optimization"
|
|
175
|
+
|
|
176
|
+
frontend-typescript-testing:
|
|
177
|
+
file: "frontend/typescript-testing.md"
|
|
178
|
+
tags: [frontend, react, quality, testing, tdd, coverage, vitest, react-testing-library, msw, implementation]
|
|
179
|
+
typical-use: "React component testing, React Testing Library tests, MSW API mocking, frontend test creation"
|
|
180
|
+
size: small
|
|
181
|
+
key-references:
|
|
182
|
+
- "React Testing Library - Kent C. Dodds"
|
|
183
|
+
- "MSW (Mock Service Worker) - MSW Team"
|
|
184
|
+
- "Test-Driven Development - Kent Beck"
|
|
185
|
+
- "Red-Green-Refactor - Kent Beck"
|
|
186
|
+
- "User-Observable Behavior Testing - Testing Library"
|
|
187
|
+
sections:
|
|
188
|
+
- "Test Framework"
|
|
189
|
+
- "Basic Testing Policy"
|
|
190
|
+
- "Test Implementation Conventions"
|
|
191
|
+
- "Mock Type Safety Enforcement"
|
|
192
|
+
- "Basic React Testing Library Example"
|
|
193
|
+
|
|
194
|
+
frontend-technical-spec:
|
|
195
|
+
file: "frontend/technical-spec.md"
|
|
196
|
+
tags: [frontend, react, vite, architecture, design, environment, data-flow, implementation, performance]
|
|
197
|
+
typical-use: "React technical design, Vite configuration, frontend environment setup, component architecture decisions"
|
|
198
|
+
size: medium
|
|
199
|
+
key-references:
|
|
200
|
+
- "React Official Documentation"
|
|
201
|
+
- "Build Tool Best Practices"
|
|
202
|
+
- "Single Source of Truth"
|
|
203
|
+
sections:
|
|
204
|
+
- "Basic Technology Stack Policy"
|
|
205
|
+
- "Environment Variable Management and Security"
|
|
206
|
+
- "Architecture Design"
|
|
207
|
+
- "Unified Data Flow Principles"
|
|
208
|
+
- "Build and Testing"
|
|
209
|
+
- "Quality Check Requirements"
|
|
210
|
+
- "Coverage Requirements"
|
|
211
|
+
- "Non-functional Requirements"
|