3-에이전트, 스킬, 오케스트레이터의 책임 분리

• 에이전트, 스킬, 오케스트레이터 각각의 역할과 경계를 이해하고, 책임이 뒤섞였을 때 나타나는 네 가지 문제를 파악한다.
  • 재사용 불가
  • 병렬화 불가
  • 누락 반복
  • 컨텍스트 폭발

2인 팀을 분해해보자

• 하네스는 누가(Agent), 어떻게 (Skill), 언제∙누구와(Orchestrator) 라는 세 가지 요소로 나뉘며, 이들은 독립적으로 설계되고 실행 시점에만 맞물린다.

한 파일에 다 넣으면 무엇이 깨지는가

• 위 에이전트가 문제가 되는 이유
  • 재사용 불가: “Conventional Commits 형식 체크” 로직을 PR 리뷰용 에이전트에서도 쓰고 싶다면 복사-붙여넣기밖에 방법이 없다. 한쪽을 고치면 다른 쪽도 함께 고쳐야 하고, 그러다 일관성이 흐트러진다.
  • 병렬 불가: ‘생성’과 ‘검증’이 한 에이전트 안에 있으므로 두 작업을 동시에 돌릴 수 없다. 각각 다른 에이전트에 맡기면 병렬 실행이 가능해진다.
  • 누락 반복: 같은 모델이 같은 컨텍스트로 자신의 출력을 검토하면, 만들 때 놓친 문제를 검증할 때도 똑같이 놓치기 쉽다.
  • 컨텍스트 폭발: 역할 설명, 판정 기준, 형식 지식, 호출 순서, 에러 정책이 한 파일에 쌓이면서 어느 순간 수백 줄이 넘는 복잡한 파일이 된다.
• 해법은 누가, 어떻게, 언제 누구와를 분리한다.

세 가지 핵심 요소

핵심 요소1: 에이전트 - 누가

• 에이전트는 ‘누가 이 작업을 맡는가’에 답한다.
• 에이전트 정의 파일은 역할 계약서다.
  • 그 에이전트가 무엇을 담당하고, 어떤 기준으로 판단하며, 누구와 어떻게 소통하는지를 명시한 살아있는 문서다.

핵심 요소 2: 스킬 - 어떻게

• 스킬은 ‘이 작업을 어떤 절차로 하는가’에 답한다.
• “어떻게는 스킬에, 누가는 에이전트에”

핵심 요소 3: 오케스트레이터 - 언제, 누구와

• 오케스트레이터는 ‘이 작업을 언제, 누구와 하는가’에 답한다.
• 영속 파일 하나로 고정되지 않는다.
• 오케스트레이션은 주로 실행 흐름을 담고 있다.
• 2장의 예제에서 오케스트레이터는 commit-message 스킬 본문의 번호 목록이 있었다. 이 4줄이 오케스트레이션이다.
  • 1. Preconditoin 체크, 2. author 호출, 3. reviewer 호출, 4. 판정 분기
• 오케스트레이터는 지시자가 아니라 자휘자이다. 팀원 각자가 자신의 악기를 연주하도록 맡기는 것이 최고의 연주를 만든다.

왜 작업(Task)이 아니라 오케스트레이터인가

• Task는 조율의 수단이지, 독립된 관심사가 아니다.
• 기록 구조의 설계 책임은 오케스트레이터에 있다.
• 기준이 셋일 때 가장 기억하기 쉽다.

세 가지 핵심 요소는 어떻게 동작하는가

세 가지 핵심 요소가 섞이면 생기는 문제

안티패턴 1. 에이전트 한 명이 모든 역할을 다 맡는다

• 문제점
  • 재사용이 막힌다. ‘코딩만 필요한 상황’에서도 기획, 리뷰, 배포 원칙을 통째로 싣고 돌아야 한다.
  • 고치기 어려워진다. 코딩 원칙 하나 바꾸려 해도 파일 전체를 읽고 수정해야 한다.
  • 권한이 과도하게 늘어난다. 배포까지 맡은 에이전트는 자연스럽게 모든 도구를 갖게 되고, 최소 권한 원칙이 깨진다.
• 해결 방법: 역할을 쪼개서 3~4인의 에이전트로 분리한다. 여러 에이전트가 공통으로 쓰는 절차가 있다면 스킬로 뺀다.

안티패턴 2. 스킬이 팀 전체를 지휘하려 한다

• 문제점
  • 스킬은 ‘어떻게 하는가’를 담는 그릇이자 절차적 지식을 정리하는 자산이다. 여기에 팀 구성, 단계 전환, 에러 복구까지 넣으면 스킬 본연의 정체성을 잃게 된다.
  • 다른 팀 구성에 이 스킬을 재사용하려 해도, 오케스트레이션 로직이 뒤엉켜 있어서 떼어내기가 어렵다.
• 예외
  • 오케스트레이션 자체를 목적으로 만든 메타스킬은 스킬 본문에 조율 로직을 담는 것이 정석이다.
  • 일반적인 절차 스킬이 조율까지 떠안는 경우만 안티패턴이다.
  • 구분 기준: 스킬 주어가 ‘절차’라면 분기는 가볍가 두고 조율은 밖으로 빼고, 스킬 주어가 ‘팀 조율’이라면 Phase를 직접 선언해도 된다.
• 해결방법: 팀이 커지고 분기가 복잡해지면 조율은 6장의 오케스트레이션 도구로 분리한다. 스킬은 ‘한 절차 조각’만 맡고, 여러 절차의 순서와 조건은 오케스트레이터 맡는다.

안티패턴 3. 리더가 직접 일을 처리한다

• 내용: 리더 에이전트가 팀원에게 시키지 않고 직접 diff를읽고, 직접 리뷰를 쓰고, 직접 수정한다. 팀원이 있긴 하지만 호출되지 않거나, 호출되더라도 결과가 반드시 리더를 거쳐야 다른 팀원에게 전달한다.
• 문제점
  • 팀원이 4명이 있어도 모든 정보가 리더를 거쳐야 한다면, 팀원들은 서로의 존재를 모른 채 각자의 방에 갇혀 있는 것과 다름없다.
  • 팀은 그냥 순서대로 실행되는 파이프라인이 되고, 병렬 처리와 상호 검증이라는 팀 협업의 이점이 사라진다.
  • 리더의 컨텍스트는 한계를 넘고, 리더 자신이 병목이 된다.
• 해결 방법
  • 오케스트레이터는 설계자 역할만 한다.
  • 시작 전에 팀을 구성하고 작업을 나눠주고, 실행 중에는 팀원들이 SendMessage로 직접 소통하게 두고, 끝나면 결과를 통합하고 팀을 해체한다.
  • 팀원이 작업 결과를 파일로 저장하고, 관련 팀원에게 직접 알리고, 공유 작업 목록에 진행 상황을 직접 기록하는 것이 올바른 구조이다. 리더는 중개하지 않는다.

안티패턴 4. 에이전트 파일에 절차 지식을 다 넣는다.

• 문제점
  • 절차적 지식은 여러 에이전트가 함께 쓸 수 있는 자산이다.
  • PR 리뷰 에이전트도, 코드 리뷰 에이전트도 같은 Conventional Commits 규칙을 쓸 수 있다. 에이전트 파일마다 따로 넣어두면 두 파일이 갖가 다르게 수정되었다가 기준이 엇갈리고, 팀원마다 판정 기준이 달라지는 사오항이 생긴다.
• 해결 방법
  • 보통 지식을 스킬로 분리한다.