이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다.
클로드 코드 오케스트레이션, 팬아웃·팬인으로 게임 3개 만드는 법
클로드 코드 오케스트레이션으로 에이전트 셋에게 게임 3개(우주 슈팅, 벽돌깨기, 지렁이)를 나눠 만들게 하고 하나의 페이지로 합치는 방법을 프롬프트 원문과 함께 설명한다. CLAUDE.md 템플릿 만들기부터 팬아웃, 팬인이 실패했을 때의 재작업, 과정 전체를 스킬로 저장하는 단계까지 순서대로 따라 할 수 있다. 실제로 해 보면 어디서 막히는지도 함께 적었다.

클로드 코드 오케스트레이션이란, 여기서 쓸 패턴
오케스트레이션은 여러 에이전트를 어떻게 협업시킬지 정하는 작업 설계다. 에이전트는 지시를 받으면 스스로 여러 단계를 이어서 처리하는 AI를 말한다. 설계할 때 따질 것은 작업을 어떻게 나눌지(분해), 어떤 순서로 돌릴지(의존 관계), 결과를 어떻게 모을지(종합)다.
자주 쓰는 패턴은 여섯 가지다. 쓰기 쉬운 순서로 놓으면 오케스트레이터-워커 → 병렬 팬아웃-팬인 → 파이프라인(순차) → 적대적 검증/토론 → 심사위원단 → 블랙보드다. 정해진 정답 순위는 아니다. 처음이라면 1~3순위만 알아도 충분하고, 이 글에서는 2번 병렬 팬아웃-팬인을 쓴다. 1~3순위를 짧게 풀면 이렇다.
- 오케스트레이터-워커: 지휘하는 에이전트 하나가 일을 나눠 주고 일꾼 에이전트들이 받아서 처리한다.
- 병렬 팬아웃-팬인: 팬아웃은 한 작업을 여러 에이전트에게 동시에 나눠 맡기는 것, 팬인은 그 결과를 모아 하나로 만드는 것이다.
- 파이프라인: 앞 에이전트의 결과를 다음 에이전트가 이어받아 차례로 처리한다.
팬인은 단순한 "합치기"가 아니다. 결과를 그대로 나열할 수도, 새로운 형태로 재구성할 수도 있으니 사실상 "만들기"에 가깝다. 팬아웃보다 팬인이 더 중요하다. 아래 실습에서 처음 실패한 곳도 팬인이었다.
시작 전 준비: 클로드 코드와 프로젝트 폴더
클로드 코드는 터미널에서 대화하듯 시키면 파일을 만들고 고치는 클로드다. 처음이라면 이렇게 준비한다.
- Anthropic 공식 문서의 안내대로 클로드 코드를 설치한다.
- 게임을 담을 빈 폴더를 하나 만든다. 예시에서는 "321 레트로 게임"이라는 이름을 썼다.
- 터미널을 연다. 맥은 응용 프로그램 > 유틸리티 > 터미널, 윈도우는 시작 메뉴에서 PowerShell을 검색해 연다.
cd뒤에 한 칸 띄우고 만든 폴더를 터미널 창에 끌어다 놓은 뒤 Enter를 누른다. 그 폴더로 이동한다.
CLAUDE.md 템플릿 만들기
CLAUDE.md는 클로드 코드가 그 폴더에서 일을 시작할 때 가장 먼저 읽는 규칙 파일이다. 템플릿은 그 규칙을 채워 넣을 기본 틀을 말한다.
- 웹이나 앱의 일반 대화창(Claude Chat)에 접속한다.
- 아래 프롬프트(AI에게 주는 지시 문장)를 그대로 입력한다.
나는 병렬 팬아웃·팬인 오케스트레이션을 만들고 싶다. CLAUDE.md 템플릿을 클로드 코드에서 사용할 수 있는 템플릿 구조로 만들어 줘. 내 메모리는 참고하지 말고 만들어.
- 생성된 파일을 다운로드한다.
- 준비 단계에서 만든 프로젝트 폴더에 CLAUDE.md라는 이름으로 저장한다.
"내 메모리는 참고하지 말고"는 꼭 붙인다. 빼면 개인 메모리(클로드가 이전 대화에서 기억해 둔 내 정보)가 템플릿에 섞여 나오는 일이 여러 번 테스트에서 확인됐다. 이렇게 만든 템플릿에는 "플랜 → 팬아웃 → 컬렉트 → 팬인 → verify" 워크플로가 들어 있었다. 컬렉트는 결과 모으기, verify는 검증 단계다. 플랜 단계가 거추장스러우면 지워도 되지만, 그대로 두고 진행해도 문제는 없다.
팬아웃 실행과 1차 팬인 실패
터미널에서 claude
우리는 브라우저에서 실행되는 3인용 레트로 아케이드 오락실 만들 거야. 오케스트레이션 패턴으로 진행할 테니 규칙 확정해 줘.
처음엔 게임 폴더만 생기고 공통 규칙 파일(contract.md, 세 게임이 함께 지킬 약속을 적은 문서)이 만들어지지 않았다. 이럴 때는 contract.md를 따로 만들어 달라고 요청하면 된다. 규칙이 나온 뒤 "요걸 그대로 복사해서 팬아웃 해달라"고 하면 범용(general-purpose) 에이전트가 자동으로 워커1(우주 슈팅), 워커2(벽돌깨기), 워커3(지렁이)을 만들어 일을 나눈다.
세 게임을 index.html(브라우저로 여는 웹페이지 파일) 하나로 합쳐 달라고 하면 "팬인 완료" 보고가 돌아온다. 그런데 실제로 열어 보니 실행이 되지 않았다. 완료 보고만 믿지 말고 결과 파일을 직접 열어 확인해야 하는 이유다.
재작업: 더블클릭으로 열리게 다시 만들기
서브에이전트는 큰 작업의 일부를 따로 맡도록 이름과 역할을 정해 만든 보조 에이전트다. 범용 에이전트 대신 전용 서브에이전트로 다시 하게 하려면 이렇게 지시한다.
지금부터 그냥 세 개의 서브 에이전트를 만들어서 팬아웃 보충하고 팬인 새롭게 해주자. 제너럴 퍼포즈 에이전트 쓰지 말고 직접 만들자.
클로드 코드가 "작업의 목적이 무엇인가요?"라고 되물으면 목적을 한 줄로 답한다.
더블클릭만으로 실행되게.
그러면 ES 모듈 구조를 버리고 일반 스크립트 방식으로 다시 만든다는 응답이 온다. ES 모듈은 자바스크립트 파일끼리 서로 불러 쓰게 나누는 방식이다. 파일을 더블클릭해 여는 주소(file://)에서는 브라우저가 이런 불러오기를 막는 경우가 많다. 1차 팬인이 열리지 않은 것도 ES 모듈 구조를 file://로 직접 열었기 때문으로 보인다.
중간에 커밋(현재 파일 상태를 저장 기록으로 남기는 것)을 요청해 두면 되돌리기 쉽다. 이번 재작업에서는 서브에이전트 폴더에 파일이 끝내 생기지 않았고, /diff(무엇이 바뀌었는지 보여 주는 명령)도 변경 내역 대신 말로 된 설명만 돌려줬다. 서브에이전트가 제대로 만들어졌는지는 이렇게 확인한다.
- 클로드 코드 안에서
/agents를 입력해 서브에이전트 목록을 연다. - 확인: 방금 만든 세 서브에이전트 이름이 목록에 보이면 된다.
- 목록에 없으면 프로젝트 폴더의
.claude/agents/안에 서브에이전트별.md파일이 있는지 본다. - 파일이 없으면
/agents화면에서 직접 새 서브에이전트를 만들고, 이름·설명·쓸 수 있는 도구(권한)를 하나씩 정한다.
전용 서브에이전트 3개가 만들어지지 않았는데도, 구조를 ES 모듈에서 일반 스크립트로 바꾼 것만으로 세 게임이 하나의 index.html에서 정상 동작했다. 이번 버전은 속도를 위해 소넷 모델로 만들었다. 오퍼스와 소넷은 클로드 모델 이름으로, 오퍼스가 더 무겁고 성능이 높은 쪽, 소넷이 더 빠른 쪽이다. 같은 게임을 오퍼스로 만든 버전(교사용 모드·다시하기·음악 기능 포함)과 비교하면 완성도가 낮았다.
학습용 게임 변형과 오케스트레이션 스킬 저장
완성한 게임을 다시 팬아웃해 분수 벽돌깨기, 영단어 슈팅, 연산 지렁이(초등 저학년용)로 바꿀 수 있다. 이미 인터페이스가 있어서 빨리 끝난다. 다만 분수 벽돌깨기의 조작 방식이 키보드가 아니라 마우스+스페이스로 바뀌어 버렸다. 조작 방식처럼 바뀌면 안 되는 요구 사항은 지시에 분명히 적어 둬야 한다.
팬아웃-팬인 과정 전체는 스킬로 저장해 둘 수 있다. 스킬은 한 번 해 본 작업 절차를 파일로 묶어 두고 다음에 이름만 불러 다시 쓰게 하는 기능이다.
지금까지 내가 병렬 팬아웃·팬인으로 한 과정을 스킬로 만들어서 저장해 주자. 이 오케스트레이션을 다음에도 사용할 수 있게.
저장한 스킬은 새 폴더에서 불러 다른 일에 쓸 수 있다. 아래는 국어·수학·사회 학습지를 만드는 예다. 성취기준은 교육과정이 학년별로 정해 둔 학습 목표다.
이 오케스트레이션을 사용해서 국어 수학 사회 팬인 하는 학습지 만들어줘. 성취 기준은 네가 알아서 웹을 검색해서 확인해서 찾아줘.
초등학생 5학년 용으로 부탁해.
오케스트레이션이 막히는 지점
학습지 실습에서는 다음 문제가 드러났다.
- 성취기준을 웹에서 찾을 때 나무위키를 참고해 신빙성이 떨어졌다. 교육부나 국가교육과정정보센터처럼 공식 출처를 쓰라고 프롬프트에 적어 두는 편이 낫다.
- 학습지 디자인 품질이 기대에 못 미쳤다. 디자인 시스템을 따로 주거나 오퍼스 모델로 바꾸는 것이 개선 방향이다.
- 시간이 부족해 서브에이전트 완료를 기다리지 않고 "그냥 결과 기다리지 말고 지금까지 나온 것들 팬인 하자"고 밀어붙였다. 그 결과 수학 학습지는 "완료"로 표시됐지만 실제 파일이 생성되지 않았고, 세 과목을 합친 최종 결과물도 나오지 않았다.
모든 워커가 끝났는지, 결과 파일이 실제로 생겼는지 확인한 다음에 팬인해야 한다는 것이 이 실습에서 얻은 가장 분명한 교훈이다.
자주 묻는 질문
클로드 코드 오케스트레이션이란 무엇인가요?
여러 에이전트에게 일을 어떻게 나누고, 어떤 순서로 돌리고, 결과를 어떻게 모을지 설계하는 것이다. 이 글의 실습에서는 게임 3개를 에이전트 셋에게 동시에 맡기고 결과를 하나의 페이지로 모았다. 처음이라면 오케스트레이터-워커, 병렬 팬아웃-팬인, 파이프라인 세 가지만 알아도 된다.
팬아웃과 팬인은 무엇이 다른가요?
팬아웃은 한 작업을 여러 에이전트에게 나눠 동시에 맡기는 단계이고, 팬인은 흩어진 결과를 모아 하나로 만드는 단계다. 팬인은 이어 붙이기가 아니라 새로 만드는 일에 가까워서 더 중요하다. 실습의 첫 실패도 팬인 단계에서 나왔다.
합친 index.html이 더블클릭으로 열리지 않으면 어떻게 하나요?
ES 모듈 구조로 만들어졌는지부터 의심해 본다. 파일을 더블클릭해 여는 방식에서는 브라우저가 모듈 불러오기를 막는 경우가 많다. "더블클릭만으로 실행되게"라고 목적을 알려 일반 스크립트 방식으로 다시 만들게 하면 해결된다.
서브에이전트가 끝나기 전에 팬인해도 되나요?
권하지 않는다. 실습에서 기다리지 않고 팬인했더니 수학 학습지는 "완료"로 표시됐지만 실제 파일이 없었다. 모든 워커가 끝났는지, 파일이 실제로 생겼는지 확인한 뒤 팬인하는 편이 안전하다.
이 글의 본문은 아래 원본 유튜브 영상의 내용을 바탕으로 쓸모연구소가 다시 정리해 쓴 것입니다. 세부 내용과 최신 정보는 원본 영상과 공식 안내에서 확인해 주세요.
원본 영상 보러가기 ↗