4장 §2-A · Claude-Focused Multi-Agent Team Practice

터미널이나 별도 에디터에서 미리 파일을 만들지 않는다. 아래 세 단계를 그대로 따라간다 — 회색 코드 상자는 전부 "복사" 버튼으로 그대로 복사해서 붙여넣으면 되는 내용이다.

1. ① Claude Desktop App에서 프로젝트 열기

   Claude Desktop App을 실행하고, 방금 만든 harness-lab/ 폴더를 프로젝트로 연다.

2. ② 서브에이전트 생성 요청 — 채팅창에 아래 문장을 그대로 붙여넣고 전송

   AGENTS.md에 적힌 reviewer 역할 명세를 그대로 따라서, .claude/agents/reviewer.md에 reviewer 서브에이전트를 만들어줘. tools는 Read, Grep만 허용하고 model은 sonnet으로 설정해줘.

   복사

   Claude Desktop App이 AGENTS.md의 "역할/입력/출력/권한" 명세를 읽고, 그 내용을 .claude/agents/reviewer.md의 YAML frontmatter(description, tools)와 시스템 프롬프트로 옮겨 Write 도구로 직접 생성한다. 명세는 그대로고 표현 형식만 도구에 맞게 바뀐 것이다 — 생성이 끝나면 채팅에 표시된 파일 내용을 AGENTS.md와 비교해본다.
3. ③ 검토 대상 파일 생성 + 서브에이전트 호출 — 같은 채팅창에 이어서 붙여넣고 전송

   notes.txt 파일을 만들고 "이 프로젝트는 매우 좋다. 이것은 아주 좋다."라고 써넣은 뒤, reviewer 서브에이전트로 notes.txt를 검토해줘.

   복사

   Claude Desktop App이 Agent(Task) 툴을 description="notes.txt 검토", subagent_type="reviewer"로 호출한다. 화면에는 서브에이전트가 스폰되는 과정과, 작업을 마친 뒤 메인 세션으로 돌아오는 요약 결과가 순서대로 표시된다.

Claude Code(CLI)에서도 동일하게 — 터미널에서 claude를 실행한 뒤 ②③의 문장을 그대로 채팅으로 붙여넣으면, 명령줄 인터페이스(CLI)가 똑같이 AGENTS.md 명세를 읽고 .claude/agents/reviewer.md를 직접 생성·호출한다. CLI에는 추가로 PostToolUse 등 자동화 훅이 발화한다는 차이가 있다(App에서는 훅이 발화하지 않는다).

G-1과 마찬가지로 파일을 미리 준비하지 않는다. G-1에서 열어 둔 같은 harness-lab/ 채팅에서 이어서 진행한다.

1. ① writer 서브에이전트 생성 요청 — 채팅창에 그대로 붙여넣고 전송

   AGENTS.md에 적힌 writer 역할 명세를 그대로 따라서, .claude/agents/writer.md에 writer 서브에이전트를 만들어줘. tools는 Write, Read를 허용하고 model은 sonnet으로 설정해줘.

   복사

   Claude Desktop App이 AGENTS.md의 writer 명세를 읽고 Write 도구로 .claude/agents/writer.md를 직접 생성한다. G-1에서 이미 만들어 둔 reviewer.md와 같은 .claude/agents/ 폴더 안에 나란히 놓인다 — AGENTS.md의 handoff_to: reviewer가 다음 단계에서 실제로 이어진다.
2. ② writer → reviewer 순차 파이프라인 실행 요청 — 같은 채팅창에 이어서 붙여넣고 전송

   writer 서브에이전트로 draft.txt에 '원격 근무의 장점' 주제 초안을 쓰게 하고, 완료되면 reviewer 서브에이전트로 draft.txt를 검토해줘. 두 단계를 순서대로 진행해.

   복사

   메인 세션은 먼저 subagent_type="writer"로 Agent를 호출해 draft.txt를 생성시키고, 그 결과가 돌아온 뒤에야 subagent_type="reviewer" 호출을 보낸다. 두 전문가 사이의 의존 관계를 조율하는 것은 서브에이전트가 아니라 메인 세션의 몫이다.

Claude Code(CLI)에서도 동일하게 — 같은 writer.md/reviewer.md를 그대로 쓰고, 터미널에서 ①②의 문장을 그대로 붙여넣으면 동일하게 순차 디스패치된다.

D-1을 마친 같은 채팅에서 이어서 진행한다. 매번 어떤 서브에이전트가 몇 번 호출되는지 화면에 표시되는 과정을 눈여겨본다.

1. ① 단순 요청 — reviewer 하나만 필요한 경우

   draft.txt의 오탈자만 훑어봐줘.

   복사

   오케스트레이터는 이번 요청에 writer가 필요 없다고 판단해 reviewer 하나만 호출한다. 같은 팀(writer+reviewer)이 정의돼 있어도, 실제로 투입되는 인원은 요청마다 오케스트레이터가 그때그때 결정한다는 것을 보여주는 가장 단순한 예다.
2. ② 복합 요청 — writer와 reviewer를 두 관점으로 조합

   draft2.txt에 '4일 근무제' 주제로 새 초안을 써줘. 초안이 완료되면, 그 초안을 문법 관점과 논리 관점 두 가지로 각각 독립적으로 동시에 검토해줘.

   복사

   이번에는 writer 한 번(파이프라인의 첫 단계) 이후에 reviewer가 "문법 관점"과 "논리 관점"이라는 서로 다른 지시를 받아 두 번 동시에(팬아웃) 호출된다. 파이프라인(writer → reviewer)과 팬아웃(reviewer ×2 동시 실행)이라는 두 오케스트레이션 패턴이 한 요청 안에서 조합되는 것을 확인할 수 있다 — 같은 두 서브에이전트로 ①과는 완전히 다른 모양의 워크플로우가 만들어졌다.

Claude Code(CLI)에서도 동일하게 — 같은 writer.md/reviewer.md를 그대로 쓰고, 터미널에서 ①②의 문장을 그대로 붙여넣으면 동일하게 동작한다.

같은 harness-lab/ 폴더에서 실험적 기능인 Agent Teams를 활성화한다. Desktop App에서는 teammateMode가 반드시 in-process여야 한다(tmux는 지원되지 않는다).

1. ① 설정 파일 작성 (터미널) — .claude/settings.json이 없다면 새로 만들고, 있다면 아래 두 키를 병합

   macOS/Linux/Git Bash에서는 아래 명령을 그대로 쓴다.

   이 명령은 .claude/settings.json 파일 전체를 덮어씁니다. 이미 다른 설정이 들어있는 파일이라면 기존 내용이 모두 사라지므로, 필요한 설정이 있다면 미리 백업하거나 아래 내용을 수동으로 병합하세요.

   cat > .claude/settings.json << 'EOF'
   {
     "env": {
       "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
     },
     "teammateMode": "in-process"
   }
   EOF

   복사

   Windows PowerShell에서는 here-string으로 같은 파일을 만든다.

   @'
   {
     "env": {
       "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
     },
     "teammateMode": "in-process"
   }
   '@ | Set-Content .claude/settings.json

   복사
2. ② Claude Desktop App 재시작

   설정을 적용하려면 Claude Desktop App을 완전히 종료했다가 다시 연다.

3. ③ 팀메이트 병렬 스폰 요청 — 채팅창에 아래 문장을 그대로 붙여넣고 전송

   writer 팀메이트 두 명을 병렬로 스폰해서 하나는 topic-a.txt에 '재택근무', 다른 하나는 topic-b.txt에 '4일 근무제' 초안을 동시에 쓰게 해줘. 각 파일이 완료되면 reviewer 팀메이트가 검토하게 하고, 공유 작업 목록도 보여줘.

   복사

Claude Code(CLI)에서도 동일하게 — 같은 설정과 같은 요청 문장이 그대로 동작한다. CLI에서만 teammateMode: "tmux"를 추가로 선택할 수 있어, tmux 분할 창으로 각 팀메이트의 화면을 나란히 볼 수 있다는 점이 Desktop App과 다르다.

G-1의 notes.txt보다 조금 더 복잡한, 논리적 허점이 있는 글을 준비한다. 채팅창에 아래 문장을 그대로 붙여넣는다.

1. ① 검토 대상 파일 준비

   argument.txt 파일을 만들고 다음 내용을 써줘: "재택근무는 항상 사무실 근무보다 생산적이다. 왜냐하면 재택근무를 하는 사람들이 재택근무가 좋다고 말하기 때문이다. 따라서 모든 회사는 재택근무만 해야 한다."

   복사
2. ② haiku 티어로 검토

   채팅창에 아래 문장을 그대로 붙여넣는다. Claude Desktop App이 reviewer.md의 model 필드를 haiku로 바꾼 뒤 검토를 수행한다.

   .claude/agents/reviewer.md의 model 필드를 haiku로 바꿔줘. 그리고 argument.txt를 reviewer 서브에이전트로 검토해줘.

   복사
3. ③ sonnet 티어로 같은 요청 반복

   같은 방식으로 model을 sonnet으로 바꾼 뒤 검토한다. 순환 논증(circular reasoning) 같은 논리적 허점을 정확히 짚어내는지 haiku 결과와 비교한다.

   .claude/agents/reviewer.md의 model 필드를 sonnet으로 바꿔줘. 그리고 argument.txt를 reviewer 서브에이전트로 검토해줘.

   복사
4. ④ opus 티어로 같은 요청 반복

   같은 방식으로 model을 opus로 바꾼 뒤 검토한다. 응답 시간과 지적의 깊이가 ②③과 어떻게 다른지 기록한다.

   .claude/agents/reviewer.md의 model 필드를 opus로 바꿔줘. 그리고 argument.txt를 reviewer 서브에이전트로 검토해줘.

   복사