Orkestra: 대규모로 AI 에이전트 오케스트레이션하기

이 글의 수치는 게시 시점(2026년 1월) 기준입니다. 최신 수치는 팀 페이지를 참고하세요.

Claude Code로 구축을 시작했을 때, 우리는 AI 코딩 어시스턴트를 사용하는 모든 팀이 결국 마주치는 문제에 부딪혔습니다. 하나의 에이전트가 모든 것을 잘할 수는 없다는 것입니다.

에이전트에게 데이터베이스 전문가가 되라고 프롬프트할 수 있습니다. 혹은 보안 감사자가. 혹은 프런트엔드 엔지니어가. 하지만 이 셋을 동시에 되라고 요청하는 순간, 품질이 떨어집니다. 컨텍스트가 희석됩니다. 지침이 충돌합니다. 에이전트는 모든 것에서 평범한 제너럴리스트가 됩니다.

그래서 우리는 Orkestra를 만들었습니다.

Orkestra란 무엇인가?

Orkestra는 Claude Code와 유사한 AI 코딩 도구를 위한 에이전트 오케스트레이션 시스템입니다. 저마다 다른 전문성을 가진 여러 전문 에이전트를, 작업을 알맞은 전문가에게 라우팅하는 단일 오케스트레이터 아래에서 조율합니다.

AI 에이전트를 위한 인력 파견 업체라고 생각하면 됩니다. 오케스트레이터는 작업을 받고, 어떤 전문가가 그것을 처리해야 하는지 파악하며, 알맞은 컨텍스트와 함께 위임합니다. 작업이 끝나면 결과는 종합을 위해 오케스트레이터로 다시 흘러들어옵니다.

수치가 이를 말해줍니다.

구성 요소	개수
전문 에이전트	46
재사용 가능한 스킬	466
아이덴티티 원형	27
마인드셋	11
커뮤니케이션 스타일	10
지식 도메인	21

캐릭터 시스템: 에이전트를 위한 D&D

Orkestra 뒤에 있는 핵심 통찰은 에이전트의 행동이 세 가지 조합 가능한 요소로부터 나온다는 것입니다.

**아이덴티티(Identity)**는 에이전트가 무엇인지를 정의합니다. 아키텍트는 시스템 구조를 설계합니다. 디버거는 실패를 근본 원인까지 추적합니다. 가디언은 컴플라이언스와 보안 경계를 강제합니다. 우리는 섞어 쓸 수 있는 27개의 아이덴티티 원형을 갖고 있습니다.

**마인드셋(Mindset)**은 에이전트가 어떻게 생각하는지를 정의합니다. 분석적 마인드셋은 주장을 근거에 기반해 세우고 불확실성을 수치화합니다. 회의적 마인드셋은 가정에 의문을 제기하고 반증 근거를 찾습니다. 탐색적 마인드셋은 모호함을 받아들이고 여러 접근법을 시도합니다.

**스타일(Style)**은 에이전트가 어떻게 소통하는지를 정의합니다. 기술적 스타일은 정확한 값을 포함하고 구체적인 파일을 참조합니다. 간결한 스타일은 군더더기를 쳐내고 답부터 제시합니다. 외교적 스타일은 솔직함과 요령 사이의 균형을 잡습니다.

에이전트는 이 요소들을 조합합니다.

# architecture-advisor.yaml
identity:
  - knowledge-architect
  - architect
  - strategist
mindset: analytical
style: concise

이 조합은 시스템을 설계하고, 도메인 전반의 지식을 연결하며, 전략적 방향을 설정하고, 근거와 데이터로 사고하며, 군더더기 없이 소통하는 에이전트를 만들어냅니다.

힘은 조합 폭발에 있습니다. 27개의 아이덴티티 곱하기 11개의 마인드셋 곱하기 10개의 스타일은 거의 3,000가지의 가능한 에이전트 성격을 만들어냅니다. 하지만 여러분은 자신의 작업에 중요한 조합만 정의하면 됩니다.

스킬: 재사용 가능한 역량 모듈

스킬은 에이전트가 호출할 수 있는 지식과 워크플로입니다. 범위에 따른 계층 체계를 따릅니다.

계층	이름	범위	예시
K0	Foundations(기초)	보편적인 방법론	테스트 우선 원칙, 근거 기반 완료
K1	Identities(아이덴티티)	역할 기반 워크플로	CLI 인터페이스 표준, 성능 플레이북
K2	Domains(도메인)	도메인별 지식	데이터베이스 마이그레이션 패턴, 인증 검증
K3	Stacks(스택)	기술별	Cloudflare 배포, Supabase 운영
K4	Project(프로젝트)	이 코드베이스 전용	프로젝트별 워크플로와 관례

스킬은 지연 로딩됩니다. 에이전트는 시작 시 스킬의 이름과 설명만 보고, 전체 스킬 내용은 트리거되었을 때만 로드됩니다. 이는 수백 개의 스킬을 발견 가능하게 하면서도 컨텍스트를 가볍게 유지합니다.

각 스킬은 다음을 포함합니다.

• 명확한 트리거 조건 (“데이터베이스 스키마를 마이그레이션할 때 사용”)
• 단계별 가이던스
• 워크플로에 허용된 도구
• 성공 기준과 실패 복구 경로

우리 레지스트리의 466개 스킬은 git 워크트리 격리부터 웹 조사 워크플로, 배포 상태 검증까지 모든 것을 다룹니다.

오케스트레이션이 중요한 이유

단일 에이전트 아키텍처는 금방 벽에 부딪힙니다.

컨텍스트 희석. 20만 토큰 컨텍스트 윈도우는 데이터베이스 스키마, API 문서, 테스트 픽스처, 도메인 지식을 로드하기 전까지는 커 보입니다. 전문 에이전트는 목표가 명확한 컨텍스트로 작업할 수 있습니다.

지침 충돌. 에이전트에게 “철저하되 빠르게”와 “모든 것을 검증하되 과도하게 설계하지 마라”를 동시에 말하면 긴장이 생깁니다. 전문 에이전트는 명확한 범위를 가짐으로써 이를 해결합니다.

전문성의 깊이. 제너럴리스트 에이전트는 모든 것을 조금씩 압니다. 알맞은 아이덴티티와 스킬로 구성된 전문 에이전트는 자신의 도메인을 깊이 압니다.

Orkestra는 평평한(flat) 오케스트레이션을 구현합니다. 하나의 오케스트레이터가 여러 전문 에이전트를 조율합니다. 전문 에이전트는 하위 전문 에이전트를 생성할 수 없습니다. 이는 복잡성 폭발을 막으면서도 병렬 작업을 가능하게 합니다.

오케스트레이터는 220만 토큰의 실질적인 용량에 접근할 수 있습니다. 자신의 20만 토큰 윈도우에 더해, 각각 20만 토큰을 가진 10개의 동시 서브에이전트입니다. 단일 에이전트라면 소진해버릴 작업도 이 플릿 전반에 걸쳐 여유롭게 실행됩니다.

렌더링 파이프라인

에이전트 정의는 YAML에 존재합니다. Claude Code는 마크다운을 읽습니다. Orkestra는 결정적인 렌더링 파이프라인으로 이 간극을 잇습니다.

YAML Registries → Jinja Templates → .claude/agents/*.md

운영자는 YAML 소스를 편집합니다. orkestra sync를 실행합니다. 렌더링된 마크다운이 .claude/agents/에 나타납니다. Claude Code가 변경 사항을 인식합니다.

이 분리는 서로 다른 대상을 위한 것입니다.

• YAML 소스는 라이프사이클 메타데이터, 태그, 검증 규칙, 도구를 위한 폐기 안내를 포함합니다
• 렌더링된 마크다운은 모델이 필요로 하는 것만 포함합니다. 설명, 도구, 스킬, 행동 가이던스입니다.

파이프라인은 아이덴티티, 마인드셋, 스타일, 스킬을 하나의 일관된 프롬프트로 합성합니다. 설계자-분석형-간결형 에이전트는 몇몇 기저 스킬을 공유하더라도 디버거-회의적-기술형 에이전트와는 매우 다른 시스템 프롬프트를 받습니다.

도메인 지식: 4개 파일 패턴

모든 지식 도메인은 일관된 구조를 따릅니다.

domain-name/
  decisions.md      # Key choices, rationale, consequences
  patterns.md       # Step-by-step guidance and examples
  anti-patterns.md  # Failure modes and remediation
  evolution.md      # Dated log of changes

이 구조는 에이전트의 컨텍스트 로딩을 위한 것입니다. 인증 작업을 하는 에이전트는 가이던스를 위해 authentication/patterns.md를, 알려진 함정을 피하기 위해 authentication/anti-patterns.md을 로드합니다. 파일들은 효율적인 컨텍스트 로딩에 맞는 크기입니다. 유용할 만큼 초점이 맞춰져 있으면서도, 권위를 가질 만큼 포괄적입니다.

우리는 애널리틱스, 인증, 데이터 사이언스, 인프라, 머신러닝, 성능, 보안 등을 포함한 21개의 최상위 도메인을 유지합니다. 각 도메인은 더 세밀한 단위를 위한 하위 도메인을 가질 수 있습니다.

가치: 운영체제

모든 에이전트는 자신이 어떻게 작동하는지를 정의하는 기본 가치 계층을 공유합니다.

단순함이 먼저. 작동하는 가장 단순한 해법을 사용하세요. 정당화될 때만 복잡성을 더하세요.

근본 원인을 고치세요. 실패를 임시방편으로 땜질하지 마세요. 파이프라인이 실패하면 파이프라인을 디버깅하세요. 테스트가 실패하면 코드나 테스트를 고치세요.

근거 기반. 주장을 (벤치마크가 있는) “검증됨”이나 (가정이 있는) “추정됨”으로 표시하세요. 패턴이 발견되었다고 해서 문제가 확인된 것은 아닙니다.

컨텍스트 경제학. MCP 도구는 컨텍스트의 0.1%를 소모합니다. 파일 읽기는 각각 2%를 소모합니다. 코드를 탐색하기 전에 도메인 전문성을 적용하세요.

이 가치들은 렌더링 파이프라인을 거쳐 모든 전문 에이전트에게 전파됩니다. 에이전트는 조합을 통해서도 이를 우회할 수 없습니다.

CLI: 제어 평면

Orkestra는 에이전트 생태계를 관리하기 위한 CLI와 함께 제공됩니다.

# Discovery
orkestra agents search "database"
orkestra agents info database-architect

# Validation
orkestra validate --show-warnings

# Rendering
orkestra sync --dry-run
orkestra sync

# Skills
orkestra skills list
orkestra skills info schema-migration-workflow

# Decisions
orkestra decisions search "authentication"

CLI는 어떤 에이전트가 존재하는지, 그들이 어떤 스킬을 갖고 있는지, 시스템이 건강한지에 대한 단일 진실 공급원(source of truth)입니다. 문제를 조기에 잡기 위해 동기화 전에 검증을 실행합니다.

오픈소스에 대한 고려

우리는 우리 자신의 문제를 해결하기 위해 Orkestra를 만들었습니다. 복잡한 코드베이스를 위해 대규모로 AI 에이전트를 조율하는 문제 말입니다. 우리가 발견한 패턴들은 우리 도메인에만 국한되지 않습니다.

캐릭터 조합 시스템(아이덴티티 + 마인드셋 + 스타일)은 에이전트 성격을 정의하는 어떤 팀에게도 적용됩니다.

스킬 계층 시스템(K0-K4)은 재사용 가능한 역량을 범위별로 정리하는 사고 모델을 제공합니다.

렌더링 파이프라인 패턴(YAML 소스 + 템플릿 + 생성된 산출물)은 도구와 모델 소비 사이의 관심사를 분리합니다.

평평한 오케스트레이션 모델(하나의 조율자, 다수의 전문가)은 병렬성을 가능하게 하면서도 복잡성을 피합니다.

Orkestra가 오픈소스가 될지는 Claude Code로 구축하는 다른 사람들에게 이 패턴들이 가치가 있는지에 달려 있습니다. 우리가 설명한 벽에 부딪히고 있다면, 이 아키텍처가 도움이 될지도 모릅니다.

우리가 배운 것

Orkestra를 만들면서 우리는 오케스트레이션이 에이전트를 더 똑똑하게 만드는 것이 아니라는 것을 배웠습니다. 이는 에이전트를 더 집중하게 만드는 것에 관한 일입니다.

완벽한 지침을 가진 단일 에이전트도 결국 컨텍스트가 바닥납니다. 모든 스킬을 가진 단일 에이전트도 어느 것을 적용해야 할지 혼란스러워합니다. 모든 것이 되려는 단일 에이전트는 모든 곳에서 평범한 결과를 냅니다.

각자의 도메인에서 뛰어난 40여 명의 전문가를, 언제 위임해야 할지 아는 오케스트레이터가 조율하는 것. 그것이 우리가 결과물을 내는 방식입니다.

수치는 아키텍처보다 덜 중요합니다. 여러분에게는 다섯 개의 에이전트가 필요할 수도, 쉰 개가 필요할 수도 있습니다. 원칙은 그대로입니다. 능력보다 조합, 일반화보다 전문화, 개인의 영웅적 활약보다 조율입니다.

---

Orkestra는 우리의 코드 인텔리전스 플랫폼인 Maguyva 뒤에 있는 에이전트 생태계를 구동합니다. 더 알고 싶으신가요? 팀에 문의하세요.