클로드 코드 오케스트레이션 실습, 팬아웃·팬인으로 게임 3개 만들기

클로드 코드 오케스트레이션으로 여러 에이전트에게 게임 3개를 나눠 만들게 하고 하나로 합치는 과정을, 실제로 입력한 프롬프트 원문과 함께 정리했다. CLAUDE.md 템플릿 만들기부터 팬아웃, 실패한 팬인과 재작업, 스킬 저장까지 따라 할 수 있고, 라이브 중에 드러난 실패 지점도 그대로 적었다.

바탕이 된 영상은 시리즈 7강 라이브다. 강사는 우주 슈팅·벽돌깨기·지렁이 게임 3개를 "병렬 팬아웃-팬인" 방식으로 40분 안에 만드는 실습을 진행한다. 제목은 "프롬프트 2번에 게임 3개"지만, 실제로는 1차 팬인이 실패해 재작업했고 마지막 학습지 데모는 시간 부족으로 끝을 못 봤다.

클로드 코드 오케스트레이션이란, 오늘 쓸 패턴

오케스트레이션은 여러 에이전트를 어떻게 협업시킬지에 대한 작업 설계다. 에이전트는 지시를 받으면 스스로 여러 단계를 이어서 처리하는 AI를 말한다. 고려할 건 세 가지, 분해(작업을 어떻게 나눌지)·의존 관계(순서)·종합(결과를 어떻게 모을지)다.

강사가 정리한 여섯 패턴 중 순위는 오케스트레이터-워커 → 병렬 팬아웃-팬인 → 파이프라인(순차) → 적대적 검증/토론 → 심사위원단 → 블랙보드 순이다("정답은 아니다"라고 못박는다). "일반인은 1~3순위만 알면 된다"고 말하며, 오늘은 2번 병렬 팬아웃-팬인을 쓴다. 1~3순위를 짧게 풀면 이렇다.

• 오케스트레이터-워커: 지휘하는 에이전트 하나가 일을 나눠 주고 일꾼 에이전트들이 받아서 처리한다.
• 병렬 팬아웃-팬인: 팬아웃은 한 작업을 여러 에이전트에게 동시에 나눠 맡기는 것, 팬인은 그 결과를 모아 하나로 만드는 것이다.
• 파이프라인: 앞 에이전트의 결과를 다음 에이전트가 이어받아 차례로 처리한다.

팬인은 단순한 "합치기"가 아니라 "만들기"다. 그대로 나열할 수도, 새로운 형태로 재구성할 수도 있다는 뜻이며, 강사는 "팬아웃보다 팬인이 더 중요하다"고 반복 강조한다.

시작 전 준비: 클로드 코드와 프로젝트 폴더

영상은 클로드 코드가 이미 깔려 있다고 보고 시작한다. 클로드 코드는 터미널에서 대화하듯 시키면 파일을 만들고 고치는 클로드다. 처음이라면 이렇게 준비한다.

1. 앤트로픽 공식 문서의 안내대로 클로드 코드를 설치한다.
2. 게임을 담을 빈 폴더를 하나 만든다. 영상에서는 "321 레트로 게임"이라는 폴더를 썼다.
3. 터미널을 연다. 맥은 응용 프로그램 > 유틸리티 > 터미널, 윈도우는 시작 메뉴에서 PowerShell을 검색해 연다.
4. cd 뒤에 한 칸 띄우고 만든 폴더를 터미널 창에 끌어다 놓은 뒤 Enter를 누른다. 그 폴더로 이동한다.

CLAUDE.md 템플릿 만들기

CLAUDE.md는 클로드 코드가 그 폴더에서 일을 시작할 때 가장 먼저 읽는 규칙 파일이다. 템플릿은 그 규칙을 채워 넣을 기본 틀을 말한다.

1. 웹이나 앱의 일반 대화창(Claude Chat)에 접속한다.
2. 아래 프롬프트(AI에게 주는 지시 문장)를 그대로 입력한다.

나는 병렬 펜 아웃 펜인 오케스트레이션을 만들고 싶다. 클로드 MD 템플릿을 클로드 코드에서 사용할 수 있는 템플릿 구조로 만들어 줘. 내 메모리는 참고하지 말고 만들어.

1. 생성된 파일을 다운로드한다.
2. 준비 단계에서 만든 프로젝트 폴더에 CLAUDE.md라는 이름으로 저장한다.

"내 메모리는 참고하지 말고"를 붙이지 않으면 개인 메모리(클로드가 이전 대화에서 기억해 둔 내 정보)가 섞여 나오는 걸 여러 번 테스트로 확인했다고 한다. 생성된 템플릿에는 "플랜 → 팬아웃 → 컬렉트 → 팬인 → verify" 워크플로가 들어 있었다. 컬렉트는 결과 모으기, verify는 검증 단계다. 강사는 "플랜 단계는 없었으면 좋겠다"고 하면서도 그대로 진행하고, 파일을 다운로드해 프로젝트 폴더("321 레트로 게임")에 저장한다.

팬아웃 — 그런데 1차 팬인이 실패했다

터미널에서 claude를 입력하고 Enter를 눌러 클로드 코드를 실행한 뒤 다음 프롬프트를 입력한다.

우리는 브라우저에서 실행되는 3인원 레트로 아케이드 오락실 만들 거야. 오케스트레이션 패턴으로 진행할 테니 규칙 확정해 줘.

처음엔 게임 폴더만 생기고 공통 규칙(contract.md, 세 게임이 함께 지킬 약속을 적은 문서)이 안 만들어져서 별도로 요청해 받아냈다. "요걸 그대로 복사해서 팬아웃 해달라"고 하자 범용(general-purpose) 에이전트가 자동으로 워커1(우주 슈팅)·워커2(벽돌깨기)·워커3(지렁이)를 만들었다.

세 게임을 index.html(브라우저로 여는 웹페이지 파일)로 합쳐달라고 요청해 "팬인 완료" 보고를 받았지만, 실제로 열어보니 실행이 되지 않았다. 이 실습의 첫 번째 명확한 실패 지점이다.

재작업 — 서브에이전트를 만들어 달라고 했지만

서브에이전트는 큰 작업의 일부를 따로 맡도록 이름과 역할을 정해 만든 보조 에이전트다.

지금부터 그냥 세 개의 서브 에이전트를 만들어서 팬아웃 보충하고 팬인 새롭게 해주자. 제너럴 퍼포즈 에이전트 쓰지 말고 직접 만들자.

Claude Code가 "작업의 목적이 무엇인가요?"라고 되묻자 이렇게 답한다.

더블클릭만으로 실행되게.

ES 모듈 구조를 버리고 일반 스크립트 방식으로 다시 만든다는 응답을 받는다. ES 모듈은 자바스크립트 파일끼리 서로 불러 쓰게 나누는 방식인데, 파일을 더블클릭해 여는 주소(file://)에서는 브라우저가 이런 불러오기를 막는 경우가 많다. 1차 실패는 ES 모듈 구조를 file://로 직접 열면 동작하지 않은 정황으로 보인다.

중간에 커밋(현재 파일 상태를 저장 기록으로 남기는 것)을 요청했고, 서브에이전트 이름·권한을 확인하려 했지만 서브에이전트 폴더에는 파일이 끝내 생성되지 않았다. 강사는 이를 "오류가 있는 것 같다"며 권한 시연을 다음 기회로 미뤘고, /diff(무엇이 바뀌었는지 보여주는 명령)도 이날은 표시되지 않고 말로 설명하는 방식으로 응답했다(원인 불명).

재작업 결과, 요청했던 전용 서브에이전트 3개는 끝내 만들어지지 않았지만, 구조를 ES 모듈에서 일반 스크립트로 바꾼 것만으로 세 게임이 하나의 index.html에서 정상 동작했다. 다만 이번엔 오퍼스가 아니라 소넷 모델로 의도적으로 빠르게 만든 것이다. 오퍼스와 소넷은 클로드 모델 이름으로, 오퍼스가 더 무겁고 성능이 높은 쪽, 소넷이 더 빠른 쪽이다. 앞서 시연한 오퍼스 버전(교사용 모드·다시하기·음악 기능 포함)보다 퀄리티가 낮다고 강사가 직접 밝힌다.

심화: 학습용 게임 변형과 오케스트레이션 스킬 저장

완성 게임을 다시 팬아웃해 분수 벽돌깨기·영단어 슈팅·연산 지렁이(초등 저학년용)로 변형했다. 기존 인터페이스가 있어 빠르게 끝났지만, 분수 벽돌깨기 조작 방식이 키보드가 아니라 마우스+스페이스로 바뀌어버렸다. 강사는 "요구 사항을 명확히 지침으로 내줬어야 했다"고 인정한다.

이후 이 팬아웃-팬인 과정 전체를 스킬로 저장했다. 스킬은 한 번 해본 작업 절차를 파일로 묶어 두고 다음에 이름만 불러 다시 쓰게 하는 기능이다.

지금까지 내가 병렬 펜 아웃 펜인 한 과정을 스킬로 만들어서 저장해 주자. 이 오케스트레이션을 다음에도 사용할 수 있게.

새 폴더에서 이 스킬을 불러 국어·수학·사회 학습지 만들기를 시도한다. 성취기준은 교육과정이 학년별로 정해 둔 학습 목표다.

이 오케스트레이션을 사용해서 국어 수학 사회 팬인 하는 학습지 만들어줘. 성취 기준은 네가 알아서 웹을 검색해서 확인해서 찾아줘.

초등학생 5학년 용으로 부탁해.

오케스트레이션 실습에서 드러난 한계

• 성취기준 검색에 나무위키를 참고해 "신빙성이 없다"는 우려가 나왔다.
• 학습지 디자인 품질이 마음에 들지 않았고, 개선안(디자인 시스템 또는 오퍼스 모델)은 "다음에 별도로 안내하겠다"며 이번엔 다루지 않았다.
• 시간이 부족해지자 서브에이전트 완료를 기다리지 않고 "그냥 결과 기다리지 말고 지금까지 나온 것들 팬인 하자"고 강행했다. 강사 스스로 "원래 이런 식으로 하시면 안 됩니다"라고 밝힌다. 결과적으로 수학 학습지는 "완료"로 표시됐지만 실제 파일이 생성되지 않았고, 최종 통합본은 방송 종료까지 화면에 나오지 않았다.

다음 강의는 API(프로그램에서 AI 모델을 직접 불러 쓰는 방식)를 활용한 "바이브 코딩 해커톤"으로 예고됐다. 바이브 코딩은 말로 원하는 것을 설명하고 코드 작성은 AI에게 맡기는 방식이다.

자막 기반(빠른 모드) 캡처를 원문으로 썼다. 화면 판독은 하지 않아서, 프롬프트 정확한 줄바꿈까지는 확인 못 한 구간이 있다.

원본 영상: youtube.com/…