# 3주차 추가자료 · 혼자 일하던 Claude에게 팀을 붙이기

> **이번 주 목표** — 코드는 한 줄도 안 씁니다. **빈 폴더 하나**에서 시작해, Claude를 세 가지 방식으로 굴려보고 그 차이를 몸으로 느낍니다.
> ① 혼자 → ② 서브에이전트(부하 직원) → ③ 에이전트 팀(동료들)
>
> 1·2주차 결과물(대시보드·방명록·위키)은 이번 주에 **건드리지 않습니다.** 새 폴더에서 깨끗하게 시작합니다.

---

## 🎬 먼저 — 시각화를 옆에 띄워두세요

글로 읽는 것보다 **움직이는 걸 보는 게** 빠릅니다. 실습 내내 옆에 띄워두고 단계마다 돌려볼 자료입니다.

**👉 [에이전트 구조 시각화 열기](/viz/agent-structure.html)** — 새 탭에서 열어두세요

> 💾 **오프라인으로 쓰고 싶다면** — 위 페이지에서 마우스 우클릭 → "다른 이름으로 저장" 하면 파일 하나가 떨어집니다.
> 인터넷 없이도 더블클릭만으로 열립니다. 설치·계정·로그인 전부 필요 없습니다.

| 탭 | 보여주는 것 |
|---|---|
| **① 서브에이전트** | 관제탑이 3명을 띄우고 → 각자 자기 책상에서 읽고 → **결과 한 장만** 돌려주고 사라지는 8단계 |
| **② 에이전트 팀** | 독립 세션 3개가 공유 할일목록을 **스스로 집어가고** → **서로 반박**하고 → 내가 팀원에게 직통으로 끼어드는 9단계 |
| **③ 내 설정으로 돌려보기** | **내가 만든 에이전트 파일을 넣으면 그 설정 그대로** 다시 그려집니다. 잘못 만든 곳은 잘못 도는 게 보입니다 |

**조작키** — `Space` 재생/정지 · `→` `←` 한 단계씩 · `Tab` 두 구조 전환 · `R` 처음으로

화면에서 특히 볼 곳 두 군데:

- **각 카드 아래 컨텍스트 막대** — 서브에이전트에선 봇들 막대가 74·66·88%까지 차오르는데 **관제탑은 34%에 머뭅니다.** 이게 "내 책상을 지킨다"의 실제 그림입니다.
- **우측 상단 토큰 미터** — 같은 회의록인데 서브에이전트 **70** vs 팀 **152**. 팀이 왜 아무 일에나 쓰면 안 되는지가 숫자로 보입니다.

---

## 목차

1. [왜 나누는가 — 책상 비유](#1-왜-나누는가--책상-비유)
2. [3단 구조 한눈에](#2-3단-구조-한눈에)
3. [실습 준비](#3-실습-준비)
4. [STEP 1 — 빈 폴더에 일감 만들기](#step-1--빈-폴더에-일감-만들기)
5. [STEP 2 — 서브에이전트 3명 채용하기](#step-2--서브에이전트-3명-채용하기)
6. [STEP 3 — CLAUDE.md로 교통정리(관제탑)](#step-3--claudemd로-교통정리관제탑)
7. [STEP 4 — 자동 위임 시험](#step-4--자동-위임-시험)
8. [STEP 5 — 에이전트 팀 켜기 (이번 주의 핵심 키워드)](#step-5--에이전트-팀-켜기-이번-주의-핵심-키워드)
9. [STEP 6 — 팀원 3명 스폰 + 직접 대화](#step-6--팀원-3명-스폰--직접-대화)
10. [STEP 7 — 셋을 나란히 놓고 비교](#step-7--셋을-나란히-놓고-비교)
11. [부록 A — 에러 대처표](#부록-a--에러-대처표)
12. [부록 B — 막혔을 때 쓰는 보조 프롬프트](#부록-b--막혔을-때-쓰는-보조-프롬프트)
13. [부록 C — 완료 체크리스트](#부록-c--완료-체크리스트)

---

## 1. 왜 나누는가 — 책상 비유

Claude와의 대화창은 **책상 한 개**입니다. 자료를 올릴수록 책상이 좁아지고, 결국 아까 올려둔 중요한 종이가 밀려 떨어집니다. 이게 "대화가 길어지면 앞을 까먹는" 현상의 정체입니다.

여기서 선택지가 갈립니다.

| 방식 | 비유 | 책상 |
|---|---|---|
| 혼자 시킨다 | 내가 다 한다 | 책상 1개. 금방 꽉 참 |
| **서브에이전트** | 부하 직원에게 심부름 | 직원이 **자기 책상**에서 뒤지고, **결과 한 장만** 갖고 옴 |
| **에이전트 팀** | 동료 3명과 회의 | 각자 **자기 사무실**. 서로 전화하고 반박하며 결론을 만듦 |

> 💡 **핵심** — 나눠 쓰는 진짜 이유는 "빠르니까"가 아니라 **내 책상을 깨끗하게 지키려고**입니다. 속도는 덤입니다.

---

## 2. 3단 구조 한눈에

```
① 혼자
   [나] ─ [Claude]

② 서브에이전트  (한 세션 안의 부하 직원)
   [나] ─ [Claude(관제탑)] ─┬─ [요약봇]   →  결과만 보고
                            ├─ [할일봇]   →  결과만 보고
                            └─ [위키봇]   →  결과만 보고
              ※ 봇끼리는 서로 말을 못 겁니다. 무조건 관제탑 경유.

③ 에이전트 팀  (각자가 독립된 Claude Code 세션)
   [나] ─ [팀장]
            ║  ┌──────────────┐
            ╠══╡ 팀원A ⟷ 팀원B │  서로 직접 메시지
            ║  │   ⟷ 팀원C    │  공유 할일목록에서 각자 일을 집어감
            ║  └──────────────┘
            └─ 나도 팀원에게 직접 말을 걸 수 있음
```

### 비교표

| | 서브에이전트 | 에이전트 팀 |
|---|---|---|
| **만드는 법** | `/agents` 명령 · `.claude/agents/*.md` 파일 | 환경변수를 켠 뒤 **자연어로 "팀원 3명 스폰해줘"** |
| **정체** | 한 세션 안의 작업자 | 각각이 **독립된 Claude Code 세션** |
| **서로 대화** | ❌ 불가. 관제탑에만 보고 | ✅ 팀원끼리 직접 메시지 |
| **일 배분** | 관제탑이 전부 지시 | **공유 할일목록**에서 팀원이 스스로 집어감 |
| **내가 개입** | 관제탑을 통해서만 | 팀원 세션에 **직접 들어가 대화 가능** |
| **비용** | 낮음 | **높음** (사람 수만큼 늘어남) |
| **안정성** | 정식 기능 | **실험 기능** (기본 꺼짐) |
| **잘 맞는 일** | 조사·검색·요약처럼 **결과만** 필요한 일 | 서로 **반박·토론**이 필요한 일 |

### 선택 기준 한 줄

> **서로 말을 섞어야 하면 팀, 결과만 받으면 되면 서브에이전트.**

애매하면 서브에이전트입니다. 팀은 비싸고 아직 실험 단계입니다.

---

## 3. 실습 준비

### 시작 전에 확인할 것

- [ ] Claude Code 최신 버전인지 (터미널에서 `claude update`)
- [ ] **OneDrive·iCloud 밖**에 실습 폴더 만들 위치 정하기 (동기화 폴더는 충돌이 잦습니다)

### 이번 주에 안 쓰는 것

GitHub · Vercel · Supabase — **전부 안 씁니다.** 배포도 없습니다. 내 컴퓨터 폴더 하나로 끝납니다.

### 폴더 만들기

바탕화면이 OneDrive와 동기화 중이라면 `C:\study\my-ai-team` (Mac은 `~/study/my-ai-team`)처럼 **동기화 밖 경로**에 빈 폴더를 만드세요.

터미널을 열고 그 폴더로 이동한 뒤:

```
claude
```

---

## STEP 1 — 빈 폴더에 일감 만들기

에이전트를 나누려면 **나눌 일**이 있어야 합니다. 폴더가 비었으니 일감부터 Claude에게 만들게 합니다.

### 붙여넣을 프롬프트

```
지금 이 폴더는 비어 있어. 실습용 샘플 자료를 만들어줘.

1. notes/ 폴더를 만들고, 그 안에 가상의 회의록 3개를 만들어줘.
   - 파일명: 2026-07-14-주간회의.md / 2026-07-21-주간회의.md / 2026-07-28-주간회의.md
   - 내용은 가상의 작은 회사가 신규 서비스를 준비하는 회의라고 가정
   - 각 회의록에 참석자 / 논의 내용 / 결정사항 / 미결 안건이 섞여 있게
   - 회차마다 이야기가 이어지되, 앞뒤가 살짝 어긋나는 부분을 일부러 한두 개 넣어줘
     (나중에 서로 반박하는 실습에 쓸 거야)

2. 다 만들면 파일 목록만 보여주고 멈춰줘. 아직 다른 건 하지 마.
```

**확인:** `notes/` 안에 .md 파일 3개가 생겼으면 통과.

> 이 회의록이 오늘 실습 내내 쓰는 **단 하나의 소재**입니다. 같은 재료를 세 가지 방식으로 다뤄보면서 차이를 봅니다.

---

## STEP 2 — 서브에이전트 3명 채용하기

### 2-1. 대화형으로 만들기 (권장)

터미널에 입력:

```
/agents
```

메뉴가 뜨면 새 에이전트 만들기를 고르고, 안내에 따라 만듭니다. 처음이라면 **Claude에게 대신 시키는 쪽**이 편합니다.

### 2-2. Claude에게 시키기

```
이 폴더에서 쓸 서브에이전트 3명을 .claude/agents/ 에 만들어줘.
각각 별도 .md 파일로, 이름·설명·시스템 프롬프트를 채워서.

1) summarizer  — notes/ 의 회의록을 읽고 핵심만 요약. 회의록 원본은 절대 수정 금지.
2) todo-picker — 회의록에서 "할 일"과 "담당자"만 뽑아 표로 정리. 결정사항과 미결 안건을 구분할 것.
3) fact-checker — 회의록끼리 앞뒤가 안 맞는 부분을 찾아 목록으로 보고. 추측 금지, 근거가 되는 파일명과 문장을 반드시 인용.

조건:
- 각 에이전트의 description에는 "어떤 요청이 오면 이 에이전트를 부르는지" 트리거 키워드를 분명히 적어줘.
  (설명이 두루뭉술하면 자동 위임이 안 걸린다고 들었어)
- 세 에이전트 모두 파일을 새로 쓰지는 말고 읽고 보고만 하게 해줘.
- 다 만들면 각 파일의 맨 윗부분(설정 부분)을 보여줘.
```

### 2-3. 만들어진 파일 구조 이해하기

```
my-ai-team/
├─ notes/                    ← 회의록 3개 (원본, 건드리지 않음)
└─ .claude/
   └─ agents/
      ├─ summarizer.md
      ├─ todo-picker.md
      └─ fact-checker.md
```

에이전트 파일은 이렇게 생겼습니다:

```markdown
---
name: summarizer
description: 회의록 요약이 필요할 때 사용. "요약", "정리", "무슨 얘기 나왔어" 등의 요청에 호출.
tools: Read, Glob, Grep
---

당신은 회의록 요약 전문가입니다.
notes/ 폴더의 회의록을 읽고 핵심만 간추립니다.
원본 파일은 절대 수정하지 않습니다.
...
```

| 칸 | 뜻 |
|---|---|
| `name` | 부를 이름 |
| `description` | **언제 이 에이전트를 부를지.** 자동 위임의 성패가 여기서 갈립니다 |
| `tools` | 쓸 수 있는 도구 제한. 안 적으면 전부 허용 |
| 본문 | 그 에이전트의 성격·규칙 (시스템 프롬프트) |

> ⚠️ **가장 흔한 실수** — `description`을 "요약 담당"처럼 짧게 쓰면 Claude가 언제 불러야 할지 몰라 그냥 자기가 처리해버립니다. **어떤 말이 나오면 부르는지**를 적어야 합니다.

---

## STEP 3 — CLAUDE.md로 교통정리(관제탑)

에이전트를 만들어놨어도 교통정리 규칙이 없으면 뒤섞입니다. 폴더 맨 위에 규칙 파일을 둡니다.

```
이 폴더 루트에 CLAUDE.md를 만들어줘. 내용은:

1. 이 폴더가 뭘 하는 곳인지 두 줄 설명
2. 담당 표 — 어떤 요청이 오면 어떤 에이전트에게 넘기는지 (summarizer / todo-picker / fact-checker)
3. 공통 규칙:
   - 답변은 한국어로
   - notes/ 안의 원본 회의록은 누구도 수정하지 않는다
   - 각 답변 맨 앞에 누가 대답했는지 이름표를 붙인다
     (관제탑 / summarizer / todo-picker / fact-checker)
4. 여러 에이전트가 필요한 요청이면 관제탑이 쪼개서 나눠주고, 결과를 모아서 보고한다

표 형태로 간결하게 써줘.
```

**확인:** 루트에 `CLAUDE.md`가 생겼으면 통과.

> 💡 `CLAUDE.md`는 그 폴더에서 Claude를 켤 때마다 **자동으로 읽히는 사규집**입니다. 매번 설명할 필요가 없어지는 지점이 여기입니다.

---

## STEP 4 — 자동 위임 시험

여기서 **한 번 나갔다 들어와야** 합니다. `CLAUDE.md`와 새 에이전트를 새로 읽어야 하기 때문입니다.

1. `Ctrl+C` 두 번 (또는 `/exit`)으로 종료
2. 같은 폴더에서 다시 `claude`

이제 **에이전트 이름을 부르지 말고** 일반적인 말로 시켜봅니다.

```
지난 회의들 무슨 얘기 나왔는지 정리해줘
```

```
회의에서 나온 할 일 목록 뽑아줘
```

```
회의록들끼리 말이 안 맞는 부분 있나 확인해줘
```

**성공 판정:** 각 요청에서 서로 **다른 에이전트가 호출**되면 성공입니다. (화면에 어떤 에이전트가 도는지 표시됩니다.)

**셋 다 관제탑이 직접 처리해버렸다면** — `description`이 약한 겁니다:

```
방금 요청에서 서브에이전트가 안 불렸어.
각 에이전트의 description을 자동 위임이 잘 걸리도록 트리거 키워드를 넣어 고쳐줘.
고친 뒤 뭐가 어떻게 달라졌는지 한 줄로 설명해줘.
```

### 이어서 — 동시에 굴려보기

```
세 가지를 한꺼번에 부탁할게. 가능하면 동시에 진행해줘.
1) 회의 3건 전체 요약
2) 할 일 목록 추출
3) 회의록 간 모순점 점검
끝나면 셋을 합쳐서 한 장짜리 보고서로 보여줘. 파일로 저장하지는 말고 화면에만.
```

세 에이전트가 각자 자기 책상에서 일하고, 관제탑이 결과를 모아옵니다. **여기까지가 서브에이전트의 전부**입니다.

> 여기서 잠깐 멈추고 스스로 물어보세요 — *"방금 세 봇은 서로 대화했을까?"*
> 답은 **아니오**입니다. 셋은 서로의 존재도 모릅니다. 전부 관제탑을 거쳤습니다.
> 그래서 **서로 반박해야 하는 일**은 이 구조로 안 됩니다. 그게 다음 단계가 있는 이유입니다.

### 🎬 여기서 시각화를 돌려보세요 — [① 서브에이전트 탭](/viz/agent-structure.html)

방금 내 터미널에서 벌어진 일이 그대로 재생됩니다. **5단계에서 빨간 ✕가 뜨는 지점**을 놓치지 마세요 — 봇 사이에 선이 아예 없다는 표시입니다.

마지막 8단계에서 숫자를 확인하세요: 봇들은 74·66·88%까지 찼는데 **관제탑은 34%**. 세 봇이 읽은 회의록 원문은 전부 **각자의 책상에 남고**, 내 책상엔 결과 세 장만 왔기 때문입니다.

### 🔬 그리고 — [③ 내 설정으로 돌려보기](/viz/agent-structure.html)

여기가 오늘 자료의 핵심입니다. **내가 방금 만든 에이전트를 넣으면, 그 설정 그대로 그림이 다시 그려집니다.**

1. ③ 탭을 엽니다
2. **1단계** — 화면의 프롬프트를 복사해 Claude Code에 붙여넣습니다 (`export/` 폴더가 만들어집니다)

```
.claude/agents/ 안의 모든 .md 파일과 루트의 CLAUDE.md 를
이 폴더 바로 아래 export/ 폴더에 그대로 복사해줘.
내용은 하나도 바꾸지 말고 원본 그대로. 다 되면 파일 목록만 보여줘.
```

3. **2단계** — 드롭존 클릭 → `export` 폴더 열기 → **`Ctrl+A`(Mac은 `Cmd+A`)로 .md 파일 전부 선택** → 열기
4. 점수와 진단이 뜨고, 재생하면 **내 설정대로** 돌아갑니다

> ⚠️ **폴더가 아니라 파일을 넣어야 합니다.** 브라우저는 폴더 안을 열어보지 못합니다 — 특히 `.claude` 처럼 점(.)으로 시작하는 **숨김 폴더**는 탐색기·Finder에서 보이지도 않습니다.
> 그래서 1단계에서 **숨김이 아닌 `export/` 로 복사**해두고, 2단계에서 **그 안의 파일들을 한꺼번에 선택**하는 것입니다.
>
> 터미널 화면을 복사해 붙여넣는 방식은 쓰지 마세요 — `---` 구분선이 화면에서는 **수평선으로 그려져 사라지고**, 표는 박스 문자로 바뀌어 원문이 깨집니다.

> 🔒 파일은 **어디로도 전송되지 않습니다.** 브라우저 안에서만 읽고 끝납니다 — 인터넷을 꺼도 동작합니다.

잘못 만들었으면 **잘못 도는 게 그대로 보입니다.**

| 내가 잘못 만든 것 | 화면에서 벌어지는 일 |
|---|---|
| `description`이 짧음 | 그 에이전트가 **회색으로 죽고** "✕ 호출 안 됨" — 화살표가 아예 안 나갑니다 |
| `---` 를 빠뜨림 | 💀 "로드 실패" — 만든 적이 없는 것과 같습니다 |
| 두 설명이 비슷함 | 패킷이 **엉뚱한 에이전트로** 날아갑니다 ("잘못 배달됨") |
| `tools`에 Write/Edit + 금지 규칙 없음 | 빨간 화살표가 `notes/`로 날아가며 **"원본 덮어씀"** |
| `CLAUDE.md` 없음 | 관제탑이 "⚠ 라우팅 규칙 없음" 상태로 시작 |
| 호출 실패한 에이전트가 있음 | 그 몫을 **관제탑이 떠안아** 컨텍스트가 90%대로 폭주 |

각 진단 카드에는 **"고치는 법"**이 함께 나옵니다. 고쳐서 다시 넣으면 화살표가 어떻게 달라지는지 바로 보입니다.

> 💡 **파일이 아직 없어도 됩니다** — 하단의 `✅ 잘 만든 예시` / `❌ 잘못 만든 예시` 버튼으로 두 경우를 바로 비교해볼 수 있습니다.

---

## STEP 5 — 에이전트 팀 켜기 (이번 주의 핵심 키워드)

서브에이전트와 달리, 에이전트 팀은 **기본적으로 꺼져 있습니다.** 켜는 스위치가 따로 있고, 이게 사람들이 못 찾는 그 "키워드"입니다.

### 켜는 방법 — 이 실습 폴더에서만

설정 파일에 환경변수 한 줄을 넣습니다. **실습 폴더 안의 `.claude/settings.json`** 에 넣으면 **이 폴더에서만** 켜집니다.

```
my-ai-team/
└─ .claude/
   ├─ agents/          ← 아까 만든 에이전트 3명
   └─ settings.json    ← 여기에 넣습니다 (새로 만듦)
```

```json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}
```

직접 편집이 부담되면 Claude에게 시키세요:

```
이 실습 폴더에서만 에이전트 팀 기능이 켜지게 해줘.

- 내 전역 설정(~/.claude/settings.json)은 절대 건드리지 말 것
- 이 폴더의 .claude/settings.json 에 환경변수
  CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 를 "1"로 넣어줘
- 파일이 이미 있으면 기존 설정은 그대로 두고 env 항목만 추가
- 다 되면 파일 전체 내용을 보여줘
```

> 💡 **왜 폴더 안에 넣나** — Claude Code 설정은 **로컬 > 프로젝트 > 전역** 순으로 겹쳐 읽습니다. 폴더 안 `.claude/settings.json`은 **그 폴더에서 Claude를 켤 때만** 적용되므로, 평소 쓰는 다른 작업에는 영향이 없습니다.
> 실습이 끝나고 되돌리고 싶으면 **실습 폴더를 통째로 지우면 끝**입니다. 전역 설정은 손대지 않았으니까요.

### ⚠️ 반드시 재시작

설정을 바꿨으면 **Claude Code를 완전히 껐다 켜야** 적용됩니다. 안 켜진 상태에서는 팀원을 스폰해달라고 해도 **아무 일도 일어나지 않습니다.**

### 미리 알아둘 세 가지

| 항목 | 내용 |
|---|---|
| **실험 기능** | 공식적으로 experimental. 중간에 덜컹거릴 수 있습니다 |
| **화면 모드** | 기본은 **한 터미널 안(in-process)**. 창을 쪼개려면 tmux나 iTerm2가 필요한데, **Windows Terminal·VS Code 터미널에서는 분할이 안 됩니다.** 기본값 그대로 쓰세요 |
| **비용** | 팀원 한 명 = Claude Code 한 개. 3명이면 대략 3배로 씁니다 |

> 📌 인터넷에 `TeamCreate` 명령으로 팀을 먼저 만들라는 옛날 설명이 돌아다니는데, **그 도구는 지금 없습니다.** 환경변수만 켜면 바로 자연어로 부르면 됩니다.

---

## STEP 6 — 팀원 3명 스폰 + 직접 대화

재시작한 뒤, 같은 폴더에서 그냥 **말로** 시킵니다.

### 붙여넣을 프롬프트

```
팀원 3명을 스폰해서 서로 토론시켜줘. 이름은 각각 optimist, skeptic, organizer로 지어줘.

주제: notes/ 폴더의 회의록 3건을 근거로, 다음 분기에 뭘 해야 하는지 결정하기

- optimist: 회의에서 나온 아이디어 중 밀어붙일 것을 골라 강하게 주장
- skeptic: optimist의 주장을 근거를 대며 반박. 회의록에서 어긋나는 부분을 찾아 공격
- organizer: 둘의 논쟁을 지켜보다가 합의된 것과 끝내 갈린 것을 구분해 정리

조건:
- 팀원끼리 서로 직접 메시지를 주고받으며 반박하게 해줘 (나를 거치지 말고)
- 각 주장에는 반드시 회의록 파일명과 문장을 근거로 인용할 것
- 근거 없는 추측은 "추측"이라고 표시할 것
- 회의록 원본은 아무도 수정하지 말 것
- 결론이 나면 네가 종합해서 나에게 한 장으로 보고해줘

⭐ 대화 기록 규칙 (이게 없으면 무슨 말이 오갔는지 화면에서 안 보입니다)
- 이 폴더에 debate.md 파일을 만들고, 팀원끼리 주고받는 메시지를 전부 여기에 이어붙여줘.
- 형식은 이렇게:

  ## optimist → skeptic
  (보낸 메시지 원문 그대로)

  ## skeptic → optimist
  (보낸 메시지 원문 그대로)

- 메시지를 받은 팀원은 답하기 전에 "○○가 이렇게 말했다: (인용)" 으로
  받은 내용을 먼저 옮겨 적고, 그 다음에 반박해줘.
- debate.md 는 이어붙이기만. 앞 내용을 지우거나 요약하지 말 것.
```

### ⚠️ 화면에는 "무엇을" 주고받았는지 안 나옵니다

팀원 탭에 들어가도 **"○○에게 전달했다"** 정도만 보이고, **받은 메시지의 내용은 표시되지 않습니다.** 도구 호출 한 줄로 처리되기 때문입니다. 서로 대화한다는 게 이번 주 핵심인데, 정작 그게 화면에서 안 보입니다.

**그래서 위 프롬프트에 `debate.md` 규칙을 넣었습니다.** 실습 폴더에 생기는 이 파일을 **메모장이나 VS Code로 열어두세요.** 팀원끼리 오간 말이 실시간으로 쌓입니다 — 이게 "서로 대화한다"를 눈으로 보는 유일한 방법입니다.

```
optimist → skeptic
  회의록 07-14 기준으로 A안을 밀어야 한다. "..." 라고 적혀 있다.

skeptic → optimist
  optimist가 이렇게 말했다: "A안을 밀어야 한다"
  그런데 07-21 회의록에는 "A안은 보류"로 적혀 있다. 근거가 어긋난다.
```

**즉석으로 확인하고 싶다면** — 팀원 탭에 들어가서 직접 물어보세요:

```
방금 누구한테서 무슨 메시지를 받았어? 받은 내용을 원문 그대로 보여줘.
```

> 💡 시각화 ② 탭의 **5단계**(optimist ↔ skeptic 사이로 메시지가 오가는 장면)가 바로 이 부분입니다. 터미널에는 안 보이는 걸 그림으로는 볼 수 있으니, **`debate.md` 와 시각화를 나란히 놓고** 보면 무슨 일이 벌어지는지 한 번에 잡힙니다.

### 진행 중에 해볼 것 — 여기가 서브에이전트와 갈리는 지점

프롬프트 입력창 아래에 **팀원 목록 패널**이 뜹니다.

| 조작 | 결과 |
|---|---|
| `↑` `↓` | 팀원 선택 |
| `Enter` | **그 팀원의 화면으로 들어가 직접 대화** |
| `Esc` | 그 팀원의 현재 작업 중단 |
| `x` | 선택한 팀원 중지 |
| `Ctrl+T` | 공유 할일목록 열기/닫기 |

**꼭 해보세요:** `skeptic`을 골라 Enter를 누르고, 직접 이렇게 말을 걸어보세요.

```
방금 네 반박 근거가 약해 보여. 회의록에서 직접 인용할 수 있는 문장으로 다시 대봐.
```

관제탑을 거치지 않고 **팀원과 1:1로 대화**가 됩니다. 서브에이전트로는 불가능했던 일입니다.

### 🎬 여기서 다시 시각화 — [② 에이전트 팀 탭](/viz/agent-structure.html) (`Tab` 키로 전환)

내 터미널에서 방금 일어난 걸 옆에서 본 그림입니다. 세 군데를 비교해보세요.

| 단계 | 서브에이전트에는 **없던** 장면 |
|---|---|
| 4단계 | 팀원들이 공유 할일목록에서 **스스로 일을 집어감** (팀장이 안 시킴) |
| 5단계 | optimist ↔ skeptic 사이로 **메시지가 양방향으로 오감** — 아까 ✕가 있던 자리 |
| 6단계 | 나 → skeptic 으로 **노란 직통선**이 켜짐 (지금 막 해본 그것) |

그리고 마지막 9단계 — 토큰 **152 vs 70**. 이 그림이 "팀은 좋은 게 아니라 **비싼 것**"이라는 얘기입니다.

### 팀원 정리하기

```
optimist 팀원에게 종료 요청해줘
```

세션을 끝내면 팀 정보는 자동으로 정리되므로 따로 치울 건 없습니다.

---

## STEP 7 — 셋을 나란히 놓고 비교

마지막으로 오늘 한 걸 스스로 정리합니다.

```
오늘 이 폴더에서 한 걸 정리해줘.

1) 서브에이전트로 처리했을 때와 2) 에이전트 팀으로 처리했을 때
같은 회의록을 다뤘는데 결과물이 어떻게 달랐는지 표로 비교해줘.

그리고 내 실제 업무에서
- 서브에이전트가 맞는 일은 어떤 종류인지
- 굳이 팀을 써야 하는 일은 어떤 종류인지
각각 3가지씩 예를 들어줘.

마지막으로 이 내용을 요약해서 오늘의정리.md 파일로 저장해줘.
```

**오늘의 최종 결과물:** `오늘의정리.md` 한 장 + `.claude/agents/` 3명.

---

## 부록 A — 에러 대처표

| 증상 | 원인 | 해결 |
|---|---|---|
| 서브에이전트가 안 불리고 Claude가 직접 함 | `description`이 두루뭉술 | 트리거 키워드를 넣어 다시 작성 |
| 새로 만든 에이전트가 목록에 없음 | 재시작을 안 함 | Claude Code 껐다 켜기 |
| `CLAUDE.md`를 안 지킴 | 파일 만든 뒤 재시작 안 함 | 껐다 켜기 |
| **팀원을 스폰해달라 해도 아무 일 없음** | 환경변수 미설정 **또는 재시작 안 함** | 실습 폴더의 `.claude/settings.json` 확인 → **완전히 재시작** |
| 팀원 대신 서브에이전트가 뜸 | Claude가 팀이 불필요하다고 판단 | "서브에이전트 말고 **에이전트 팀**으로 해줘"라고 명시 |
| 창이 안 쪼개짐 | Windows Terminal·VS Code는 분할 미지원 | 정상입니다. 한 터미널 안에서 `↑↓`+Enter로 이동 |
| **팀원끼리 무슨 말을 주고받는지 안 보임** | Claude Code가 메시지 **내용**을 표시하지 않음 (정상 동작) | `debate.md` 를 열어두기 · 팀원 탭에서 "받은 내용 원문 그대로 보여줘" |
| 팀원 목록에서 한 명이 사라짐 | 일이 끝나 잠시 숨은 것 | 죽은 게 아닙니다. 이름을 불러 메시지 보내면 다시 나타남 |
| 권한 확인 창이 계속 뜸 | 팀원 요청이 팀장에게 모임 | 팀장 화면에서 승인. 자주 쓰는 건 미리 허용해두기 |
| 팀원이 에러 나고 멈춤 | 실험 기능의 한계 | 그 팀원에게 직접 지시하거나 새로 스폰 |
| 답변이 자꾸 짧아지고 앞을 까먹음 | 책상이 꽉 참 | `/clear`로 정리 후 다시 시작 |

---

## 부록 B — 막혔을 때 쓰는 보조 프롬프트

**① 지금 상태 점검**
```
지금 이 폴더에 어떤 에이전트가 정의돼 있고, CLAUDE.md에 어떤 규칙이 있는지 정리해서 보여줘.
그리고 에이전트 팀 기능이 지금 켜져 있는 상태인지도 확인해줘.
```

**② 자동 위임이 안 될 때**
```
방금 요청에 서브에이전트가 안 불렸어. 왜 안 불렸는지 진단하고,
description을 어떻게 고치면 걸리는지 수정본을 보여줘.
```

**③ 팀이 안 만들어질 때**
```
에이전트 팀으로 하고 싶은데 팀원이 안 생겨.
이 폴더의 .claude/settings.json 에 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 가
제대로 들어가 있는지, 그리고 실제로 적용된 상태인지 확인해줘.
안 돼 있으면 어떻게 해야 하는지 순서대로 알려줘.
```

**④ 다음 세션에서 이어할 때**
```
이 폴더는 3주차 실습 폴더야. CLAUDE.md와 .claude/agents/ 를 읽고
지금까지 뭘 만들어놨는지 파악한 다음, 이어서 뭘 하면 좋을지 제안해줘.
```

**⑤ 팀이 산으로 갈 때**
```
팀원들이 결론 없이 계속 겉돌고 있어.
지금까지 나온 주장 중 근거가 있는 것만 남기고, 나머지는 잘라내서 결론을 내줘.
```

---

## 부록 C — 완료 체크리스트

**준비**
- [ ] [시각화](/viz/agent-structure.html)를 새 탭에 띄워둠
- [ ] 동기화 폴더 밖에 빈 폴더 생성
- [ ] 그 폴더에서 `claude` 실행

**서브에이전트 (필수)**
- [ ] `notes/`에 샘플 회의록 3개 생성
- [ ] `.claude/agents/`에 에이전트 3개 생성
- [ ] 루트에 `CLAUDE.md` 작성
- [ ] 재시작 후 **일반적인 말로 시켰을 때 알맞은 에이전트가 호출됨**
- [ ] 세 가지를 한 번에 시켜 결과를 종합받음
- [ ] **시각화 ③ 탭에 내 파일을 넣어 진단 점수 확인**
- [ ] 진단에서 나온 것을 고치고 **다시 넣어 점수가 오르는 것을 확인**

**에이전트 팀 (도전)**
- [ ] 실습 폴더의 `.claude/settings.json`에 환경변수 추가 (전역 아님)
- [ ] Claude Code 완전 재시작
- [ ] 팀원 3명 스폰 성공
- [ ] **`debate.md` 에서 팀원끼리 오간 말을 눈으로 확인**
- [ ] **팀원 한 명에게 직접 말을 걸어봄** (`↑↓` → Enter)

**마무리**
- [ ] `오늘의정리.md` 생성
- [ ] 시각화 ①·② 양쪽을 끝까지 돌려봄
- [ ] 서브에이전트 vs 팀, 차이를 내 말로 설명할 수 있음

---

## 여기까지 하면

- `.claude/agents/` 에 **내 전용 에이전트**를 만들 수 있습니다
- `CLAUDE.md` 로 **"어떤 요청은 누구에게"** 규칙을 정할 수 있습니다
- 어떤 일에 서브에이전트를 쓰고, 어떤 일에 팀을 꺼내야 하는지 **판단할 수 있습니다**

실습 폴더는 지우셔도 됩니다. 방식만 그대로 내 업무 폴더로 옮기면 됩니다 — **회의록 자리에 내 자료를, 세 에이전트 자리에 내가 반복하는 일을** 넣으면 똑같이 돌아갑니다.

---

## 오늘의 한 줄

> **서브에이전트는 "결과만 갖고 와"이고, 에이전트 팀은 "너희끼리 싸워보고 결론 내와"입니다.**
> 대부분의 업무는 전자로 충분합니다. 후자는 답이 하나로 안 정해지는 일에만 꺼내 쓰세요.