코디네이터 모드

코디네이터 모드는 CLAUDE_CODE_COORDINATOR_MODE=1만 켠다고 끝나는 단순 토글이 아닙니다. 공개 레퍼런스에서는 현재 실행이 live coordinator 경로인지, 재개한 세션이 원래 coordinator였는지, 그리고 그 결과 어떤 도구 집합을 노출해야 하는지를 함께 맞춘 뒤에야 실제 coordinator 동작이 활성화됩니다.

핵심 설계 원칙은 다음 네 가지입니다.

• 위임 전용: 코디네이터는 직접 편집, 검색, 명령 실행을 하지 않습니다.
• 엄격한 도구 제한: 코디네이터 자체에 노출되는 도구는 Agent, SendMessage, TaskStop, SyntheticOutput 네 개뿐입니다.
• 세션 일관성 우선: 재개 세션이 coordinator였다면 현재 셸 상태보다 이전 세션 모드를 우선 복원합니다.
• 요약 전달: 워커에게는 전체 대화 덤프가 아니라 작업 목적, 발견 사실, 제약, 완료 조건을 주입합니다.

공개 레퍼런스의 핵심은 원하는 모드와 실제 실행 모드를 분리해서 본다는 점입니다. 사용자가 env var로 coordinator를 요청했더라도, 라이브 coordinator 경로가 아니면 일반 단일 에이전트 동작으로 남을 수 있습니다. 반대로 세션 재개 시점에 이전 세션이 coordinator였다면, 현재 셸에 env var가 빠져 있어도 세션 매칭 단계가 coordinator로 다시 맞춥니다.

// 개념 요약: 원하는 모드와 재개 세션 모드를 맞춘다
function matchSessionMode({ resumeMode, requestedMode, isLiveCoordinatorPath }) {
  if (resumeMode === 'coordinator') {
    process.env.CLAUDE_CODE_COORDINATOR_MODE = '1'
    return {
      mode: 'coordinator',
      warning: requestedMode === 'single-agent'
        ? '재개 세션이 coordinator였으므로 해당 모드로 복원합니다.'
        : undefined,
    }
  }

  if (requestedMode === 'coordinator' && isLiveCoordinatorPath) {
    return { mode: 'coordinator' }
  }

  return { mode: 'single-agent' }
}

코디네이터 모드의 가장 중요한 차이는 도구 열거 단계입니다. 공개 레퍼런스 기준으로 coordinator는 전체 도구 목록에서 필요한 것만 남기는 식이 아니라, 처음부터 coordinator 전용의 극도로 좁은 목록을 사용합니다. 그래서 Bash, Read, Edit, Glob, Grep 같은 직접 작업 도구는 아예 빠집니다.

// 개념 요약: coordinator는 4개 도구만 본다
const COORDINATOR_TOOLS = [
  'Agent',
  'SendMessage',
  'TaskStop',
  'SyntheticOutput',
]

function getAllowedTools(mode, workerMode) {
  if (mode === 'coordinator') return COORDINATOR_TOOLS
  if (workerMode === 'simple') return ['Bash', 'Read', 'Edit']
  return FULL_TOOLSET
}

시스템 프롬프트도 이 제한을 전제로 작성됩니다. 요지는 간단합니다. 코디네이터는 직접 실행하지 말 것, 먼저 작업을 쪼갤 것, 워커 결과를 종합할 것, 필요한 경우 기존 워커에 이어서 지시할 것, 그리고 최종 응답은 조정자 관점에서 정리할 것입니다.

// 개념 요약: coordinator system prompt의 핵심 톤
당신은 직접 편집하거나 셸 명령을 실행하지 않는다.
작업을 적절한 워커로 위임하고, 결과를 비교하고, 다음 단계를 결정한다.
전체 대화 대신 정제된 컨텍스트와 완료 조건을 워커에 전달한다.
같은 워커를 계속 쓸지, 새 워커를 띄울지 비용과 컨텍스트 보존을 기준으로 판단한다.

single-agent 모드에서는 하나의 에이전트가 사용자 지시, 파일 조사, 편집, 검증까지 한 흐름 안에서 처리합니다. 반면 coordinator 모드에서는 그 흐름을 여러 워커에 나눠 맡기므로, 각 워커가 필요한 만큼만 이해할 수 있게 요약 컨텍스트를 주입해야 합니다.

// 개념 요약: 워커에게 전체 로그 대신 작업 요약을 넣는다
function buildWorkerContext({ task, repoFacts, constraints, acceptance, priorFindings }) {
  return [
    `목표: ${task}`,
    `이미 확인한 사실: ${repoFacts.join('; ')}`,
    `제약: ${constraints.join('; ')}`,
    `완료 조건: ${acceptance.join('; ')}`,
    priorFindings?.length ? `이전 워커 결과: ${priorFindings.join('; ')}` : '',
  ].filter(Boolean).join('\n')
}

• single-agent: 컨텍스트는 길어도 하나의 사고 흐름 안에 유지됩니다.
• coordinator: 컨텍스트를 압축하지 않으면 워커가 같은 탐색을 반복하거나, 서로 다른 가정으로 구현을 시작하기 쉽습니다.
• continue 경로: 이미 파일 구조를 파악한 워커에게 합성 스펙만 추가하면 됩니다.
• spawn 경로: 다른 역할의 워커가 필요할 때 새 컨텍스트 팩을 만들어 보냅니다.

이 문맥의 scratchpad는 마법 같은 공유 메모장이 아닙니다. 핵심은 코디네이터가 워커 출력에서 중요한 사실만 뽑아 다음 지시에 재주입하는 작업 메모 계층이라는 점입니다. 공개 레퍼런스에서 강조되는 부분도 여기에 있습니다. scratchpad가 풍부할수록 같은 워커를 계속 사용할 때 이득이 커지고, 부족할수록 새 워커를 띄울 때 다시 컨텍스트를 꾸려야 합니다.

// 개념 요약: continue는 동일 워커의 문맥을 살리고, spawn은 새 역할을 분리한다
if (workerAlreadyKnowsTargetFiles && nextStepUsesSameContext) {
  SendMessage(workerId, synthesizedSpec)
} else {
  Agent({ role: 'verification', context: verificationPacket })
}

예를 들어 사용자가 “두 레슨 문서를 공개 참조와 맞춰 고쳐 달라”고 요청했다고 가정해 보겠습니다. coordinator는 먼저 탐색 워커에게 관련 HTML 구조와 누락 항목을 조사하게 하고, 그 결과를 scratchpad에 압축한 뒤 같은 워커에 계속 수정 지시를 내리거나 별도 검증 워커를 띄웁니다.

// 예시 세션 흐름
User: 21번과 45번 레슨 문서를 참조와 맞춰 수정해 줘.

Coordinator:
1. 탐색 워커 생성, 현재 섹션 구조와 누락 사실 수집
2. scratchpad 갱신, "21은 세션 매칭과 도구 제한 누락, 45는 buddy 아키텍처가 참조와 다름"
3. 수정 워커에 한국어 서술, 기존 번호 체계 유지, 두 파일만 편집 조건 전달
4. 필요 시 검증 워커에 HTML 일관성과 퀴즈 문항 점검 지시

Worker context:
목표: 지정된 두 레슨 HTML만 수정
제약: 로컬 lesson scaffold 유지, 한국어 유지, unsupported API 금지
완료 조건: 누락 섹션, 코드 블록, 세부 사실 반영