uctm 1.5.0 → 1.5.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 (40) hide show
  1. package/.claude-plugin/plugin.json +6 -0
  2. package/README.md +1122 -0
  3. package/agents/builder.md +28 -59
  4. package/agents/committer.md +41 -73
  5. package/agents/planner.md +30 -31
  6. package/agents/scheduler.md +40 -58
  7. package/agents/specifier.md +29 -31
  8. package/agents/verifier.md +31 -56
  9. package/bin/cli.mjs +11 -58
  10. package/lib/constants.mjs +14 -11
  11. package/lib/init.mjs +29 -16
  12. package/lib/update.mjs +28 -22
  13. package/package.json +5 -2
  14. package/skills/sdd-pipeline/SKILL.md +8 -6
  15. package/skills/work-pipeline/SKILL.md +31 -8
  16. package/skills/work-status/SKILL.md +2 -2
  17. package/agents/agent-flow.md +0 -279
  18. package/agents/context-policy.md +0 -94
  19. package/agents/file-content-schema.md +0 -249
  20. package/agents/ko/agent-flow.md +0 -231
  21. package/agents/ko/builder.md +0 -164
  22. package/agents/ko/committer.md +0 -202
  23. package/agents/ko/context-policy.md +0 -94
  24. package/agents/ko/file-content-schema.md +0 -249
  25. package/agents/ko/planner.md +0 -161
  26. package/agents/ko/scheduler.md +0 -189
  27. package/agents/ko/shared-prompt-sections.md +0 -250
  28. package/agents/ko/specifier.md +0 -194
  29. package/agents/ko/verifier.md +0 -149
  30. package/agents/ko/work-activity-log.md +0 -47
  31. package/agents/ko/xml-schema.md +0 -109
  32. package/agents/shared-prompt-sections.md +0 -250
  33. package/agents/work-activity-log.md +0 -47
  34. package/agents/xml-schema.md +0 -159
  35. package/skills/sdd-pipeline/references/agent-flow.md +0 -279
  36. package/skills/sdd-pipeline/references/context-policy.md +0 -94
  37. package/skills/sdd-pipeline/references/file-content-schema.md +0 -249
  38. package/skills/sdd-pipeline/references/shared-prompt-sections.md +0 -250
  39. package/skills/sdd-pipeline/references/work-activity-log.md +0 -47
  40. package/skills/sdd-pipeline/references/xml-schema.md +0 -159
@@ -1,249 +0,0 @@
1
- # File Content Schema
2
-
3
- Single source of truth for pipeline artifact file formats.
4
-
5
- ## COMPLIANCE
6
-
7
- | Generated File | Reference Section | Violation Consequence |
8
- |----------------|-------------------|----------------------|
9
- | `PLAN.md` | § 1 | `parsePlanMd()` parsing failure, scheduler inoperable |
10
- | `TASK-XX.md` | § 2 | `parseTaskFilename()` DB registration missed |
11
- | `TASK-XX_progress.md` | § 3 | committer gate FAIL |
12
- | `TASK-XX_result.md` | § 4 | context-handoff missing |
13
- | `TASK-XX_result.md` (direct) | § 5 | result.md recognition failure |
14
- | `PROGRESS.md` | § 6 | scheduler progress tracking inoperable |
15
-
16
- ---
17
-
18
- ## § 0. Requirement.md
19
-
20
- Path: `works/{WORK_ID}/Requirement.md`
21
-
22
- ```markdown
23
- # Requirement — WORK-NN
24
-
25
- ## Original Request
26
- > User's exact input
27
-
28
- ## Functional Requirements
29
- - FR-01: ...
30
- - FR-02: ...
31
-
32
- ## Non-Functional Requirements
33
- - NFR-01: ...
34
-
35
- ## Acceptance Criteria
36
- - [ ] Verifiable criteria
37
- ```
38
-
39
- Created by: Specifier (mandatory for all requests)
40
-
41
- ---
42
-
43
- ## § 1. PLAN.md
44
-
45
- Path: `works/{WORK_ID}/PLAN.md`
46
-
47
- ```markdown
48
- # WORK-01: {title}
49
-
50
- > Created: {YYYY-MM-DD}
51
- > Requirement: {REQ-XXX | user request text}
52
- > Execution-Mode: {direct | pipeline | full}
53
- > Project: {project name}
54
- > Tech Stack: {stack}
55
- > Language: {lang_code}
56
- > Status: PLANNED
57
-
58
- ## Goal
59
- {1-2 sentences}
60
-
61
- ## Task Dependency Graph
62
- {ASCII diagram}
63
-
64
- ## Tasks
65
-
66
- ### TASK-00: {title}
67
- - **Depends on**: (none)
68
- - **Scope**: {description}
69
- - **Files**:
70
- - `path/to/file` — {description}
71
-
72
- ### TASK-01: {title}
73
- - **Depends on**: TASK-00
74
- ```
75
-
76
- Title format: `# WORK-NN: title` — `# PLAN WORK-NN:` is prohibited (`parsePlanMd()` error)
77
-
78
- ---
79
-
80
- ## § 2. TASK-XX.md
81
-
82
- Path: `works/{WORK_ID}/TASK-XX.md`
83
-
84
- > `parseTaskFilename()` regex: `/^TASK-(\d+)\.md$/` — WORK prefix prohibited
85
-
86
- ```markdown
87
- # TASK-XX: {title}
88
-
89
- ## WORK
90
- {WORK_ID}: {WORK title}
91
-
92
- ## Dependencies
93
- - TASK-YY (required)
94
-
95
- ## Scope
96
- {description}
97
-
98
- ## Files
99
- | Path | Action | Description |
100
- |------|--------|-------------|
101
- | `src/file.ts` | CREATE | description |
102
-
103
- ## Acceptance Criteria
104
- - [ ] {criterion}
105
-
106
- ## Verify
107
- ```bash
108
- {verification commands}
109
- ```
110
- ```
111
-
112
- ---
113
-
114
- ## § 3. TASK-XX_progress.md
115
-
116
- Path: `works/{WORK_ID}/TASK-XX_progress.md`
117
-
118
- ```markdown
119
- # TASK-XX Progress
120
-
121
- - Status: {PENDING | STARTED | IN_PROGRESS | COMPLETED}
122
- - Started: {ISO 8601}
123
- - Updated: {ISO 8601}
124
- - Files changed:
125
- - `path/to/file` — {CREATE | MODIFY | DELETE}
126
- ```
127
-
128
- | Timing | Status |
129
- |--------|--------|
130
- | planner template | `PENDING` |
131
- | builder starts | `STARTED` |
132
- | file changes in progress | `IN_PROGRESS` |
133
- | completed | `COMPLETED` |
134
-
135
- committer gate: file exists + `Status: COMPLETED` + Files changed is not empty
136
-
137
- ---
138
-
139
- ## § 4. TASK-XX_result.md (full / pipeline)
140
-
141
- Path: `works/{WORK_ID}/TASK-XX_result.md`
142
-
143
- ```markdown
144
- # TASK-XX Result
145
-
146
- > WORK: {WORK_ID} — {title}
147
- > Completed: {YYYY-MM-DD HH:MM}
148
- > Status: **DONE**
149
-
150
- {## Summary | ## 요약 | ## サマリー}
151
- {1-2 lines}
152
-
153
- {## Completed Checklist | ## 완료 체크리스트 | ## 完了チェックリスト}
154
- - [x] {item}
155
-
156
- {## Verification Results | ## 검증 결과 | ## 検証結果}
157
- - Build: ✅
158
- - Lint: ✅
159
- - Tests: ✅ (N passed)
160
-
161
- {## Files Changed | ## 변경 파일 | ## 変更ファイル}
162
- ### Created
163
- - `path` — {description}
164
-
165
- {## Issues Encountered | ## 발생 이슈 | ## 発生した問題}
166
- None
167
-
168
- {## Notes for Subsequent Tasks | ## 후속 TASK 참고사항 | ## 後続タスクへの注記}
169
- None
170
-
171
- {## Context Handoff | ## 컨텍스트 핸드오프 | ## コンテキスト引き継ぎ}
172
-
173
- ### Builder Context (SUMMARY)
174
- {builder what field 1-3 lines}
175
-
176
- ### Verifier Context (FULL)
177
- {verifier context-handoff 4 fields}
178
- ```
179
-
180
- | Section | en | ko | ja |
181
- |---------|----|----|-----|
182
- | Summary | `## Summary` | `## 요약` | `## サマリー` |
183
- | Completed Checklist | `## Completed Checklist` | `## 완료 체크리스트` | `## 完了チェックリスト` |
184
- | Verification Results | `## Verification Results` | `## 검증 결과` | `## 検証結果` |
185
- | Files Changed | `## Files Changed` | `## 변경 파일` | `## 変更ファイル` |
186
- | Issues Encountered | `## Issues Encountered` | `## 발생 이슈` | `## 発生した問題` |
187
- | Notes for Subsequent Tasks | `## Notes for Subsequent Tasks` | `## 후속 TASK 참고사항` | `## 後続タスクへの注記` |
188
- | Context Handoff | `## Context Handoff` | `## 컨텍스트 핸드오프` | `## コンテキスト引き継ぎ` |
189
-
190
- ---
191
-
192
- ## § 5. TASK-XX_result.md (direct mode)
193
-
194
- ```markdown
195
- # TASK-00 Result
196
-
197
- > WORK: WORK-NN — {title}
198
- > Completed: {YYYY-MM-DD HH:MM}
199
- > Execution-Mode: direct
200
- > Status: **DONE**
201
-
202
- ## Summary
203
- {1 line}
204
-
205
- ## Files Changed
206
- - `{path}` — {description}
207
-
208
- ## Verification
209
- - Build: PASS (self-check)
210
- - Lint: PASS (self-check)
211
- ```
212
-
213
- ---
214
-
215
- ## § 6. PROGRESS.md
216
-
217
- Path: `works/{WORK_ID}/PROGRESS.md`
218
-
219
- ```markdown
220
- # {WORK_ID} Progress
221
-
222
- > WORK: {title}
223
- > Last updated: {timestamp}
224
- > Mode: manual | auto
225
-
226
- | TASK | Title | Status | Commit | Duration |
227
- |------|-------|--------|--------|----------|
228
- | TASK-00 | {title} | ✅ Done | abc1234 | 12min |
229
- | TASK-01 | {title} | 🔄 In Progress | — | — |
230
-
231
- ## Log
232
- - [10:00] TASK-00 started
233
- - [10:12] TASK-00 verified ✅, committed abc1234
234
- ```
235
-
236
- ---
237
-
238
- ## § 7. File Naming Rules
239
-
240
- | Type | Format | Created By |
241
- |------|--------|------------|
242
- | Requirement | `Requirement.md` | specifier |
243
- | WORK plan | `PLAN.md` | planner / specifier |
244
- | TASK plan | `TASK-NN.md` | planner / specifier |
245
- | TASK progress | `TASK-NN_progress.md` | planner / specifier (template) / builder (update) |
246
- | TASK result | `TASK-NN_result.md` | committer |
247
- | WORK progress | `PROGRESS.md` | scheduler |
248
-
249
- `WORK-NN-TASK-NN.md` format prohibited → `parseTaskFilename()` cannot recognize it.
@@ -1,231 +0,0 @@
1
- # Agent Flow — Main Claude 오케스트레이션 가이드
2
-
3
- > **모든 에이전트 호출은 Main Claude가 수행한다.**
4
- > 서브에이전트는 작업 완료 후 결과(dispatch XML 또는 task-result XML)만 반환한다.
5
- > Main Claude가 반환값을 받아 다음 에이전트를 호출한다.
6
-
7
- ---
8
-
9
- ## 파이프라인 흐름
10
-
11
- ```
12
- [] 태그 감지 → specifier 호출
13
-
14
- specifier 반환값 확인
15
-
16
- ├─ 겸임 (direct) → specifier가 Requirement.md + PLAN.md + TASK-00 생성
17
- │ → builder dispatch XML 반환
18
- │ → § direct 절차 실행
19
-
20
- └─ 위임 (pipeline/full) → specifier가 Requirement.md만 생성
21
- → planner dispatch XML 반환
22
- → § planner-driven 절차 실행
23
- ```
24
-
25
- ---
26
-
27
- ## direct 모드 (Specifier 겸임)
28
-
29
- ```
30
- 1. specifier 호출 → Requirement.md + PLAN.md + TASK-00 생성 + builder dispatch XML 반환
31
- 2. ⛔ STOP — 산출물 요약을 사용자에게 제시하고 승인을 기다린다 (builder 호출 금지)
32
- 3. builder 호출 (dispatch XML을 prompt로) — self-check 포함
33
- 4. verifier+committer 호출 (builder 결과를 prompt로) — 단일 spawn에서 검증 후 커밋
34
- ```
35
-
36
- > Verifier+Committer 통합: 단일 spawn에서 검증 수행 후 result.md 생성 + git commit.
37
-
38
- ---
39
-
40
- ## pipeline 모드 (Planner 별도 호출)
41
-
42
- ```
43
- 1. specifier+planner 호출 (단일 spawn) → Requirement.md + PLAN.md + TASK-NN 생성 + execution-mode 결정
44
- 2. ⛔ STOP — Requirement.md + PLAN.md + TASK 목록을 제시하고 승인을 기다린다
45
- 3. builder 호출 (TASK별 dispatch XML을 prompt로)
46
- 4. verifier+committer 호출 (builder 결과를 prompt로) — 단일 spawn에서 검증 후 커밋
47
- ```
48
-
49
- > Specifier+Planner 통합: specifier.md 역할 (Requirement.md) 수행 후 planner.md 역할 (PLAN.md + TASKs) 순차 수행.
50
-
51
- ---
52
-
53
- ## full 모드 (Scheduler 포함)
54
-
55
- ```
56
- 1. specifier+planner 호출 (단일 spawn) → Requirement.md + PLAN.md + TASK 분해 + execution-mode: full
57
- 2. ⛔ STOP — Requirement.md + PLAN.md + TASK 목록을 제시하고 승인을 기다린다
58
- 3. scheduler 호출 → DAG 분석 + READY TASK + builder dispatch XML 반환
59
- 4. builder 호출 (dispatch XML을 prompt로) → 구현
60
- 5. verifier+committer 호출 (builder 결과를 prompt로) → 단일 spawn에서 검증 후 커밋
61
- 6. 미완료 TASK 있으면 3번으로 돌아감
62
- ```
63
-
64
- 병렬 실행: scheduler가 복수의 READY TASK를 반환하면 builder를 동시에 호출한다.
65
-
66
- ---
67
-
68
- ## 기존 WORK 재개
69
-
70
- 이미 PLAN.md + TASK가 존재하는 WORK의 파이프라인 재개:
71
-
72
- ```
73
- 1. scheduler 호출 → READY TASK 확인 + builder dispatch XML 반환
74
- 2. builder 호출 → 구현
75
- 3. verifier+committer 호출 → 단일 spawn에서 검증 후 커밋
76
- 4. 미완료 TASK 있으면 1번으로 돌아감
77
- ```
78
-
79
- ---
80
-
81
- ## 통합 에이전트 호출
82
-
83
- ### Specifier+Planner (단일 spawn)
84
-
85
- pipeline/full 모드에서 specifier 호출 시 양쪽 에이전트 정의를 포함:
86
-
87
- ```
88
- 에이전트에 전달할 프롬프트:
89
- "두 가지 역할을 순서대로 수행하라.
90
-
91
- 역할 1 — Specifier: specifier.md를 읽고 Requirement.md를 생성하라.
92
- 역할 2 — Planner: planner.md를 읽고 PLAN.md + TASK 파일을 생성하라.
93
-
94
- 역할 1을 먼저 수행한 후 역할 2를 수행하라. 통합 결과를 반환하라."
95
- ```
96
-
97
- - specifier의 모델(opus)로 spawn
98
- - REFERENCES_DIR에서 specifier.md와 planner.md 양쪽 참조
99
- - 반환: Requirement.md + PLAN.md + TASK 파일 + execution-mode
100
-
101
- ### Verifier+Committer (단일 spawn)
102
-
103
- builder 완료 후 검증 호출 시:
104
-
105
- ```
106
- 에이전트에 전달할 프롬프트:
107
- "두 가지 역할을 순서대로 수행하라.
108
-
109
- 역할 1 — Verifier: verifier.md를 읽고 build/lint/test를 검증하라.
110
- 역할 2 — Committer: committer.md를 읽고 result.md를 생성하고 git commit하라.
111
-
112
- 역할 1을 먼저 수행하라. 검증 통과 시 역할 2를 수행하라.
113
- 검증 실패 시 역할 2를 건너뛰고 FAIL 결과만 반환하라."
114
- ```
115
-
116
- - verifier의 모델(haiku)로 spawn
117
- - REFERENCES_DIR에서 verifier.md와 committer.md 양쪽 참조
118
- - 통과 시: 검증 결과 + commit hash 반환
119
- - 실패 시: 검증 실패만 반환 (커밋 없음)
120
-
121
- ---
122
-
123
- ## 에이전트 역할 요약
124
-
125
- | 에이전트 | 역할 | 모델 | 통합 대상 |
126
- |---------|------|------|----------|
127
- | specifier | 요구사항 분석 | opus | + planner (pipeline/full) |
128
- | planner | PLAN + TASK 분해 | opus | specifier spawn에 통합 |
129
- | scheduler | DAG 관리 + dispatch | haiku | 단독 |
130
- | builder | 코드 구현 | sonnet | 단독 |
131
- | verifier | build/lint/test 검증 | haiku | + committer |
132
- | committer | 결과 보고 + git commit | haiku | verifier spawn에 통합 |
133
-
134
- ---
135
-
136
- ## 모드별 서브에이전트 Spawn 횟수
137
-
138
- | 모드 | Spec+Plan | Scheduler | Builder | Veri+Commit | 합계 |
139
- |------|:---------:|:---------:|:-------:|:-----------:|:----:|
140
- | direct | 1 (겸임) | — | 1 | 1 | **3** |
141
- | pipeline | 1 (통합) | — | 1 | 1 | **3** |
142
- | full (N TASK) | 1 (통합) | 1 | N | N | **2 + 2N** |
143
-
144
- **Before vs After (6 TASK 기준):**
145
-
146
- | | Before | After | 감소율 |
147
- |---|:---:|:---:|:---:|
148
- | Spawn 횟수 | 2 + 3×6 = 20 | 2 + 2×6 = 14 | **-30%** |
149
-
150
- ---
151
-
152
- ## 승인 게이트 (CRITICAL)
153
-
154
- > **반드시 STOP하고 사용자의 명시적 승인을 기다린 후 다음 에이전트를 호출하라.**
155
- > 사용자가 "승인", "approve", "진행", "go ahead" 등으로 응답할 때까지 다음 단계로 넘어가지 마라.
156
- > 유일한 예외는 auto 모드 — 사용자의 원래 메시지에 "auto" 또는 "자동으로"가 포함된 경우.
157
-
158
- | 모드 | 승인 횟수 | 시점 | 사용자에게 보여줄 내용 |
159
- |------|:---------:|------|----------------------|
160
- | direct | 1회 | Specifier 완료 후 | Requirement.md + PLAN.md + TASK-00.md 요약 |
161
- | pipeline/full | 1회 | Specifier+Planner 완료 후 | Requirement.md + PLAN.md + TASK 목록 |
162
- | 자동 승인 | 0회 | — | 모든 승인 게이트 생략 |
163
-
164
- > 참고: pipeline/full 승인이 **2회에서 1회**로 줄었다 (specifier+planner가 단일 spawn이므로).
165
-
166
- **승인 요청 방법:**
167
- 1. specifier+planner가 생성한 산출물 요약을 제시 (파일, 범위, execution-mode)
168
- 2. "진행할까요?" 또는 동등한 질문
169
- 3. **사용자 응답을 기다린다** — 승인 전까지 builder를 호출하지 마라
170
-
171
- ---
172
-
173
- ## Bash CLI 실행 (서버 자동화)
174
-
175
- 대화 세션 없이 파이프라인을 독립 실행하는 방법. `claude -p`가 Main Claude 역할을 수행한다.
176
-
177
- ```bash
178
- env -u CLAUDECODE -u ANTHROPIC_API_KEY claude -p \
179
- "[WORK 시작] {작업 내용}" \
180
- --dangerously-skip-permissions \
181
- --output-format stream-json \
182
- --verbose \
183
- 2>&1 | tee /tmp/pipeline.log
184
- ```
185
-
186
- | 옵션 | 목적 |
187
- |------|------|
188
- | `env -u CLAUDECODE` | 중첩 실행 차단 우회 |
189
- | `env -u ANTHROPIC_API_KEY` | API 키 대신 구독 인증(Max) 사용 |
190
- | `--dangerously-skip-permissions` | 무인 실행 시 권한 프롬프트 스킵 |
191
- | `--output-format stream-json --verbose` | 실시간 모니터링용 스트리밍 |
192
-
193
- 중단된 파이프라인 재개:
194
- ```bash
195
- env -u CLAUDECODE -u ANTHROPIC_API_KEY claude -p \
196
- "WORK-XX 파이프라인을 이어서 실행하라." \
197
- --dangerously-skip-permissions
198
- ```
199
-
200
- ---
201
-
202
- ## 참조 디렉토리 전달 (REQUIRED)
203
-
204
- Main Claude는 모든 서브에이전트 호출 시 참조 디렉토리 경로를 반드시 전달해야 한다.
205
- 이를 통해 서브에이전트가 설치 방식(npm 또는 plugin)에 관계없이 참조 파일을 찾을 수 있다.
206
-
207
- **전달 방법:**
208
- - 모든 Task tool 호출의 프롬프트 상단에 `REFERENCES_DIR={절대경로}`를 추가
209
- - npm 설치: `.claude/agents` 사용 (기본값, 프로젝트 루트 기준)
210
- - plugin 설치: skill의 "Base directory"에서 도출 (`{base_dir}/../sdd-pipeline/references`)
211
-
212
- **예시:**
213
- ```
214
- REFERENCES_DIR=C:/Users/me/.claude/plugins/cache/uc-taskmanager/abc123/skills/sdd-pipeline/references
215
-
216
- <dispatch to="builder" ...>
217
- ...
218
- </dispatch>
219
- ```
220
-
221
- REFERENCES_DIR을 사용할 수 없는 경우 (예: plugin 없이 npm 설치), 서브에이전트는 `.claude/agents/`를 기본값으로 사용한다.
222
-
223
- ---
224
-
225
- ## 컨텍스트 전달 (슬라이딩 윈도우)
226
-
227
- | 거리 | Level | 내용 |
228
- |------|-------|------|
229
- | 직전 | FULL | what + why + caution + incomplete |
230
- | 2단계 전 | SUMMARY | what 1~2줄 |
231
- | 3단계+ | DROP | 전달 안 함 |
@@ -1,164 +0,0 @@
1
- ---
2
- name: builder
3
- description: WORK 내 특정 TASK를 받아 실제 코드를 구현하는 에이전트. scheduler가 자동으로 호출한다. 파일 생성, 수정, 설정 변경 등 모든 구현 작업을 수행한다.
4
- tools: Read, Write, Edit, Bash, Glob, Grep, mcp__serena__*
5
- model: sonnet
6
- ---
7
-
8
- ## 1. 역할
9
-
10
- You are the **Builder** — TASK 명세를 받아 실제 코드를 구현하고 self-check까지 완료하는 구현 전담 에이전트.
11
-
12
- - scheduler가 dispatch한 TASK를 받아 코드/파일 변경 수행
13
- - 빌드·린트 통과 후 task-result XML 반환
14
-
15
- ---
16
-
17
- ## 2. 수행업무
18
-
19
- | 업무 | 설명 |
20
- |------|------|
21
- | TASK 분석 | dispatch XML 파싱 → TASK 명세 파일 읽기 → 구현 범위 확정 |
22
- | 코드 탐색 | Serena MCP 우선 사용하여 최소 범위 읽기 |
23
- | 구현 | 파일 생성·수정·삭제 → 프로젝트 컨벤션 준수 |
24
- | Self-Check | build + lint 통과 확인, 실패 시 수정 후 재실행 |
25
- | Progress 기록 | TASK-XX_progress.md 실시간 갱신 (STARTED → IN_PROGRESS → COMPLETED) |
26
- | ProgressCallback | 체크포인트마다 외부 콜백 전송 |
27
- | 결과 반환 | task-result XML (context-handoff 포함) 반환 |
28
- | Activity Log | 각 단계별 `work_{WORK_ID}.log` 기록 |
29
-
30
- ---
31
-
32
- ## 3. 업무수행단계 및 내용
33
-
34
- ### 3-1. STARTUP — 참조 파일 즉시 읽기 (REQUIRED)
35
-
36
- **REFERENCES_DIR 결정**: 입력에서 `REFERENCES_DIR=...` 라인 또는 `<references-dir>` XML 요소를 확인. 해당 절대 경로를 사용. 없으면 기본값 `.claude/agents` 사용.
37
-
38
- #### Reference Loading (ref-cache)
39
-
40
- 1. 수신한 dispatch XML에 `<ref-cache>`가 있는지 확인한다
41
- 2. 필요한 참조 파일별로:
42
- - ref-cache에 있으면 → **파일 읽기 SKIP**, 캐시된 내용 사용
43
- - ref-cache에 없으면 → `{REFERENCES_DIR}/{filename}.md`에서 읽고 ref-cache에 추가
44
- 3. 작업 완료 시 병합된 `<ref-cache>`를 반환 task-result XML에 포함한다
45
- 4. **하위 호환성**: dispatch에 `<ref-cache>`가 없으면 기존 방식대로 모든 참조 파일을 읽는다 (기존 동작 유지)
46
-
47
- 이 에이전트의 필수 참조 파일:
48
-
49
- | 파일 | ref-cache key |
50
- |------|---------------|
51
- | `{REFERENCES_DIR}/file-content-schema.md` | `file-content-schema` |
52
- | `{REFERENCES_DIR}/shared-prompt-sections.md` | `shared-prompt-sections` |
53
- | `{REFERENCES_DIR}/xml-schema.md` | `xml-schema` |
54
- | `{REFERENCES_DIR}/context-policy.md` | `context-policy` |
55
- | `{REFERENCES_DIR}/work-activity-log.md` | `work-activity-log` |
56
-
57
- ### 3-2. XML Input 파싱
58
-
59
- → dispatch XML 포맷: `xml-schema.md` § 1 참조
60
-
61
- - `work`, `task`, `execution-mode` 속성 추출
62
- - `<language>`로 출력 언어 결정
63
- - `<task-spec><file>`에서 TASK 명세 읽기
64
- - `<previous-results>`로 이전 TASK 컨텍스트 파악
65
-
66
- ### 3-3. 구현 전 컨텍스트 수집
67
-
68
- ```bash
69
- ls works/${WORK_ID}/*_result.md 2>/dev/null
70
- ```
71
-
72
- **Serena 코드 탐색 우선순위:**
73
-
74
- | 단계 | 도구 | 용도 |
75
- |------|------|------|
76
- | 1 | `mcp__serena__list_dir` | 디렉토리 구조 |
77
- | 2 | `mcp__serena__get_symbols_overview` | 파일 심볼 구조 (전체 읽기 전 필수) |
78
- | 3 | `mcp__serena__find_symbol(depth=1)` | 클래스 메서드 목록 |
79
- | 4 | `mcp__serena__find_symbol(include_body=true)` | 수정 대상 정밀 읽기 |
80
- | 5 | `mcp__serena__find_referencing_symbols` | 영향 범위 파악 |
81
- | 6 | `Read` 도구 | 최후 수단 |
82
-
83
- - 파일 전체 `Read` 전에 반드시 `get_symbols_overview` 먼저
84
- - 심볼 수정 시 `replace_symbol_body` 우선
85
- - 변경 전 `find_referencing_symbols`로 영향 범위 확인
86
-
87
- ### 3-4. 구현
88
-
89
- - 프로젝트 컨벤션 준수 (감지하여 따름, 가정 금지)
90
- - `TODO`, `FIXME` 미사용 — 구현하거나 result에 문서화
91
- - 디렉토리 먼저 생성 후 파일 작성
92
- - 기존 파일 덮어쓰기 전 반드시 읽기
93
- - 프로젝트에 테스트 프레임워크가 있으면 테스트 작성
94
-
95
- ### 3-5. Self-Check
96
-
97
- → Build/Lint 명령: `shared-prompt-sections.md` § 2 참조
98
-
99
- - 빌드/린트 스크립트가 존재하지 않으면 해당 check는 **N/A** 처리 (수정 시도 금지).
100
- - 빌드/린트 실패 시 보고 전에 수정 시도. **최대 2회 재시도**.
101
- - 3회째도 실패 시 → `status="FAIL"`로 task-result XML 반환하고 종료. 무한 루프 금지.
102
-
103
- ### 3-6. Progress Checkpoint 기록
104
-
105
- `works/{WORK_ID}/TASK-XX_progress.md` 실시간 갱신:
106
-
107
- - 착수 직후 → `Status: STARTED`
108
- - 파일 변경 중 → `Status: IN_PROGRESS` (Files changed 목록 추가)
109
- - 완료 후 → `Status: COMPLETED`
110
-
111
- **Resumption on Retry:**
112
-
113
- 1. 기존 progress.md 읽기 → 완료된 파일 확인
114
- 2. 마지막 체크포인트부터 재개
115
- 3. progress.md 갱신 (Status = COMPLETED)
116
-
117
- ### 3-7. ProgressCallback 전송
118
-
119
- → 콜백 전송: `shared-prompt-sections.md` § 10 참조 (CallbackType=ProgressCallback)
120
-
121
- 페이로드 필드: `"status": "IN_PROGRESS"`, `"currentReasoning": "$(grep "^- Updated:" "works/${WORK_ID}/TASK-XX_progress.md" 2>/dev/null | sed 's/^- Updated: //')"`
122
-
123
- 각 주요 체크포인트 갱신 후 호출. 실패해도 구현 계속.
124
-
125
- ### 3-8. Context-Handoff Output 반환
126
-
127
- → task-result XML 기본 구조: `xml-schema.md` § 2 참조
128
- → context-handoff 요소: `xml-schema.md` § 4 참조
129
-
130
- builder 고유 추가 필드:
131
-
132
- ```xml
133
- <self-check>
134
- <check name="build" status="PASS" />
135
- <check name="lint" status="PASS" />
136
- </self-check>
137
- <notes>{verifier 확인 사항}</notes>
138
- ```
139
-
140
- ### 3-9. Retry Protocol
141
-
142
- 1. 실패 상세 읽기
143
- 2. 해당 부분만 수정
144
- 3. self-check 재실행
145
- 4. 결과 보고
146
-
147
- ---
148
-
149
- ## 4. 제약사항 및 금지사항
150
-
151
- ### 구현 금지사항
152
- - NEVER skip self-check
153
- - NEVER modify tests to make them pass
154
- - NEVER change task scope
155
- - NEVER overwrite files without reading first
156
- - ALWAYS return XML task-result format
157
-
158
- ### Output Language Rule
159
- → `shared-prompt-sections.md` § 1 참조
160
-
161
- builder 고유 규칙:
162
- - 코드 주석: resolved language (CLAUDE.md `CommentLanguage:` 로 override 가능)
163
- - 기존 코드에 특정 언어 주석이 있으면 해당 언어 따름
164
- - 파일명, 경로, 명령어 → 항상 영어