@kood/claude-code 0.4.1 → 0.5.0

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 (149) hide show
  1. package/dist/index.js +53 -7
  2. package/package.json +2 -1
  3. package/templates/.claude/PARALLEL_AGENTS.md +737 -0
  4. package/templates/.claude/agents/analyst.md +416 -0
  5. package/templates/.claude/agents/architect.md +569 -0
  6. package/templates/.claude/agents/code-reviewer.md +132 -133
  7. package/templates/.claude/agents/dependency-manager.md +93 -94
  8. package/templates/.claude/agents/deployment-validator.md +64 -65
  9. package/templates/.claude/agents/designer.md +655 -0
  10. package/templates/.claude/agents/document-writer.md +500 -0
  11. package/templates/.claude/agents/explore.md +499 -0
  12. package/templates/.claude/agents/git-operator.md +74 -75
  13. package/templates/.claude/agents/implementation-executor.md +138 -109
  14. package/templates/.claude/agents/ko-to-en-translator.md +18 -22
  15. package/templates/.claude/agents/lint-fixer.md +250 -93
  16. package/templates/.claude/agents/planner.md +356 -0
  17. package/templates/.claude/agents/refactor-advisor.md +135 -136
  18. package/templates/.claude/commands/bug-fix.md +296 -207
  19. package/templates/.claude/commands/git-all.md +199 -46
  20. package/templates/.claude/commands/git-session.md +113 -57
  21. package/templates/.claude/commands/lint-fix.md +219 -153
  22. package/templates/.claude/commands/lint-init.md +113 -76
  23. package/templates/.claude/commands/pre-deploy.md +190 -124
  24. package/templates/.claude/commands/refactor.md +407 -162
  25. package/templates/.claude/commands/version-update.md +138 -37
  26. package/templates/.claude/instructions/context-engineering/ANTHROPIC_CONTEXT_ENGINEERING.md +178 -0
  27. package/templates/.claude/instructions/context-engineering/references/claude-4x.md +215 -0
  28. package/templates/.claude/instructions/context-engineering/references/core-principles.md +137 -0
  29. package/templates/.claude/instructions/context-engineering/references/examples.md +351 -0
  30. package/templates/.claude/instructions/context-engineering/references/techniques.md +162 -0
  31. package/templates/.claude/instructions/parallel-agent-execution.md +874 -0
  32. package/templates/.claude/skills/docs-creator/AGENTS.md +238 -0
  33. package/templates/.claude/{commands/docs-creator.md → skills/docs-creator/SKILL.md} +61 -75
  34. package/templates/.claude/skills/docs-refactor/AGENTS.md +270 -0
  35. package/templates/.claude/{commands/docs-refactor.md → skills/docs-refactor/SKILL.md} +30 -44
  36. package/templates/.claude/skills/execute/SKILL.md +451 -0
  37. package/templates/.claude/skills/figma-to-code/AGENTS.md +287 -0
  38. package/templates/.claude/skills/figma-to-code/SKILL.md +225 -225
  39. package/templates/.claude/skills/figma-to-code/references/design-tokens.md +75 -73
  40. package/templates/.claude/skills/figma-to-code/references/figma-mcp-tools.md +73 -73
  41. package/templates/.claude/skills/figma-to-code/references/layout-mapping.md +104 -104
  42. package/templates/.claude/skills/figma-to-code/references/responsive-design.md +99 -99
  43. package/templates/.claude/skills/figma-to-code/references/verification.md +91 -91
  44. package/templates/.claude/skills/global-uiux-design/AGENTS.md +317 -0
  45. package/templates/.claude/skills/global-uiux-design/SKILL.md +738 -0
  46. package/templates/.claude/skills/global-uiux-design/references/accessibility.md +401 -0
  47. package/templates/.claude/skills/global-uiux-design/references/color-system.md +275 -0
  48. package/templates/.claude/skills/global-uiux-design/references/design-philosophy.md +206 -0
  49. package/templates/.claude/skills/global-uiux-design/references/design-systems.md +446 -0
  50. package/templates/.claude/skills/korea-uiux-design/AGENTS.md +307 -0
  51. package/templates/.claude/skills/korea-uiux-design/SKILL.md +170 -0
  52. package/templates/.claude/skills/nextjs-react-best-practices/AGENTS.md +95 -116
  53. package/templates/.claude/skills/nextjs-react-best-practices/SKILL.md +134 -152
  54. package/templates/.claude/skills/nextjs-react-best-practices/rules/advanced-event-handler-refs.md +6 -6
  55. package/templates/.claude/skills/nextjs-react-best-practices/rules/advanced-use-latest.md +5 -5
  56. package/templates/.claude/skills/nextjs-react-best-practices/rules/async-api-routes.md +5 -5
  57. package/templates/.claude/skills/nextjs-react-best-practices/rules/async-defer-await.md +22 -22
  58. package/templates/.claude/skills/nextjs-react-best-practices/rules/async-dependencies.md +5 -5
  59. package/templates/.claude/skills/nextjs-react-best-practices/rules/async-parallel.md +4 -4
  60. package/templates/.claude/skills/nextjs-react-best-practices/rules/async-suspense-boundaries.md +21 -21
  61. package/templates/.claude/skills/nextjs-react-best-practices/rules/bundle-barrel-imports.md +18 -18
  62. package/templates/.claude/skills/nextjs-react-best-practices/rules/bundle-conditional.md +4 -4
  63. package/templates/.claude/skills/nextjs-react-best-practices/rules/bundle-defer-third-party.md +4 -4
  64. package/templates/.claude/skills/nextjs-react-best-practices/rules/bundle-dynamic-imports.md +4 -4
  65. package/templates/.claude/skills/nextjs-react-best-practices/rules/bundle-preload.md +5 -5
  66. package/templates/.claude/skills/nextjs-react-best-practices/rules/client-event-listeners.md +9 -9
  67. package/templates/.claude/skills/nextjs-react-best-practices/rules/client-swr-dedup.md +7 -7
  68. package/templates/.claude/skills/nextjs-react-best-practices/rules/js-batch-dom-css.md +13 -13
  69. package/templates/.claude/skills/nextjs-react-best-practices/rules/js-cache-function-results.md +14 -14
  70. package/templates/.claude/skills/nextjs-react-best-practices/rules/js-cache-property-access.md +4 -4
  71. package/templates/.claude/skills/nextjs-react-best-practices/rules/js-cache-storage.md +10 -10
  72. package/templates/.claude/skills/nextjs-react-best-practices/rules/js-combine-iterations.md +4 -4
  73. package/templates/.claude/skills/nextjs-react-best-practices/rules/js-early-exit.md +7 -7
  74. package/templates/.claude/skills/nextjs-react-best-practices/rules/js-hoist-regexp.md +6 -6
  75. package/templates/.claude/skills/nextjs-react-best-practices/rules/js-index-maps.md +6 -6
  76. package/templates/.claude/skills/nextjs-react-best-practices/rules/js-length-check-first.md +14 -14
  77. package/templates/.claude/skills/nextjs-react-best-practices/rules/js-min-max-loop.md +16 -16
  78. package/templates/.claude/skills/nextjs-react-best-practices/rules/js-set-map-lookups.md +4 -4
  79. package/templates/.claude/skills/nextjs-react-best-practices/rules/js-tosorted-immutable.md +17 -17
  80. package/templates/.claude/skills/nextjs-react-best-practices/rules/rendering-activity.md +4 -4
  81. package/templates/.claude/skills/nextjs-react-best-practices/rules/rendering-animate-svg-wrapper.md +11 -11
  82. package/templates/.claude/skills/nextjs-react-best-practices/rules/rendering-conditional-render.md +8 -8
  83. package/templates/.claude/skills/nextjs-react-best-practices/rules/rendering-content-visibility.md +4 -4
  84. package/templates/.claude/skills/nextjs-react-best-practices/rules/rendering-hoist-jsx.md +6 -6
  85. package/templates/.claude/skills/nextjs-react-best-practices/rules/rendering-hydration-no-flicker.md +14 -14
  86. package/templates/.claude/skills/nextjs-react-best-practices/rules/rendering-svg-precision.md +5 -5
  87. package/templates/.claude/skills/nextjs-react-best-practices/rules/rerender-defer-reads.md +4 -4
  88. package/templates/.claude/skills/nextjs-react-best-practices/rules/rerender-dependencies.md +7 -7
  89. package/templates/.claude/skills/nextjs-react-best-practices/rules/rerender-derived-state.md +5 -5
  90. package/templates/.claude/skills/nextjs-react-best-practices/rules/rerender-functional-setstate.md +34 -34
  91. package/templates/.claude/skills/nextjs-react-best-practices/rules/rerender-lazy-state-init.md +15 -15
  92. package/templates/.claude/skills/nextjs-react-best-practices/rules/rerender-memo.md +5 -5
  93. package/templates/.claude/skills/nextjs-react-best-practices/rules/rerender-transitions.md +4 -4
  94. package/templates/.claude/skills/nextjs-react-best-practices/rules/server-after-nonblocking.md +24 -24
  95. package/templates/.claude/skills/nextjs-react-best-practices/rules/server-cache-lru.md +10 -10
  96. package/templates/.claude/skills/nextjs-react-best-practices/rules/server-cache-react.md +4 -4
  97. package/templates/.claude/skills/nextjs-react-best-practices/rules/server-parallel-fetching.md +5 -5
  98. package/templates/.claude/skills/nextjs-react-best-practices/rules/server-serialization.md +6 -6
  99. package/templates/.claude/skills/plan/SKILL.md +594 -0
  100. package/templates/.claude/skills/prd/SKILL.md +496 -0
  101. package/templates/.claude/skills/ralph/AGENTS.md +393 -0
  102. package/templates/.claude/skills/ralph/SKILL.md +1035 -0
  103. package/templates/.claude/skills/tanstack-start-react-best-practices/AGENTS.md +100 -121
  104. package/templates/.claude/skills/tanstack-start-react-best-practices/SKILL.md +139 -157
  105. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/async-defer-await.md +22 -22
  106. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/async-dependencies.md +5 -5
  107. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/async-loader.md +7 -7
  108. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/async-parallel.md +4 -4
  109. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/bundle-barrel-imports.md +18 -18
  110. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/bundle-conditional.md +4 -4
  111. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/bundle-defer-third-party.md +4 -4
  112. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/bundle-lazy-routes.md +12 -12
  113. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/bundle-preload.md +5 -5
  114. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/client-event-listeners.md +9 -9
  115. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/client-tanstack-query.md +12 -12
  116. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/js-batch-dom-css.md +13 -13
  117. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/js-cache-function-results.md +14 -14
  118. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/js-cache-property-access.md +4 -4
  119. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/js-cache-storage.md +10 -10
  120. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/js-combine-iterations.md +4 -4
  121. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/js-early-exit.md +7 -7
  122. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/js-hoist-regexp.md +6 -6
  123. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/js-index-maps.md +6 -6
  124. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/js-length-check-first.md +14 -14
  125. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/js-min-max-loop.md +16 -16
  126. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/js-set-map-lookups.md +4 -4
  127. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/js-tosorted-immutable.md +17 -17
  128. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/rendering-animate-svg-wrapper.md +11 -11
  129. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/rendering-conditional-render.md +8 -8
  130. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/rendering-content-visibility.md +4 -4
  131. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/rendering-hoist-jsx.md +6 -6
  132. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/rendering-svg-precision.md +5 -5
  133. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/rerender-defer-reads.md +4 -4
  134. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/rerender-dependencies.md +7 -7
  135. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/rerender-derived-state.md +5 -5
  136. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/rerender-functional-setstate.md +34 -34
  137. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/rerender-lazy-state-init.md +15 -15
  138. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/rerender-memo.md +5 -5
  139. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/rerender-transitions.md +4 -4
  140. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/server-cache-lru.md +12 -12
  141. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/server-deferred-data.md +14 -14
  142. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/server-parallel-fetching.md +9 -9
  143. package/templates/.claude/skills/tanstack-start-react-best-practices/rules/server-serialization.md +6 -6
  144. package/templates/.claude/commands/agent-creator.md +0 -370
  145. package/templates/.claude/commands/command-creator.md +0 -524
  146. package/templates/.claude/commands/execute.md +0 -469
  147. package/templates/.claude/commands/git.md +0 -98
  148. package/templates/.claude/commands/plan.md +0 -526
  149. package/templates/.claude/commands/prd.md +0 -629
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: tanstack-start-react-best-practices
3
- description: TanStack Start and React performance optimization guide. Ensures optimal performance patterns when writing, reviewing, or refactoring TanStack Start pages and React components. Triggers on tasks involving React components, TanStack Router routes, data fetching, bundle optimization, or performance improvements.
3
+ description: TanStack Start React 성능 최적화 가이드. React 컴포넌트, TanStack Start 페이지 작성/리뷰/리팩토링 최적 성능 패턴 보장. React 컴포넌트, TanStack Router 라우트, 데이터 페칭, 번들 최적화, 성능 개선 작업에 트리거.
4
4
  license: MIT
5
5
  metadata:
6
6
  author: vercel
@@ -8,41 +8,23 @@ metadata:
8
8
  adapted_for: tanstack-start
9
9
  ---
10
10
 
11
- # TanStack Start React Best Practices
11
+ # TanStack Start React 베스트 프랙티스
12
12
 
13
- Performance optimization guide for React and TanStack Start applications. Contains 39 rules across 7 categories, prioritized by impact to guide automated refactoring and code generation.
14
-
15
- ---
16
-
17
- <communication>
18
-
19
- ## User Communication
20
-
21
- **IMPORTANT: Always communicate with the user in Korean (한국어), even though this document is in English.**
22
-
23
- When:
24
- - Asking questions
25
- - Providing summaries
26
- - Explaining decisions
27
- - Reporting progress
28
-
29
- Use Korean for all user-facing communication while applying these English guidelines internally.
30
-
31
- </communication>
13
+ React TanStack Start 애플리케이션 성능 최적화 가이드. 7 카테고리, 38개 규칙 포함. 영향도별 우선순위로 자동 리팩토링과 코드 생성 가이드 제공.
32
14
 
33
15
  ---
34
16
 
35
17
  <when_to_use>
36
18
 
37
- ## When to Apply
19
+ ## 사용 시점
38
20
 
39
- | Situation | Description |
40
- |-----------|-------------|
41
- | **Writing Components** | Creating new React components or TanStack Start routes |
42
- | **Data Fetching** | Implementing client-side or server-side data fetching |
43
- | **Code Review** | Reviewing code for performance issues |
44
- | **Refactoring** | Improving existing React/TanStack Start code |
45
- | **Optimization** | Optimizing bundle size or load times |
21
+ | 상황 | 설명 |
22
+ |------|------|
23
+ | **컴포넌트 작성** | React 컴포넌트, TanStack Start 라우트 신규 작성 |
24
+ | **데이터 페칭** | 클라이언트/서버 사이드 데이터 페칭 구현 |
25
+ | **코드 리뷰** | 성능 이슈 검토 |
26
+ | **리팩토링** | 기존 React/TanStack Start 코드 개선 |
27
+ | **최적화** | 번들 크기, 로딩 시간 최적화 |
46
28
 
47
29
  </when_to_use>
48
30
 
@@ -50,17 +32,17 @@ Use Korean for all user-facing communication while applying these English guidel
50
32
 
51
33
  <categories>
52
34
 
53
- ## Rule Categories by Priority
35
+ ## 카테고리별 우선순위
54
36
 
55
- | Priority | Category | Impact | Prefix |
56
- |----------|----------|--------|--------|
57
- | 1 | Eliminating Waterfalls | **CRITICAL** | `async-` |
58
- | 2 | Bundle Size Optimization | **CRITICAL** | `bundle-` |
59
- | 3 | Server-Side Performance | HIGH | `server-` |
60
- | 4 | Client-Side Data Fetching | MEDIUM-HIGH | `client-` |
61
- | 5 | Re-render Optimization | MEDIUM | `rerender-` |
62
- | 6 | Rendering Performance | MEDIUM | `rendering-` |
63
- | 7 | JavaScript Performance | LOW-MEDIUM | `js-` |
37
+ | 우선순위 | 카테고리 | 영향도 | 접두사 |
38
+ |---------|---------|--------|--------|
39
+ | 1 | Waterfall 제거 | **CRITICAL** | `async-` |
40
+ | 2 | 번들 크기 최적화 | **CRITICAL** | `bundle-` |
41
+ | 3 | 서버 사이드 성능 | HIGH | `server-` |
42
+ | 4 | 클라이언트 데이터 페칭 | MEDIUM-HIGH | `client-` |
43
+ | 5 | Re-render 최적화 | MEDIUM | `rerender-` |
44
+ | 6 | 렌더링 성능 | MEDIUM | `rendering-` |
45
+ | 7 | JavaScript 성능 | LOW-MEDIUM | `js-` |
64
46
 
65
47
  </categories>
66
48
 
@@ -68,81 +50,81 @@ Use Korean for all user-facing communication while applying these English guidel
68
50
 
69
51
  <rules>
70
52
 
71
- ## Quick Reference
72
-
73
- ### 1. Eliminating Waterfalls (CRITICAL)
74
-
75
- | Rule | Description |
76
- |------|-------------|
77
- | `async-defer-await` | Move await into branches where actually used |
78
- | `async-parallel` | Use Promise.all() for independent operations |
79
- | `async-dependencies` | Use better-all for partial dependencies |
80
- | `async-loader` | Parallel data fetching in TanStack Router loader |
81
-
82
- ### 2. Bundle Size Optimization (CRITICAL)
83
-
84
- | Rule | Description |
85
- |------|-------------|
86
- | `bundle-barrel-imports` | Import directly, avoid barrel files |
87
- | `bundle-lazy-routes` | Route-based code splitting |
88
- | `bundle-defer-third-party` | Load analytics/logging after hydration |
89
- | `bundle-conditional` | Load modules only when feature is activated |
90
- | `bundle-preload` | Preload on hover/focus for perceived speed |
91
-
92
- ### 3. Server-Side Performance (HIGH)
93
-
94
- | Rule | Description |
95
- |------|-------------|
96
- | `server-cache-lru` | Use LRU cache for cross-request caching |
97
- | `server-serialization` | Minimize data passed to client components |
98
- | `server-parallel-fetching` | Parallel data fetching in loader |
99
- | `server-deferred-data` | Use defer() for non-blocking data loading |
100
-
101
- ### 4. Client-Side Data Fetching (MEDIUM-HIGH)
102
-
103
- | Rule | Description |
104
- |------|-------------|
105
- | `client-tanstack-query` | TanStack Query for automatic caching/deduplication |
106
- | `client-event-listeners` | Deduplicate global event listeners |
107
-
108
- ### 5. Re-render Optimization (MEDIUM)
109
-
110
- | Rule | Description |
111
- |------|-------------|
112
- | `rerender-defer-reads` | Don't subscribe to state only used in callbacks |
113
- | `rerender-memo` | Extract expensive work into memoized components |
114
- | `rerender-dependencies` | Use primitive dependencies in effects |
115
- | `rerender-derived-state` | Subscribe to derived booleans, not raw values |
116
- | `rerender-functional-setstate` | Use functional setState for stable callbacks |
117
- | `rerender-lazy-state-init` | Pass function to useState for expensive values |
118
- | `rerender-transitions` | Use startTransition for non-urgent updates |
119
-
120
- ### 6. Rendering Performance (MEDIUM)
121
-
122
- | Rule | Description |
123
- |------|-------------|
124
- | `rendering-animate-svg-wrapper` | Animate div wrapper, not SVG element |
125
- | `rendering-content-visibility` | Use content-visibility for long lists |
126
- | `rendering-hoist-jsx` | Extract static JSX outside components |
127
- | `rendering-svg-precision` | Reduce SVG coordinate precision |
128
- | `rendering-conditional-render` | Use ternary, not && for conditionals |
129
-
130
- ### 7. JavaScript Performance (LOW-MEDIUM)
131
-
132
- | Rule | Description |
133
- |------|-------------|
134
- | `js-batch-dom-css` | Group CSS changes via classes or cssText |
135
- | `js-index-maps` | Build Map for repeated lookups |
136
- | `js-cache-property-access` | Cache object properties in loops |
137
- | `js-cache-function-results` | Cache function results in module-level Map |
138
- | `js-cache-storage` | Cache localStorage/sessionStorage reads |
139
- | `js-combine-iterations` | Combine multiple filter/map into one loop |
140
- | `js-length-check-first` | Check array length before expensive comparison |
141
- | `js-early-exit` | Return early from functions |
142
- | `js-hoist-regexp` | Hoist RegExp creation outside loops |
143
- | `js-min-max-loop` | Use loop for min/max instead of sort |
144
- | `js-set-map-lookups` | Use Set/Map for O(1) lookups |
145
- | `js-tosorted-immutable` | Use toSorted() for immutability |
53
+ ## 빠른 참조
54
+
55
+ ### 1. Waterfall 제거 (CRITICAL)
56
+
57
+ | 규칙 | 설명 |
58
+ |------|------|
59
+ | `async-defer-await` | await 실제 사용 지점으로 이동 |
60
+ | `async-parallel` | 독립 작업은 Promise.all() 사용 |
61
+ | `async-dependencies` | 부분 의존성은 better-all 사용 |
62
+ | `async-loader` | TanStack Router loader에서 병렬 데이터 페칭 |
63
+
64
+ ### 2. 번들 크기 최적화 (CRITICAL)
65
+
66
+ | 규칙 | 설명 |
67
+ |------|------|
68
+ | `bundle-barrel-imports` | 직접 import, barrel 파일 회피 |
69
+ | `bundle-lazy-routes` | 라우트 기반 코드 스플리팅 |
70
+ | `bundle-defer-third-party` | 분석/로깅은 hydration 로드 |
71
+ | `bundle-conditional` | 기능 활성화 시에만 모듈 로드 |
72
+ | `bundle-preload` | hover/focus preload로 체감 속도 향상 |
73
+
74
+ ### 3. 서버 사이드 성능 (HIGH)
75
+
76
+ | 규칙 | 설명 |
77
+ |------|------|
78
+ | `server-cache-lru` | LRU 캐시로 요청 캐싱 |
79
+ | `server-serialization` | 클라이언트로 전달 데이터 최소화 |
80
+ | `server-parallel-fetching` | loader에서 병렬 데이터 페칭 |
81
+ | `server-deferred-data` | defer() 비차단 데이터 로딩 |
82
+
83
+ ### 4. 클라이언트 데이터 페칭 (MEDIUM-HIGH)
84
+
85
+ | 규칙 | 설명 |
86
+ |------|------|
87
+ | `client-tanstack-query` | TanStack Query 자동 캐싱/중복 제거 |
88
+ | `client-event-listeners` | 전역 이벤트 리스너 중복 제거 |
89
+
90
+ ### 5. Re-render 최적화 (MEDIUM)
91
+
92
+ | 규칙 | 설명 |
93
+ |------|------|
94
+ | `rerender-defer-reads` | 콜백 전용 상태는 구독 |
95
+ | `rerender-memo` | 비싼 작업은 memoized 컴포넌트로 추출 |
96
+ | `rerender-dependencies` | effect에 원시값 의존성 사용 |
97
+ | `rerender-derived-state` | 파생 boolean 구독, raw 구독 회피 |
98
+ | `rerender-functional-setstate` | 안정적 콜백용 함수형 setState |
99
+ | `rerender-lazy-state-init` | 비싼 초기값은 함수로 useState 전달 |
100
+ | `rerender-transitions` | 비긴급 업데이트는 startTransition |
101
+
102
+ ### 6. 렌더링 성능 (MEDIUM)
103
+
104
+ | 규칙 | 설명 |
105
+ |------|------|
106
+ | `rendering-animate-svg-wrapper` | SVG 대신 wrapper div 애니메이션 |
107
+ | `rendering-content-visibility` | 리스트는 content-visibility 사용 |
108
+ | `rendering-hoist-jsx` | 정적 JSX 컴포넌트 외부로 추출 |
109
+ | `rendering-svg-precision` | SVG 좌표 정밀도 감소 |
110
+ | `rendering-conditional-render` | 조건부 렌더링은 &&가 아닌 삼항 연산자 |
111
+
112
+ ### 7. JavaScript 성능 (LOW-MEDIUM)
113
+
114
+ | 규칙 | 설명 |
115
+ |------|------|
116
+ | `js-batch-dom-css` | CSS 변경은 클래스나 cssText로 그룹화 |
117
+ | `js-index-maps` | 반복 조회용 Map 빌드 |
118
+ | `js-cache-property-access` | 루프에서 객체 속성 캐싱 |
119
+ | `js-cache-function-results` | 함수 결과를 모듈 레벨 Map 캐싱 |
120
+ | `js-cache-storage` | localStorage/sessionStorage 읽기 캐싱 |
121
+ | `js-combine-iterations` | 여러 filter/map 하나의 루프로 결합 |
122
+ | `js-length-check-first` | 비싼 비교 배열 길이 먼저 체크 |
123
+ | `js-early-exit` | 함수에서 조기 반환 |
124
+ | `js-hoist-regexp` | RegExp 생성을 루프 밖으로 |
125
+ | `js-min-max-loop` | sort 대신 루프로 min/max |
126
+ | `js-set-map-lookups` | O(1) 조회용 Set/Map 사용 |
127
+ | `js-tosorted-immutable` | 불변성용 toSorted() 사용 |
146
128
 
147
129
  </rules>
148
130
 
@@ -150,17 +132,17 @@ Use Korean for all user-facing communication while applying these English guidel
150
132
 
151
133
  <patterns>
152
134
 
153
- ## Core Patterns
135
+ ## 핵심 패턴
154
136
 
155
- ### ✅ Eliminate Waterfalls
137
+ ### ✅ Waterfall 제거
156
138
 
157
139
  ```typescript
158
- // ❌ Sequential execution, 3 round trips
140
+ // ❌ 순차 실행, 3 왕복
159
141
  const user = await fetchUser()
160
142
  const posts = await fetchPosts()
161
143
  const comments = await fetchComments()
162
144
 
163
- // ✅ Parallel execution, 1 round trip
145
+ // ✅ 병렬 실행, 1 왕복
164
146
  const [user, posts, comments] = await Promise.all([
165
147
  fetchUser(),
166
148
  fetchPosts(),
@@ -174,7 +156,7 @@ const [user, posts, comments] = await Promise.all([
174
156
  import { createServerFn } from '@tanstack/react-start'
175
157
  import { createFileRoute } from '@tanstack/react-router'
176
158
 
177
- // Define Server Functions
159
+ // Server Functions 정의
178
160
  const getPost = createServerFn().handler(async (postId: string) => {
179
161
  return await db.post.findUnique({ where: { id: postId } })
180
162
  })
@@ -183,7 +165,7 @@ const getComments = createServerFn().handler(async (postId: string) => {
183
165
  return await db.comment.findMany({ where: { postId } })
184
166
  })
185
167
 
186
- // ❌ Sequential loading
168
+ // ❌ 순차 로딩
187
169
  export const Route = createFileRoute('/posts/$postId')({
188
170
  loader: async ({ params }) => {
189
171
  const post = await getPost(params.postId)
@@ -192,7 +174,7 @@ export const Route = createFileRoute('/posts/$postId')({
192
174
  }
193
175
  })
194
176
 
195
- // ✅ Parallel loading
177
+ // ✅ 병렬 로딩
196
178
  export const Route = createFileRoute('/posts/$postId')({
197
179
  loader: async ({ params }) => {
198
180
  const [post, comments] = await Promise.all([
@@ -204,24 +186,24 @@ export const Route = createFileRoute('/posts/$postId')({
204
186
  })
205
187
  ```
206
188
 
207
- ### ✅ Bundle Optimization
189
+ ### ✅ 번들 최적화
208
190
 
209
191
  ```tsx
210
- // ❌ Import entire library (1583 modules, ~2.8s)
192
+ // ❌ 전체 라이브러리 import (1583 모듈, ~2.8초)
211
193
  import { Check, X, Menu } from 'lucide-react'
212
194
 
213
- // ✅ Direct imports (3 modules only)
195
+ // ✅ 직접 import (3 모듈만)
214
196
  import Check from 'lucide-react/dist/esm/icons/check'
215
197
  import X from 'lucide-react/dist/esm/icons/x'
216
198
  import Menu from 'lucide-react/dist/esm/icons/menu'
217
199
  ```
218
200
 
219
- ### ✅ TanStack Query for Caching
201
+ ### ✅ TanStack Query 캐싱
220
202
 
221
203
  ```typescript
222
204
  import { useQuery } from '@tanstack/react-query'
223
205
 
224
- // ❌ No deduplication, each instance fetches
206
+ // ❌ 중복 제거 없음, 인스턴스가 fetch
225
207
  function UserList() {
226
208
  const [users, setUsers] = useState([])
227
209
  useEffect(() => {
@@ -231,7 +213,7 @@ function UserList() {
231
213
  }, [])
232
214
  }
233
215
 
234
- // ✅ Multiple instances share one request
216
+ // ✅ 여러 인스턴스가 하나의 요청 공유
235
217
  function UserList() {
236
218
  const { data: users } = useQuery({
237
219
  queryKey: ['users'],
@@ -240,15 +222,15 @@ function UserList() {
240
222
  }
241
223
  ```
242
224
 
243
- ### ✅ Re-render Optimization
225
+ ### ✅ Re-render 최적화
244
226
 
245
227
  ```tsx
246
- // ❌ items as dependency, recreated every time
228
+ // ❌ items 의존성, 매번 재생성
247
229
  const addItems = useCallback((newItems: Item[]) => {
248
230
  setItems([...items, ...newItems])
249
231
  }, [items])
250
232
 
251
- // ✅ Stable callback, never recreated
233
+ // ✅ 안정적 콜백, 재생성 없음
252
234
  const addItems = useCallback((newItems: Item[]) => {
253
235
  setItems(curr => [...curr, ...newItems])
254
236
  }, [])
@@ -260,17 +242,17 @@ const addItems = useCallback((newItems: Item[]) => {
260
242
 
261
243
  <tanstack_specific>
262
244
 
263
- ## TanStack Start Specific Patterns
245
+ ## TanStack Start 특화 패턴
264
246
 
265
- ### createServerFn for Server Functions
247
+ ### createServerFn으로 Server Functions
266
248
 
267
249
  ```typescript
268
250
  import { createServerFn } from '@tanstack/react-start'
269
251
  import { z } from 'zod'
270
252
 
271
- // ✅ Basic Server Function
253
+ // ✅ 기본 Server Function
272
254
  const getUser = createServerFn().handler(async () => {
273
- // Only runs on server
255
+ // 서버에서만 실행
274
256
  return await db.user.findMany()
275
257
  })
276
258
 
@@ -283,12 +265,12 @@ const createUserSchema = z.object({
283
265
  const createUser = createServerFn({ method: 'POST' })
284
266
  .inputValidator(createUserSchema)
285
267
  .handler(async ({ data }) => {
286
- // data is fully typed and validated
268
+ // data 완전히 타입 검증됨
287
269
  return await db.user.create({ data })
288
270
  })
289
271
  ```
290
272
 
291
- ### Loader Optimization
273
+ ### Loader 최적화
292
274
 
293
275
  ```typescript
294
276
  import { createServerFn } from '@tanstack/react-start'
@@ -302,7 +284,7 @@ const getStats = createServerFn().handler(async () => {
302
284
  return await db.stats.findMany()
303
285
  })
304
286
 
305
- // ✅ Parallel data fetching
287
+ // ✅ 병렬 데이터 페칭
306
288
  export const Route = createFileRoute('/dashboard')({
307
289
  loader: async () => {
308
290
  const [user, stats] = await Promise.all([
@@ -314,7 +296,7 @@ export const Route = createFileRoute('/dashboard')({
314
296
  })
315
297
  ```
316
298
 
317
- ### Deferred Data (Automatic Handling)
299
+ ### Deferred Data (자동 처리)
318
300
 
319
301
  ```typescript
320
302
  import { createServerFn } from '@tanstack/react-start'
@@ -326,17 +308,17 @@ const getPost = createServerFn().handler(async (postId: string) => {
326
308
  })
327
309
 
328
310
  const getComments = createServerFn().handler(async (postId: string) => {
329
- await new Promise(r => setTimeout(r, 3000)) // Slow query simulation
311
+ await new Promise(r => setTimeout(r, 3000)) // 느린 쿼리 시뮬레이션
330
312
  return await db.comment.findMany({ where: { postId } })
331
313
  })
332
314
 
333
- // ✅ Await important data, defer non-critical data
315
+ // ✅ 중요 데이터는 await, 비중요 데이터는 Promise 그대로 반환
334
316
  export const Route = createFileRoute('/posts/$postId')({
335
317
  loader: async ({ params }) => {
336
- // Fast data: await
318
+ // 빠른 데이터는 await
337
319
  const post = await getPost(params.postId)
338
320
 
339
- // Slow data: return Promise (automatically deferred)
321
+ // 느린 데이터는 Promise 그대로 반환 (자동으로 deferred 처리됨)
340
322
  const deferredComments = getComments(params.postId)
341
323
 
342
324
  return {
@@ -346,7 +328,7 @@ export const Route = createFileRoute('/posts/$postId')({
346
328
  }
347
329
  })
348
330
 
349
- // Handle with Await in component
331
+ // 컴포넌트에서 Await 처리
350
332
  function PostPage() {
351
333
  const { post, deferredComments } = Route.useLoaderData()
352
334
 
@@ -363,13 +345,13 @@ function PostPage() {
363
345
  }
364
346
  ```
365
347
 
366
- ### Route-Based Code Splitting
348
+ ### 라우트 기반 코드 스플리팅
367
349
 
368
350
  ```typescript
369
351
  import { lazy } from 'react'
370
352
  import { createFileRoute } from '@tanstack/react-router'
371
353
 
372
- // ✅ Heavy components lazy loaded
354
+ // ✅ 무거운 컴포넌트는 lazy load
373
355
  const HeavyEditor = lazy(() => import('./components/HeavyEditor'))
374
356
 
375
357
  export const Route = createFileRoute('/editor')({
@@ -387,9 +369,9 @@ export const Route = createFileRoute('/editor')({
387
369
 
388
370
  <usage>
389
371
 
390
- ## Usage
372
+ ## 사용법
391
373
 
392
- **Detailed rules and examples:**
374
+ **상세 규칙 예시:**
393
375
 
394
376
  ```
395
377
  rules/async-parallel.md
@@ -398,13 +380,13 @@ rules/client-tanstack-query.md
398
380
  rules/server-deferred-data.md
399
381
  ```
400
382
 
401
- Each rule file contains:
402
- - Why it matters
403
- - ❌ Incorrect code example with explanation
404
- - ✅ Correct code example with explanation
405
- - Additional context and references
383
+ 규칙 파일 포함 내용:
384
+ - 중요한 이유 설명
385
+ - ❌ 잘못된 코드 예시 + 설명
386
+ - ✅ 올바른 코드 예시 + 설명
387
+ - 추가 컨텍스트 참조
406
388
 
407
- **Full compiled document:** `AGENTS.md`
389
+ **전체 컴파일 문서:** `PARALLEL_AGENTS.md`
408
390
 
409
391
  </usage>
410
392
 
@@ -412,10 +394,10 @@ Each rule file contains:
412
394
 
413
395
  <references>
414
396
 
415
- ## References
397
+ ## 참고 자료
416
398
 
417
- ### TanStack Official Documentation
418
- 1. [React](https://react.dev)
399
+ ### TanStack 공식 문서
400
+ 1. [React 공식 문서](https://react.dev)
419
401
  2. [TanStack Start Overview](https://tanstack.com/start/latest/docs/framework/react/overview)
420
402
  3. [TanStack Start Quick Start](https://tanstack.com/start/latest/docs/framework/react/quick-start)
421
403
  4. [TanStack Router](https://tanstack.com/router)
@@ -423,7 +405,7 @@ Each rule file contains:
423
405
  6. [TanStack Query](https://tanstack.com/query)
424
406
  7. [Server Functions Guide](https://tanstack.com/start/latest/docs/framework/react/guide/server-functions)
425
407
 
426
- ### External Resources
408
+ ### 외부 자료
427
409
  8. [better-all](https://github.com/shuding/better-all)
428
410
  9. [node-lru-cache](https://github.com/isaacs/node-lru-cache)
429
411
  10. [Using Server Functions and TanStack Query](https://www.brenelz.com/posts/using-server-functions-and-tanstack-query/)
@@ -5,76 +5,76 @@ impactDescription: avoids blocking unused code paths
5
5
  tags: async, await, conditional, optimization
6
6
  ---
7
7
 
8
- ## Defer Await Until Needed
8
+ ## 필요할 때까지 Await 연기하기
9
9
 
10
- Move `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them.
10
+ 실제로 사용되는 분기점에서만 `await` 작업을 수행하여 필요하지 않은 코드 경로가 블로킹되는 것을 방지합니다.
11
11
 
12
- **Incorrect (blocks both branches):**
12
+ **❌ 잘못된 예시 ( 분기 모두 블로킹):**
13
13
 
14
14
  ```typescript
15
15
  async function handleRequest(userId: string, skipProcessing: boolean) {
16
16
  const userData = await fetchUserData(userId)
17
-
17
+
18
18
  if (skipProcessing) {
19
- // Returns immediately but still waited for userData
19
+ // 즉시 반환하지만 여전히 userData를 기다렸음
20
20
  return { skipped: true }
21
21
  }
22
-
23
- // Only this branch uses userData
22
+
23
+ // 분기에서만 userData를 사용함
24
24
  return processUserData(userData)
25
25
  }
26
26
  ```
27
27
 
28
- **Correct (only blocks when needed):**
28
+ **✅ 올바른 예시 (필요할 때만 블로킹):**
29
29
 
30
30
  ```typescript
31
31
  async function handleRequest(userId: string, skipProcessing: boolean) {
32
32
  if (skipProcessing) {
33
- // Returns immediately without waiting
33
+ // 기다리지 않고 즉시 반환
34
34
  return { skipped: true }
35
35
  }
36
-
37
- // Fetch only when needed
36
+
37
+ // 필요할 때만 가져오기
38
38
  const userData = await fetchUserData(userId)
39
39
  return processUserData(userData)
40
40
  }
41
41
  ```
42
42
 
43
- **Another example (early return optimization):**
43
+ **다른 예시 (조기 반환 최적화):**
44
44
 
45
45
  ```typescript
46
- // Incorrect: always fetches permissions
46
+ // 잘못된 예시: 항상 권한을 가져옴
47
47
  async function updateResource(resourceId: string, userId: string) {
48
48
  const permissions = await fetchPermissions(userId)
49
49
  const resource = await getResource(resourceId)
50
-
50
+
51
51
  if (!resource) {
52
52
  return { error: 'Not found' }
53
53
  }
54
-
54
+
55
55
  if (!permissions.canEdit) {
56
56
  return { error: 'Forbidden' }
57
57
  }
58
-
58
+
59
59
  return await updateResourceData(resource, permissions)
60
60
  }
61
61
 
62
- // Correct: fetches only when needed
62
+ // 올바른 예시: 필요할 때만 가져오기
63
63
  async function updateResource(resourceId: string, userId: string) {
64
64
  const resource = await getResource(resourceId)
65
-
65
+
66
66
  if (!resource) {
67
67
  return { error: 'Not found' }
68
68
  }
69
-
69
+
70
70
  const permissions = await fetchPermissions(userId)
71
-
71
+
72
72
  if (!permissions.canEdit) {
73
73
  return { error: 'Forbidden' }
74
74
  }
75
-
75
+
76
76
  return await updateResourceData(resource, permissions)
77
77
  }
78
78
  ```
79
79
 
80
- This optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive.
80
+ 최적화는 건너뛴 분기가 자주 실행되거나, 연기된 작업이 비용이 많이 드는 경우 특히 유용합니다.
@@ -5,11 +5,11 @@ impactDescription: 2-10× improvement
5
5
  tags: async, parallelization, dependencies, better-all
6
6
  ---
7
7
 
8
- ## Dependency-Based Parallelization
8
+ ## 의존성 기반 병렬화
9
9
 
10
- For operations with partial dependencies, use `better-all` to maximize parallelism. It automatically starts each task at the earliest possible moment.
10
+ 부분적인 의존성이 있는 작업의 경우 `better-all`을 사용하여 병렬성을 최대화합니다. 작업을 가능한 가장 빠른 시점에 자동으로 시작합니다.
11
11
 
12
- **Incorrect (profile waits for config unnecessarily):**
12
+ **❌ 잘못된 예시 (profile 불필요하게 config 기다림):**
13
13
 
14
14
  ```typescript
15
15
  const [user, config] = await Promise.all([
@@ -19,7 +19,7 @@ const [user, config] = await Promise.all([
19
19
  const profile = await fetchProfile(user.id)
20
20
  ```
21
21
 
22
- **Correct (config and profile run in parallel):**
22
+ **✅ 올바른 예시 (config profile 병렬로 실행):**
23
23
 
24
24
  ```typescript
25
25
  import { all } from 'better-all'
@@ -33,4 +33,4 @@ const { user, config, profile } = await all({
33
33
  })
34
34
  ```
35
35
 
36
- Reference: [https://github.com/shuding/better-all](https://github.com/shuding/better-all)
36
+ 참고: [https://github.com/shuding/better-all](https://github.com/shuding/better-all)