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.
Files changed (150) hide show
  1. package/.claude/agents/acceptance-test-generator.md +316 -0
  2. package/.claude/agents/code-reviewer.md +193 -0
  3. package/.claude/agents/document-reviewer.md +182 -0
  4. package/.claude/agents/prd-creator.md +186 -0
  5. package/.claude/agents/quality-fixer.md +295 -0
  6. package/.claude/agents/requirement-analyzer.md +161 -0
  7. package/.claude/agents/rule-advisor.md +194 -0
  8. package/.claude/agents/task-decomposer.md +291 -0
  9. package/.claude/agents/task-executor.md +270 -0
  10. package/.claude/agents/technical-designer.md +343 -0
  11. package/.claude/agents/work-planner.md +181 -0
  12. package/.claude/agents-en/acceptance-test-generator.md +256 -0
  13. package/.claude/agents-en/code-reviewer.md +195 -0
  14. package/.claude/agents-en/design-sync.md +225 -0
  15. package/.claude/agents-en/document-reviewer.md +190 -0
  16. package/.claude/agents-en/integration-test-reviewer.md +195 -0
  17. package/.claude/agents-en/prd-creator.md +196 -0
  18. package/.claude/agents-en/quality-fixer-frontend.md +334 -0
  19. package/.claude/agents-en/quality-fixer.md +291 -0
  20. package/.claude/agents-en/requirement-analyzer.md +165 -0
  21. package/.claude/agents-en/rule-advisor.md +194 -0
  22. package/.claude/agents-en/task-decomposer.md +291 -0
  23. package/.claude/agents-en/task-executor-frontend.md +276 -0
  24. package/.claude/agents-en/task-executor.md +272 -0
  25. package/.claude/agents-en/technical-designer-frontend.md +441 -0
  26. package/.claude/agents-en/technical-designer.md +371 -0
  27. package/.claude/agents-en/work-planner.md +216 -0
  28. package/.claude/agents-ja/acceptance-test-generator.md +256 -0
  29. package/.claude/agents-ja/code-reviewer.md +195 -0
  30. package/.claude/agents-ja/design-sync.md +225 -0
  31. package/.claude/agents-ja/document-reviewer.md +192 -0
  32. package/.claude/agents-ja/integration-test-reviewer.md +195 -0
  33. package/.claude/agents-ja/prd-creator.md +194 -0
  34. package/.claude/agents-ja/quality-fixer-frontend.md +335 -0
  35. package/.claude/agents-ja/quality-fixer.md +292 -0
  36. package/.claude/agents-ja/requirement-analyzer.md +164 -0
  37. package/.claude/agents-ja/rule-advisor.md +194 -0
  38. package/.claude/agents-ja/task-decomposer.md +291 -0
  39. package/.claude/agents-ja/task-executor-frontend.md +276 -0
  40. package/.claude/agents-ja/task-executor.md +272 -0
  41. package/.claude/agents-ja/technical-designer-frontend.md +442 -0
  42. package/.claude/agents-ja/technical-designer.md +370 -0
  43. package/.claude/agents-ja/work-planner.md +213 -0
  44. package/.claude/commands/build.md +78 -0
  45. package/.claude/commands/design.md +27 -0
  46. package/.claude/commands/implement.md +79 -0
  47. package/.claude/commands/plan.md +43 -0
  48. package/.claude/commands/project-inject.md +76 -0
  49. package/.claude/commands/refine-rule.md +206 -0
  50. package/.claude/commands/review.md +78 -0
  51. package/.claude/commands/sync-rules.md +116 -0
  52. package/.claude/commands/task.md +13 -0
  53. package/.claude/commands-en/build.md +77 -0
  54. package/.claude/commands-en/design.md +39 -0
  55. package/.claude/commands-en/front-build.md +103 -0
  56. package/.claude/commands-en/front-design.md +42 -0
  57. package/.claude/commands-en/front-plan.md +40 -0
  58. package/.claude/commands-en/implement.md +75 -0
  59. package/.claude/commands-en/plan.md +45 -0
  60. package/.claude/commands-en/project-inject.md +76 -0
  61. package/.claude/commands-en/refine-rule.md +208 -0
  62. package/.claude/commands-en/review.md +78 -0
  63. package/.claude/commands-en/sync-rules.md +116 -0
  64. package/.claude/commands-en/task.md +13 -0
  65. package/.claude/commands-ja/build.md +75 -0
  66. package/.claude/commands-ja/design.md +37 -0
  67. package/.claude/commands-ja/front-build.md +103 -0
  68. package/.claude/commands-ja/front-design.md +42 -0
  69. package/.claude/commands-ja/front-plan.md +40 -0
  70. package/.claude/commands-ja/implement.md +73 -0
  71. package/.claude/commands-ja/plan.md +43 -0
  72. package/.claude/commands-ja/project-inject.md +76 -0
  73. package/.claude/commands-ja/refine-rule.md +206 -0
  74. package/.claude/commands-ja/review.md +78 -0
  75. package/.claude/commands-ja/sync-rules.md +116 -0
  76. package/.claude/commands-ja/task.md +13 -0
  77. package/.claude/settings.local.json +74 -0
  78. package/.husky/pre-commit +1 -0
  79. package/.husky/pre-push +3 -0
  80. package/.madgerc +14 -0
  81. package/.tsprunerc +11 -0
  82. package/CLAUDE.en.md +102 -0
  83. package/CLAUDE.ja.md +102 -0
  84. package/CLAUDE.md +111 -0
  85. package/LICENSE +21 -0
  86. package/README.ja.md +233 -0
  87. package/README.md +243 -0
  88. package/bin/create-project.js +87 -0
  89. package/biome.json +51 -0
  90. package/docs/adr/template-en.md +64 -0
  91. package/docs/adr/template-ja.md +64 -0
  92. package/docs/design/template-en.md +281 -0
  93. package/docs/design/template-ja.md +285 -0
  94. package/docs/guides/en/quickstart.md +111 -0
  95. package/docs/guides/en/rule-editing-guide.md +266 -0
  96. package/docs/guides/en/sub-agents.md +343 -0
  97. package/docs/guides/en/use-cases.md +308 -0
  98. package/docs/guides/ja/quickstart.md +112 -0
  99. package/docs/guides/ja/rule-editing-guide.md +266 -0
  100. package/docs/guides/ja/sub-agents.md +343 -0
  101. package/docs/guides/ja/use-cases.md +290 -0
  102. package/docs/guides/sub-agents.md +306 -0
  103. package/docs/plans/20250123-integration-test-improvement.md +993 -0
  104. package/docs/plans/template-en.md +130 -0
  105. package/docs/plans/template-ja.md +130 -0
  106. package/docs/prd/template-en.md +109 -0
  107. package/docs/prd/template-ja.md +109 -0
  108. package/docs/rules/ai-development-guide.md +260 -0
  109. package/docs/rules/architecture/implementation-approach.md +136 -0
  110. package/docs/rules/documentation-criteria.md +180 -0
  111. package/docs/rules/project-context.md +38 -0
  112. package/docs/rules/rules-index.yaml +137 -0
  113. package/docs/rules/technical-spec.md +47 -0
  114. package/docs/rules/typescript-testing.md +188 -0
  115. package/docs/rules/typescript.md +166 -0
  116. package/docs/rules-en/architecture/implementation-approach.md +136 -0
  117. package/docs/rules-en/coding-standards.md +333 -0
  118. package/docs/rules-en/documentation-criteria.md +184 -0
  119. package/docs/rules-en/frontend/technical-spec.md +143 -0
  120. package/docs/rules-en/frontend/typescript-testing.md +124 -0
  121. package/docs/rules-en/frontend/typescript.md +131 -0
  122. package/docs/rules-en/integration-e2e-testing.md +149 -0
  123. package/docs/rules-en/project-context.md +38 -0
  124. package/docs/rules-en/rules-index.yaml +211 -0
  125. package/docs/rules-en/technical-spec.md +86 -0
  126. package/docs/rules-en/typescript-testing.md +149 -0
  127. package/docs/rules-en/typescript.md +116 -0
  128. package/docs/rules-ja/architecture/implementation-approach.md +136 -0
  129. package/docs/rules-ja/coding-standards.md +333 -0
  130. package/docs/rules-ja/documentation-criteria.md +180 -0
  131. package/docs/rules-ja/frontend/technical-spec.md +143 -0
  132. package/docs/rules-ja/frontend/typescript-testing.md +124 -0
  133. package/docs/rules-ja/frontend/typescript.md +131 -0
  134. package/docs/rules-ja/integration-e2e-testing.md +149 -0
  135. package/docs/rules-ja/project-context.md +38 -0
  136. package/docs/rules-ja/rules-index.yaml +196 -0
  137. package/docs/rules-ja/technical-spec.md +86 -0
  138. package/docs/rules-ja/typescript-testing.md +149 -0
  139. package/docs/rules-ja/typescript.md +116 -0
  140. package/package.json +98 -0
  141. package/scripts/check-unused-exports.js +69 -0
  142. package/scripts/cleanup-test-processes.sh +32 -0
  143. package/scripts/post-setup.js +110 -0
  144. package/scripts/set-language.js +310 -0
  145. package/scripts/setup-project.js +199 -0
  146. package/scripts/show-coverage.js +74 -0
  147. package/src/index.ts +11 -0
  148. package/templates/.gitignore.template +52 -0
  149. package/tsconfig.json +50 -0
  150. 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"