@wooojin/forgen 0.2.0 → 0.3.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 (158) hide show
  1. package/CHANGELOG.md +72 -0
  2. package/README.ja.md +79 -14
  3. package/README.ko.md +100 -14
  4. package/README.md +124 -17
  5. package/README.zh.md +79 -14
  6. package/agents/analyst.md +48 -4
  7. package/agents/architect.md +39 -4
  8. package/agents/code-reviewer.md +107 -77
  9. package/agents/critic.md +47 -4
  10. package/agents/debugger.md +46 -4
  11. package/agents/designer.md +40 -4
  12. package/agents/executor.md +112 -30
  13. package/agents/explore.md +45 -5
  14. package/agents/git-master.md +48 -4
  15. package/agents/planner.md +121 -18
  16. package/agents/test-engineer.md +58 -4
  17. package/agents/verifier.md +92 -77
  18. package/commands/architecture-decision.md +127 -258
  19. package/commands/calibrate.md +225 -0
  20. package/commands/code-review.md +163 -178
  21. package/commands/compound.md +127 -68
  22. package/commands/deep-interview.md +273 -0
  23. package/commands/docker.md +68 -178
  24. package/commands/forge-loop.md +215 -0
  25. package/commands/learn.md +231 -0
  26. package/commands/retro.md +215 -0
  27. package/commands/ship.md +277 -0
  28. package/dist/cli.js +26 -9
  29. package/dist/core/auto-compound-runner.js +14 -0
  30. package/dist/core/config-injector.d.ts +2 -1
  31. package/dist/core/config-injector.js +2 -1
  32. package/dist/core/dashboard.d.ts +108 -0
  33. package/dist/core/dashboard.js +495 -0
  34. package/dist/core/doctor.js +151 -21
  35. package/dist/core/drift-score.d.ts +49 -0
  36. package/dist/core/drift-score.js +87 -0
  37. package/dist/core/harness.d.ts +6 -1
  38. package/dist/core/harness.js +75 -19
  39. package/dist/core/mcp-config.d.ts +2 -0
  40. package/dist/core/mcp-config.js +6 -1
  41. package/dist/core/paths.d.ts +6 -1
  42. package/dist/core/paths.js +18 -2
  43. package/dist/core/spawn.d.ts +3 -2
  44. package/dist/core/spawn.js +27 -8
  45. package/dist/core/types.d.ts +34 -0
  46. package/dist/engine/compound-export.d.ts +41 -0
  47. package/dist/engine/compound-export.js +169 -0
  48. package/dist/engine/compound-lifecycle.d.ts +4 -3
  49. package/dist/engine/compound-lifecycle.js +91 -46
  50. package/dist/engine/compound-loop.js +18 -0
  51. package/dist/engine/meta-learning/adaptive-thresholds.d.ts +20 -0
  52. package/dist/engine/meta-learning/adaptive-thresholds.js +126 -0
  53. package/dist/engine/meta-learning/extraction-tuner.d.ts +15 -0
  54. package/dist/engine/meta-learning/extraction-tuner.js +99 -0
  55. package/dist/engine/meta-learning/matcher-weight-tuner.d.ts +21 -0
  56. package/dist/engine/meta-learning/matcher-weight-tuner.js +151 -0
  57. package/dist/engine/meta-learning/runner.d.ts +14 -0
  58. package/dist/engine/meta-learning/runner.js +90 -0
  59. package/dist/engine/meta-learning/scope-promoter.d.ts +21 -0
  60. package/dist/engine/meta-learning/scope-promoter.js +84 -0
  61. package/dist/engine/meta-learning/session-quality-scorer.d.ts +61 -0
  62. package/dist/engine/meta-learning/session-quality-scorer.js +166 -0
  63. package/dist/engine/meta-learning/types.d.ts +114 -0
  64. package/dist/engine/meta-learning/types.js +43 -0
  65. package/dist/engine/solution-format.d.ts +2 -2
  66. package/dist/engine/solution-format.js +249 -34
  67. package/dist/engine/solution-index.d.ts +1 -1
  68. package/dist/engine/solution-matcher.d.ts +30 -1
  69. package/dist/engine/solution-matcher.js +235 -45
  70. package/dist/fgx.js +12 -8
  71. package/dist/hooks/context-guard.d.ts +15 -0
  72. package/dist/hooks/context-guard.js +218 -56
  73. package/dist/hooks/db-guard.js +2 -2
  74. package/dist/hooks/hook-config.d.ts +27 -1
  75. package/dist/hooks/hook-config.js +72 -12
  76. package/dist/hooks/hooks-generator.d.ts +3 -0
  77. package/dist/hooks/hooks-generator.js +23 -6
  78. package/dist/hooks/intent-classifier.d.ts +0 -2
  79. package/dist/hooks/intent-classifier.js +32 -18
  80. package/dist/hooks/keyword-detector.js +126 -204
  81. package/dist/hooks/notepad-injector.js +2 -2
  82. package/dist/hooks/permission-handler.js +2 -2
  83. package/dist/hooks/post-tool-failure.js +12 -6
  84. package/dist/hooks/post-tool-handlers.d.ts +1 -1
  85. package/dist/hooks/post-tool-handlers.js +14 -11
  86. package/dist/hooks/post-tool-use.d.ts +11 -0
  87. package/dist/hooks/post-tool-use.js +184 -71
  88. package/dist/hooks/pre-compact.d.ts +11 -1
  89. package/dist/hooks/pre-compact.js +112 -37
  90. package/dist/hooks/pre-tool-use.js +86 -56
  91. package/dist/hooks/rate-limiter.js +3 -3
  92. package/dist/hooks/secret-filter.js +2 -2
  93. package/dist/hooks/session-recovery.js +256 -236
  94. package/dist/hooks/shared/hook-response.d.ts +4 -4
  95. package/dist/hooks/shared/hook-response.js +13 -24
  96. package/dist/hooks/shared/hook-timing.d.ts +15 -0
  97. package/dist/hooks/shared/hook-timing.js +64 -0
  98. package/dist/hooks/skill-injector.d.ts +4 -3
  99. package/dist/hooks/skill-injector.js +47 -16
  100. package/dist/hooks/slop-detector.js +3 -3
  101. package/dist/hooks/solution-injector.js +224 -197
  102. package/dist/hooks/subagent-tracker.js +2 -2
  103. package/dist/host/codex-adapter.d.ts +10 -0
  104. package/dist/host/codex-adapter.js +154 -0
  105. package/dist/mcp/solution-reader.d.ts +5 -5
  106. package/dist/mcp/solution-reader.js +34 -24
  107. package/dist/renderer/rule-renderer.js +9 -11
  108. package/dist/services/session.d.ts +19 -0
  109. package/dist/services/session.js +62 -0
  110. package/hooks/hooks.json +2 -2
  111. package/package.json +2 -1
  112. package/skills/architecture-decision/SKILL.md +113 -257
  113. package/skills/calibrate/SKILL.md +207 -0
  114. package/skills/code-review/SKILL.md +151 -178
  115. package/skills/compound/SKILL.md +126 -68
  116. package/skills/deep-interview/SKILL.md +266 -0
  117. package/skills/docker/SKILL.md +57 -179
  118. package/skills/forge-loop/SKILL.md +198 -0
  119. package/skills/learn/SKILL.md +216 -0
  120. package/skills/retro/SKILL.md +199 -0
  121. package/skills/ship/SKILL.md +259 -0
  122. package/agents/code-simplifier.md +0 -197
  123. package/agents/performance-reviewer.md +0 -172
  124. package/agents/qa-tester.md +0 -158
  125. package/agents/refactoring-expert.md +0 -168
  126. package/agents/scientist.md +0 -144
  127. package/agents/security-reviewer.md +0 -137
  128. package/agents/writer.md +0 -184
  129. package/commands/api-design.md +0 -268
  130. package/commands/ci-cd.md +0 -270
  131. package/commands/database.md +0 -263
  132. package/commands/debug-detective.md +0 -99
  133. package/commands/documentation.md +0 -276
  134. package/commands/ecomode.md +0 -51
  135. package/commands/frontend.md +0 -271
  136. package/commands/git-master.md +0 -90
  137. package/commands/incident-response.md +0 -292
  138. package/commands/migrate.md +0 -101
  139. package/commands/performance.md +0 -288
  140. package/commands/refactor.md +0 -105
  141. package/commands/security-review.md +0 -288
  142. package/commands/tdd.md +0 -183
  143. package/commands/testing-strategy.md +0 -265
  144. package/skills/api-design/SKILL.md +0 -262
  145. package/skills/ci-cd/SKILL.md +0 -264
  146. package/skills/database/SKILL.md +0 -257
  147. package/skills/debug-detective/SKILL.md +0 -95
  148. package/skills/documentation/SKILL.md +0 -270
  149. package/skills/ecomode/SKILL.md +0 -46
  150. package/skills/frontend/SKILL.md +0 -265
  151. package/skills/git-master/SKILL.md +0 -86
  152. package/skills/incident-response/SKILL.md +0 -286
  153. package/skills/migrate/SKILL.md +0 -96
  154. package/skills/performance/SKILL.md +0 -282
  155. package/skills/refactor/SKILL.md +0 -100
  156. package/skills/security-review/SKILL.md +0 -282
  157. package/skills/tdd/SKILL.md +0 -178
  158. package/skills/testing-strategy/SKILL.md +0 -260
@@ -0,0 +1,273 @@
1
+ ---
2
+ name: deep-interview
3
+ description: This skill should be used when the user asks to "deep-interview,딥인터뷰,심층인터뷰,deep interview". Deep requirement interview with weighted dimension scoring, challenge modes, and ontology tracking
4
+ argument-hint: "[project or feature description]"
5
+ triggers:
6
+ - "deep-interview"
7
+ - "딥인터뷰"
8
+ - "심층인터뷰"
9
+ - "deep interview"
10
+ - "요구사항 인터뷰"
11
+ ---
12
+
13
+ <Purpose>
14
+ 프로젝트의 요구사항을 체계적으로 심층 인터뷰하여 모호성을 제거합니다.
15
+ 가중 차원 점수(Weighted Dimension Scoring)로 모호성을 정량화하고,
16
+ 한 번에 하나의 질문만 던져 깊이 있는 답변을 이끌어냅니다.
17
+ 목표: ambiguity <= 0.20 (20% 이하)까지 인터뷰를 진행합니다.
18
+ </Purpose>
19
+
20
+ <Compound_Integration>
21
+ ## 시작 전: compound-search로 이전 인터뷰 검색
22
+
23
+ 인터뷰 시작 전 반드시 compound-search MCP 도구로 유사한 프로젝트의 이전 인터뷰를 검색합니다.
24
+
25
+ ```
26
+ compound-search("[프로젝트명 또는 핵심 도메인 키워드]")
27
+ ```
28
+
29
+ 검색 결과가 있으면 인터뷰 시작 시 표시합니다:
30
+
31
+ ```
32
+ 이전 인터뷰 발견:
33
+ - [프로젝트명]: [핵심 토픽] (최종 ambiguity: 0.XX)
34
+ - 재사용 가능한 결정사항: [패턴/결론]
35
+ - 이전 인터뷰에서 해결된 항목은 이번에 건너뜁니다.
36
+ ```
37
+
38
+ ## 진행 중: 관련 compound 솔루션 로드
39
+
40
+ 질문 주제와 관련된 compound 솔루션이 있으면 더 정확한 질문을 구성합니다.
41
+
42
+ ## 종료 후: 인터뷰 결과를 compound로 저장
43
+
44
+ ```bash
45
+ forgen compound --solution "interview-{project}-spec" "인터뷰 결과 명세서 전문"
46
+ ```
47
+ </Compound_Integration>
48
+
49
+ <Steps>
50
+ ## Phase 0: 프로젝트 유형 감지
51
+
52
+ 사용자 요청을 분석하여 프로젝트 유형을 자동 판별합니다.
53
+
54
+ ### Greenfield (새 프로젝트)
55
+ - 채점 공식: `ambiguity = 1 - (goal * 0.40 + constraints * 0.30 + criteria * 0.30)`
56
+
57
+ ### Brownfield (기존 코드베이스 확장/수정)
58
+ - Glob/Grep/Read로 기존 코드베이스를 탐색하여 기술 컨텍스트를 자동 수집
59
+ - 채점 공식: `ambiguity = 1 - (goal * 0.35 + constraints * 0.25 + criteria * 0.25 + context * 0.15)`
60
+
61
+ ### 자동 감지 절차
62
+ ```
63
+ 1. 현재 디렉토리에 package.json, tsconfig.json, go.mod 등이 있는가?
64
+ 2. git log가 존재하는가?
65
+ 3. 사용자 요청에 "기존", "현재", "수정", "추가" 등의 키워드가 있는가?
66
+ → 2개 이상 해당하면 Brownfield → 아니면 Greenfield
67
+ ```
68
+
69
+ ## Phase 1: 차원 초기 채점
70
+
71
+ 각 차원을 0.0 ~ 1.0 범위로 채점합니다 (1.0 = 완전히 명확, 0.0 = 전혀 모름).
72
+
73
+ ### Greenfield 차원 (3개)
74
+ | 차원 | 가중치 | 의미 |
75
+ |------|--------|------|
76
+ | **goal** | 0.40 | 무엇을 만드는가? 최종 산출물은? 성공 기준은? |
77
+ | **constraints** | 0.30 | 기술 제약, 시간, 예산, 팀 역량, 비기능 요구사항 |
78
+ | **criteria** | 0.30 | 완료 기준, 수용 기준, 테스트 가능한 조건 |
79
+
80
+ ### Brownfield 추가 차원 (1개)
81
+ | 차원 | 가중치 | 의미 |
82
+ |------|--------|------|
83
+ | **context** | 0.15 | 기존 아키텍처, 의존성, 코드 패턴, 데이터 모델 |
84
+
85
+ ### 채점 기준 상세
86
+
87
+ **goal (가중치 0.40)**
88
+ - 최종 산출물이 명확한가? (0.0~1.0)
89
+ - 핵심 기능이 열거되었는가? (0.0~1.0)
90
+ - 사용자/대상이 특정되었는가? (0.0~1.0)
91
+ - 비즈니스 근거(왜 만드는가)가 있는가? (0.0~1.0)
92
+
93
+ **constraints (가중치 0.30)**
94
+ - 기술 스택이 결정되었는가? (0.0~1.0)
95
+ - 비기능 요구사항이 정의되었는가? (0.0~1.0)
96
+ - 일정/예산 제약이 있는가? (0.0~1.0)
97
+ - 외부 연동/의존성이 파악되었는가? (0.0~1.0)
98
+
99
+ **criteria (가중치 0.30)**
100
+ - 수용 기준이 테스트 가능한 형태인가? (0.0~1.0)
101
+ - 엣지 케이스가 고려되었는가? (0.0~1.0)
102
+ - 비정상 시나리오 대응이 정의되었는가? (0.0~1.0)
103
+
104
+ **context (가중치 0.15, Brownfield만)**
105
+ - 기존 아키텍처를 파악했는가? (0.0~1.0)
106
+ - 영향받는 모듈/파일을 식별했는가? (0.0~1.0)
107
+ - 기존 테스트 커버리지를 확인했는가? (0.0~1.0)
108
+ - 기존 코드 패턴을 이해했는가? (0.0~1.0)
109
+
110
+ ## Phase 2: 인터뷰 루프 (라운드 기반)
111
+
112
+ ### 질문 프로토콜 -- 반드시 한 번에 하나의 질문만
113
+
114
+ 매 라운드마다:
115
+ 1. **가장 약한 차원 식별**: 가중 점수가 가장 낮은 차원을 선택
116
+ 2. **질문 하나만 생성**: 해당 차원의 점수를 가장 효과적으로 올릴 수 있는 질문
117
+ 3. **표시 형식**:
118
+ ```
119
+ Round N | ambiguity: 0.XX | 목표 차원: {dimension}
120
+ ─────────────────────────────────────────────────
121
+ Q. [구체적이고 개방형 질문]
122
+ (이 답변으로 {dimension} 점수 +0.X 예상)
123
+ ```
124
+ 4. **답변 수신 후**: 점수 재산정 -> 보드 갱신 -> 다음 라운드
125
+
126
+ ### Push Until Evidence 규칙
127
+
128
+ 모호한 답변("대충", "아마", "비슷한") → 같은 차원에서 후속 질문.
129
+ 가정 기반 답변("아마 ~일 거예요") → "확인된 사실인가요, 검증이 필요한 가정인가요?"
130
+ 범위 미정 답변("다 되면 좋겠어요") → "MVP 범위에서 반드시 포함해야 하는 3가지는?"
131
+
132
+ ## Phase 3: 챌린지 모드 (라운드 기반 자동 활성화)
133
+
134
+ ### Round 4+: Contrarian (반론 모드)
135
+ "만약 정반대가 사실이라면?" — 사용자의 전제를 뒤집어 검증합니다.
136
+
137
+ ### Round 6+: Simplifier (단순화 모드)
138
+ "가장 단순하면서도 가치있는 버전은?" — 불필요한 복잡성을 제거합니다.
139
+
140
+ ### Round 8+ (ambiguity > 0.30): Ontologist (본질 탐구 모드)
141
+ "이것은 본질적으로 무엇인가요?" — 핵심 엔티티의 정의와 경계를 명확히 합니다.
142
+
143
+ ## Phase 4: 온톨로지 추적
144
+
145
+ 매 라운드마다 핵심 엔티티(명사)를 추적합니다.
146
+ ```
147
+ ONTOLOGY TRACKER
148
+ ──────────────────────────────────────
149
+ Entity | First | Last | Status
150
+ User | R1 | R5 | stable
151
+ Order | R1 | R6 | refined
152
+ ──────────────────────────────────────
153
+ Stability: 3/4 (75%)
154
+ ```
155
+ - stability_ratio >= 0.90: 도메인 모델 안정 -> 종료 가능
156
+ - stability_ratio < 0.70: 유동적 -> 본질 질문 필요
157
+ </Steps>
158
+
159
+ ## 반아첨(Anti-Sycophancy) 규칙
160
+
161
+ | 금지 표현 | 대체 행동 |
162
+ |-----------|-----------|
163
+ | "좋은 접근이네요" | 입장을 취합니다. 근거와 함께 동의 또는 반대. |
164
+ | "그것도 될 수 있어요" | 근거를 바탕으로 된다/안 된다 판단. |
165
+ | "고려해 보시면..." | "이것은 틀렸습니다. 이유는..." 또는 "이것이 맞습니다. 이유는..." |
166
+ | "흥미로운 접근이네요" | "이 접근은 {구체적 이유}로 {성공/실패}할 것입니다." |
167
+
168
+ 사용자가 틀렸으면 틀렸다고 말합니다. 근거를 함께 제시합니다.
169
+
170
+ ## Ambiguity Score 보드
171
+
172
+ ```
173
+ DEEP INTERVIEW BOARD
174
+ ═══════════════════════════════════════════════════
175
+ Project: {name} | Type: {Greenfield/Brownfield}
176
+ Round: {N} | Ambiguity: {0.XX} | Target: <= 0.20
177
+
178
+ DIMENSION SCORES
179
+ ────────────────────────────────────────────────────
180
+ Dimension Weight Score Weighted Trend
181
+ goal 0.40 0.75 0.300 0.2->0.5->0.75 ++
182
+ constraints 0.30 0.50 0.150 0.1->0.50 +
183
+ criteria 0.30 0.30 0.090 0.3 NEW
184
+ ────────────────────────────────────────────────────
185
+ Clarity: 0.540 | Ambiguity: 0.460 | Status: Continue
186
+
187
+ ONTOLOGY ({N} entities, {stability}% stable)
188
+ ACTIVE CHALLENGE: {None / CONTRARIAN / SIMPLIFIER / ONTOLOGIST}
189
+ ═══════════════════════════════════════════════════
190
+ ```
191
+
192
+ ## 종료 조건
193
+
194
+ | 조건 | 기준 |
195
+ |------|------|
196
+ | **Ready** | ambiguity <= 0.20 |
197
+ | **Conditional** | 0.20 < ambiguity <= 0.35 |
198
+ | **User Exit** | 사용자 요청 (경고 표시 후 종료) |
199
+ | **Plateau** | 3라운드 연속 변화 < 0.05 -> Ontologist 전환 |
200
+ | **Hard Cap** | 20라운드 도달 -> 강제 종료 |
201
+
202
+ 라운드 제한: 최소 3, 소프트 캡 10, 하드 캡 20.
203
+
204
+ ## 실행 브릿지
205
+
206
+ ```
207
+ ambiguity <= 0.20 -> "준비 완료. 권장: /forge-loop"
208
+ ambiguity 0.20~0.35 -> "가정 목록 확인 필요. 확인 후 /forge-loop"
209
+ ambiguity > 0.35 -> "인터뷰 계속 필요."
210
+ ```
211
+
212
+ ## 최종 명세서 형식
213
+
214
+ ```markdown
215
+ # Deep Interview Spec: {title}
216
+ ## Metadata (rounds, score, type, timestamp)
217
+ ## Clarity Breakdown (dimension scores table)
218
+ ## Goal
219
+ ## Constraints
220
+ ## Non-Goals
221
+ ## Acceptance Criteria (testable)
222
+ ## Assumptions (exposed & resolved)
223
+ ## Technical Context
224
+ ## Key Entities (ontology table)
225
+ ## Ontology Convergence (round-by-round stability)
226
+ ## Next Action: /forge-loop | /ch-architecture-decision | manual
227
+ ```
228
+
229
+ <Failure_Modes>
230
+ ## 피해야 할 실패 패턴
231
+
232
+ NEVER: **한 번에 여러 질문**: 질문은 반드시 1개. 2개 이상 금지.
233
+
234
+ NEVER: **코드에서 답을 찾을 수 있는 것을 질문**: Brownfield에서 Read/Grep으로 먼저 확인.
235
+
236
+ NEVER: **보드 갱신 누락**: 매 라운드 종료 후 반드시 보드 표시.
237
+
238
+ NEVER: **아첨/동의 기본값**: 근거 없는 동의 금지. 모든 판단에 근거 필요.
239
+
240
+ NEVER: **모호한 답변 수용**: Push Until Evidence 규칙 적용.
241
+
242
+ NEVER: **3라운드 전 종료**: 경고 표시 필수.
243
+
244
+ NEVER: **챌린지 모드 건너뛰기**: Round 4+ 이후 반드시 적용.
245
+ </Failure_Modes>
246
+
247
+ <Policy>
248
+ - 라운드당 질문은 반드시 1개만 (깊이 > 넓이)
249
+ - 가장 낮은 가중 점수의 차원부터 공략
250
+ - 답변 후 즉시 점수 재산정 + 보드 갱신
251
+ - 사용자가 "모르겠다" -> 해당 요소 0.0 유지, 다음 질문
252
+ - 기술적 판단 가능한 항목 -> 합리적 가정 제안
253
+ - 비즈니스 판단 필요 항목 -> 반드시 사용자 확인
254
+ - Anti-Sycophancy 규칙 준수
255
+ - Brownfield -> 코드 탐색 선행, context 차원 자동 채점
256
+ - 온톨로지 추적 매 라운드 수행
257
+ </Policy>
258
+
259
+ <Arguments>
260
+ ## 사용법
261
+ `deep-interview {프로젝트 또는 기능 설명}`
262
+
263
+ ### 예시
264
+ - `deep-interview 이커머스 플랫폼 MVP`
265
+ - `deep-interview 사내 HR 시스템 리뉴얼`
266
+ - `deep-interview 실시간 채팅 기능 추가`
267
+
268
+ ### 인자
269
+ - 인터뷰할 프로젝트 또는 기능의 자연어 설명
270
+ - 기존 코드베이스가 있으면 Brownfield로 자동 전환
271
+ </Arguments>
272
+
273
+ $ARGUMENTS
@@ -1,6 +1,17 @@
1
1
  ---
2
2
  name: docker
3
- description: This skill should be used when the user asks to "docker,container,컨테이너,dockerfile,도커,docker-compose". Containerization with Docker, Dockerfile optimization, and compose configuration
3
+ description: This skill should be used when the user asks to "docker,container,컨테이너,dockerfile,도커,docker-compose". Docker 컨테이너화 -- Dockerfile 최적화, Compose 구성, 보안 강화
4
+ argument-hint: "[컨테이너화 대상]"
5
+ model: sonnet
6
+ allowed-tools:
7
+ - Read
8
+ - Grep
9
+ - Glob
10
+ - Bash
11
+ - Write
12
+ - Edit
13
+ - mcp__forgen-compound__compound-search
14
+ - mcp__forgen-compound__compound-read
4
15
  triggers:
5
16
  - "docker"
6
17
  - "container"
@@ -9,7 +20,6 @@ triggers:
9
20
  - "도커"
10
21
  - "docker-compose"
11
22
  ---
12
- <!-- forgen-managed -->
13
23
 
14
24
  <Purpose>
15
25
  Docker를 활용한 컨테이너화를 체계적으로 수행합니다.
@@ -17,107 +27,35 @@ Docker를 활용한 컨테이너화를 체계적으로 수행합니다.
17
27
  Docker Compose 구성, 헬스 체크까지 컨테이너 라이프사이클 전체를 다룹니다.
18
28
  </Purpose>
19
29
 
20
- <Steps>
21
- 1. **의존성 분석**: 애플리케이션의 런타임 요구사항을 파악합니다
22
- - 런타임 환경 (Node.js, Python, Go 등)
23
- - 시스템 의존성 (네이티브 바이너리, 라이브러리)
24
- - 환경 변수 목록 및 기본값
25
- - 포트 매핑 (애플리케이션 포트, 디버그 포트)
26
- - 볼륨 마운트 필요 사항 (데이터 영속성, 설정 파일)
27
- - 외부 서비스 의존성 (DB, Redis, 메시지 큐)
28
-
29
- 2. **Dockerfile 작성**: 최적화된 Dockerfile을 구성합니다
30
- - 베이스 이미지 선택 (alpine vs slim vs distroless)
31
- - 멀티스테이지 빌드 적용 (빌드 스테이지 / 런타임 스테이지)
32
- - 레이어 캐싱 최적화 (변경 빈도 낮은 것부터 순서)
33
- * 시스템 의존성 설치
34
- * package.json / lockfile 복사 + npm install
35
- * 소스 코드 복사 + 빌드
36
- - .dockerignore 설정 (node_modules, .git, 테스트 파일)
37
- - 비루트 사용자 설정 (보안)
38
- - 시그널 핸들링 (SIGTERM graceful shutdown)
39
- - HEALTHCHECK 명령 설정
40
-
41
- 3. **이미지 최적화**: 이미지 크기와 보안을 개선합니다
42
- - 레이어 수 최소화 (RUN 명령 결합)
43
- - 불필요한 파일 제거 (빌드 도구, 캐시, 문서)
44
- - 프로덕션 의존성만 설치 (--omit=dev)
45
- - 이미지 크기 측정 및 목표 설정
46
- - 보안 스캔 (Trivy, Docker Scout)
47
- - 이미지 태깅 전략 (semver, git SHA, latest)
30
+ <Compound_Integration>
31
+ ## 시작 전: 이전 Docker 구성 패턴 검색
48
32
 
49
- 4. **Docker Compose 구성**: 멀티 컨테이너 환경을 정의합니다
50
- - 서비스 정의 (app, db, cache, proxy)
51
- - 네트워크 구성 (서비스 간 통신)
52
- - 볼륨 정의 (데이터 영속성)
53
- - 환경 변수 관리 (.env 파일, 인라인)
54
- - 의존성 순서 (depends_on + healthcheck)
55
- - 개발/프로덕션 오버라이드 분리
56
- - 리소스 제한 설정 (CPU, 메모리)
57
-
58
- 5. **헬스 체크 및 모니터링**: 컨테이너 상태를 관리합니다
59
- - HEALTHCHECK 엔드포인트 구현 (/health, /ready)
60
- - Liveness probe vs Readiness probe 구분
61
- - 로그 수집 구성 (stdout/stderr → 로그 시스템)
62
- - 메트릭 노출 (Prometheus 엔드포인트)
63
- - Graceful shutdown 구현 (SIGTERM 처리)
64
- - 재시작 정책 설정 (restart: unless-stopped)
65
- </Steps>
66
-
67
- ## 에이전트 위임
68
-
69
- `executor` 에이전트(Sonnet 모델)에 위임하여 Docker 구성을 구현합니다:
33
+ 컨테이너화를 시작하기 전에 compound-search MCP 도구로 유사한 런타임/애플리케이션의 과거 Docker 구성을 검색합니다.
70
34
 
71
35
  ```
72
- Agent(
73
- subagent_type="executor",
74
- model="sonnet",
75
- prompt="DOCKER TASK
76
-
77
- Docker 컨테이너화를 구현하세요.
78
-
79
- Application: [애플리케이션 설명]
80
- Runtime: [Node.js / Python / Go / etc.]
81
- Services: [필요한 외부 서비스 목록]
82
-
83
- Docker Checklist:
84
- 1. Dockerfile 작성 (멀티스테이지, 최적화)
85
- 2. .dockerignore 설정
86
- 3. Docker Compose 구성 (개발/프로덕션)
87
- 4. 헬스 체크 설정
88
- 5. 보안 설정 (비루트 사용자, 이미지 스캔)
89
- 6. 볼륨 및 네트워크 구성
90
-
91
- Output: Docker 구성 파일 및 문서:
92
- - Dockerfile
93
- - .dockerignore
94
- - docker-compose.yml (dev/prod)
95
- - 이미지 크기 리포트
96
- - 실행 명령 가이드"
97
- )
36
+ compound-search("[런타임명 또는 애플리케이션 타입 키워드]")
37
+ compound-search("Docker 최적화")
98
38
  ```
99
39
 
100
- ## External Consultation (Optional)
101
-
102
- executor 에이전트는 교차 검증을 위해 Claude Task 에이전트에 자문할 수 있습니다.
103
-
104
- ### Protocol
105
- 1. **자체 Docker 구성을 먼저 완료** -- 독립적으로 구현
106
- 2. **검증을 위한 자문** -- Claude Task 에이전트를 통해 구성 교차 확인
107
- 3. **비판적 평가** -- 외부 제안을 맹목적으로 수용하지 않음
108
- 4. **우아한 폴백** -- 위임이 불가능할 경우 절대 차단하지 않음
40
+ 검색 결과가 있으면 의존성 분석 단계 전에 표시합니다:
41
+ ```
42
+ 이전 Docker 구성 패턴:
43
+ - [애플리케이션명]: [베이스 이미지] → 최종 크기 [N]MB (날짜: YYYY-MM-DD)
44
+ - 주요 최적화: [레이어 전략, 보안 설정 등]
45
+ - 주의사항: [이전에 발견된 문제나 트릭]
46
+ ```
109
47
 
110
- ### 자문이 필요한 경우
111
- - 복잡한 멀티스테이지 빌드
112
- - 프로덕션 수준의 보안 강화
113
- - 오케스트레이션 (Kubernetes 연동)
114
- - 네이티브 의존성이 있는 이미지 최적화
48
+ 이전 구성을 출발점으로 삼아 중복 탐색을 줄이고, 검증된 패턴을 재사용합니다.
49
+ 완료 주요 최적화 내용과 이미지 크기를 compound에 기록합니다.
50
+ </Compound_Integration>
115
51
 
116
- ### 자문을 생략하는 경우
117
- - 단순 Node.js/Python 컨테이너화
118
- - 개발 환경용 Docker Compose
119
- - 알려진 이미지 패턴
120
- - 기존 Dockerfile의 경미한 수정
52
+ <Steps>
53
+ 1. **의존성 분석**: 런타임 환경, 시스템 의존성, 포트, 볼륨, 외부 서비스
54
+ 2. **Dockerfile 작성**: 멀티스테이지, 레이어 캐싱, 비루트 사용자, HEALTHCHECK
55
+ 3. **이미지 최적화**: 레이어 최소화, 프로덕션 의존성만, 보안 스캔, 크기 측정
56
+ 4. **Docker Compose 구성**: 서비스, 네트워크, 볼륨, 환경 변수, 오버라이드
57
+ 5. **헬스 체크 및 모니터링**: probe, 로그 수집, graceful shutdown, 재시작 정책
58
+ </Steps>
121
59
 
122
60
  ## Docker 체크리스트
123
61
 
@@ -129,11 +67,12 @@ executor 에이전트는 교차 검증을 위해 Claude Task 에이전트에 자
129
67
  - [ ] 레이어 캐싱이 최적화됨
130
68
  - [ ] HEALTHCHECK가 설정됨
131
69
 
132
- ### 보안 (4개)
70
+ ### 보안 (5개)
133
71
  - [ ] 이미지 취약점 스캔 완료
134
72
  - [ ] 최소 권한 원칙 적용 (비루트, 읽기 전용 파일시스템)
135
- - [ ] 시크릿이 이미지에 포함되지 않음
73
+ - [ ] 시크릿이 이미지에 포함되지 않음 (ENV, ARG, COPY 모두 확인)
136
74
  - [ ] 불필요한 도구/패키지가 제거됨
75
+ - [ ] 빌드 시 민감 레이어 캐시 방지
137
76
 
138
77
  ### 운영 (4개)
139
78
  - [ ] Graceful shutdown이 구현됨 (SIGTERM)
@@ -154,7 +93,28 @@ executor 에이전트는 교차 검증을 위해 Claude Task 에이전트에 자
154
93
  | Node.js | < 150MB | node:20-alpine |
155
94
  | Python | < 200MB | python:3.12-slim |
156
95
  | Go | < 30MB | gcr.io/distroless/static |
157
- | Rust | < 30MB | debian:bookworm-slim (빌드) + scratch (런타임) |
96
+ | Rust | < 30MB | debian:bookworm-slim + scratch |
97
+ | Java | < 250MB | eclipse-temurin:21-jre-alpine |
98
+
99
+ <Failure_Modes>
100
+ ## 피해야 할 실패 패턴
101
+
102
+ ### 이미지 빌드
103
+ - **:latest 태그 사용**: 빌드 재현 불가능. 항상 `node:20.11.1-alpine3.19` 같이 고정.
104
+ - **단일 스테이지**: 빌드 도구가 런타임에 포함됨. 멀티스테이지 필수.
105
+ - **레이어 순서 오류**: 소스 코드를 lockfile보다 먼저 배치하면 캐시 무효화.
106
+
107
+ ### 보안
108
+ - **root 실행**: `USER` 지시어 없이 실행. 컨테이너 탈출 시 호스트 루트 권한 획득 위험.
109
+ - **시크릿 하드코딩**: ENV/ARG/RUN에 시크릿 포함. BuildKit `--mount=type=secret` 사용.
110
+ - **ARG로 시크릿 전달**: 중간 레이어에 남음. BuildKit secret mount 사용.
111
+
112
+ ### 구성
113
+ - **.dockerignore 누락**: node_modules, .git, .env가 이미지에 포함됨.
114
+ - **SIGTERM 미처리**: 10초 후 SIGKILL로 강제 종료. 데이터 손실 가능.
115
+ - **HEALTHCHECK 누락**: 애플리케이션 응답 불능 상태 미감지.
116
+ - **Compose 비밀번호 하드코딩**: .env 파일 또는 Docker secrets 사용.
117
+ </Failure_Modes>
158
118
 
159
119
  <Output>
160
120
  ```
@@ -166,95 +126,25 @@ Runtime: [Node.js 20]
166
126
  Image Size: [최종 이미지 크기]
167
127
 
168
128
  DOCKERFILE / Dockerfile
169
- -------------------------
170
- # Build stage
171
- FROM node:20-alpine AS builder
172
- WORKDIR /app
173
- COPY package*.json ./
174
- RUN npm ci --omit=dev
175
- COPY . .
176
- RUN npm run build
177
-
178
- # Runtime stage
179
- FROM node:20-alpine AS runtime
180
- RUN addgroup -g 1001 -S appgroup && \
181
- adduser -S appuser -u 1001 -G appgroup
182
- WORKDIR /app
183
- COPY --from=builder --chown=appuser:appgroup /app/dist ./dist
184
- COPY --from=builder --chown=appuser:appgroup /app/node_modules ./node_modules
185
- USER appuser
186
- EXPOSE 3000
187
- HEALTHCHECK --interval=30s --timeout=3s \
188
- CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
189
- CMD ["node", "dist/index.js"]
190
-
191
129
  DOCKER COMPOSE / docker-compose.yml
192
- --------------------------------------
193
- services:
194
- app:
195
- build: .
196
- ports: ["3000:3000"]
197
- depends_on:
198
- db: { condition: service_healthy }
199
- environment:
200
- DATABASE_URL: postgres://user:pass@db:5432/app
201
- db:
202
- image: postgres:16-alpine
203
- volumes: ["pgdata:/var/lib/postgresql/data"]
204
- healthcheck:
205
- test: ["CMD-SHELL", "pg_isready"]
206
-
207
130
  IMAGE ANALYSIS / 이미지 분석
208
- ------------------------------
209
- Total Size: 142MB
210
- Layers: 8
211
- Base Image: node:20-alpine (45MB)
212
- Dependencies: 85MB
213
- Application: 12MB
214
-
215
131
  SECURITY SCAN / 보안 스캔
216
- ---------------------------
217
- Vulnerabilities: 0 CRITICAL, 0 HIGH, 2 MEDIUM
218
- Recommendation: [조치 사항]
219
132
  ```
220
133
  </Output>
221
134
 
222
135
  <Policy>
223
- - 베이스 이미지에 항상 고정 태그를 사용합니다 (latest 금지)
224
- - 프로덕션 이미지에서 반드시 비루트 사용자로 실행합니다
225
- - 시크릿은 절대 이미지에 포함하지 않습니다 (빌드 시에도)
226
- - 이미지 크기를 정기적으로 모니터링합니다
227
- - 보안 스캔을 CI/CD에 통합하여 취약한 이미지 배포를 차단합니다
228
- - Graceful shutdown 반드시 구현하여 데이터 손실을 방지합니다
136
+ - 베이스 이미지에 항상 고정 태그 사용 (latest 금지)
137
+ - 프로덕션 이미지에서 비루트 사용자 실행 필수
138
+ - 시크릿은 절대 이미지에 포함하지 않음
139
+ - 멀티스테이지 빌드 기본 적용
140
+ - .dockerignore 필수 작성
141
+ - Graceful shutdown 필수 구현
229
142
  </Policy>
230
143
 
231
144
  ## 다른 스킬과의 연동
232
-
233
- **CI/CD 연동:**
234
- ```
235
- /forgen:ci-cd Docker 이미지 빌드 및 푸시 파이프라인
236
- ```
237
- CI에서 Docker 이미지 자동 빌드/배포
238
-
239
- **보안 리뷰 연동:**
240
- ```
241
- /forgen:security-review Dockerfile 및 이미지
242
- ```
243
- Docker 구성의 보안 취약점 점검
244
-
245
- **성능 연동:**
246
- ```
247
- /forgen:performance 컨테이너 리소스 사용량 분석
248
- ```
249
- 컨테이너의 리소스 최적화
250
-
251
- ## Best Practices
252
-
253
- - **작은 이미지** -- 불필요한 것을 빼서 크기를 줄임
254
- - **멀티스테이지** -- 빌드 도구를 런타임에 포함하지 않음
255
- - **캐시 활용** -- 레이어 순서를 변경 빈도 기준으로 정렬
256
- - **보안 우선** -- 비루트, 최소 권한, 시크릿 분리
257
- - **헬스 체크** -- 컨테이너 상태를 자동으로 모니터링
145
+ - `/forgen:ci-cd` -- Docker 이미지 빌드/배포 파이프라인
146
+ - `/forgen:security-review` -- Dockerfile/이미지 보안 점검
147
+ - `/forgen:performance` -- 컨테이너 리소스 최적화
258
148
 
259
149
  <Arguments>
260
150
  ## 사용법