---
name: kkirikkiri
description: 자연어 한마디로 AI 에이전트 팀을 자동 구성하고 실행하는 스킬. "/kkirikkiri", "팀 만들어줘", "리서치 팀", "끼리끼리", "팀 구성해줘" 같은 요청에 사용됩니다.
---

# 끼리끼리 Team Builder Skill

> 자연어 한마디 → 인터뷰 → 환경 스캔 → 팀 구성 → 실행 → 리포트

사용자의 자연어 요청을 받아 목적에 맞는 AI 에이전트 팀을 구성하고 실행한다.

---

## WHEN TRIGGERED - EXECUTE IMMEDIATELY

**이 문서는 참고 문서가 아니라 실행 지시서다.**
- 첫 번째 action: 사전 준비(레퍼런스 파일 읽기) 후 즉시 Step 1~3의 AskUserQuestion 도구를 호출
- 텍스트 출력 후 질문하지 않는다. 도구를 먼저 호출한다.
- 모든 질문은 AskUserQuestion 도구 호출로만 진행한다.

---

## 사전 준비

이 스킬이 호출되면 반드시 다음 레퍼런스 파일을 읽는다:
- `${CLAUDE_PLUGIN_ROOT}/skills/kkirikkiri/references/presets.md` — 프리셋 정의
- `${CLAUDE_PLUGIN_ROOT}/skills/kkirikkiri/references/interview-guide.md` — 인터뷰 방법론
- `${CLAUDE_PLUGIN_ROOT}/skills/kkirikkiri/references/metaphor-guide.md` — 기술 용어 → 일상 표현 변환표

---

## 워크플로우 개요

```
Step 1: 의도 파악 + 프리셋 매칭
Step 2: 환경 스캔 (백그라운드)
Step 3: 인터뷰 (AskUserQuestion)
Step 4: 동적 팀 구성
Step 5: 팀 구성 제안 + 유저 확인
Step 6: 팀 생성 + 공유 메모리 초기화 + 실행
Step 7: 검증 루프 (품질이 충분할 때까지 반복)
Step 8: 결과 수집 + 리포트
```

### 핵심 운영 원칙

**1. 기억 외부화**: 클로드의 기억력을 믿지 마. 중요한 결정은 반드시 파일에 기록.
**2. 심부름꾼 패턴**: 팀원은 필요하면 하위 에이전트를 스폰하여 병렬 작업 가능.
**3. 검증 루프**: 1라운드 결과가 부족하면 팀을 재구성하여 2라운드 진행.

---

## Step 1: 의도 파악 + 프리셋 매칭

사용자의 자연어 입력에서 키워드를 추출하여 프리셋을 매칭한다.

### 매칭 규칙 (presets.md의 keywords 참조)

| 프리셋 | 키워드 |
|--------|--------|
| research | 조사, 리서치, 찾아줘, 알아봐줘, 검색, 분석해줘, 비교해줘 |
| development | 만들어줘, 구현해줘, 개발해줘, 코딩해줘, 기능 추가, 리팩토링 |
| analysis | 분석해줘, 파악해줘, 구조 분석, 코드 분석, 리뷰해줘, 검토해줘 |
| content | 문서, README, 작성해줘, 써줘, 블로그, 가이드, 튜토리얼 |

### 입력 모드

| 모드 | 입력 예시 | 처리 |
|------|----------|------|
| **자연어** (기본) | "리서치 팀 만들어줘" | 키워드 매칭 → 프리셋 → 인터뷰 |
| **파일 지정** | "@deep-research 팀으로 실행해줘" | 파일 분석 → 역할 자동 분해 |

#### 파일 모드 처리

사용자 입력에 `@파일명` 또는 파일 경로가 포함되면:

1. 해당 파일을 Read로 읽기 (`.claude/agents/*.md`, 스킬 파일, 일반 `.md` 등)
2. 파일 내용을 분석하여 필요한 역할 자동 추출:
   - 스킬 파일 → 스킬의 단계별 역할을 팀원으로 분해
   - 에이전트 파일 → 해당 에이전트를 팀원으로 포함
   - 일반 문서 → 문서 목표를 기반으로 프리셋 매칭
3. 인터뷰는 1-2개로 축소 (파일에서 대부분의 정보를 이미 파악했으므로)

```
사용자: "@deep-research 팀으로 실행해줘"
→ .claude/agents/deep-research.md 읽기
→ 에이전트의 역할/도구/목표 파악
→ 필요한 보조 역할 자동 설계
→ "이 에이전트를 중심으로 팀을 구성할게요. 추가로 뭘 도와줄까요?" (인터뷰 축소)
```

### 매칭 방법 (자연어 모드)
1. 사용자 입력에서 각 프리셋의 키워드 매칭 횟수를 세기
2. 가장 많이 매칭된 프리셋 선택
3. 동점이면 입력 문맥을 분석하여 가장 적합한 것 선택
4. **매칭 실패 시**: generic(범용) 인터뷰로 전환 (presets.md의 "범용 팀" 참조)

### 주의
- "분석해줘"는 research와 analysis 모두 매칭 가능 → 문맥으로 판단
  - "경쟁사 분석" → research (외부 정보 조사)
  - "코드 분석" → analysis (내부 코드 탐색)

---

## Step 2: 환경 스캔

인터뷰와 **병렬로** 환경을 스캔한다. Bash 도구로 아래를 확인한다.

### Auto-memory 활용

Auto-memory를 2가지 용도로 활용한다:

**1. 환경 캐싱 (시작 속도 향상):**
- 이전 스캔 결과가 있으면 빠른 확인만 수행 (변경 없으면 "이전과 동일한 환경입니다" 한 줄로 진행)
- 선호 프리셋/팀 구성 패턴이 기억에 있으면 인터뷰 시 "(기억 기반 추천)" 표시

**2. 공유 컨텍스트 인덱스 (팀원 교체 대응):**
팀원이 교체되면 새 팀원은 기존 맥락을 모른다. 팀장이 팀원 프롬프트에 공유 문서 인덱스를 포함하여 교체된 팀원이 즉시 따라잡을 수 있게 한다.

팀장이 교체 팀원에게 전달할 컨텍스트 인덱스:
```
프로젝트 공유 메모리 (반드시 읽을 것):
- {프로젝트루트}/.kkirikkiri/TEAM_PLAN.md — 전체 계획 + 역할 배분 (최우선)
- {프로젝트루트}/.kkirikkiri/TEAM_PROGRESS.md — 현재 진행 상황
- {프로젝트루트}/.kkirikkiri/TEAM_FINDINGS.md — 지금까지 발견한 것들
- {프로젝트루트}/.kkirikkiri/DEAD_ENDS — 실패한 접근 (이 방법은 하지 마)
```

교체 팀원 온보딩 순서: DEAD_ENDS(하지 말 것) → TEAM_PLAN(할 것) → PROGRESS(현재 상황) → FINDINGS(참고)

Step 8 완료 시, 이 인덱스 + 팀 구성/환경/결과를 자연어로 요약 출력하여 Auto-memory 저장을 유도한다.

### 스캔 항목

```bash
# 1. 외부 AI CLI 확인
command -v codex >/dev/null 2>&1 && codex --version
command -v gemini >/dev/null 2>&1 && gemini --version

# 2. 개발 도구 확인
command -v gh >/dev/null 2>&1    # GitHub CLI
command -v npm >/dev/null 2>&1   # npm
command -v bun >/dev/null 2>&1   # bun
command -v pnpm >/dev/null 2>&1  # pnpm

# 3. 기존 에이전트 파일 확인
ls .claude/agents/*.md 2>/dev/null
```

### 스캔 결과 저장 (내부 변수로 관리)

스캔 결과를 다음 구조로 정리한다 (파일 저장 불필요, 메모리에만):

```
환경 정보:
- codex_cli: true/false (경로, 버전)
- gemini_cli: true/false (경로, 버전)
- gh_cli: true/false
- package_manager: npm/bun/pnpm
- existing_agents: [파일 목록]
- perplexity_mcp: true/false (MCP 도구 목록에서 perplexity 확인)
```

### 기존 에이전트 재활용

`.claude/agents/` 에 기존 에이전트 파일이 있으면 팀에 활용할 수 있습니다.

#### 재활용 판단 기준

1. 기존 에이전트 파일을 Read로 읽기
2. 에이전트의 역할/도구/목표가 현재 팀 목적과 관련 있는지 판단
3. 관련 있으면 → 해당 에이전트를 팀원으로 포함 (별도 스폰 불필요)
4. 관련 없으면 → 무시

#### 재활용 방법

기존 에이전트를 팀에 포함할 때:

```
Task({
  team_name: "[팀이름]",
  name: "[에이전트-파일명]",
  subagent_type: "[에이전트-파일명]",  // .claude/agents/ 내 파일명
  model: "opus",
  prompt: "[팀 컨텍스트 + 공유 메모리 경로 추가]"
})
```

- 기존 에이전트의 시스템 프롬프트에 공유 메모리 규칙을 **추가로** 덧붙임
- 기존 에이전트의 원래 역할은 그대로 유지
- 팀장에게 "이 팀원은 기존에 정의된 전문가입니다" 알림

#### 사용자 안내

기존 에이전트를 발견하면:
```
"기존에 설정된 전문가가 있어요: [에이전트 설명].
 팀에 포함시킬까요?"
```

### MCP 확인 방법

현재 세션에서 사용 가능한 MCP 도구가 있는지 확인한다:
- `mcp__perplexity__` 로 시작하는 도구 → Perplexity MCP 있음
- 기타 MCP 도구 → 해당 도구 활용 가능

---

## Step 3: 인터뷰

presets.md에 정의된 프리셋별 인터뷰 질문을 **반드시 AskUserQuestion 도구를 호출하여** 진행한다. 질문/옵션을 텍스트로 출력하면 안 된다.

### 인터뷰 실행 규칙

1. **Q1만 스킵 가능, Q2/Q3는 반드시 AskUserQuestion으로 호출한다** (예외 없음)
   - Q1(열린 질문)은 사용자가 이미 자연어로 답한 경우에만 생략 가능
   - 예: "경쟁사 3곳 비교 리서치 해줘" → Q1("어떤 주제?")의 답이 이미 있음
   - Q2, Q3는 **절대 스킵하지 않는다**. 반드시 AskUserQuestion을 호출하여 사용자 선택을 받는다
   - "테스트", "진행해줘" 같은 모호한 입력은 Q1도 스킵하지 않는다

2. **EXECUTE:** presets.md의 프리셋별 질문을 아래 JSON 형식으로 변환한 후 AskUserQuestion 도구를 즉시 호출한다:

   ```json
   {
     "questions": [
       {
         "question": "결과물은 어떤 형태면 좋겠어요?",
         "header": "결과물",
         "options": [
           {"label": "종합 리포트 (추천)", "description": "깊이 있는 분석 문서. 여러 소스 교차 검증. 시간 좀 걸림."},
           {"label": "비교표", "description": "여러 옵션을 나란히 비교. 의사결정할 때 좋음."},
           {"label": "핵심 요약", "description": "1-2페이지. 빠르게 핵심만."},
           {"label": "잘 모르겠어요", "description": "종합 리포트로 갈게요."}
         ],
         "multiSelect": false
       }
     ]
   }
   ```

3. **절대 금지**:
   - 4개 이상 질문 금지
   - 기술 용어(Opus, Sonnet, MCP, Agent Teams) 유저에게 노출 금지
   - 설명 없이 옵션만 나열 금지

4. **generic 프리셋일 경우**:
   - Q1으로 목표 파악 → Q2로 유형 선택 → 해당 프리셋 인터뷰 이어서 진행

---

## Step 4: 동적 팀 구성

인터뷰 답변 + 환경 스캔 결과를 종합하여 최종 팀을 구성한다.

### 구성 프로세스

1. **프리셋 기본 구성**에서 시작 (presets.md 참조)
2. **인터뷰 답변으로 조정**:
   - 리서치 Q3 "깊고 포괄적" → 확장 구성 (4-5명)
   - 개발 Q3 "테스트도 같이" → Tester 추가
   - 분석 Q2에서 여러 관점 선택 → Explorer 역할 세분화
3. **환경 스캔으로 조정**:
   - Codex CLI 있음 → 코드 리뷰/분석 역할에 외부 CLI 배정
   - Gemini CLI 있음 → 디자인/대규모 분석에 외부 CLI 배정
   - Perplexity MCP 있음 → 리서치 팀원에게 도구로 배정
   - gh CLI 있음 → 개발 팀에 PR 관리 가능 알림

### 모델 배정 규칙 (절대 준수)

| 역할 | 모델 | 비고 |
|------|------|------|
| Lead (팀장) | **Opus** | 무조건. 예외 없음 |
| 핵심 작업자 | **Opus** | 기본값 |
| 보조 작업자 | **Sonnet** | 최소한으로만 |
| Haiku | **사용 금지** | 어떤 역할에도 배정하지 않음 |
| 외부 분석 | **Codex CLI** | CLI 없으면 Opus로 폴백 |
| 외부 디자인/분석 | **Gemini CLI** | CLI 없으면 Sonnet으로 폴백 |

### 팀장 R&R (절대 준수)

- 팀장은 **코드를 짜지 않는다**
- 팀장은 **직접 검색하지 않는다**
- 팀장은 **직접 문서를 작성하지 않는다**
- 팀장은 **계획 수립, 태스크 분배, 결과 검증, 최종 통합**만 수행
- 팀장이 직접 작업하면 R&R 위반

### CLI 없을 때 폴백

외부 CLI(Codex/Gemini)가 없는 경우:

1. 사용자에게 안내 (기술 용어 없이):
   ```
   "추가 AI 도구가 있으면 더 전문적인 분석이 가능해요.
    설치하시겠어요? (선택사항이에요, 없어도 잘 동작해요)"
   ```
2. 사용자가 거절하면 → 해당 역할을 Claude(Opus 또는 Sonnet)로 대체
3. 사용자가 수락하면 → 설치 명령어 안내 후 재스캔

---

## Step 5: 팀 구성 제안 + 유저 확인

최종 팀 구성을 사용자에게 보여주고 확인을 받습니다.

### 제안 형식

```
이렇게 팀을 구성할게요:

📋 목표: [인터뷰에서 파악한 목표]

팀 구성:
├── 팀장 — [구체적 역할 설명] (가장 똑똑한 AI)
├── [역할명 1] — [구체적 역할 설명] (전문 AI)
├── [역할명 2] — [구체적 역할 설명] (전문 AI)
└── (선택) [외부 도구] — [역할 설명] (백그라운드)

예상 작업 방식:
1. 팀장이 전체 계획을 세우고 각자 역할을 배분합니다
2. 팀원들이 동시에 작업을 수행합니다
3. 팀장이 결과를 검증하고 통합합니다
4. 최종 리포트를 생성합니다

⏱️ 예상 소요 시간: [규모에 따라 10-30분]

이대로 진행할까요?
```

### 비용/시간 안내 규칙

유저에게 팀 구성을 제안할 때, **예상 소요 시간**을 반드시 안내한다.

| 팀 규모 | 예상 소요 시간 |
|---------|---------------|
| 기본 3명 | 10-15분 |
| 확장 4-5명 | 15-25분 |
| 외부 CLI 포함 | +5-10분 |

비용 절약 힌트도 제공:
```
💡 팁: 빠르게 핵심만 필요하면 팀 규모를 줄일 수 있어요.
   대신 깊이가 좀 얕아질 수 있어요.
```

### 모델 비유 용어 (유저에게 보여줄 때)

| 내부 모델명 | 유저에게 보여줄 표현 | 설명 |
|------------|-------------------|------|
| Opus | "가장 똑똑한 AI" | 복잡한 판단, 기획, 통합에 적합 |
| Sonnet | "전문 AI" 또는 "균형잡힌 AI" | 실행력 좋고 효율적 |
| Codex CLI | "코드 전문 AI" | 코드 분석/리뷰 특화 |
| Gemini CLI | "대규모 분석 AI" | 큰 파일/많은 문서 처리에 강함 |

### 제안 시 금지사항
- 모델명(Opus, Sonnet) 노출 금지
- 기술 용어(TeamCreate, Task, MCP) 노출 금지
- 위의 비유 용어표를 사용하여 일상 용어로 설명

### 유저 확인

**반드시 AskUserQuestion을 호출하여 유저의 승인을 받는다.** 텍스트로 "이대로 진행할까요?"라고만 말하지 말고, AskUserQuestion 도구를 실제로 호출한다.

markdown 필드에는 팀 구성을 문자열로 동적 생성하여 전달한다. 아래는 호출 형식:

**EXECUTE:** 아래 JSON의 markdown 필드를 팀 구성 트리 + 역할 테이블 + 예상 소요시간으로 채운 후 AskUserQuestion 도구를 즉시 호출한다:

```json
{
  "questions": [
    {
      "question": "이 팀 구성으로 시작할까요?",
      "header": "팀 확인",
      "options": [
        {
          "label": "네, 시작해주세요 (추천)",
          "description": "위 구성대로 팀을 만들고 바로 작업을 시작합니다.",
          "markdown": "(동적: 팀 구성 트리 + 역할 테이블 + 예상 소요시간)"
        },
        {
          "label": "팀원을 조정하고 싶어요",
          "description": "역할이나 인원수를 바꿀 수 있어요."
        },
        {
          "label": "처음부터 다시",
          "description": "인터뷰를 다시 진행합니다."
        }
      ],
      "multiSelect": false
    }
  ]
}
```

**markdown 필드 생성 규칙:**
- markdown은 반드시 하나의 문자열이어야 한다 (줄바꿈은 `\n` 사용)
- 팀 구성에 맞게 트리, 표, 소요시간을 동적으로 채워 넣는다
- 모델명은 비유 용어표를 사용한다 (Opus → "가장 똑똑한 AI" 등)
- 이 코드블록의 `[대괄호]` 부분을 실제 값으로 치환한다

**응답 처리:**
- "네, 시작해주세요" → Step 6으로 진행
- "조정하고 싶어요" → 어떤 부분을 바꾸고 싶은지 추가 질문 후 Step 4로
- "처음부터 다시" → Step 1로

---

## Step 6: 팀 생성 + 공유 메모리 + 실행

확인을 받으면 Claude Code Agent Teams를 사용하여 팀을 생성하고 실행한다.

### 6-1. 팀 생성

```
TeamCreate({
  team_name: "kkirikkiri-{preset}-{timestamp}",
  description: "[팀 목표 요약]"
})
```

team_name 예시: `kkirikkiri-research-0227-1430`

### 6-2. 공유 메모리 초기화 (기억 외부화)

> **클로드의 기억력을 믿지 마. 중요한 결정은 반드시 파일에 기록.**
> 대화가 길어지면 오래된 내용이 압축되어 까먹는다.
> 파일에 기록하면 기억이 날아가도 파일만 읽으면 복구된다.

팀 생성 직후, 프로젝트 루트에 공유 메모리 파일 3종을 생성한다.

**기존 파일 처리 (중요):**
이전 세션의 `.kkirikkiri/` 파일이 남아있을 수 있다. Write 도구는 읽지 않은 파일에 쓰기를 거부하므로, 반드시 아래 순서를 따른다:

```
1. Bash("ls {프로젝트루트}/.kkirikkiri/ 2>/dev/null") 로 기존 파일 존재 확인
2. 파일이 존재하면 → Read(file_path, limit=5) 로 먼저 읽기
3. 그 후 Write 로 새 내용으로 덮어쓰기
4. 파일이 없으면 → 바로 Write 로 생성
```

대상 파일:
```
{프로젝트루트}/.kkirikkiri/TEAM_PLAN.md
{프로젝트루트}/.kkirikkiri/TEAM_PROGRESS.md
{프로젝트루트}/.kkirikkiri/TEAM_FINDINGS.md
```

#### TEAM_PLAN.md (팀장이 관리)
```markdown
# 팀 작업 계획

- 팀명: [team_name]
- 목표: [인터뷰에서 파악한 목표]
- 생성 시각: [timestamp]

## 팀 구성
| 이름 | 역할 | 모델 | 담당 업무 |
|------|------|------|----------|
| [leader] | 팀장 | Opus | 계획/배분/검증/통합 |
| [member-1] | [역할] | [모델] | [업무] |
| ... | ... | ... | ... |

## 태스크 목록
- [ ] 태스크 1: [설명] → [담당자]
- [ ] 태스크 2: [설명] → [담당자]

## 주요 결정사항
(팀장이 결정할 때마다 여기에 기록)
```

#### TEAM_PROGRESS.md (모든 팀원이 기록)
```markdown
# 진행 상황

## [timestamp] — [팀원명]
- 상태: 진행 중 / 완료 / 차단됨
- 작업: [수행한 작업]
- 결과: [핵심 발견/산출물]
- 다음: [다음 할 일]
```

#### TEAM_FINDINGS.md (모든 팀원이 기록)
```markdown
# 발견 사항 & 공유 자료

## [timestamp] — [팀원명]: [제목]
[발견한 내용, URL, 코드 스니펫 등]

---

# DEAD_ENDS (시도했으나 실패한 접근)

## [timestamp] — [팀원명]: [시도한 접근]
- 시도: [무엇을 했는지]
- 결과: [왜 실패/부적합했는지]
- 근거: [파일경로, 에러 메시지, 테스트 결과 등]
```

> **DEAD_ENDS가 중요한 이유**: 팀을 재구성할 때 새 팀이 같은 막다른 골목을 다시 탐색하는 것을 방지한다.
> 긍정적 발견만 기록하면 공유 메모리의 효과가 60-70%에 그치지만,
> 실패한 접근까지 기록하면 75-80%까지 컨텍스트를 복구할 수 있습니다.

### 공유 메모리 규칙

| 규칙 | 설명 |
|------|------|
| **팀장은 TEAM_PLAN.md를 유지** | 결정이 나올 때마다 즉시 기록 |
| **모든 팀원은 PROGRESS에 기록** | 작업 시작/완료/차단 시 반드시 업데이트 |
| **팀원은 FINDINGS에 공유** | 다른 팀원에게 유용한 발견은 파일로 공유 |
| **실패한 접근은 DEAD_ENDS에 기록** | "시도 → 실패 이유 → 근거"를 남겨서 다음 라운드/새 팀이 같은 실수 방지 |
| **기억이 의심되면 파일을 읽어** | 컨텍스트가 길어졌다 싶으면 공유 파일 재확인 |
| **팀장은 통합 전 3개 파일 전부 읽어** | 최종 결과물 만들기 전 전체 맥락 복구 |
| **새 팀원은 합류 시 3개 파일 + DEAD_ENDS 먼저 읽어** | 이전 컨텍스트 복구 후 작업 시작 |

### 6-3. 태스크 생성

팀장이 수행할 전체 작업 계획을 기반으로 TaskCreate로 태스크를 생성한다.

```
TaskCreate({
  subject: "[태스크 제목]",
  description: "[구체적 작업 내용, 기대 결과물, 제약사항]",
  activeForm: "[진행 중 표시 텍스트]"
})
```

태스크 예시 (리서치 팀):
1. "리서치 계획 수립" — 팀장이 소스 배분, 검색 전략 결정
2. "웹 리서치 수행" — 리서처 1이 최신 뉴스/블로그 조사
3. "문서 리서치 수행" — 리서처 2가 공식 문서/학술 자료 조사
4. "결과 통합 + 리포트" — 팀장이 검증/통합, 리포트 작성 지시

### 6-4. Claude 팀원 스폰

각 팀원을 Task 도구로 스폰한다:

```
Task({
  team_name: "kkirikkiri-{preset}-{timestamp}",
  name: "[팀원-이름]",
  subagent_type: "general-purpose",
  model: "opus",  // 또는 "sonnet" (역할에 따라)
  prompt: "[상세 역할 지시]"
})
```

### 팀원 스폰 시 프롬프트 작성 규칙

각 팀원의 프롬프트에 반드시 포함할 내용:

```
당신은 "[팀명]"의 [역할명]입니다.

## 당신의 역할
[구체적 R&R 설명]

## 당신이 해야 할 일
[구체적 태스크 목록]

## 절대 하지 마
[R&R 위반 사항]

## 공유 메모리 (반드시 활용)
팀의 기억은 파일에 있습니다. 기억이 가물가물하면 반드시 파일을 다시 읽으세요.

- 작업 계획: {프로젝트루트}/.kkirikkiri/TEAM_PLAN.md (Read로 확인)
- 진행 상황: {프로젝트루트}/.kkirikkiri/TEAM_PROGRESS.md (작업 시작/완료 시 Edit으로 추가)
- 발견 사항: {프로젝트루트}/.kkirikkiri/TEAM_FINDINGS.md (유용한 발견 시 Edit으로 추가)

**규칙**:
- 작업 시작할 때 TEAM_PROGRESS.md에 "시작" 기록
- 작업 완료할 때 TEAM_PROGRESS.md에 "완료" + 결과 요약 기록
- 다른 팀원에게 유용한 정보 발견 시 TEAM_FINDINGS.md에 기록
- **시도했으나 실패한 접근은 DEAD_ENDS 섹션에 반드시 기록** (시도 → 실패 이유 → 근거)
- 컨텍스트가 길어져서 기억이 흐릿하면 3개 파일을 다시 읽기

## 심부름꾼 (하위 에이전트) 활용
작업량이 많거나 병렬 처리가 필요하면, Task 도구로 하위 에이전트(심부름꾼)를 스폰할 수 있습니다.

심부름꾼 스폰 방법:
```
Task({
  subagent_type: "general-purpose",
  model: "sonnet",  // 심부름꾼은 Sonnet
  prompt: "[구체적 작업 지시]"
})
```

심부름꾼 규칙:
- 심부름꾼은 단순하고 명확한 작업만 (검색, 파일 읽기, 특정 분석)
- 심부름꾼은 Sonnet 모델 사용 (비용 절약)
- 동시에 최대 3-5개까지 병렬 스폰 가능
- 심부름꾼의 결과를 받으면 반드시 검토 후 TEAM_FINDINGS.md에 기록
- 작업이 끝난 심부름꾼은 자동 종료됨 (팀에 소속되지 않음)

심부름꾼 활용 예시 (리서처):
- "키워드 A로 웹 검색해서 상위 5개 결과 요약" → 심부름꾼 1
- "키워드 B로 웹 검색해서 상위 5개 결과 요약" → 심부름꾼 2
- "이 URL 3개의 내용을 요약" → 심부름꾼 3
→ 3개 동시 실행, 결과 수집 후 통합

## 작업 완료 시
1. TEAM_PROGRESS.md에 완료 기록
2. TaskUpdate로 태스크를 completed로 변경
3. SendMessage로 팀장에게 결과를 보고
4. 다음 태스크가 있는지 TaskList로 확인

## 팀 정보
- 팀 이름: [team_name]
- 팀장: [leader-name]
- 다른 팀원: [목록]
```

### 팀장 스폰 시 특별 프롬프트

팀장은 다른 팀원보다 먼저 스폰하고, 다음을 포함:

```
당신은 "[팀명]"의 팀장입니다.

## 당신의 역할 (PM)
- 전체 작업 계획 수립 → TEAM_PLAN.md에 기록
- 태스크를 팀원에게 배분 (TaskUpdate의 owner 사용)
- 팀원의 결과를 검증하고 피드백
- 최종 결과물 통합

## 절대 하지 마
- 직접 코드를 작성하지 마세요
- 직접 검색/조사를 수행하지 마세요
- 직접 문서를 작성하지 마세요 (최종 통합 리포트만 예외)
- 당신은 PM입니다. 지시하고, 검증하고, 통합하세요.

## 공유 메모리 관리 (가장 중요한 임무)
당신은 팀의 기억을 관리하는 사람입니다.
클로드의 대화 기억은 길어지면 사라집니다. 파일만이 영구적입니다.

- **TEAM_PLAN.md**: 당신이 관리. 결정이 나올 때마다 즉시 기록.
- **TEAM_PROGRESS.md**: 팀원들이 기록. 주기적으로 읽어서 전체 진행 파악.
- **TEAM_FINDINGS.md**: 팀원들이 기록. 결과 통합 시 반드시 참조.

**핵심 규칙**:
- 중요한 결정을 내릴 때마다 TEAM_PLAN.md에 즉시 기록
- 기억이 가물가물하면 3개 파일을 전부 다시 읽기
- 최종 통합 전에 반드시 3개 파일 전부 읽고 시작

## 팀원 관리
- SendMessage로 팀원에게 지시를 내리세요
- 팀원이 결과를 보고하면 검증 후 피드백하세요
- 팀원의 결과가 부족하면 구체적 피드백과 함께 재작업 지시
- 모든 팀원의 작업이 완료되면 결과를 통합하세요

## 심부름꾼 활용 지시
팀원에게 작업량이 많을 때, 심부름꾼(하위 에이전트) 활용을 지시하세요:
- "검색할 키워드가 많으니 심부름꾼 3개 스폰해서 병렬로 처리하세요"
- "이 파일들 분석이 필요하니 심부름꾼에게 나눠서 시키세요"
- 심부름꾼은 팀원이 직접 관리 (팀장이 관여하지 않음)

## 품질 검증
1라운드 결과를 받으면 다음 4가지 기준으로 검증:

| 기준 | 통과 | 실패 |
|------|------|------|
| **목표 달성도** | 인터뷰에서 파악한 목표를 충족 | 방향 자체가 다름 → 재구성 신호 |
| **완성도** | 빠진 항목/분석/코드 없음 | 양적으로 부족 → 보강 가능 |
| **정확성** | 출처/근거/테스트 충분 | 근거 부족 → 보강 가능 |
| **일관성** | 팀원 간 결과 모순 없음 | 모순 있음 → 부분 교체 신호 |

검증 결과를 TEAM_PLAN.md의 "검증 결과" 섹션에 기록하세요:
```
## 검증 결과 (N라운드)
- 목표 달성도: PASS/FAIL — [근거]
- 완성도: PASS/FAIL — [근거]
- 정확성: PASS/FAIL — [근거]
- 일관성: PASS/FAIL — [근거]
- 종합 판정: [충분/보강필요/재구성필요]
```

**바이어스 방지**: 직접 검증이 어려우면 심부름꾼을 스폰하여 독립 검토를 시키세요.
검증자는 당신의 계획을 모르는 상태에서 결과물만 보고 판단해야 합니다 (블라인드 리뷰).

품질이 부족하면:
→ 메인 세션에 "1라운드 결과가 [이유]로 부족합니다. [목표달성도/완성도/정확성/일관성] 중 [미달 항목]이 미달입니다." 보고
→ 메인 세션이 방식 A/B/C 중 하나를 선택하여 2라운드를 진행합니다

## 작업 완료 시
모든 팀원의 작업이 완료되고 품질 검증 통과 시:
1. TEAM_PLAN.md, TEAM_PROGRESS.md, TEAM_FINDINGS.md를 전부 읽기
2. 결과를 통합하여 최종 리포트 작성 (Write 도구 사용)
3. 리포트 파일: {프로젝트루트}/kkirikkiri-report-{timestamp}.md
4. SendMessage(type: "message")로 메인 세션에 완료 보고
5. 모든 팀원에게 SendMessage(type: "shutdown_request") 전송
```

### 6-5. 외부 CLI 실행 (Codex/Gemini)

외부 CLI가 배정된 역할이 있으면, 팀장에게 다음 지시를 포함한다:

```
## 외부 AI 활용
Codex CLI로 [역할]을 수행합니다. 다음 절차를 따르세요:

1. 프롬프트 파일 작성:
   Write 도구로 .kkirikkiri/prompts/{task-id}.md에 분석 요청 작성

2. CLI 실행:
   Bash(run_in_background=true):
   "bash ${CLAUDE_PLUGIN_ROOT}/scripts/run-cli.sh start --provider codex --prompt-file .kkirikkiri/prompts/{task-id}.md"
   → 출력되는 JOB_DIR 경로를 저장

3. 완료 대기:
   Bash: "bash ${CLAUDE_PLUGIN_ROOT}/scripts/run-cli.sh wait JOB_DIR"

4. 결과 확인:
   Bash: "bash ${CLAUDE_PLUGIN_ROOT}/scripts/run-cli.sh results JOB_DIR"

5. 결과를 TEAM_FINDINGS.md에 기록
6. 작업 디렉토리 정리:
   Bash: "bash ${CLAUDE_PLUGIN_ROOT}/scripts/run-cli.sh clean JOB_DIR"
```

### 6-6. 태스크 배정

팀장이 스폰되면, 팀장에게 메시지를 보내 태스크 배분을 지시한다:

```
SendMessage({
  type: "message",
  recipient: "[leader-name]",
  content: "팀이 구성되었습니다. 공유 메모리 파일(.kkirikkiri/)이 초기화되었습니다. TEAM_PLAN.md를 읽고 팀원들에게 태스크를 배분해주세요.",
  summary: "팀 구성 완료, 태스크 배분 시작"
})
```

---

## Step 7: 검증 루프 (Ralph Pattern)

> **1라운드로 끝내지 않는다. 품질이 충분할 때까지 반복한다.**
> ddg.kang: "팀리더가 30명 심부름꾼이 구현한거 최종검토 → 나에게 최종 보고 = 버그 하나도 없음"

### 7-1. 진행 상황 모니터링

팀장과 팀원들의 메시지를 수신하며 진행 상황을 모니터링한다.
메시지는 자동으로 전달되므로 별도 폴링 불필요.

### 7-2. 1라운드 완료 확인

팀장이 완료 보고를 보내면:

1. 리포트 파일 확인 (Read 도구)
2. TEAM_PLAN.md의 "검증 결과" 섹션 확인
3. 팀장의 품질 평가 확인

### 7-3. 품질 판정

팀장의 보고를 기반으로 품질을 판정:

```
판정 기준:
- 목표 달성도: 인터뷰에서 파악한 목표를 충족하는가?
- 완성도: 빠진 항목/분석/코드가 없는가?
- 정확성: 출처/근거/테스트가 충분한가?
- 일관성: 팀원 간 결과가 모순되지 않는가?
```

### 7-4. 품질 충분 → Step 8로

모든 기준 통과 시 Step 8(결과 수집 + 리포트)로 진행.

### 7-5. 품질 부족 → 자동 판정 + 2라운드 진행

품질이 부족하면, 먼저 **어떤 기준이 미달인지** 파악하여 최적 전략을 자동 결정한다.

#### 자동 판정 로직 (Agent Council 합의)

```
IF 목표_달성도 = FAIL:
    → 방식 B (전체 재구성) — 방향 자체가 잘못됨

ELIF 일관성 = FAIL:
    → 방식 C (부분 교체) — 모순된 결과를 낸 팀원만 교체

ELIF 완성도 = FAIL OR 정확성 = FAIL:
    → 방식 A (팀 유지 + 보강) — 방향은 맞고 양/질이 부족

ELIF 라운드 >= 3:
    → 중단 — 현재 최선 결과로 리포트 생성
```

판정 결과를 사용자에게 제안 (최종 결정은 유저):

**EXECUTE:** 아래 JSON의 question 필드를 품질 판정 결과로 채운 후 AskUserQuestion 도구를 즉시 호출한다:

```json
{
  "questions": [
    {
      "question": "(동적: 1라운드 결과 + 부족한 부분 설명). 보강할까요?",
      "header": "품질 검증",
      "options": [
        {"label": "네, 보강해주세요 (추천)", "description": "부족한 부분을 집중적으로 보완합니다. 시간이 좀 더 걸려요."},
        {"label": "이 정도면 괜찮아요", "description": "현재 결과를 최종 리포트로 정리합니다."},
        {"label": "처음부터 다시", "description": "팀을 해산하고 새로 구성합니다."}
      ],
      "multiSelect": false
    }
  ]
}
```

### 7-6. 2라운드 실행 방식 (3가지)

사용자가 "보강해주세요" 선택 시, 자동 판정 결과에 따라 A/B/C 중 선택:

**방식 A: 기존 팀 유지 + 추가 지시**
- **조건**: 방향은 맞지만 완성도/정확성이 부족한 경우
- **바이어스 방지책** (반드시 적용):
  1. **외부 검증자 추가**: 심부름꾼 패턴으로 Sonnet 검증자 1명 스폰하여 독립 평가
  2. **역할 순환**: 팀원들의 담당 영역을 교차 배정하여 교차 검증
  3. **반론 의무**: 팀장에게 "기존 결론에 대한 반론을 먼저 제시하라" 지시
- 팀장에게 보강 지시:
  ```
  SendMessage({
    type: "message",
    recipient: "[leader-name]",
    content: "1라운드 결과에서 [부족한 부분]이 부족합니다. 2라운드 규칙: (1) 검증용 심부름꾼을 스폰하여 1라운드 결과를 독립 검토시키세요. (2) 팀원들의 담당 영역을 교차 배정하세요. (3) 기존 결론에 대한 반론부터 검토하세요.",
    summary: "2라운드 보강 지시 (바이어스 방지 포함)"
  })
  ```

**방식 B: 팀 해산 + 새 팀 구성**
- **조건**: 목표 달성도 자체가 미달 (접근 방식이 근본적으로 잘못됨)
- 또는 사용자가 "처음부터 다시" 선택 시
- 기존 팀 종료:
  ```
  # 기존 팀원 전원 해고
  SendMessage({ type: "shutdown_request", recipient: "[각 팀원]" })
  TeamDelete()
  ```
- 새 팀 생성: Step 6으로 돌아가되, 1라운드에서 배운 것을 반영
  - **TEAM_FINDINGS.md + DEAD_ENDS** 내용을 새 팀에 전달
  - 부족했던 부분을 새 팀의 태스크에 반영
  - 새 팀 프롬프트에 "Verify-first 5개" 목록 포함 (이전 팀의 미검증 주장)

**방식 C: 부분 교체 (문제 팀원만 교체)**
- **조건**: 팀원 간 결과가 모순되거나, 특정 팀원의 결과만 부족한 경우
- 팀장은 유지 (컨텍스트 + 조율 역할 보존)
- 문제 팀원만 해고 + 새 팀원 스폰:
  ```
  # 문제 팀원 해고
  SendMessage({ type: "shutdown_request", recipient: "[문제-팀원]" })

  # 새 팀원 스폰 (공유 메모리 읽기 지시 포함)
  Task({
    team_name: "[기존-팀-이름]",
    name: "[새-팀원-이름]",
    subagent_type: "general-purpose",
    model: "opus",
    prompt: "[역할 지시 + 공유 메모리 3종 읽기 + DEAD_ENDS 확인 필수]"
  })
  ```
- 장점: 정상 팀원의 컨텍스트 보존 + 문제 영역만 바이어스 초기화
- 팀장에게 새 팀원 합류 알림:
  ```
  SendMessage({
    type: "message",
    recipient: "[leader-name]",
    content: "[문제-팀원]을 [새-팀원]으로 교체했습니다. 새 팀원에게 TEAM_FINDINGS.md와 DEAD_ENDS를 읽게 한 후 [구체적 태스크]를 배정해주세요.",
    summary: "팀원 부분 교체 완료"
  })
  ```

### 라운드별 권장 전략

| 라운드 | 기본 전략 | 팀 상태 |
|--------|----------|---------|
| 1라운드 | 전력 실행 | 원본 팀 |
| 2라운드 | 자동 판정에 따라 A/B/C | A: 원본+검증자 / B: 새팀 / C: 혼합팀 |
| 3라운드 | 무조건 방식 B (재구성) | 새 팀 (공유 메모리 인계) |

> **핵심 인사이트**: 3라운드에 돌입한다는 것 자체가 "기존 팀의 접근에 근본적 문제가 있다"는 신호.
> 따라서 3라운드는 무조건 재구성하여 신선한 관점을 확보한다.

### 7-7. 최대 라운드 제한

- **최대 3라운드**까지만 진행
- 3라운드 후에도 부족하면: 현재까지의 최선 결과로 리포트 생성
- 사용자에게 솔직하게: "3번 시도했는데 [이 부분]은 한계가 있어요. 현재 결과를 정리해드릴게요."

---

## Step 8: 결과 수집 + 리포트

### 8-1. 팀 종료

```
# 모든 팀원에게 종료 요청 (팀장이 이미 보냈을 수 있음)
SendMessage({
  type: "shutdown_request",
  recipient: "[각 팀원 이름]",
  content: "작업이 완료되었습니다. 수고하셨습니다."
})

# 팀 리소스 정리
TeamDelete()
```

### 8-2. 유저에게 결과 전달 + Auto-memory 유도

팀 종료 후 사용자에게 결과를 보여줍니다:

```
끼리끼리 팀 작업이 완료되었어요!

📋 팀: [팀 구성 요약]
🎯 목표: [목표]
📄 결과: [리포트 파일 경로]
🔄 라운드: [수행한 라운드 수]

[리포트 핵심 요약 2-3줄]

상세 내용은 리포트 파일을 확인해주세요.
```

**Auto-memory 저장 유도**: 결과 전달 후, 팀 운영 맥락을 자연어로 요약 출력한다. 단순 설정이 아닌 **무엇이 효과적이었고 왜**가 핵심이다.

```
끼리끼리 세션 요약:

환경: Codex CLI ✓, Gemini CLI ✓, 패키지 매니저 bun

팀 구성과 결과:
- 프리셋: research, 4명 (팀장 + 리서처 2 + 검증자 1)
- 효과적이었던 점: [예: 검증자가 리서처의 편향을 잡아냄]
- 비효과적이었던 점: [예: 리서처 2명이 같은 소스를 중복 조사]
- 다음에 개선할 점: [예: 리서처에게 소스 범위를 명시적으로 분할]

공유 메모리 위치:
- .kkirikkiri/TEAM_PLAN.md — 계획
- .kkirikkiri/TEAM_FINDINGS.md — 결과
- .kkirikkiri/DEAD_ENDS — 실패한 접근
```

이 요약이 Auto-memory에 저장되면, 다음 세션에서:
- 환경 스캔 축소, 팀 구성 추천에 활용
- 교체 팀원에게 공유 메모리 인덱스로 즉시 온보딩 가능
- 이전에 실패한 전략을 반복하지 않음

### 8-3. 팀 저장 (선택)

잘 동작한 팀 구성을 저장하여 나중에 재사용할 수 있습니다.

**EXECUTE:** 아래 JSON으로 AskUserQuestion 도구를 즉시 호출한다:

```json
{
  "questions": [
    {
      "question": "이 팀 구성을 저장해둘까요? 나중에 비슷한 작업할 때 바로 불러올 수 있어요.",
      "header": "팀 저장",
      "options": [
        {"label": "네, 저장해주세요", "description": "다음에 비슷한 작업할 때 인터뷰 없이 바로 시작할 수 있어요."},
        {"label": "아니요, 괜찮아요", "description": "이번만 사용하고 저장하지 않아요."}
      ],
      "multiSelect": false
    }
  ]
}
```

저장 시 `.kkirikkiri/saved-teams/` 디렉토리에 기록:

```
Write → {프로젝트루트}/.kkirikkiri/saved-teams/{preset}-{날짜}.md
```

저장 파일 형식:
```markdown
# 저장된 팀: [팀 이름]

- 생성일: [날짜]
- 프리셋: [preset]
- 목표: [인터뷰에서 파악한 목표]

## 팀 구성
| 역할 | 모델 | 담당 |
|------|------|------|
| [팀장] | Opus | [업무] |
| [팀원1] | [모델] | [업무] |
| ... | ... | ... |

## 인터뷰 답변 요약
- Q1: [답변]
- Q2: [답변]

## 환경 조건
- Codex CLI: [있음/없음]
- Gemini CLI: [있음/없음]

## 성과
- 라운드: [수행 라운드 수]
- 품질 판정: [결과]
```

#### 저장된 팀 불러오기

사용자가 "저번 리서치 팀 다시 써줘" 또는 유사 요청 시:

1. `.kkirikkiri/saved-teams/` 디렉토리 스캔
2. 관련 팀 파일 Read로 확인
3. 저장된 구성 기반으로 Step 4로 직행 (인터뷰 생략)
4. 환경이 달라졌으면 (예: CLI 새로 설치) 자동 조정

```
"저번에 사용한 '[팀 이름]' 팀을 찾았어요. 같은 구성으로 시작할까요?"
```

### 8-4. 공유 메모리 정리

작업 완료 후 `.kkirikkiri/` 디렉토리는 유지한다 (나중에 참조 가능).
사용자가 원하면 삭제:
```
"작업 기록 파일(.kkirikkiri/)을 삭제할까요? 남겨두면 나중에 참고할 수 있어요."
```

---

## 에러 처리

### 팀원 무응답/오류 (TeammateIdle 품질 훅)

팀원이 유휴(idle) 상태가 되면 자동 알림이 옵니다. 3단계 에스컬레이션으로 관리:

| 단계 | 상태 | 대응 |
|------|------|------|
| **1회 idle** | 정상 | 무시 — 메시지 보내고 응답 대기 중일 수 있음 |
| **2회 연속 idle** | 주의 | 팀장에게 확인 요청: "이 팀원이 진행 중인지 확인해주세요" |
| **3회 연속 idle** | 조치 | 팀장에게 교체 지시: "이 팀원이 멈춘 것 같습니다. 해고하고 새 팀원을 요청하세요" |

팀장에게 전달할 품질 훅 지시:
```
## 팀원 모니터링 규칙
- 팀원이 태스크를 받고 오랫동안 진행 보고가 없으면 → SendMessage로 진행 상황 확인
- 확인 후에도 응답 없으면 → shutdown_request 후 메인 세션에 교체 요청
- 팀원이 같은 실수를 2회 반복하면 → 즉시 교체 요청 (kill criteria)
```

- 팀원 에러 발생 → 팀장이 판단하여 재시도 또는 다른 팀원에게 재배정

### 심부름꾼 관리

- 심부름꾼이 응답 없음 → 팀원이 직접 해당 작업 수행 또는 새 심부름꾼 스폰
- 심부름꾼 결과 품질 낮음 → 팀원이 직접 보완 또는 다른 심부름꾼에게 재지시

### CLI 실행 실패

- Codex/Gemini CLI 실행 실패 → Claude(Opus)로 해당 작업 수행
- 사용자에게 기술적 에러 메시지 그대로 노출 금지
- 대신: "외부 도구에서 문제가 생겨서 내부 AI로 대체했어요" 수준의 안내

### 인터뷰 중단

- 사용자가 인터뷰 중 취소 → 즉시 종료, 팀 생성하지 않음
- "언제든 다시 시작할 수 있어요" 안내

---

## 절대 하지 마 (전체 워크플로우)

- [ ] 유저 확인 없이 팀을 생성하지 마
- [ ] 프리셋을 고정값으로 쓰지 마 — 인터뷰 + 환경스캔으로 동적 조정
- [ ] 기술 용어를 유저에게 노출하지 마 — Opus/Sonnet/MCP/TeamCreate 등
- [ ] 인터뷰 질문 4개 이상 하지 마
- [ ] Haiku를 어떤 역할에도 배정하지 마
- [ ] 팀장에게 코드 작성을 시키지 마
- [ ] 에러 메시지를 그대로 보여주지 마
- [ ] 공유 메모리 파일 초기화 없이 팀을 실행하지 마
- [ ] 팀원 프롬프트에서 공유 메모리 경로를 빠뜨리지 마
- [ ] 심부름꾼을 Opus로 스폰하지 마 — 심부름꾼은 항상 Sonnet
- [ ] 검증 없이 결과를 유저에게 전달하지 마 — 반드시 품질 판정 거쳐야
- [ ] 4라운드 이상 반복하지 마 — 최대 3라운드 제한
- [ ] 팀 재구성 시 공유 메모리 파일을 삭제하지 마 — 새 팀에 전달해야

## 항상 해 (전체 워크플로우)

- [ ] 모든 인터뷰 질문에 "(추천)" 기본 옵션 포함
- [ ] 모든 인터뷰 질문에 "잘 모르겠어요 → 추천대로" 옵션 포함
- [ ] 팀 구성 제안 시 역할을 일상 용어로 설명
- [ ] 팀 실행 전 반드시 유저 확인
- [ ] 환경 스캔에서 Codex/Gemini CLI 설치 여부 확인
- [ ] 프리셋 매칭 실패 시 범용 인터뷰로 전환
- [ ] 결과 리포트에 팀 구성 + 작업 과정 + 산출물 포함
- [ ] 팀 생성 직후 공유 메모리 3종 파일 초기화 (TEAM_PLAN, TEAM_PROGRESS, TEAM_FINDINGS)
- [ ] 팀장 프롬프트에 공유 메모리 관리 의무 포함
- [ ] 팀원 프롬프트에 공유 메모리 읽기/쓰기 + 심부름꾼 스폰 방법 포함
- [ ] 1라운드 완료 후 반드시 품질 판정 수행 (목표 달성/완성도/정확성/일관성)
- [ ] 품질 부족 시 유저에게 2라운드 진행 여부 확인
- [ ] 팀 재구성 시 TEAM_FINDINGS.md 내용을 새 팀에 반드시 전달
- [ ] 팀장의 최종 통합 전 공유 메모리 3개 파일 전부 읽기 필수
- [ ] `.claude/agents/` 에 기존 에이전트가 있으면 재활용 여부 사용자에게 확인
- [ ] 파일 모드(@파일명) 입력 시 파일 분석 → 역할 자동 분해
- [ ] 작업 완료 후 팀 저장 여부 사용자에게 확인
- [ ] 저장된 팀 재사용 요청 시 saved-teams 디렉토리에서 불러오기
- [ ] 팀원 idle 3회 연속 시 팀장에게 교체 지시