나만의 에이전트 팀 구성하기

지금까지 에이전트를 만들고(9장), 스킬을 작성하고(10장), 하네스의 전체 구조를 이해했습니다(3~4장). 이 장에서는 이 모든 요소를 하나로 묶어 나만의 에이전트 팀을 구성하는 방법을 배웁니다. team-builder 스킬이 어떻게 요구사항을 수집하고, 벤치마킹하고, 제안서를 생성하는지 단계별로 살펴보고, 직접 Claude에게 팀 구성을 요청해 보겠습니다.

왜 에이전트 팀이 필요한가?

실무 시나리오

AI 에이전트는 다양한 분야에서 활용됩니다. 각 분야의 특성에 맞게 에이전트를 조합하면 훨씬 더 강력한 시스템을 만들 수 있습니다. 몇 가지 실무 시나리오를 살펴보겠습니다.

단일 AI의 한계

단일 AI 어시스턴트로도 많은 작업을 할 수 있습니다. 하지만 복잡한 프로젝트에서는 단일 AI의 한계가 명확하게 드러납니다.

• 역할 분리의 어려움 — 한 AI가 기획, 작성, 검토를 모두 수행하면 각 역할의 품질이 떨어집니다. “내 글을 내가 검토”하는 것은 편향될 수 있습니다.
• 전문성 부족 — 보안 검사, 문서 품질 검토, 성과 분석 등 각 분야의 전문 지식이 필요한 작업은 전문 에이전트가 더 잘 수행합니다.
• 확장성 — 프로젝트가 커지면 단일 AI는 작업을 순차적으로 처리해야 하므로 시간이 오래 걸립니다. 팀 구성은 병렬 처리를 가능하게 합니다.

에이전트 팀의 이점

여러 전문 에이전트가 협력하면 다음과 같은 이점을 얻을 수 있습니다.

• 역할 분담 — 각 에이전트가 자신의 전문 분야에만 집중하므로 결과물의 품질이 높아집니다.
• 품질 게이트 — 작성 에이전트와 검토 에이전트가 분리되어 있으므로, 객관적인 품질 검토가 가능합니다.
• 재사용성 — 스킬은 여러 에이전트가 공유할 수 있으므로, 중복 작업을 줄이고 일관된 결과를 얻을 수 있습니다.
• 병렬 처리 — 독립적인 작업은 동시에 실행할 수 있어 전체 프로젝트 시간이 단축됩니다.

team-builder 스킬 소개

team-builder란?

team-builder는 프로젝트의 목적과 요구사항에 맞는 맞춤형 에이전트 팀을 구성하는 스킬입니다. 사용자와의 인터뷰로 요구사항을 수집하고, 웹 검색으로 업계 벤치마크를 참고하며, 기존 팀의 상태를 진단한 뒤 최적의 팀 구성을 제안합니다.

이 스킬은 두 개의 레이어로 구성됩니다.

• AI 레이어 (Steps 1~5) — Claude(AI)가 직접 수행하는 단계입니다. 요구사항 인터뷰, 벤치마킹, 진단, 제안서 생성, 사용자 승인 게이트를 포함합니다.
• 스크립트 레이어 (Steps 6~14) — 사용자가 승인한 제안서 JSON을 기반으로 bun scripts/team-builder.ts 스크립트가 자동으로 에이전트 파일을 생성하고 시스템에 등록합니다.

왜 두 개의 레이어인가?

"모든 작업을 AI에게 맡기면 되지 않을까?"라고 궁금할 수 있습니다. 그 답은 신뢰성과 책임 소재에 있습니다.

• AI가 잘하는 것 — 의도 이해, 리서치 수행, 트레이드오프 평가, 창의적인 제안 생성입니다. Step 1~4는 바로 이러한 강점을 활용합니다.
• 스크립트가 잘하는 것 — 결정론적 파일 작업입니다. 디렉터리 생성, 정확한 형식으로 파일 작성, 상호 참조되는 여러 문서의 동시 업데이트, 매번 일관된 결과 산출이 여기에 해당합니다. Step 6~14는 바로 이런 신뢰성을 필요로 합니다.
• 사용자가 게이트가 된다 — Step 5에서 사용자가 동의 없이는 어떤 변경도 일어나지 않도록 보장합니다. 이를 통해 AI가 실수로 에이전트를 삭제하거나, 핸드오프 체인을 끊거나, 거버넌스 문서를 불일치시키는 사고를 예방합니다.

기존 시스템의 4가지 팀 구성 패턴

co-consult 시스템에는 이미 검증된 4가지 팀 구성 패턴이 존재합니다. team-builder는 이 패턴들을 참고하여 새로운 팀을 제안합니다.

AI 레이어 5-step 워크플로우

AI 레이어는 다음 5단계로 진행됩니다. 각 단계를 순서대로 따라가며, Claude가 사용자와 대화하면서 최적의 팀 구성을 제안합니다.

Step 1: 요구사항 인터뷰

첫 번째 단계에서 Claude는 사용자에게 6개의 필수 질문을 합니다. 이 질문들에 대한 답변이 팀 구성의 기준이 됩니다.

Step 2: 벤치마킹

요구사항이 확인되면, Claude는 웹 검색을 통해 업계의 표준 팀 구성을 조사합니다. 최소 2개 이상의 권위 있는 출처(McKinsey, BCG, Gartner, Forrester 등)를 참고하며, 각 참조 팀 구성의 적합도를 1~5점 척도로 평가합니다.

• 출처의 신뢰성 검증 (최근 5년 이내, 공식 도메인)
• 참조 팀의 역할, 계층 구조, 강점/약점 분석
• 사용자 요구사항과의 적합도 점수 계산

Step 3: 현재 팀 진단

벤치마킹 결과를 바탕으로, Claude는 기존 팀의 상태를 진단합니다. 현재 프로젝트에 이미 존재하는 에이전트, 스킬, 종속성을 파악하여 불필요한 중복을 피하고 기존 자산을 최대한 활용합니다.

• 에이전트 인벤토리 — 기존 agents/*.md 파일의 목록과 상태
• 스킬 인벤토리 — 기존 skills/*/SKILL.md 파일의 목록과 소유자
• 종속성 맵 — 에이전트 간 핸드오프 관계, 스킬 소유 관계
• 스킬 이전 계획 — 삭제되는 에이전트의 스킬을 다른 에이전트에 이전하는 계획

Step 4: 제안서 생성

진단 결과와 벤치마킹을 종합하여, Claude는 구조화된 제안서를 생성합니다. 제안서에는 팀 비교표, 에이전트 변경 내역, 스킬 변경 계획, 워크플로우 설계, 벤치마킹 근거가 포함됩니다.

Step 5: 사용자 승인 (MANDATORY GATE)

제안서가 완성되면 Claude는 사용자에게 전체 제안서를 보여주고 명시적인 승인을 요청합니다. 이 단계는 필수 게이트(Mandatory Gate)이므로, 사용자가 “approve”라고 명시적으로 답변하기 전까지 다음 단계로 진행되지 않습니다.

제안서 형식

제안서 JSON 구조

team-builder가 생성하는 제안서는 JSON 형식으로 저장됩니다. 이 JSON은 스크립트 레이어(bun scripts/team-builder.ts)의 입력으로 사용됩니다. 제안서의 주요 필드는 다음과 같습니다.

제안서 JSON 예시

다음은 제안서 JSON의 축약된 예시입니다.

{
  "version": "1.0.0",
  "timestamp": "2026-08-10T14:30:00Z",
  "teamName": "digital-marketing",
  "benchmarkSources": [
    "https://www.mckinsey.com/.../marketing-operations"
  ],
  "changes": {
    "agentsToCreate": [
      {
        "name": "content-strategist",
        "formalName": "Content Strategist",
        "tier": { "claude": "medium" },
        "description": "Plans and outlines content strategy",
        "phases": ["1", "2"],
        "requiredSkills": ["research", "seo-analysis"],
        "rationale": "벤치마킹: 콘텐츠 전략 역할 필수"
      }
    ],
    "agentsToDelete": [],
    "skillsToCreate": [
      {
        "name": "seo-analysis",
        "owner": "content-strategist",
        "description": "Performs SEO keyword and trend analysis"
      }
    ],
    "workflowPhases": [
      { "phase": 0, "name": "Initiation", "lead": "pm" },
      { "phase": 1, "name": "Research", "lead": "content-strategist" }
    ]
  },
  "approvedBy": "user",
  "approvedAt": "2026-08-10T15:00:00Z"
}

최상위 필드

제안서 JSON의 최상위 필드는 메타데이터 필드와 changes 객체 안의 변경 배열로 나뉩니다.

워크플로우 단계 항목

workflowPhases 배열은 프로젝트 라이프사이클 전반에서 에이전트들이 어떻게 협력하는지 정의합니다:

{
  "phase": 0,
  "name": "Project Initiation",
  "lead": "engagement-leader",
  "supporting": ["strategy-analyst"]
}

각 단계는 오케스트레이션을 맡는 리드 에이전트(lead)와 선택적으로 기여하는 지원 에이전트(supporting)를 지정합니다. 이 구조는 앞 장에서 본 AGENTS.md의 디스패치 테이블과 직접 대응됩니다.

스킬 재할당 항목

에이전트를 삭제할 때는 해당 에이전트가 소유한 스킬을 반드시 남아 있는 에이전트에게 이전해야 합니다. 제안서는 이 내용을 다음과 같이 기록합니다:

{
  "skill": "research",
  "fromOwner": "old-analyst",
  "toOwner": "strategy-analyst"
}

이를 통해 에이전트가 삭제되더라도 고아 스킬이 발생하지 않습니다. Step 3의 선제적 스킬 이전 계획은 삭제가 일어나기 전에 모든 스킬이 유효한 소유자를 갖도록 보장합니다.

스크립트 레이어

제안서 JSON에서 실제 파일로

사용자가 Step 5에서 제안서를 승인하면, Claude는 제안서를 JSON 파일로 저장합니다(memory/team-builder-proposal-YYYY-MM-DD.json). 이후 사용자가 bun scripts/team-builder.ts 스크립트를 실행하면, 스크립트가 JSON을 읽어 자동으로 다음 작업을 수행합니다.

# 스크립트 레이어 실행 명령어
bun scripts/team-builder.ts memory/team-builder-proposal-2026-08-10.json

스크립트 동작 방식

위 명령어로 스크립트를 실행하면, 제안서 JSON을 읽어 정해진 안전한 순서에 따라 변경을 실행하며 각 단계마다 체크포인트 로그를 기록합니다:

문제가 발생하면 어떻게 되나요?

스크립트는 모든 단계에서 체크포인트 로깅을 수행합니다. 도중에 오류가 발생하면(예: 파일이 이미 존재하거나 권한이 거부된 경우), 스크립트는 정확히 어떤 단계가 실패했고 무엇이 이미 완료되었는지 보고합니다. 문제를 수정한 뒤 스크립트를 다시 실행하면, 이미 성공적으로 완료된 단계는 건너뜁니다.

기존 팀 구성 패턴 참고

co-consult 시스템에는 이미 검증된 4가지 팀 구성 패턴이 있습니다. 새로운 팀을 구성할 때 이 패턴들을 참고하면 빠르게 시작할 수 있습니다.

패턴별 에이전트 로스터

각 패턴을 구성하는 실제 에이전트 명단은 다음과 같습니다.

패턴 선택 가이드

상황에 맞는 패턴을 고를 때 다음 가이드를 활용하세요:

실습: 나만의 에이전트 팀 만들기

실습 목표

이번 실습에서는 Claude Desktop App에서 /team-builder 명령을 사용하여 나만의 커스텀 에이전트 팀을 구성해 봅니다. 관심 분야를 선택하고, 요구사항을 준비하여 Claude에게 팀 구성을 요청해 보세요.

실습 단계

예시 프롬프트

/team-builder

저는 교육 콘텐츠 제작을 위한 에이전트 팀을 구성하고 싶습니다.

1. 도메인: 온라인 교육 콘텐츠 제작
2. 팀 규모: 4~5개 에이전트
3. 주요 업무: 강의 자료 기획, 슬라이드 제작, 퀴즈 출제, 품질 검토
4. 기술 스택: Markdown, HTML,Claude Code
5. 협업 방식: 순차 파이프라인 (기획→작성→검토→완성)
6. 성과 지표: 완성도, 일관성, 학습 목표 달성률

요약