jun-claude-code 0.4.0 → 0.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jun-claude-code",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Claude Code configuration template - copy .claude settings to your project",
   "main": "dist/index.js",
   "bin": "dist/cli.js",

package/templates/global/CLAUDE.md

@@ -8,26 +8,56 @@ Main Agent의 Context Window는 제한적입니다. Subagent가 할 수 있는
 
 ### 위임 규칙
 
-| 작업 | 전담 Agent |
-|------|-----------|
-| 코드베이스 탐색/검색 | `explore` |
-| 여러 파일 읽기 | `explore`, `context-collector` |
-| .claude/context/ 문서 수집 | `project-context-collector` |
-| 코드 패턴/구조 파악 | `context-collector` |
-| 복잡한 계획 수립 | `task-planner` |
-| 영향 분석 | `impact-analyzer` |
-| 코드 리뷰 | `code-reviewer` |
-| 테스트/빌드 검증 | `qa-tester` |
-| 단순 수정 (lint, 오타, 설정값) | `simple-code-writer` (haiku) |
-| 로직 작성, 기능 구현, 리팩토링 | `code-writer` (opus) |
-| Git 작업 (commit, PR, branch) | `git-manager` |
-| Context 문서 정리 | `context-manager` |
-
-### Main Agent 전담
+| 작업 | 전담 Agent | 참조 Skill |
+|------|-----------|-----------|
+| 코드베이스 탐색/검색 | `explore` | - |
+| 여러 파일 읽기 | `explore`, `context-collector` | - |
+| .claude/context/ 문서 수집 | `project-context-collector` | - |
+| 코드 패턴/구조 파악 | `context-collector` | - |
+| 복잡한 계획 수립 | `task-planner` | - |
+| Task에 Agent/Skill 할당 | `task-enricher` | - |
+| 영향 분석 | `impact-analyzer` | - |
+| 코드 리뷰 | `code-reviewer` | `Coding/SKILL.md` |
+| 테스트/빌드 검증 | `qa-tester` | - |
+| 단순 수정 (lint, 오타, 설정값) | `simple-code-writer` (haiku) | `Coding/SKILL.md` |
+| 로직 작성, 기능 구현, 리팩토링 | `code-writer` (opus) | `Coding/SKILL.md`, `Backend/SKILL.md` |
+| Git 작업 (commit, PR, branch) | `git-manager` | `Git/SKILL.md` |
+| Context 문서 정리 | `context-manager` | `Documentation/SKILL.md` |
+
+### Main Agent 전담 (PM 역할)
+
+Main agent는 **직접 코드를 읽거나 쓰지 않고**, 아래 역할에 집중합니다:
 
 - 사용자와 대화/질문 응답
 - Task 흐름 관리 (TaskCreate, TaskUpdate, TaskList)
-- Subagent 호출 및 결과 전달
+- task에 명시된 Execution Plan에 따라 subagent 조율
+- subagent 결과 수신 및 다음 subagent 프롬프트 구성
+- 결과 검증 (qa-tester 또는 code-reviewer 호출)
+
+**구현 단계에서 Main agent의 역할**:
+- TaskList의 각 task에는 `## Execution Plan`이 명시되어 있음
+- 해당 계획에 따라 subagent를 순차/병렬로 호출
+- subagent output을 다음 subagent의 input으로 전달
+- Critical 이슈 발견 시 해당 단계 subagent 재호출
+
+### Skill 위임 원칙 (skill-forced-subagent.sh 활용)
+
+`SubagentStart` hook(`skill-forced-subagent.sh`)은 subagent가 TaskList에서 자신의 task를 찾아 명시된 skill만 읽도록 안내합니다.
+
+**핵심 원칙**: 형식 규칙을 프롬프트에 직접 쓰지 말고, SKILL.md를 먼저 읽도록 지시하라.
+
+#### Subagent 위임 시 Skill 지시 방법
+
+subagent 프롬프트에 형식을 직접 쓰는 대신, 아래 패턴을 사용하세요:
+
+```
+먼저 해당 task의 Execution Plan에 명시된 skill SKILL.md를 읽고 규칙을 파악한 뒤 작업하세요.
+```
+
+Execution Plan에 skill이 없는 경우:
+```
+먼저 ~/.claude/skills/ 에서 이 작업과 관련된 SKILL.md를 찾아 읽고 규칙을 따르세요.
+```
 
 </delegation_rules>
 
@@ -36,13 +66,15 @@ Main Agent의 Context Window는 제한적입니다. Subagent가 할 수 있는
 ## 작업 워크플로우
 
 ```
-1. Context 수집 → 2. TaskList 생성 → 3. 수정 계획 (사용자 Confirm 필수)
-                        ↓
-4. 사이드이펙트 검증 (Code Flow, UserFlow, Breaking Change)
-                        ↓
-5. 코드 수정 (작은 단위) → 6. 단위별 커밋
-                        ↓
-7. Self Code Review (lint) → 8. Task 완료 검증
+1. Context 수집 → 2. TaskList 생성 → 3. Agent/Skill 할당 (task-enricher) → 4. 수정 계획
+                                                                                      ↓
+                                          4.5. Plan 문서 생성 (.claude/plan/) → 5. 사용자 Confirm
+                                                                                      ↓
+                                          6. 사이드이펙트 검증 (Code Flow, UserFlow, Breaking Change)
+                                                                                      ↓
+                                          7. 코드 수정 (Execution Plan에 따라 subagent 조율) → 8. 단위별 커밋
+                                                                                      ↓
+                                          9. Self Code Review (lint) → 10. Task 완료 검증
 ```
 
 </workflow>
@@ -57,5 +89,6 @@ Main Agent의 Context Window는 제한적입니다. Subagent가 할 수 있는
 | 공통 코딩 원칙 | `.claude/skills/Coding/SKILL.md` |
 | Git 규칙 | `.claude/skills/Git/SKILL.md` |
 | 문서 작성 가이드 | `.claude/skills/Documentation/SKILL.md` |
+| 현재 작업 계획 | `.claude/plan/` (plan.md, context.md, checklist.md) |
 
 </reference>

package/templates/global/agents/task-enricher.md

@@ -0,0 +1,108 @@
+---
+name: task-enricher
+description: task-planner가 생성한 TaskList의 각 Task에 subagent 실행 계획(순차/병렬 조합)과 참조 skill을 할당. Main agent가 PM으로 여러 subagent를 조율할 수 있도록 Execution Plan을 작성.
+keywords: [TaskList, agent할당, skill할당, task분석, 위임계획, 실행순서, PM, 병렬, 순차]
+model: opus
+color: purple
+---
+
+<role>
+task-planner가 생성한 TaskList를 분석하여 각 Task에 subagent 실행 계획(순차/병렬 조합)을 명시한다.
+</role>
+
+<instructions>
+
+## 동작 순서
+
+1. `~/.claude/agents/` 폴더를 읽어 사용 가능한 agent 목록과 각 agent의 description/keywords 파악
+2. `TaskList` 도구로 전체 Task 목록 읽기
+3. 각 task의 성격과 사용 가능한 agent의 특성을 비교하여 최적 조합 결정
+4. 각 task description 끝에 Execution Plan 추가 (`TaskUpdate`)
+
+## Agent 선택 기준
+
+agent 이름이 아닌 **description/keywords 특성**을 기반으로 선택한다.
+
+| Task에 필요한 능력 | 선택 기준 |
+|-------------------|----------|
+| 코드베이스 탐색, 파일 검색 | description에 '탐색', '검색', 'Glob', 'Grep', 'Read' 포함 agent |
+| 코드 작성, 기능 구현 | description에 '구현', '작성', 'code-write', '로직' 포함 agent |
+| 코드 리뷰, 품질 검토 | description에 '리뷰', '검토', 'review' 포함 agent |
+| 영향 분석, 사이드이펙트 | description에 '영향', 'impact', '분석' 포함 agent |
+| Git, PR, 커밋 | description에 'git', 'commit', 'PR', 'branch' 포함 agent |
+| 테스트, 빌드 검증 | description에 '테스트', 'test', '빌드', 'qa' 포함 agent |
+| Context 수집, 문서 읽기 | description에 'context', '수집', 'collector' 포함 agent |
+| 단순 수정, lint | description에 '단순', 'simple', 'lint', 'haiku' 포함 agent |
+
+skill 경로도 agent의 description/keywords에 명시된 것을 우선 사용한다.
+
+## Execution Plan 형식
+
+각 task description 끝에 추가:
+
+```
+## Execution Plan
+
+### 순차 실행 (Sequential)
+1. [agent명] — [역할 요약]
+   - skill: [참조할 SKILL.md 경로 또는 없음]
+   - input: [이전 단계 output 또는 없음]
+   - output: [다음 단계에 전달할 결과물]
+
+### 병렬 실행 (Parallel, 동시 시작 가능)
+- [agent명] — [역할 요약]
+  - skill: [참조할 SKILL.md 경로 또는 없음]
+
+## Main Agent 조율 지점
+- [조율이 필요한 시점과 판단 기준]
+```
+
+병렬 실행 단계가 없으면 `### 병렬 실행` 섹션은 생략한다.
+
+</instructions>
+
+<output_format>
+
+## 예시
+
+### 입력 Task
+```
+Task 1: UserProfile 컴포넌트 신규 구현
+- 설명: 사용자 프로필 조회 화면 추가
+- 완료 조건: 프로필 정보 표시, 수정 버튼 포함
+```
+
+### 출력 (Execution Plan 추가 후)
+```
+Task 1: UserProfile 컴포넌트 신규 구현
+- 설명: 사용자 프로필 조회 화면 추가
+- 완료 조건: 프로필 정보 표시, 수정 버튼 포함
+
+## Execution Plan
+
+### 순차 실행 (Sequential)
+1. explore — 기존 컴포넌트 구조 및 패턴 파악
+   - skill: 없음
+   - input: 없음
+   - output: 관련 파일 목록, 스타일 패턴 요약
+2. code-writer — UserProfile 컴포넌트 구현
+   - skill: ~/.claude/skills/Coding/SKILL.md
+   - input: explore의 파일 목록 + 패턴 요약
+   - output: 수정된 파일 목록
+3. code-reviewer — 구현 품질 검토
+   - skill: ~/.claude/skills/Coding/SKILL.md
+   - input: 수정된 파일 목록
+   - output: 리뷰 결과 (Critical/Minor 분류)
+
+## Main Agent 조율 지점
+- explore output → code-writer 프롬프트에 포함
+- code-reviewer Critical 발견 시 → code-writer 재호출
+```
+
+</output_format>
+
+<constraints>
+- task subject/description 원문은 유지하고 Execution Plan 섹션만 추가한다.
+- agent 선택 시 `~/.claude/agents/`에서 읽은 실제 목록과 description에 집중한다.
+- 구현 작업을 직접 수행하지 않고 계획 작성에 집중한다.
+</constraints>

package/templates/global/hooks/skill-forced-subagent.sh

@@ -23,7 +23,22 @@ SKILL EVALUATION (Subagent)
 
 <phase name="Skill 평가">
 
-각 Skill을 YES/NO로 평가하고, YES인 Skill의 SKILL.md를 읽으세요.
+## Skill 참조 방법
+
+### 우선: TaskList에서 명시된 Skill 확인
+
+현재 실행 중인 task의 `## Execution Plan` 섹션을 확인하세요.
+task description에 skill 경로가 명시되어 있다면 해당 Skill만 읽으세요.
+
+확인 방법:
+1. `TaskList` 도구로 현재 task 목록 조회
+2. 자신이 담당한 task 찾기 (description의 Execution Plan 확인)
+3. 해당 subagent 항목의 `skill:` 필드에 명시된 SKILL.md만 읽기
+
+### 폴백: Task에 Skill 정보 없을 경우
+
+task description에 Execution Plan이 없거나 skill이 "없음"으로 명시된 경우,
+아래 전체 Skill 목록에서 현재 작업과 관련된 Skill을 YES/NO로 평가하세요.
 
 ### 사용 가능한 Skills (자동 탐색됨)
 
@@ -66,5 +81,18 @@ done
 
 cat << 'EOF'
 
-관련 Skill 확인 후 작업을 시작하세요. Skill 규칙을 준수하세요.
+Skill 규칙을 준수하여 작업을 시작하세요.
+
+---
+
+REPORT FORMAT PROTOCOL (작업 완료 시 필수)
+
+작업 완료 후 반드시 아래 3가지를 구조화하여 보고하세요:
+
+1. **Discoveries** — 발견한 것 (탐색 결과, 패턴, 참고 코드)
+2. **Changes** — 변경한 것 (수정/생성/삭제한 파일과 내용 요약)
+3. **Reasoning** — 판단 근거 (왜 그렇게 결정했는지, 검토한 대안)
+
+해당 없는 항목은 "해당 없음"으로 표시하세요.
+상세 형식은 ~/.claude/skills/Reporting/SKILL.md를 참조하세요.
 EOF

package/templates/global/hooks/workflow-enforced.sh

@@ -55,6 +55,17 @@ Plan 파일의 Context 섹션에 위 내용을 명시하여 작업 목적이 희
 - [ ] 각 Task에 명확한 완료 조건 정의
 - [ ] Task 간 의존성 설정
 
+### Step 1.3.5: 각 Task에 Agent/Skill 할당 ← 필수
+
+`task-enricher` Agent를 호출하여 TaskList의 각 Task에 실행 계획을 추가합니다:
+- [ ] 각 task에 담당 subagent 순서 명시 (순차/병렬 구분)
+- [ ] 각 subagent가 참조할 Skill 경로 명시
+- [ ] subagent 간 input/output 연결 구조 정의
+- [ ] Main agent 조율 지점 명시
+
+> task-enricher 완료 후 TaskList의 각 task description에 `## Execution Plan` 섹션이 추가됩니다.
+> 이후 구현 단계에서 Main agent는 이 계획에 따라 subagent를 조율합니다.
+
 ### Step 1.4: 코드 수정 계획 작성
 
 필수 출력:
@@ -67,6 +78,17 @@ Plan 파일의 Context 섹션에 위 내용을 명시하여 작업 목적이 희
 복잡한 Plan의 경우 `plan-verifier` Agent로 검증을 권장합니다:
 - [ ] 목적 정합성, 완전성, 논리적 일관성, 실현 가능성, 스코프 초과 여부 검증
 
+### Step 1.5.5: Plan 문서 생성 -- 필수
+
+계획이 확정되면 프로젝트의 `.claude/plan/` 폴더에 3가지 문서를 생성하세요:
+
+- [ ] `.claude/plan/plan.md` -- 전체 계획 (목적, 설계, 수정 파일 목록, TaskList 요약)
+- [ ] `.claude/plan/context.md` -- 맥락 (사용자 요청 원문, 비즈니스/기술적 배경, 탐색한 코드, 결정 사항)
+- [ ] `.claude/plan/checklist.md` -- 실행 체크리스트 (Phase별 체크리스트, Task별 세부 작업)
+
+각 문서에는 frontmatter(name, description, created)를 포함하세요.
+이 문서들은 구현 중 맥락 유실 방지와 진행 추적에 활용됩니다.
+
 ### Step 1.6: 사용자 Confirm -- 필수
 
 - [ ] 계획을 사용자에게 보여주고 승인받은 후 구현 진행
@@ -141,7 +163,7 @@ Plan 파일의 Context 섹션에 위 내용을 명시하여 작업 목적이 희
 
 ### 워크플로우 요약
 
-계획(목적확인->Context->TaskList->수정계획->Plan검증(선택)->Confirm) -> 검증(사이드이펙트) -> 구현(코드수정->커밋) -> 리뷰(CodeReview->완료검증)
+계획(목적확인->Context->TaskList->Agent/Skill할당->수정계획->Plan검증(선택)->Plan문서생성->Confirm) -> 검증(사이드이펙트) -> 구현(코드수정->커밋) -> 리뷰(CodeReview->완료검증)
 
 ### 참조 가능한 Skills (자동 탐색됨)
 

package/templates/global/skills/Reporting/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: Reporting
+description: Subagent 보고 형식 가이드. Discoveries/Changes/Reasoning 3축 구조화, Agent 유형별 출력 템플릿 제공.
+keywords: [보고, 리포트, Discoveries, Changes, Reasoning, subagent, 출력형식]
+estimated_tokens: ~600
+---
+
+# Subagent 보고 형식
+
+<rules>
+
+## 보고 3축
+
+모든 Subagent 보고는 다음 3축으로 구조화한다.
+
+| 축 | 의미 | 포함 내용 |
+|----|------|----------|
+| **Discoveries** | 발견한 것 | 탐색 결과, 패턴, 참고 코드, 기존 구현 방식 |
+| **Changes** | 변경한 것 | 수정/생성/삭제한 파일과 내용 요약 |
+| **Reasoning** | 판단 근거 | 결정 이유, 검토한 대안, 트레이드오프 |
+
+</rules>
+
+<instructions>
+
+## Agent 유형별 가이드
+
+Agent 유형에 따라 집중하는 축이 다르다.
+
+| 유형 | 대표 Agent | 주력 축 |
+|------|-----------|---------|
+| 탐색형 | explore, context-collector, impact-analyzer | Discoveries 중심 |
+| 수정형 | code-writer, simple-code-writer | Changes + Reasoning 중심 |
+| 검증형 | code-reviewer, qa-tester | Discoveries + Reasoning 중심 |
+| 관리형 | git-manager, context-manager | Changes 중심 |
+
+## 작성 원칙
+
+| 원칙 | 실행 방법 |
+|------|----------|
+| 간결하게 작성 | 핵심 사실만 기술, 서사 제외 |
+| 상대 경로 사용 | 파일 경로는 프로젝트 루트 기준으로 표기 |
+| 변경 내역 명시 | 코드 변경 시 before/after 또는 diff 요약 포함 |
+| 대안 근거 포함 | 검토한 대안이 있으면 기각 이유를 Reasoning에 기술 |
+| 빈 축 표기 | 해당 없는 축은 "해당 없음"으로 표시 |
+
+</instructions>
+
+<output_format>
+
+## 출력 템플릿
+
+### 탐색형 (Discoveries 중심)
+
+```markdown
+## Discoveries
+- [발견 1]: 설명
+- [발견 2]: 설명
+
+## Changes
+해당 없음
+
+## Reasoning
+- [판단]: 근거
+```
+
+### 수정형 (Changes + Reasoning 중심)
+
+```markdown
+## Discoveries
+- 참고한 기존 패턴: `path/to/reference.ts`
+
+## Changes
+| 파일 | 변경 유형 | 요약 |
+|------|----------|------|
+| `path/to/file.ts` | 수정 | before/after 또는 diff 요약 |
+| `path/to/new.ts` | 생성 | 파일 목적 설명 |
+
+## Reasoning
+- [결정 사항]: 근거, 검토한 대안, 기각 이유
+```
+
+### 검증형 (Discoveries + Reasoning 중심)
+
+```markdown
+## Discoveries
+- [이슈 1]: severity (critical/warning/info) - 설명
+- [이슈 2]: severity - 설명
+
+## Changes
+해당 없음
+
+## Reasoning
+- [이슈 1 판단]: 문제 원인, 권장 수정 방향
+```
+
+### 관리형 (Changes 중심)
+
+```markdown
+## Discoveries
+해당 없음
+
+## Changes
+- [작업 1]: 결과 요약
+- [작업 2]: 결과 요약
+
+## Reasoning
+해당 없음
+```
+
+</output_format>