Part 03. 메타스킬(Meta-Skill)과 아키텍처 패턴 [하네스 엔지니어링 with 제미나이]

본 글은 하네스 엔지니어링 with 클로드 코드 기반으로 작성되었습니다. 해당 책을 같이 보시면 이해에 도움이 됩니다
https://product.kyobobook.co.kr/detail/S000220048885

Part 03. 메타스킬(Meta-Skill)과 아키텍처 패턴: 팀을 조립하고 배치하는 법

Chapter 07. 메타스킬 파이프라인과 슬래시 명령어

조립 설명서를 만드는 '레시피': 메타스킬

레고 블록을 조립할 때, 매번 부품을 상자에서 하나씩 뒤져가며 감으로 맞추면 시간도 오래 걸리고 모양도 엉망이 됩니다. 하지만 "어떤 블록을 몇 번 순서로 꺼내서 조립하라"는 조립 설명서가 있으면 누구나 5분 만에 멋진 우주선을 완성할 수 있습니다.

메타스킬(Meta-Skill)은 에이전트 시스템의 조립 설명서입니다.

• "보안 검사관 1명과 DB 전문가 1명을 소집해라."
• "보안 검사가 통과되면 DB 전문가에게 넘겨라."
• "작업이 끝나면 팀을 해산하고 결과만 보고해라."

이처럼 팀원을 어떻게 모으고 어떤 순서로 일시킬지 적어둔 지휘 매뉴얼 마크다운 문서를 바로 메타스킬이라고 부릅니다.

부르면 즉시 출동하는 마법 주문: 슬래시 명령어

에이전트에게 매번 "이 코드를 보고 보안 검사관이랑 DB 전문가를 불러서 차례대로 검토해 줘"라고 길게 말할 필요가 없습니다.

마크다운 문서 맨 위에 /review-all처럼 전용 주문(슬래시 명령어)을 딱 하나 등록해 두면 됩니다.

• /review-all [내 코드]를 치는 순간, 오케스트레이터는 긴말하지 않고 즉시 해당 팀을 조립해 작업을 시작합니다.
• 특정 친구만 부르고 싶다면 /review-sec [내 코드]처럼 보안 담당자만 핀포인트로 깨울 수도 있습니다.

반장이 혼자 아는 척하지 못하게 막기

명령어를 쓰지 않고 자연어로 "쿼리 튜닝 좀 해줘"라고 말하면, 오케스트레이터(반장)가 전문 에이전트를 부르지 않고 "어? 나도 그거 아는데 그냥 내가 대충 답해줄게"라며 자기가 아는 척 글을 써버리는 실수를 합니다.

전문가가 가진 엄격한 체크리스트를 완전히 무시해 버리는 치명적인 문제입니다. 그래서 오케스트레이터에게는 "너는 직접 글을 쓰지 말고, 정해진 슬래시 명령어가 들어오면 무조건 해당 전문가만 호출하라"는 단단한 브레이크(가드레일)를 걸어두어야 합니다.

---

Chapter 08. 6가지 핵심 아키텍처 패턴

팀을 세우는 모양에 따라 결과가 달라진다

축구 경기에서 공격수와 수비수의 진형을 짜듯, AI 에이전트들도 일의 성격에 맞게 대형을 짜야 합니다. 대표적인 6가지 대형이 있습니다.

1. 파이프라인 (이어달리기): 1번 주자가 글을 다 쓰면 2번 주자가 오탈자를 잡고, 3번 주자가 번역하는 직렬 방식.
2. 팬아웃 · 팬인 (부채 펼치고 접기): 1개의 주제를 여러 에이전트에게 동시에 뿌려서 조사하게 한 뒤(팬아웃), 마지막에 한 명의 에이전트가 결과를 하나로 합치는(팬인) 병렬 방식.
3. 전문가 풀 (안내 데스크): 입구에서 질문을 듣고 영어 질문은 영어 선생님에게, 수학 질문은 수학 선생님에게 연결해 주는 방식.
4. 생성-검증 (숙제 검사): 작성자가 글을 만들어오면 검사관이 확인하고, "불합격"이면 다시 고쳐오게 만드는 반복 피드백 방식.
5. 감독자 (현장 지휘관): 상황을 실시간으로 보면서 "이번엔 네가 가봐", "다음은 저쪽이야"라고 그때그때 일감을 나눠주는 방식.
6. 계층적 위임 (회사 조직도): 부장 $\rightarrow$ 과장 $\rightarrow$ 사원처럼 위에서 아래로 세부적인 일을 쪼개어 내려보내는 방식.

팬아웃(Fan-out)과 팬인(Fan-in)의 저울질(트레이드오프)

부채를 쫙 펼치듯 여러 명에게 동시에 일을 시키면 순서대로 할 때보다 끝나는 시간(속도)은 엄청나게 빨라집니다.

하지만 얻는 것이 있으면 반드시 잃는 것도 있습니다.

• 3명을 동시에 부르면 컴퓨터 자원과 요금(토큰)도 3배로 한 번에 나갑니다.
• 3명 중 2명은 1초 만에 끝났는데 1명이 인터넷 오류로 멈추면, 결국 그 1명을 기다리느라 전체 결과 합치기(팬인)가 지연됩니다.
  따라서 무조건 병렬로 돌리기보다는 "서로 기다릴 필요가 없는 독립된 조사 작업"에만 팬아웃을 쓰는 것이 현명합니다.

---

Chapter 09. 실행 모드: 심부름꾼 vs 동아리 팀 vs 하이브리드

• 서브에이전트 (심부름꾼): 메인 에이전트가 중심을 잡고 "너 계산기 좀 두드려와", "너 날씨 좀 검색해 와" 하고 간단한 잔심부름을 시킨 뒤 결과를 바로 뺏어오는 구조.
• 에이전트 팀 (동아리 조원): 기획자, 디자이너, 개발자가 동등한 위치에서 서로 의견을 주고받으며 하나의 결과물을 깎아 나가는 협동 구조.
• 하이브리드 (혼합형): 큰 단계(기획 $\rightarrow$ 제작 $\rightarrow$ 검토)는 팀으로 움직이되, 각 단계 안에서 생기는 단순 검색은 심부름꾼을 시키는 가장 실무적인 구조.

내 작업에 어떤 방식이 어울릴지 헷갈린다면, 고민할 필요 없이 제미나이에게 "내 작업 내용을 이 3가지 방식으로 돌렸을 때 속도와 비용, 결과 품질이 어떻게 다를지 가상으로 표를 그려서 비교해 줘"라고 요청하면 최적의 답을 미리 찾아줍니다.

---

Chapter 10. 하네스 등록, 감사(Audit), 지속적 진화

배포 전 5가지 함정 검사하기 (안티패턴 감사)

시스템을 완성했다고 바로 쓰면 안 됩니다. 마치 비행기를 띄우기 전에 점검표를 확인하듯 아래 5가지를 꼭 확인해야 합니다.

1. 혼자 다 하려는 욕심 (중앙 허브): 반장이 모든 데이터를 직접 고치며 병목을 만들고 있지는 않은가?
2. 반장의 아는 척 (라우터 하이재킹): 전문가를 부르지 않고 반장이 직접 답변해 버리는 구멍이 있는가?
3. 끝없는 핑퐁 (무한 루프): 검토자와 작성자가 끝없이 "다시 해와"를 외치다 요금이 폭발하지 않도록 "최대 3회" 제한을 걸었는가?
4. 연장 주머니 과적 (도구 과적): 한 에이전트 손에 도구를 10개 넘게 쥐여주어 헷갈리게 만들지 않았는가?
5. 비상구 없음 (블랙박스 에이전트): 에이전트 하나가 고장 났을 때 전체 시스템이 멈추지 않고 사람 바구니(manual-queue)로 넘어가게 했는가?

기계의 장부(batches.json)를 사람이 손으로 고치면 안 되는 이유

시스템이 여러 작업을 돌릴 때 어디까지 끝났는지 적어두는 메모장을 batches.json 같은 상태 파일이라고 부릅니다.

작업이 조금 늦어진다고 사람이 답답해서 이 메모장 글자를 직접 키보드로 수정해 버리면, "AI가 기억하는 현재 상태"와 "사람이 바꾼 실제 상태"의 싱크가 깨져버립니다. AI는 영문도 모른 채 이미 끝난 숙제를 다시 하거나 시스템 전체가 멈춰버리는 락(Lock)에 걸리므로, 상태 파일은 반드시 기계 시스템의 자동 루틴을 통해서만 변경되도록 두어야 합니다.