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,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