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,333 @@
|
|
|
1
|
+
# Universal Coding Standards
|
|
2
|
+
|
|
3
|
+
## Technical Anti-patterns (Red Flag Patterns)
|
|
4
|
+
|
|
5
|
+
Immediately stop and reconsider design when detecting the following patterns:
|
|
6
|
+
|
|
7
|
+
### Code Quality Anti-patterns
|
|
8
|
+
1. **Writing similar code 3 or more times** - Violates Rule of Three
|
|
9
|
+
2. **Multiple responsibilities mixed in a single file** - Violates Single Responsibility Principle (SRP)
|
|
10
|
+
3. **Defining same content in multiple files** - Violates DRY principle
|
|
11
|
+
4. **Making changes without checking dependencies** - Potential for unexpected impacts
|
|
12
|
+
5. **Disabling code with comments** - Should use version control
|
|
13
|
+
6. **Error suppression** - Hiding problems creates technical debt
|
|
14
|
+
7. **Excessive use of type assertions (as)** - Abandoning type safety
|
|
15
|
+
|
|
16
|
+
### Design Anti-patterns
|
|
17
|
+
- **"Make it work for now" thinking** - Accumulation of technical debt
|
|
18
|
+
- **Patchwork implementation** - Unplanned additions to existing code
|
|
19
|
+
- **Optimistic implementation of uncertain technology** - Designing unknown elements assuming "it'll probably work"
|
|
20
|
+
- **Symptomatic fixes** - Surface-level fixes that don't solve root causes
|
|
21
|
+
- **Unplanned large-scale changes** - Lack of incremental approach
|
|
22
|
+
|
|
23
|
+
## Basic Principles
|
|
24
|
+
|
|
25
|
+
✅ **Aggressive Refactoring** - Prevent technical debt and maintain health
|
|
26
|
+
❌ **Unused "Just in Case" Code** - Violates YAGNI principle (Kent Beck)
|
|
27
|
+
|
|
28
|
+
## Comment Writing Rules
|
|
29
|
+
|
|
30
|
+
- **Function Description Focus**: Describe what the code "does"
|
|
31
|
+
- **No Historical Information**: Do not record development history
|
|
32
|
+
- **Timeless**: Write only content that remains valid whenever read
|
|
33
|
+
- **Conciseness**: Keep explanations to necessary minimum
|
|
34
|
+
|
|
35
|
+
## Error Handling Fundamentals
|
|
36
|
+
|
|
37
|
+
### Fail-Fast Principle
|
|
38
|
+
Fail quickly on errors to prevent processing continuation in invalid states. Error suppression is prohibited.
|
|
39
|
+
|
|
40
|
+
For detailed implementation methods (Result type, custom error classes, layered error handling, etc.), refer to language and framework-specific rules.
|
|
41
|
+
|
|
42
|
+
## Rule of Three - Criteria for Code Duplication
|
|
43
|
+
|
|
44
|
+
How to handle duplicate code based on Martin Fowler's "Refactoring":
|
|
45
|
+
|
|
46
|
+
| Duplication Count | Action | Reason |
|
|
47
|
+
|-------------------|--------|--------|
|
|
48
|
+
| 1st time | Inline implementation | Cannot predict future changes |
|
|
49
|
+
| 2nd time | Consider future consolidation | Pattern beginning to emerge |
|
|
50
|
+
| 3rd time | Implement commonalization | Pattern established |
|
|
51
|
+
|
|
52
|
+
### Criteria for Commonalization
|
|
53
|
+
|
|
54
|
+
**Cases for Commonalization**
|
|
55
|
+
- Business logic duplication
|
|
56
|
+
- Complex processing algorithms
|
|
57
|
+
- Areas likely requiring bulk changes
|
|
58
|
+
- Validation rules
|
|
59
|
+
|
|
60
|
+
**Cases to Avoid Commonalization**
|
|
61
|
+
- Accidental matches (coincidentally same code)
|
|
62
|
+
- Possibility of evolving in different directions
|
|
63
|
+
- Significant readability decrease from commonalization
|
|
64
|
+
- Simple helpers in test code
|
|
65
|
+
|
|
66
|
+
### Implementation Example
|
|
67
|
+
```typescript
|
|
68
|
+
// ❌ Immediate commonalization on 1st duplication
|
|
69
|
+
function validateUserEmail(email: string) { /* ... */ }
|
|
70
|
+
function validateContactEmail(email: string) { /* ... */ }
|
|
71
|
+
|
|
72
|
+
// ✅ Commonalize on 3rd occurrence
|
|
73
|
+
function validateEmail(email: string, context: 'user' | 'contact' | 'admin') { /* ... */ }
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
## Common Failure Patterns and Avoidance Methods
|
|
77
|
+
|
|
78
|
+
### Pattern 1: Error Fix Chain
|
|
79
|
+
**Symptom**: Fixing one error causes new errors
|
|
80
|
+
**Cause**: Surface-level fixes without understanding root cause
|
|
81
|
+
**Avoidance**: Identify root cause with 5 Whys before fixing
|
|
82
|
+
|
|
83
|
+
### Pattern 2: Abandoning Type Safety
|
|
84
|
+
**Symptom**: Excessive use of any type or as
|
|
85
|
+
**Cause**: Impulse to avoid type errors
|
|
86
|
+
**Avoidance**: Handle safely with unknown type and type guards
|
|
87
|
+
|
|
88
|
+
### Pattern 3: Implementation Without Sufficient Testing
|
|
89
|
+
**Symptom**: Many bugs after implementation
|
|
90
|
+
**Cause**: Ignoring Red-Green-Refactor process
|
|
91
|
+
**Avoidance**: Always start with failing tests
|
|
92
|
+
|
|
93
|
+
### Pattern 4: Ignoring Technical Uncertainty
|
|
94
|
+
**Symptom**: Frequent unexpected errors when introducing new technology
|
|
95
|
+
**Cause**: Assuming "it should work according to official documentation" without prior investigation
|
|
96
|
+
**Avoidance**:
|
|
97
|
+
- Record certainty evaluation at the beginning of task files
|
|
98
|
+
```
|
|
99
|
+
Certainty: low (Reason: no examples of MCP connection found)
|
|
100
|
+
Exploratory implementation: true
|
|
101
|
+
Fallback: use conventional API
|
|
102
|
+
```
|
|
103
|
+
- For low certainty cases, create minimal verification code first
|
|
104
|
+
|
|
105
|
+
### Pattern 5: Insufficient Existing Code Investigation
|
|
106
|
+
**Symptom**: Duplicate implementations, architecture inconsistency, integration failures
|
|
107
|
+
**Cause**: Insufficient understanding of existing code before implementation
|
|
108
|
+
**Avoidance Methods**:
|
|
109
|
+
- Before implementation, always search for similar functionality (using domain, responsibility, configuration patterns as keywords)
|
|
110
|
+
- Similar functionality found → Use that implementation (do not create new implementation)
|
|
111
|
+
- Similar functionality is technical debt → Create ADR improvement proposal before implementation
|
|
112
|
+
- No similar functionality exists → Implement new functionality following existing design philosophy
|
|
113
|
+
- Record all decisions and rationale in "Existing Codebase Analysis" section of Design Doc
|
|
114
|
+
|
|
115
|
+
## Debugging Techniques
|
|
116
|
+
|
|
117
|
+
### 1. Error Analysis Procedure
|
|
118
|
+
1. Read error message (first line) accurately
|
|
119
|
+
2. Focus on first and last of stack trace
|
|
120
|
+
3. Identify first line where your code appears
|
|
121
|
+
|
|
122
|
+
### 2. 5 Whys - Root Cause Analysis
|
|
123
|
+
```
|
|
124
|
+
Symptom: Build error
|
|
125
|
+
Why1: Type definitions don't match → Why2: Interface was updated
|
|
126
|
+
Why3: Dependency change → Why4: Package update impact
|
|
127
|
+
Why5: Major version upgrade with breaking changes
|
|
128
|
+
Root cause: Inappropriate version specification
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
### 3. Minimal Reproduction Code
|
|
132
|
+
To isolate problems, attempt reproduction with minimal code:
|
|
133
|
+
- Remove unrelated parts
|
|
134
|
+
- Replace external dependencies with mocks
|
|
135
|
+
- Create minimal configuration that reproduces problem
|
|
136
|
+
|
|
137
|
+
### 4. Debug Log Output
|
|
138
|
+
```typescript
|
|
139
|
+
console.log('DEBUG:', {
|
|
140
|
+
context: 'operation-name',
|
|
141
|
+
input: { /* relevant data */ },
|
|
142
|
+
state: currentState,
|
|
143
|
+
timestamp: new Date().toISOString()
|
|
144
|
+
})
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
## Type Safety Fundamentals
|
|
148
|
+
|
|
149
|
+
**Type Safety Principle**: Use `unknown` type with type guards. `any` type disables type checking and causes runtime errors.
|
|
150
|
+
|
|
151
|
+
**any Type Alternatives (Priority Order)**
|
|
152
|
+
1. **unknown Type + Type Guards**: Use for validating external input
|
|
153
|
+
2. **Generics**: When type flexibility is needed
|
|
154
|
+
3. **Union Types・Intersection Types**: Combinations of multiple types
|
|
155
|
+
4. **Type Assertions (Last Resort)**: Only when type is certain
|
|
156
|
+
|
|
157
|
+
**Type Guard Implementation Pattern**
|
|
158
|
+
```typescript
|
|
159
|
+
function isUser(value: unknown): value is User {
|
|
160
|
+
return typeof value === 'object' && value !== null && 'id' in value && 'name' in value
|
|
161
|
+
}
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
**Modern Type Features**
|
|
165
|
+
- **satisfies Operator**: `const config = { port: 3000 } satisfies Config` - Preserves inference
|
|
166
|
+
- **const Assertion**: `const ROUTES = { HOME: '/' } as const satisfies Routes` - Immutable and type-safe
|
|
167
|
+
- **Branded Types**: `type UserId = string & { __brand: 'UserId' }` - Distinguish meaning
|
|
168
|
+
- **Template Literal Types**: `type Endpoint = \`\${HttpMethod} \${Route}\`` - Express string patterns with types
|
|
169
|
+
|
|
170
|
+
**Type Complexity Management**
|
|
171
|
+
- Field Count: Up to 20 (split by responsibility if exceeded, external API types are exceptions)
|
|
172
|
+
- Optional Ratio: Up to 30% (separate required/optional if exceeded)
|
|
173
|
+
- Nesting Depth: Up to 3 levels (flatten if exceeded)
|
|
174
|
+
- Type Assertions: Review design if used 3+ times
|
|
175
|
+
- **External API Types**: Relax constraints and define according to reality (convert appropriately internally)
|
|
176
|
+
|
|
177
|
+
## Refactoring Techniques
|
|
178
|
+
|
|
179
|
+
**Basic Policy**
|
|
180
|
+
- Small Steps: Maintain always-working state through gradual improvements
|
|
181
|
+
- Safe Changes: Minimize the scope of changes at once
|
|
182
|
+
- Behavior Guarantee: Ensure existing behavior remains unchanged while proceeding
|
|
183
|
+
|
|
184
|
+
**Implementation Procedure**: Understand Current State → Gradual Changes → Behavior Verification → Final Validation
|
|
185
|
+
|
|
186
|
+
**Priority**: Duplicate Code Removal > Large Function Division > Complex Conditional Branch Simplification > Type Safety Improvement
|
|
187
|
+
|
|
188
|
+
## Situations Requiring Technical Decisions
|
|
189
|
+
|
|
190
|
+
### Timing of Abstraction
|
|
191
|
+
- Extract patterns after writing concrete implementation 3 times
|
|
192
|
+
- Be conscious of YAGNI, implement only currently needed features
|
|
193
|
+
- Prioritize current simplicity over future extensibility
|
|
194
|
+
|
|
195
|
+
### Performance vs Readability
|
|
196
|
+
- Prioritize readability unless clear bottleneck exists
|
|
197
|
+
- Measure before optimizing (don't guess, measure)
|
|
198
|
+
- Document reason with comments when optimizing
|
|
199
|
+
|
|
200
|
+
### Granularity of Type Definitions
|
|
201
|
+
- Overly detailed types reduce maintainability
|
|
202
|
+
- Design types that appropriately express domain
|
|
203
|
+
- Use utility types to reduce duplication
|
|
204
|
+
|
|
205
|
+
## Continuous Improvement Mindset
|
|
206
|
+
|
|
207
|
+
- **Humility**: Perfect code doesn't exist, welcome feedback
|
|
208
|
+
- **Courage**: Execute necessary refactoring boldly
|
|
209
|
+
- **Transparency**: Clearly document technical decision reasoning
|
|
210
|
+
|
|
211
|
+
## Implementation Completeness Assurance
|
|
212
|
+
|
|
213
|
+
### Required Procedure for Impact Analysis
|
|
214
|
+
|
|
215
|
+
**Completion Criteria**: Complete all 3 stages
|
|
216
|
+
|
|
217
|
+
#### 1. Discovery
|
|
218
|
+
```bash
|
|
219
|
+
Grep -n "TargetClass\|TargetMethod" -o content
|
|
220
|
+
Grep -n "DependencyClass" -o content
|
|
221
|
+
Grep -n "targetData\|SetData\|UpdateData" -o content
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
#### 2. Understanding
|
|
225
|
+
**Mandatory**: Read all discovered files and include necessary parts in context:
|
|
226
|
+
- Caller's purpose and context
|
|
227
|
+
- Dependency direction
|
|
228
|
+
- Data flow: generation → modification → reference
|
|
229
|
+
|
|
230
|
+
#### 3. Identification
|
|
231
|
+
Structured impact report (mandatory):
|
|
232
|
+
```
|
|
233
|
+
## Impact Analysis
|
|
234
|
+
### Direct Impact: ClassA, ClassB (with reasons)
|
|
235
|
+
### Indirect Impact: SystemX, ComponentY (with integration paths)
|
|
236
|
+
### Processing Flow: Input → Process1 → Process2 → Output
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
**Important**: Do not stop at search; execute all 3 stages
|
|
240
|
+
|
|
241
|
+
### Unused Code Deletion Rule
|
|
242
|
+
|
|
243
|
+
When unused code is detected → Will it be used?
|
|
244
|
+
- Yes → Implement immediately (no deferral allowed)
|
|
245
|
+
- No → Delete immediately (remains in Git history)
|
|
246
|
+
|
|
247
|
+
Target: Code, documentation, configuration files
|
|
248
|
+
|
|
249
|
+
### Existing Code Deletion Decision Flow
|
|
250
|
+
|
|
251
|
+
```
|
|
252
|
+
In use? No → Delete immediately (remains in Git history)
|
|
253
|
+
Yes → Working? No → Delete + Reimplement
|
|
254
|
+
Yes → Fix
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
## Red-Green-Refactor Process (Test-First Development)
|
|
258
|
+
|
|
259
|
+
**Recommended Principle**: Always start code changes with tests
|
|
260
|
+
|
|
261
|
+
**Background**:
|
|
262
|
+
- Ensure behavior before changes, prevent regression
|
|
263
|
+
- Clarify expected behavior before implementation
|
|
264
|
+
- Ensure safety during refactoring
|
|
265
|
+
|
|
266
|
+
**Development Steps**:
|
|
267
|
+
1. **Red**: Write test for expected behavior (it fails)
|
|
268
|
+
2. **Green**: Pass test with minimal implementation
|
|
269
|
+
3. **Refactor**: Improve code while maintaining passing tests
|
|
270
|
+
|
|
271
|
+
**NG Cases (Test-first not required)**:
|
|
272
|
+
- Pure configuration file changes (.env, config, etc.)
|
|
273
|
+
- Documentation-only updates (README, comments, etc.)
|
|
274
|
+
- Emergency production incident response (post-incident tests mandatory)
|
|
275
|
+
|
|
276
|
+
## Test Design Principles
|
|
277
|
+
|
|
278
|
+
### Test Case Structure
|
|
279
|
+
- Tests consist of three stages: "Arrange," "Act," "Assert"
|
|
280
|
+
- Clear naming that shows purpose of each test
|
|
281
|
+
- One test case verifies only one behavior
|
|
282
|
+
|
|
283
|
+
### Test Data Management
|
|
284
|
+
- Manage test data in dedicated directories
|
|
285
|
+
- Define test-specific environment variable values
|
|
286
|
+
- Always mock sensitive information
|
|
287
|
+
- Keep test data minimal, using only data directly related to test case verification purposes
|
|
288
|
+
|
|
289
|
+
### Mock and Stub Usage Policy
|
|
290
|
+
|
|
291
|
+
✅ **Recommended: Mock external dependencies in unit tests**
|
|
292
|
+
- Merit: Ensures test independence and reproducibility
|
|
293
|
+
- Practice: Mock DB, API, file system, and other external dependencies
|
|
294
|
+
|
|
295
|
+
❌ **Avoid: Actual external connections in unit tests**
|
|
296
|
+
- Reason: Slows test speed and causes environment-dependent problems
|
|
297
|
+
|
|
298
|
+
### Test Failure Response Decision Criteria
|
|
299
|
+
|
|
300
|
+
**Fix tests**: Wrong expected values, references to non-existent features, dependence on implementation details, implementation only for tests
|
|
301
|
+
**Fix implementation**: Valid specifications, business logic, important edge cases
|
|
302
|
+
**When in doubt**: Confirm with user
|
|
303
|
+
|
|
304
|
+
## Test Helper Utilization Rules
|
|
305
|
+
|
|
306
|
+
### Basic Principles
|
|
307
|
+
Use test helpers to reduce duplication and improve maintainability.
|
|
308
|
+
|
|
309
|
+
### Decision Criteria
|
|
310
|
+
| Mock Characteristics | Response Policy |
|
|
311
|
+
|---------------------|-----------------|
|
|
312
|
+
| **Simple and stable** | Consolidate in common helpers |
|
|
313
|
+
| **Complex or frequently changing** | Individual implementation |
|
|
314
|
+
| **Duplicated in 3+ places** | Consider consolidation |
|
|
315
|
+
| **Test-specific logic** | Individual implementation |
|
|
316
|
+
|
|
317
|
+
## Test Granularity Principles
|
|
318
|
+
|
|
319
|
+
### Core Principle: Observable Behavior Only
|
|
320
|
+
**MUST Test**: Public APIs, return values, exceptions, external calls, persisted state
|
|
321
|
+
**MUST NOT Test**: Private methods, internal state, algorithm implementation details
|
|
322
|
+
|
|
323
|
+
```typescript
|
|
324
|
+
// ✅ Test observable behavior
|
|
325
|
+
expect(calculateTotal(100, 0.1)).toBe(110)
|
|
326
|
+
|
|
327
|
+
// ❌ Test implementation details
|
|
328
|
+
expect((calculator as any).internalState).toBe(someValue)
|
|
329
|
+
```
|
|
330
|
+
|
|
331
|
+
## Continuity Test Scope
|
|
332
|
+
|
|
333
|
+
Limited to verifying existing feature impact when adding new features. Long-term operations and load testing are infrastructure responsibilities, not test scope.
|
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
# Documentation Creation Criteria
|
|
2
|
+
|
|
3
|
+
## Creation Decision Matrix
|
|
4
|
+
|
|
5
|
+
| Condition | Required Documents | Creation Order |
|
|
6
|
+
|-----------|-------------------|----------------|
|
|
7
|
+
| New Feature Addition | PRD → [ADR] → Design Doc → Work Plan | After PRD approval |
|
|
8
|
+
| ADR Conditions Met (see below) | ADR → Design Doc → Work Plan | Start immediately |
|
|
9
|
+
| 6+ Files | ADR → Design Doc → Work Plan (Required) | Start immediately |
|
|
10
|
+
| 3-5 Files | Design Doc → Work Plan (Recommended) | Start immediately |
|
|
11
|
+
| 1-2 Files | None | Direct implementation |
|
|
12
|
+
|
|
13
|
+
## ADR Creation Conditions (Required if Any Apply)
|
|
14
|
+
|
|
15
|
+
### 1. Type System Changes
|
|
16
|
+
- **Adding nested types with 3+ levels**: `type A = { b: { c: { d: T } } }`
|
|
17
|
+
- Rationale: Deep nesting has high complexity and wide impact scope
|
|
18
|
+
- **Changing/deleting types used in 3+ locations**
|
|
19
|
+
- Rationale: Multiple location impacts require careful consideration
|
|
20
|
+
- **Type responsibility changes** (e.g., DTO→Entity)
|
|
21
|
+
- Rationale: Conceptual model changes affect design philosophy
|
|
22
|
+
|
|
23
|
+
### 2. Data Flow Changes
|
|
24
|
+
- **Storage location changes** (DB→File, Memory→Cache)
|
|
25
|
+
- **Processing order changes with 3+ steps**
|
|
26
|
+
- Example: "Input→Validation→Save" to "Input→Save→Async Validation"
|
|
27
|
+
- **Data passing method changes** (props→Context, direct reference→events)
|
|
28
|
+
|
|
29
|
+
### 3. Architecture Changes
|
|
30
|
+
- Layer addition, responsibility changes, component relocation
|
|
31
|
+
|
|
32
|
+
### 4. External Dependency Changes
|
|
33
|
+
- Library/framework/external API introduction or replacement
|
|
34
|
+
|
|
35
|
+
### 5. Complex Implementation Logic (Regardless of Scale)
|
|
36
|
+
- Managing 3+ states
|
|
37
|
+
- Coordinating 5+ asynchronous processes
|
|
38
|
+
|
|
39
|
+
## Detailed Document Definitions
|
|
40
|
+
|
|
41
|
+
### PRD (Product Requirements Document)
|
|
42
|
+
|
|
43
|
+
**Purpose**: Define business requirements and user value
|
|
44
|
+
|
|
45
|
+
**Includes**:
|
|
46
|
+
- Business requirements and user value
|
|
47
|
+
- Success metrics and KPIs (measurable format)
|
|
48
|
+
- User stories and use cases
|
|
49
|
+
- MoSCoW prioritization (Must/Should/Could/Won't)
|
|
50
|
+
- MVP and Future phase separation
|
|
51
|
+
- User journey diagram (required)
|
|
52
|
+
- Scope boundary diagram (required)
|
|
53
|
+
|
|
54
|
+
**Excludes**:
|
|
55
|
+
- Technical implementation details (→Design Doc)
|
|
56
|
+
- Technical selection rationale (→ADR)
|
|
57
|
+
- **Implementation phases** (→Work Plan)
|
|
58
|
+
- **Task breakdown** (→Work Plan)
|
|
59
|
+
|
|
60
|
+
### ADR (Architecture Decision Record)
|
|
61
|
+
|
|
62
|
+
**Purpose**: Record technical decision rationale and background
|
|
63
|
+
|
|
64
|
+
**Includes**:
|
|
65
|
+
- Decision (what was selected)
|
|
66
|
+
- Rationale (why that selection was made)
|
|
67
|
+
- Option comparison (minimum 3 options) and trade-offs
|
|
68
|
+
- Architecture impact
|
|
69
|
+
- Principled implementation guidelines (e.g., "Use dependency injection")
|
|
70
|
+
|
|
71
|
+
**Excludes**:
|
|
72
|
+
- Implementation schedule, duration (→Work Plan)
|
|
73
|
+
- Detailed implementation procedures (→Design Doc)
|
|
74
|
+
- Specific code examples (→Design Doc)
|
|
75
|
+
- Resource assignments (→Work Plan)
|
|
76
|
+
|
|
77
|
+
### Design Document
|
|
78
|
+
|
|
79
|
+
**Purpose**: Define technical implementation methods in detail
|
|
80
|
+
|
|
81
|
+
**Includes**:
|
|
82
|
+
- **Existing codebase analysis** (required)
|
|
83
|
+
- Implementation path mapping (both existing and new)
|
|
84
|
+
- Integration point clarification (connection points with existing code even for new implementations)
|
|
85
|
+
- Technical implementation approach (vertical/horizontal/hybrid)
|
|
86
|
+
- **Technical dependencies and implementation constraints** (required implementation order)
|
|
87
|
+
- Interface and type definitions
|
|
88
|
+
- Data flow and component design
|
|
89
|
+
- **E2E verification procedures at integration points**
|
|
90
|
+
- **Acceptance criteria (EARS format: When/While/If-then/none)**
|
|
91
|
+
- Change impact map (clearly specify direct impact/indirect impact/no ripple effect)
|
|
92
|
+
- Complete enumeration of integration points
|
|
93
|
+
- Data contract clarification
|
|
94
|
+
- **Agreement checklist** (agreements with stakeholders)
|
|
95
|
+
- **Prerequisite ADRs** (including common ADRs)
|
|
96
|
+
|
|
97
|
+
**Required Structural Elements**:
|
|
98
|
+
```yaml
|
|
99
|
+
Change Impact Map:
|
|
100
|
+
Change Target: [Component/Feature]
|
|
101
|
+
Direct Impact: [Files/Functions]
|
|
102
|
+
Indirect Impact: [Data format/Processing time]
|
|
103
|
+
No Ripple Effect: [Unaffected features]
|
|
104
|
+
|
|
105
|
+
Interface Change Matrix:
|
|
106
|
+
Existing: [Method name]
|
|
107
|
+
New: [Method name]
|
|
108
|
+
Conversion Required: [Yes/No]
|
|
109
|
+
Compatibility Method: [Approach]
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
**Excludes**:
|
|
113
|
+
- Why that technology was chosen (→Reference ADR)
|
|
114
|
+
- When to implement, duration (→Work Plan)
|
|
115
|
+
- Who will implement (→Work Plan)
|
|
116
|
+
|
|
117
|
+
### Work Plan
|
|
118
|
+
|
|
119
|
+
**Purpose**: Implementation task management and progress tracking
|
|
120
|
+
|
|
121
|
+
**Includes**:
|
|
122
|
+
- Task breakdown and dependencies (maximum 2 levels)
|
|
123
|
+
- Schedule and duration estimates
|
|
124
|
+
- **Copy E2E verification procedures from Design Doc** (cannot delete, can add)
|
|
125
|
+
- **Phase 4 Quality Assurance Phase (required)**
|
|
126
|
+
- Progress records (checkbox format)
|
|
127
|
+
|
|
128
|
+
**Excludes**:
|
|
129
|
+
- Technical rationale (→ADR)
|
|
130
|
+
- Design details (→Design Doc)
|
|
131
|
+
|
|
132
|
+
**Phase Division Criteria**:
|
|
133
|
+
1. **Phase 1: Foundation Implementation** - Type definitions, interfaces, test preparation
|
|
134
|
+
2. **Phase 2: Core Feature Implementation** - Business logic, unit tests
|
|
135
|
+
3. **Phase 3: Integration Implementation** - External connections, presentation layer
|
|
136
|
+
4. **Phase 4: Quality Assurance (Required)** - Acceptance criteria achievement, all tests passing, quality checks
|
|
137
|
+
|
|
138
|
+
**Three Elements of Task Completion Definition**:
|
|
139
|
+
1. **Implementation Complete**: Code is functional
|
|
140
|
+
2. **Quality Complete**: Tests, type checks, linting pass
|
|
141
|
+
3. **Integration Complete**: Verified connection with other components
|
|
142
|
+
|
|
143
|
+
## Creation Process
|
|
144
|
+
|
|
145
|
+
1. **Problem Analysis**: Change scale assessment, ADR condition check
|
|
146
|
+
2. **ADR Option Consideration** (ADR only): Compare 3+ options, specify trade-offs
|
|
147
|
+
3. **Creation**: Use templates, include measurable conditions
|
|
148
|
+
4. **Approval**: "Accepted" after review enables implementation
|
|
149
|
+
|
|
150
|
+
## Storage Locations
|
|
151
|
+
|
|
152
|
+
| Document | Path | Naming Convention | Template |
|
|
153
|
+
|----------|------|------------------|----------|
|
|
154
|
+
| PRD | `docs/prd/` | `[feature-name]-prd.md` | `template-en.md` |
|
|
155
|
+
| ADR | `docs/adr/` | `ADR-[4-digits]-[title].md` | `template-en.md` |
|
|
156
|
+
| Design Doc | `docs/design/` | `[feature-name]-design.md` | `template-en.md` |
|
|
157
|
+
| Work Plan | `docs/plans/` | `YYYYMMDD-{type}-{description}.md` | `template-en.md` |
|
|
158
|
+
|
|
159
|
+
*Note: Work plans are excluded by `.gitignore`
|
|
160
|
+
|
|
161
|
+
## ADR Status
|
|
162
|
+
`Proposed` → `Accepted` → `Deprecated`/`Superseded`/`Rejected`
|
|
163
|
+
|
|
164
|
+
## AI Automation Rules
|
|
165
|
+
- 5+ files: Suggest ADR creation
|
|
166
|
+
- Type/data flow change detected: ADR mandatory
|
|
167
|
+
- Check existing ADRs before implementation
|
|
168
|
+
|
|
169
|
+
## Diagram Requirements
|
|
170
|
+
|
|
171
|
+
Required diagrams for each document (using mermaid notation):
|
|
172
|
+
|
|
173
|
+
| Document | Required Diagrams | Purpose |
|
|
174
|
+
|----------|------------------|---------|
|
|
175
|
+
| PRD | User journey diagram, Scope boundary diagram | Clarify user experience and scope |
|
|
176
|
+
| ADR | Option comparison diagram (when needed) | Visualize trade-offs |
|
|
177
|
+
| Design Doc | Architecture diagram, Data flow diagram | Understand technical structure |
|
|
178
|
+
| Work Plan | Phase structure diagram, Task dependency diagram | Clarify implementation order |
|
|
179
|
+
|
|
180
|
+
## Common ADR Relationships
|
|
181
|
+
1. **At creation**: Identify common technical areas (logging, error handling, async processing, etc.), reference existing common ADRs
|
|
182
|
+
2. **When missing**: Consider creating necessary common ADRs
|
|
183
|
+
3. **Design Doc**: Specify common ADRs in "Prerequisite ADRs" section
|
|
184
|
+
4. **Compliance check**: Verify design aligns with common ADR decisions
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
# Technical Design Rules (Frontend)
|
|
2
|
+
|
|
3
|
+
## Basic Technology Stack Policy
|
|
4
|
+
TypeScript-based React application implementation. Architecture patterns should be selected according to project requirements and scale.
|
|
5
|
+
|
|
6
|
+
## Environment Variable Management and Security
|
|
7
|
+
|
|
8
|
+
### Environment Variable Management
|
|
9
|
+
- **Use build tool's environment variable system**: `process.env` does not work in browser environments
|
|
10
|
+
- Centrally manage environment variables through configuration layer
|
|
11
|
+
- Implement proper type safety with TypeScript
|
|
12
|
+
- Properly implement default value settings and mandatory checks
|
|
13
|
+
|
|
14
|
+
```typescript
|
|
15
|
+
// ✅ Build tool environment variables (public values only)
|
|
16
|
+
const config = {
|
|
17
|
+
apiUrl: import.meta.env.API_URL || 'http://localhost:3000',
|
|
18
|
+
appName: import.meta.env.APP_NAME || 'My App'
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
// ❌ Does not work in frontend
|
|
22
|
+
const apiUrl = process.env.API_URL
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
### Security (Client-side Constraints)
|
|
26
|
+
- **CRITICAL**: All frontend code is public and visible in browser
|
|
27
|
+
- **Never store secrets client-side**: No API keys, tokens, or secrets in environment variables
|
|
28
|
+
- Do not include `.env` files in Git (same as backend)
|
|
29
|
+
- Prohibit logging of sensitive information (passwords, tokens, personal data)
|
|
30
|
+
- Do not include sensitive information in error messages
|
|
31
|
+
|
|
32
|
+
**Correct Approach for Secrets**:
|
|
33
|
+
```typescript
|
|
34
|
+
// ❌ Security risk: API key exposed in browser
|
|
35
|
+
const apiKey = import.meta.env.API_KEY
|
|
36
|
+
const response = await fetch(`https://api.example.com/data?key=${apiKey}`)
|
|
37
|
+
|
|
38
|
+
// ✅ Correct: Backend manages secrets, frontend accesses via proxy
|
|
39
|
+
const response = await fetch('/api/data') // Backend handles API key authentication
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Architecture Design
|
|
43
|
+
|
|
44
|
+
### Frontend Architecture Patterns
|
|
45
|
+
Strictly adhere to selected project patterns. Project-specific details reference `docs/rules/architecture/`.
|
|
46
|
+
|
|
47
|
+
**React Component Architecture**:
|
|
48
|
+
- **Function Components**: Mandatory, class components deprecated
|
|
49
|
+
- **Custom Hooks**: For logic reuse and dependency injection
|
|
50
|
+
- **Component Hierarchy**: Atoms → Molecules → Organisms → Templates → Pages
|
|
51
|
+
- **Props-driven**: Components receive all necessary data via props
|
|
52
|
+
- **Co-location**: Place tests, styles, and related files alongside components
|
|
53
|
+
|
|
54
|
+
**State Management Patterns**:
|
|
55
|
+
- **Local State**: `useState` for component-specific state
|
|
56
|
+
- **Context API**: For sharing state across component tree (theme, auth, etc.)
|
|
57
|
+
- **Custom Hooks**: Encapsulate state logic and side effects
|
|
58
|
+
- **Server State**: React Query or SWR for API data caching
|
|
59
|
+
|
|
60
|
+
## Unified Data Flow Principles
|
|
61
|
+
|
|
62
|
+
### Client-side Data Flow
|
|
63
|
+
Maintain consistent data flow throughout the React application:
|
|
64
|
+
|
|
65
|
+
- **Single Source of Truth**: Each piece of state has one authoritative source
|
|
66
|
+
- UI state: Component state or Context
|
|
67
|
+
- Server data: API responses cached in React Query/SWR
|
|
68
|
+
- Form data: Controlled components with React Hook Form
|
|
69
|
+
|
|
70
|
+
- **Unidirectional Flow**: Data flows top-down via props
|
|
71
|
+
```
|
|
72
|
+
API Response → State → Props → Render → UI
|
|
73
|
+
User Input → Event Handler → State Update → Re-render
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
- **Immutable Updates**: Use immutable patterns for state updates
|
|
77
|
+
```typescript
|
|
78
|
+
// ✅ Immutable state update
|
|
79
|
+
setUsers(prev => [...prev, newUser])
|
|
80
|
+
|
|
81
|
+
// ❌ Mutable state update
|
|
82
|
+
users.push(newUser)
|
|
83
|
+
setUsers(users)
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
### Type Safety in Data Flow
|
|
87
|
+
- **Frontend → Backend**: Props/State (Type Guaranteed) → API Request (Serialization)
|
|
88
|
+
- **Backend → Frontend**: API Response (`unknown`) → Type Guard → State (Type Guaranteed)
|
|
89
|
+
|
|
90
|
+
```typescript
|
|
91
|
+
// ✅ Type-safe data flow
|
|
92
|
+
async function fetchUser(id: string): Promise<User> {
|
|
93
|
+
const response = await fetch(`/api/users/${id}`)
|
|
94
|
+
const data: unknown = await response.json()
|
|
95
|
+
|
|
96
|
+
if (!isUser(data)) {
|
|
97
|
+
throw new Error('Invalid user data')
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
return data // Type guaranteed as User
|
|
101
|
+
}
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
## Build and Testing
|
|
105
|
+
Use the appropriate run command based on the `packageManager` field in package.json.
|
|
106
|
+
|
|
107
|
+
### Build Commands
|
|
108
|
+
- `dev` - Development server
|
|
109
|
+
- `build` - Production build
|
|
110
|
+
- `preview` - Preview production build
|
|
111
|
+
- `type-check` - Type check (no emit)
|
|
112
|
+
|
|
113
|
+
### Testing Commands
|
|
114
|
+
- `test` - Run tests
|
|
115
|
+
- `test:coverage` - Run tests with coverage
|
|
116
|
+
- `test:coverage:fresh` - Run tests with coverage (fresh cache)
|
|
117
|
+
- `test:safe` - Safe test execution (with auto cleanup)
|
|
118
|
+
- `cleanup:processes` - Cleanup Vitest processes
|
|
119
|
+
|
|
120
|
+
### Quality Check Requirements
|
|
121
|
+
Quality checks are mandatory upon implementation completion:
|
|
122
|
+
|
|
123
|
+
**Phase 1-3: Basic Checks**
|
|
124
|
+
- `check` - Biome (lint + format)
|
|
125
|
+
- `build` - TypeScript build
|
|
126
|
+
|
|
127
|
+
**Phase 4-5: Tests and Final Confirmation**
|
|
128
|
+
- `test` - Test execution
|
|
129
|
+
- `test:coverage:fresh` - Coverage measurement
|
|
130
|
+
- `check:all` - Overall integrated check
|
|
131
|
+
|
|
132
|
+
### Coverage Requirements
|
|
133
|
+
- **Mandatory**: Unit test coverage must be 60% or higher
|
|
134
|
+
- **Component-specific targets**:
|
|
135
|
+
- Atoms: 70% or higher
|
|
136
|
+
- Molecules: 65% or higher
|
|
137
|
+
- Organisms: 60% or higher
|
|
138
|
+
- Custom Hooks: 65% or higher
|
|
139
|
+
- Utils: 70% or higher
|
|
140
|
+
|
|
141
|
+
### Non-functional Requirements
|
|
142
|
+
- **Browser Compatibility**: Chrome/Firefox/Safari/Edge (latest 2 versions)
|
|
143
|
+
- **Rendering Time**: Within 5 seconds for major pages
|