코딩 에이전트(coding agent)로 무언가를 만들어 본 적이 있다면, 반드시 벽에 부딪히게 됩니다. 바로 작업이 단 하나의 프롬프트(prompt)로 처리하기에는 너무 크다는 점입니다.

왜 이 분리가 그토록 중요할까요? 바로 컨텍스트 위생 (Context hygiene) 때문입니다.
워커(worker)가 거대한 코드베이스를 grep으로 검색하고 수십 개의 파일을 읽을 때, 그 모든 내용은 오케스트레이터(orchestrator)가 아닌 워커의 컨텍스트에 쌓입니다. 워커는 그 내용을 소화하여 중요한 단 한 가지를 추출하고, 세 줄짜리 요약본을 보고합니다. 오케스트레이터의 컨텍스트는 깨끗하게 유지됩니다. 즉, _원시 데이터 (raw data)_가 아니라 _결론 (conclusions)_을 축적하는 것입니다. 이것이 핵심 비결이며, 오케스트레이터가 무너지지 않고 수십 단계의 작업을 수행할 수 있는 이유입니다.

워커 스킬(worker skill)의 구조

워커 스킬은 단순히 SKILL.md 파일이 포함된 폴더일 뿐입니다. 프론트 매터 (front matter)가 핵심적인 역할을 수행합니다:

---
name: find-usages
description: "코드베이스 전체에서 심볼, 함수 또는 패턴이 사용된 모든 위치를 찾습니다. 변경 사항이 코드에 어떻게 파급되는지 추적할 때 사용하세요."
...

조합 가능성 (composability)을 만들어내는 네 가지 중요한 요소는 다음과 같습니다:

• description — 이것은 스킬의 이력서입니다. 오케스트레이터가 이 워커를 호출할지 여부를 결정하는 기준이 됩니다 (자세한 내용은 아래 참조). 단순히 문서화 용도가 아니라, _선택 (selection)_을 목적으로 작성해야 합니다.
• context: fork — 이 스킬을 격리된 컨텍스트에서 실행합니다. 이것이 스킬을 인라인 지시어 (inline instructions)가 아닌 서브 에이전트 (sub-agent)로 만드는 요소입니다.
• allowed-tools — 워커의 범위를 필요한 것으로만 제한합니다. 읽기 전용 검색 워커에는 Grep, Read 권한만 부여하며, 파일을 수정할 수 있는 권한은 주지 않습니다. 이는 스킬별로 강제되는 안전 경계 (safety boundary)입니다.
• 출력 규약 (The output contract) — 워커는 발견한 전체 내용을 파일에 기록하고, 오케스트레이터에는 오직 _요약 (summary)_만을 반환합니다. 이것은 시스템 전체에서 가장 중요한 관례입니다. 이것만 제대로 구현하면 나머지 모든 것이 제자리를 찾게 됩니다.

요약(summary) 대 보고(report)의 분리

이 시스템을 지탱하는 핵심 아이디어이므로 명확하게 말씀드리겠습니다:

서브 에이전트는 전체 보고서를 파일에 작성하고, 오케스트레이터에는 짧은 요약만을 반환합니다.

오케스트레이터(Orchestrator)는 즉시 요약을 읽습니다. 만약 상세 내용 — 정확한 줄(line), 전체 목록 — 이 필요하다면, 요청 시에만(on demand) 파일을 읽습니다. 대부분의 경우 그럴 필요가 없습니다. 따라서 비용이 많이 드는 원시 데이터(raw data)는 추론 계층(reasoning layer)의 컨텍스트(context)를 막는 대신, 경로에 의해 참조되는 상태로 디스크에 저장됩니다.

오케스트레이터가 작업자(workers)를 선택하는 방법 (모두 읽지 않고도)

사람들을 혼란스럽게 만드는 미묘한 차이가 하나 있습니다. 만약 오케스트레이터가 20개의 작업 기술(worker skills)을 사용할 수 있다면, 각 기술이 무엇을 하는지 알기 위해 20개의 SKILL.md 파일을 모두 읽어야 한다고 생각할 수도 있습니다. 그렇게 되면 작업이 시작되기도 전에 컨텍스트가 폭발해 버릴 것입니다.

하지만 그렇지 않습니다. 에이전트는 이미 모든 기술의 **이름과 한 줄 설명(one-line description)**을 보고 있습니다. 이것이 바로 기술(skills)이 구축된 점진적 공개(progressive-disclosure) 모델입니다. 따라서 오케스트레이터는 설명만으로 작업자를 선택합니다. 오케스트레이터에 다음과 같은 명시적인 규칙을 설정하십시오:

작업자의 전체 SKILL.md 파일을 읽지 마십시오. 파일은 크기가 커서 컨텍스트를 오염시킬 것입니다. 기술 이름과 설명만으로 선택하기에 충분합니다.
이것이 바로 description 필드가 매우 중요한 이유입니다. 이것은 인간을 위한 문서가 아니라, 오케스트레이터가 선택을 수행하는 인터페이스(interface)입니다.

오케스트레이션 루프 (Orchestration loop)

이를 종합하면, 오케스트레이터는 기본적인 에이전트 루프(agent loop)를 본 적이 있다면 익숙하게 느껴질 루프를 실행합니다. 단지 한 단계 더 높은 수준일 뿐입니다. 어떤 특정 작업 아래에서도 동일한 네 가지 박자가 반복됩니다:

PLAN (한 번)
  요청을 확인하고, 범위를 정하며, 목표를 재진술합니다.
repeat (반복):
...

이것이 일반적인 형태입니다. 각 작업의 종류에 따라 빈칸을 채우는 방식만 달라질 뿐입니다.

어휘는 변하지만, 루프(loop)는 변하지 않습니다. 작업이 "독립적인 청크(chunks)로 나누고, 이를 수행한 뒤, 결과를 결합하고, 완료될 때까지 반복하라"는 형태를 띨 때마다 이것이 바로 그 패턴입니다.

실무에서 이것이 잘 작동하게 만드는 몇 가지 요소가 있습니다:

결과가 도착하는 대로 팬아웃(Fan out)하고 통합하십시오. 오케스트레이터(orchestrator)는 워커(worker)들을 백그라운드(background) 서브 에이전트로 생성하며, 모든 워커가 완료될 때까지 기다리며 차단(block)되지 않습니다. 각 요약이 돌아올 때마다 이를 현황(picture)에 통합하며 — 결정적으로 — 즉시 후속 작업을 파견(dispatch)할 수 있습니다. 사용 사례를 검색하다가 의심스러운 호출 지점(call site)을 발견했나요? 다른 워커들이 여전히 실행 중인 동안, 해당 파일에 대해 지금 즉시 git-history 워커를 실행하십시오. 루프는 일괄 처리 후 대기(batch-then-wait)하는 방식이 아니라, 인터리빙(interleaved, 교차 실행) 방식입니다.

비용이 많이 드는 워커에 제한을 두십시오. 저렴한 읽기 전용 워커(빠른 검색, 파일 읽기)는 동시성 제한(concurrency limit)이 없습니다. 필요하지 않은 워커를 실행하는 비용은 거의 제로에 가깝기 때문입니다. 더 무거운 워커(전체 테스트 스위트 실행, 심층 분석)에는

• 컨텍스트가 깨끗하게 유지됩니다 (Context stays clean). 원시 데이터(Raw data)는 워커 컨텍스트(worker contexts) 내에 격리됩니다. 추론 레이어(reasoning layer)는 정제된 결론만을 보게 되므로, 성능 저하 없이 깊고 길게 작업을 수행할 수 있습니다.
• 실질적인 병렬성 (Real parallelism). 작업을 하나씩 순차적으로 수행하는 대신, 10개의 독립적인 체크를 동시에 실행합니다. 에이전트가 20단계의 순차적 단계를 거쳐야 할 작업이 단 몇 번의 라운드 만에 완료됩니다.
• 전문화 (Specialization). 각 워커는 작고 테스트 가능하며, 정확히 한 가지 일에 특화되어 있습니다. 다른 부분을 건드리지 않고도 사용 사례 탐색기(usage-finder)를 개선할 수 있습니다.
• 워커별 안전성 (Safety per worker). allowed-tools 설정은 모델이 무엇을 결정하든 관계없이 읽기 전용(read-only) 워커가 파일을 수정할 수 없음을 의미합니다. 이 경계는 프롬프트 내의 정중한 요청이 아니라 구조적으로 정의됩니다.
• 조립 가능성 (Composability). 새로운 기능을 추가한다는 것은 스킬 폴더(skill folder)를 추가하는 것을 의미합니다. 오케스트레이터(orchestrator)는 설명을 통해 이를 인식하며, 루프(loop)를 변경할 필요가 없습니다.

직접 설정하기

이 패턴은 디버깅, 연구, 마이그레이션, 감사(audit)와 같은 모든 복잡한 작업에 적용될 수 있습니다. 시작을 위한 레시피는 다음과 같습니다:

1. 워커를 먼저 작성하세요. 각 구체적인 하위 작업(sub-task)에 대해 SKILL.md가 포함된 스킬 폴더를 만듭니다. 선택을 위한 description(설명)을 명확히 작성하고, context: fork를 설정하며, allowed-tools의 범위를 지정하고, 입력 파라미터(input params)와 출력 파일(output-file) 계약을 정의하세요.
2. 모든 곳에서 요약 대 보고서(summary-vs-report) 원칙을 강제하세요. 모든 워커는 전체 출력 내용을 파일에 기록하고, 짧은 요약(summary)만을 반환합니다. 이는 타협할 수 없는 규칙이며, 오케스트레이터의 컨텍스트를 유지하는 핵심입니다.
3. 오케스트레이터를 순수 추론(pure reasoning) 엔진으로 작성하세요. 실제 모든 작업은 위임하도록 강력하게 지시하세요. 오케스트레이터에게 루프(수집 → 해석 → 결정)를 부여하고, 워커를 직접 읽는 것이 아니라 설명을 통해 선택하도록 규칙을 정하세요.
4. 단계별 규칙을 외부화하세요. 상세한 체크리스트를 단계별 파일(phase files)에 넣어 오케스트레이터가 진입 시마다 다시 읽게 하세요. 그래야 긴 실행 시간 동안에도 주의력(attention)을 유지할 수 있습니다.
5. 비용이 많이 드는 워커의 상한을 설정하고 모든 것을 기록하세요. 비용에 따라 동시성(concurrency)을 제한하고, 추가 전용 로그(append-only log)를 신뢰할 수 있는 단일 원천(source of truth)으로 사용하세요. 이것이 바로 아키텍처입니다.

하나의 에이전트가 사고하고, 여러 에이전트가 데이터를 가져옵니다 — 각각은 자신만의 컨텍스트 (context) 내에서, 각자 맡은 하나의 작업을 잘 수행합니다. 모든 것을 단일 프롬프트 (single prompt)에 억지로 밀어넣는 것을 멈추고 기술 (skills)을 서브 에이전트 (sub-agents)로 취급하기 시작하면, 에이전트가 안정적으로 처리할 수 있는 능력의 한계치는 훨씬, 훨씬 더 높아집니다.