@choblue/claude-code-toolkit 1.2.4 → 1.2.6

package/.claude/.project-map-cache

@@ -1 +1 @@
-27c83ec4fadcaf1ee2f771651fa76d31262a831a
+661df17b80c1e5d15cac0feb533ca658c67a5155

package/.claude/CLAUDE.md

@@ -32,7 +32,45 @@ Claude는 작업 시작 전 반드시 이 규칙을 따라야 한다.
 
 ---
 
-## 2. 티어별 워크플로우
+## 2. 점진적 구현 원칙
+
+**"한 번에 하나, 완전하게"** — 범위를 넓게 잡고 80%로 끝내지 말고, 좁게 잡고 100%로 완성한다.
+
+### 작업 분해
+- 요구사항을 **가장 작은 배포 가능 단위(smallest deliverable unit)**로 쪼갠다
+- 한 단위를 **완전히 끝낸 후** 다음 단위로 이동한다
+- 에이전트 1회 호출 당 **파일 3개 이하**를 원칙으로 한다
+
+### 예시: "게시판 만들어줘"
+```
+Step 1: Entity + API (목록 조회만) → 확인
+Step 2: 목록 UI → 확인
+Step 3: 생성 API + UI → 확인
+Step 4: 수정/삭제 → 확인
+```
+
+### 금지
+- 한 번의 계획에 기능 전체를 담아 한꺼번에 구현하는 것
+- 에이전트에 5개 이상 파일 동시 생성/수정을 위임하는 것
+
+---
+
+## 2-1. 완료 기준 (Definition of Done)
+
+각 작업 단위는 다음 조건을 **모두 만족**해야 "완료"로 판단한다.
+에이전트는 구현 후 이 체크리스트를 자체 검증한다.
+
+### 공통 DoD
+- [ ] 타입 에러 없음 (`tsc --noEmit` 통과)
+- [ ] 미사용 import/변수 없음
+- [ ] 기존 테스트가 깨지지 않음
+- [ ] 기존 프로젝트 패턴과 일관성 유지
+
+> FE/BE별 추가 DoD는 프로젝트 루트 `CLAUDE.md`에서 오버라이드한다.
+
+---
+
+## 3. 티어별 워크플로우
 
 ### S 티어 (trivial)
 Main Agent가 직접 처리한다. 서브에이전트 위임 불필요.
@@ -42,15 +80,15 @@ Main Agent가 직접 처리한다. 서브에이전트 위임 불필요.
 ### M 티어 (moderate)
 TDD/Review를 생략하고 핵심 단계만 수행한다.
 1. **Planning**: 요구사항 정리, 필요 시 `explore`로 탐색
-2. **Implementation**: `code-writer` 에이전트에 구현 위임
+2. **Implementation**: `code-writer` 에이전트에 구현 위임 (단위별로 나눠 호출)
 3. **Commit**: `git-manager`로 커밋/PR 생성
 
 ### L 티어 (complex)
-파일 기반 설계 후 구현한다.
+파일 기반 설계 후 **단위별로** 구현한다.
 1. **Research**: `explore`로 탐색 → `research.md` 작성 (관련 코드 분석, 제약 조건)
-2. **Plan**: `plan.md` 작성 (접근 방식, 변경 파일, 트레이드 오프, 작업 순서)
+2. **Plan**: `plan.md` 작성 (접근 방식, 변경 파일, 트레이드 오프, **단위별 작업 순서**)
 3. **주석 사이클**: 사용자가 plan.md에 메모 → 반영 → **승인 전까지 구현 금지**
-4. **Implementation + Test**: `implementer`에 plan.md 전달하여 구현+테스트 동시 위임
+4. **Implementation + Test**: plan.md의 각 단위를 순서대로 `implementer`에 위임 (단위당 1회 호출)
 5. **Review**: `code-reviewer`로 리뷰 → `git-manager`로 커밋/PR
 
 ### 풀스택 작업 (FE + BE 동시 변경)
@@ -58,7 +96,7 @@ TDD/Review를 생략하고 핵심 단계만 수행한다.
 
 ---
 
-## 3. 문서 참조 가이드
+## 4. 문서 참조 가이드
 
 ### Agents (서브에이전트 프롬프트)
 - `.claude/agents/explore.md` - 코드베이스 탐색 전문가
@@ -88,6 +126,13 @@ TDD/Review를 생략하고 핵심 단계만 수행한다.
 - `.claude/skills/DDD/SKILL.md` - DDD 전술적 패턴 (Entity, VO, Aggregate, Repository, Domain Event)
 - `.claude/skills/Planning/SKILL.md` - 작업 계획 (티어 판단, 작업 분해, 의존성 확인)
 - `.claude/skills/Git/SKILL.md` - Git 커밋/PR/브랜치 규칙
+- `.claude/skills/FailureRecovery/SKILL.md` - 실패 복구 프로토콜 (진단, 처방, 에스컬레이션)
+- `.claude/skills/Curation/SKILL.md` - AI 결과물 큐레이션 체크리스트
+
+### Prompts (커스텀 커맨드)
+- `.claude/prompts/feature.md` - /feature [기능명] -> 새 기능 구현 시작
+- `.claude/prompts/fix.md` - /fix [증상] -> 버그 수정
+- `.claude/prompts/review.md` - /review -> 현재 변경사항 리뷰
 
 ### Scripts
 - `.claude/scripts/generate-project-map.sh` - PROJECT_MAP.md 자동 생성
@@ -98,7 +143,7 @@ TDD/Review를 생략하고 핵심 단계만 수행한다.
 
 ---
 
-## 4. 프로젝트별 오버라이드
+## 5. 프로젝트별 오버라이드
 
 프로젝트 루트에 `CLAUDE.md`가 있으면 이 글로벌 규칙보다 우선한다.
 프로젝트별 규칙은 글로벌 규칙을 확장하되, 충돌 시 프로젝트 규칙을 따른다.

package/.claude/prompts/feature.md

@@ -0,0 +1,11 @@
+새 기능 구현을 시작한다.
+
+## 입력
+- 기능명: $ARGUMENTS
+- 관련 도메인: (사용자가 지정)
+
+## 절차
+1. 티어를 판단하라
+2. PROJECT_MAP.md를 읽어라
+3. 티어별 워크플로우를 따라라
+4. 구현 후 DoD 체크리스트를 검증하라

package/.claude/prompts/fix.md

@@ -0,0 +1,11 @@
+버그를 수정한다.
+
+## 입력
+- 증상: $ARGUMENTS
+
+## 절차
+1. 에러 메시지/증상을 분석하라
+2. 관련 코드를 explore로 탐색하라
+3. 원인을 파악하고 수정 범위를 결정하라
+4. 수정 후 관련 테스트가 통과하는지 확인하라
+5. 같은 유형의 버그가 다른 곳에도 있는지 검색하라

package/.claude/prompts/review.md

@@ -0,0 +1,7 @@
+현재 변경사항을 리뷰한다.
+
+## 절차
+1. `git diff`로 변경 내용을 확인하라
+2. Curation 스킬의 체크리스트를 적용하라
+3. 코드 품질 체크리스트 (Coding SKILL.md)를 적용하라
+4. 발견사항을 심각도별로 분류하라: 필수 수정 / 권장 / 제안

package/.claude/skills/Curation/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: curation
+description: AI 결과물의 품질을 인간 관점에서 검증하는 체크리스트. code-reviewer 에이전트가 참조하거나, 사용자가 직접 리뷰할 때 활용한다.
+---
+
+# Curation Skill
+
+AI가 만든 80점짜리 결과물에서 나머지 20점을 채우기 위한 인간 리뷰 관점.
+
+---
+
+## 1. 코드 큐레이션 체크리스트
+
+### 자연스러움 (AI스러움 제거)
+- [ ] 불필요하게 과한 주석이 없는가 (모든 줄에 주석 금지)
+- [ ] 변수명이 지나치게 장황하지 않은가
+- [ ] 사용하지 않는 예외 처리가 없는가 (방어적 코딩 과잉)
+- [ ] 기존 코드베이스의 톤과 맞는가
+
+### 실용성
+- [ ] 실제로 사용될 엣지 케이스만 처리하는가 (과잉 방어 금지)
+- [ ] 추상화 수준이 적절한가 (너무 이르거나 과한 추상화 금지)
+- [ ] import가 실제로 존재하는 모듈을 참조하는가
+- [ ] 하드코딩된 값이 없는가 (환경변수, 상수로 분리)
+
+### 일관성
+- [ ] 기존 파일들과 디렉토리 위치가 맞는가
+- [ ] 네이밍 패턴이 주변 코드와 통일되는가
+- [ ] 에러 핸들링 방식이 프로젝트 관례와 맞는가
+
+## 2. 리뷰 우선순위
+
+1. **먼저 빌드/테스트 통과** 확인 (자동화 가능)
+2. **비즈니스 로직 정확성** -- 요구사항과 일치하는지
+3. **기존 패턴 일관성** -- 프로젝트 컨벤션을 따르는지
+4. **AI스러움 제거** -- 과잉 주석, 과잉 방어, 불필요한 추상화

package/.claude/skills/FailureRecovery/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: failure-recovery
+description: 에이전트가 잘못된 결과를 냈을 때의 디버깅 및 재시도 프로토콜. 단순 재실행이 아닌 원인 분석 후 처방한다.
+---
+
+# Failure Recovery Skill
+
+에이전트 결과물이 기대와 다를 때, "다시 해"가 아닌 **원인 진단 -> 처방 -> 재시도** 사이클을 따른다.
+
+---
+
+## 1. 실패 분류 및 처방
+
+| 유형 | 증상 | 처방 |
+|------|------|------|
+| **방향 오류** | 요구사항과 전혀 다른 결과 | 요구사항을 재정의하고 배경 컨텍스트 보강 |
+| **패턴 불일치** | 동작은 하지만 기존 코드와 스타일이 다름 | 참조할 기존 파일 경로를 명시적으로 전달 |
+| **부분 구현** | 일부만 되고 나머지가 빠짐 | 작업을 더 작은 단위로 재분해 |
+| **타입/런타임 에러** | 빌드 실패, 런타임 크래시 | 에러 메시지 + 관련 타입/인터페이스를 함께 전달 |
+| **반복 실패** | 같은 에러를 2회 이상 반복 | 접근 방식 자체를 변경하거나 사용자에게 에스컬레이션 |
+
+## 2. 재시도 프로토콜
+
+### Step 1: 진단 (바로 "다시 해" 금지)
+```
+실패 진단:
+- 기대한 결과: [구체적으로]
+- 실제 결과: [구체적으로]
+- 차이 원인: 방향 오류 / 패턴 불일치 / 부분 구현 / 에러
+```
+
+### Step 2: 처방
+- 방향 오류 -> 요구사항 문서를 수정하고 재전달
+- 패턴 불일치 -> "X파일의 패턴을 따라서" 참조 경로 추가
+- 부분 구현 -> 빠진 부분만 별도 작업으로 분리
+- 에러 -> 에러 메시지 + 관련 타입/인터페이스를 함께 전달
+
+### Step 3: 재시도
+- 처방 내용을 프롬프트에 반영하여 재호출
+- 동일 실패 2회 반복 시 -> 접근 방식 자체를 변경하거나 사용자에게 에스컬레이션
+
+## 3. 에스컬레이션 기준
+
+다음 중 하나라도 해당하면 사용자에게 판단을 요청한다:
+- 동일 유형 실패가 2회 반복
+- 처방 후에도 새로운 유형의 에러 발생
+- 아키텍처/설계 수준의 변경이 필요한 경우

package/.claude/skills/Planning/SKILL.md

@@ -68,10 +68,29 @@ M 티어는 파일 없이 채팅에서 간단히 계획을 제시한다:
 2. [작업] → [담당 에이전트]
 ```
 
-## 4. 작업 분해 체크리스트
+## 4. 작업 분해 원칙
 
+**"한 번에 하나, 완전하게"** — 전체를 한꺼번에 80%로 끝내지 말고, 단위별로 100% 완성한다.
+
+### 분해 기준
+- **가장 작은 배포 가능 단위(smallest deliverable unit)**로 쪼갠다
+- 각 단위는 독립적으로 동작하고 확인할 수 있어야 한다
+- 에이전트 1회 호출 당 파일 3개 이하를 원칙으로 한다
+
+### 분해 체크리스트
 - [ ] 사용자가 원하는 최종 결과물은?
+- [ ] 가장 작은 동작 단위로 쪼갰는가?
+- [ ] 각 단위가 독립적으로 확인 가능한가?
 - [ ] 변경되는 레이어는? (UI / API / Domain / DB)
-- [ ] 기존 코드에 영향을 주는 범위는?
 - [ ] 작업 간 순서 의존성이 있는가?
-- [ ] 외부 의존성이 있는가? (패키지 설치, DB 마이그레이션 등)
+- [ ] 외부 의존성이 있는가? (패키지 설치, DB 마이그레이션 등)
+
+### plan.md 작업 순서 작성 예시
+```markdown
+## 작업 순서 (단위별)
+1. Entity + Repository 정의 → implementer-be (파일 2개)
+2. 목록 조회 API → implementer-be (파일 2개) → **확인**
+3. 목록 UI → implementer-fe (파일 2~3개) → **확인**
+4. 생성 API + UI → implementer-be → implementer-fe → **확인**
+5. 수정/삭제 → implementer-be → implementer-fe → **확인**
+```

package/README.md

@@ -53,8 +53,16 @@
 │   │   ├── SKILL.md             ← TDD 핵심 원칙
 │   │   ├── frontend.md          ← React 테스트 규칙
 │   │   └── backend.md           ← NestJS 테스트 규칙
-│   └── Git/
-│       └── SKILL.md             ← 커밋/PR/브랜치 규칙
+│   ├── Git/
+│   │   └── SKILL.md             ← 커밋/PR/브랜치 규칙
+│   ├── FailureRecovery/
+│   │   └── SKILL.md             ← 실패 복구 프로토콜
+│   └── Curation/
+│       └── SKILL.md             ← AI 결과물 큐레이션 체크리스트
+├── prompts/
+│   ├── feature.md               ← /feature [기능명] 커스텀 커맨드
+│   ├── fix.md                   ← /fix [증상] 커스텀 커맨드
+│   └── review.md                ← /review 커스텀 커맨드
 ├── hooks/
 │   ├── prompt-hook.sh           ← 통합 hook (품질 체크 + 스킬 추천 + 구조 변경 감지)
 │   └── skill-keywords.conf      ← 스킬별 키워드 매핑 설정

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@choblue/claude-code-toolkit",
-  "version": "1.2.4",
+  "version": "1.2.6",
   "description": "Claude Code 서브에이전트 위임 툴킷 - npx로 바로 설치",
   "bin": {
     "claude-code-toolkit": "bin/cli.js"