코딩 하네스

코딩 하네스 (Coding Harnesses)

코딩 작업을 외부 AI 코딩 CLI(Claude Code, Codex, opencode)에 하위 에이전트로 위임해요.

출처: 문서

본문

개요 (Overview)

하네스 에이전트는 모델 API를 직접 호출하는 대신 외부 코딩 CLI — claude(Claude Code), codex(OpenAI Codex), opencode, 또는 pi — 에 작업을 위임해요. Docker Agent가 오케스트레이션, 훅, 권한, 배포를 제공하는 동안 외부 CLI가 코딩 루프를 구동해요.

이 패턴은 두 세계의 최고를 줘요:

  • 외부 CLI 강점 — 깊은 IDE 통합, 특화 코딩 워크플로, CLI 네이티브 도구 접근
  • Docker Agent 강점 — 다중 에이전트 조율, 훅 기반 감사 및 정책 강제, 권한 제어, OCI 배포, 전체 에이전트 구성 스키마

Note 하네스를 언제 쓸까 (When to use harnesses) Claude Code / Codex / opencode 세션이 더 큰 Docker Agent 워크플로 안에서 하위 에이전트 역할을 하길 원할 때 하네스를 사용해요 — 예를 들어 작업을 계획하고 코딩 작업을 특화 하네스 에이전트에게 위임하는 오케스트레이터.

사전 요구 사항 (Prerequisites)

Docker Agent를 시작하기 전에 외부 CLI가 설치되어 PATH에서 사용 가능해야 해요:

Harness type Required binary Install
claude-code claude docs.anthropic.com/en/docs/claude-code
codex codex github.com/openai/codex
opencode opencode opencode.ai
pi pi 설치 지침은 pi CLI 문서 참고

Docker Agent는 필수 바이너리가 발견되지 않으면 세션 시작 시 에러를 보고해요. claude-code 하네스는 추가로 CLI가 로그인되어 있어야 해요 — 아래 Authentication 참고.

구성 (Configuration)

어떤 에이전트 정의든 harness: 블록을 추가해 하네스 지원으로 만들어요:

agents:
  coder:
    description: A Claude Code harness agent
    harness:
      type: claude-code

하네스 에이전트는 model: 필드가 필요 없어요 — 외부 CLI가 자신의 모델 선택을 관리해요.

필드 참조 (Field Reference)

Field Applies to Type Description
type all string 필수. claude-code, codex, opencode, pi 중 하나
model all string CLI로 전달되는 선택적 모델 재정의. 생략하면 CLI가 자체 기본 모델을 사용.
effort claude-code string 추론 effort: low | medium | high | xhigh | max — --effort 로 전달. 생략하면 Claude Code가 자체 기본값 사용.
agent opencode string opencode 에이전트 프로필 이름
thinking opencode boolean 확장 thinking 활성화 — --thinking 으로 전달

Claude Code

agents:
  coder:
    description: Claude Code coding agent
    harness:
      type: claude-code
      model: claude-sonnet-4-5 # optional: alias (sonnet, opus, haiku) or full model ID
      effort: high # low | medium | high | xhigh | max
  • model 은 claude CLI가 --model 에 대해 받아들이는 것을 받아요: sonnet, opus, haiku 같은 별칭이나 claude-sonnet-4-5 같은 전체 모델 ID. 생략해 Claude Code 자체의 기본 모델을 쓰세요. 이것은 Docker Agent provider/model 참조가 아니에요 — 하네스 모델은 Docker Agent의 모델 제공자나 라우팅을 절대 통과하지 않아요.
  • effort 는 --effort 로 전달되며 low, medium, high, xhigh, max 중 하나여야 해요. 생략해 Claude Code 자체의 기본값을 쓰세요.

인증 (Claude 구독, API 키 없음) — Authentication (Claude subscription, no API key)

claude-code 하네스는 CLI 자신의 로그인으로 공식 CLI를 실행해요. Claude(claude.ai) 구독 로그인이면 충분해요 — 하네스 에이전트 자체에는 ANTHROPIC_API_KEY 도 Docker Agent 모델 자격 증명도 필요하지 않아요. 한 번 로그인해요:

$ claude auth login --claudeai # interactive, opens a browser
$ claude auth status --text # verify the login

로그인은 CLI가 OS 사용자별로 저장하며(자체 구성 및 macOS에서는 keychain에), HOME과 프로세스 환경을 통해 발견돼요. docker agent 를 실행하는 것과 같은 OS 사용자 및 환경으로 로그인을 실행하세요 — 다른 사용자, 컨테이너, sudo 컨텍스트에서 만든 로그인은 하네스에 보이지 않아요. Docker Agent는 CLI의 토큰을 읽거나, 복사하거나, 저장하지 않아요; claude 를 실행할 뿐이고, claude 가 스스로 인증해요.

하네스 에이전트가 실행될 때 CLI가 로그인되어 있지 않으면 claude 하위 프로세스가 세션 시작에 실패하고 에이전트가 하네스 에러를 보고해요 — Docker Agent는 결코 브라우저를 열거나 스스로 로그인을 시작하지 않아요. 다음으로 진단하고 고쳐요:

$ docker agent doctor ./agent.yaml # checks install + login for claude-code harness files
$ docker agent setup # pick "Claude Code harness" to be walked through it

docker agent doctor <file> 은 파일이 claude-code 하네스를 선언할 때만 CLI를 프로브하고, 설치, 버전, 안전한 로그인 메타데이터(인증 방법, API 제공자, 구독 유형 — 절대 당신의 이메일, 조직, 토큰 아님)를 보고해요. docker agent setup 은 공식 claude auth login --claudeai 를(확인 후에만) 실행해 주고 바로 실행 가능한 claude-code-agent.yaml 을 써줘요.

Warning 하네스는 Claude Code의 권한 프롬프트를 우회해요 Docker Agent는 CLI를 자체 도구와 함께 비대화형으로 실행하고 --dangerously-skip-permissions 를 전달해요: Claude Code가 묻지 않고 파일을 편집하고 명령을 실행해요. 하네스 에이전트를 신뢰하는 저장소에만 지정하고, 격리를 선호하세요 — docker agent run --worktree 는 격리된 git worktree에서 실행해 작업 변경을 체크아웃에서 벗어나게 해요(작업이 있거나 비대화형 실행에서 온 worktree는 정상 정리 규칙에 따라 검사를 위해 유지돼요). docker agent run --sandbox 는 샌드박스에 claude CLI나 그 로그인을 자동으로 가져가지 않으므로, 샌드박스 이미지가 별도로 프로비저닝되고 인증되지 않는 한 하네스를 격리할 수 없어요.

Codex

agents:
  coder:
    description: Codex coding agent
    harness:
      type: codex
      model: o4-mini # optional model override

opencode

agents:
  coder:
    description: opencode coding agent
    harness:
      type: opencode
      agent: my-profile # optional agent profile
      thinking: true # enable extended thinking

동작하지 않는 것 (What Does NOT Work)

하네스 에이전트는 Docker Agent 모델 파이프라인을 완전히 우회해요. 결과적으로:

  • Docker Agent toolset이 비활성화돼요. 외부 CLI가 자체 도구 — 파일시스템, 셸 등 — 를 제공해요. 하네스 에이전트에 정의된 toolsets: 는 조용히 무시돼요.
  • model: 라우팅을 사용할 수 없어요. 하네스 CLI가 모델 선택을 관리하고, Docker Agent의 models: 구성과 라우팅 규칙은 하네스 에이전트에 적용되지 않아요.
  • 토큰 사용량 추적은 외부 CLI에 의존해요. Docker Agent는 CLI가 보고할 때 사용량을 기록해요(Claude Code와 Codex는 모두 사용량 데이터를 보고해요). CLI가 사용량 데이터를 내보내지 않으면 세션에 0 토큰 사용량이 표시돼요.

Warning 하네스 안에는 Docker Agent toolset이 없어요 하네스 에이전트에 toolsets: 를 구성하지 마세요 — 조용히 무시돼요. Docker Agent toolset을 외부 코딩 능력과 함께 필요로 하면, 하네스 대신 transfer_task 와 함께 표준 하위 에이전트를 사용하세요.

훅 동작 (Hook Behavior)

훅은 before_llm_call 과 after_llm_call 을 포함해 하네스 에이전트에서 정상적으로 동작해요. before_llm_call 은 프롬프트가 외부 CLI로 전달되기 전에 실행되고 실행을 차단하거나 재작성할 수 있어요; after_llm_call 은 CLI가 최종 응답을 반환한 후 발동돼요.

훅 페이로드의 model_id 필드는 표준 제공자/모델 문자열 대신 하네스 라벨(예: claude-code)로 설정돼요. 이는 before_llm_call, after_llm_call, model_id 를 실는 다른 어떤 이벤트에도 적용돼요.

전체 훅 참조는 Hooks 참고.

레시피: 루트 하네스 에이전트 (Recipe: Root Harness Agent)

가장 간단한 설정: 모든 것을 Claude Code에 넘기는 단일 루트 에이전트. models: 섹션 없음, API 키 없음 — CLI의 구독 로그인이 작업을 해요. 이것은 docker agent setup 이 Claude Code 하네스 경로용으로 생성하는 파일(claude-code-agent.yaml 로)과 정확히 같아요.

# claude-code-agent.yaml
agents:
  root:
    description: Claude Code running on your Claude subscription
    harness:
      type: claude-code
      effort: medium # low | medium | high | xhigh | max; omit for the Claude Code default
      # model: claude-sonnet-4-5 # optional; omit for the Claude Code default

$ docker agent run claude-code-agent.yaml
$ docker agent doctor claude-code-agent.yaml # verify the CLI is installed and logged in

레시피: 오케스트레이터 + 하네스 하위 에이전트 (순차) — Recipe: Orchestrator + Harness Sub-Agents (Sequential)

오케스트레이터가 작업을 계획하고 한 번에 하나씩 특화 하네스 에이전트에게 위임해요. 각 코딩 에이전트는 자체 하위 세션에서 실행하고 결과를 보고해요.

# examples/coding_harnesses.yaml

models:
  claude:
    provider: anthropic
    model: claude-sonnet-4-5

agents:
  root:
    model: claude
    description: Orchestrator that plans and delegates coding tasks
    instruction: |
      You are a project orchestrator. Break down coding requests into
      focused tasks and delegate each task to the most appropriate
      coding agent. Collect results and synthesize a final summary.
    sub_agents:
      - claude-coder
      - codex-coder

  claude-coder:
    description: Claude Code specialist for complex refactors
    harness:
      type: claude-code
      model: claude-sonnet-4-5
      effort: xhigh

  codex-coder:
    description: Codex specialist for code generation
    harness:
      type: codex

오케스트레이터의 model: claude 만 Anthropic API 키가 필요해요 — claude-coder 하네스 에이전트는 CLI 자체의 구독 로그인으로 인증해요.

루트 에이전트는 transfer_task 를 호출해 하네스 하위 에이전트로 작업을 보내고, 결과를 기다린 뒤 계속해요. 전체 예제는 GitHub 참고.

레시피: 병렬 하네스 디스패치 (Recipe: Parallel Harness Dispatch)

background_agents toolset과 하네스 하위 에이전트를 결합해 여러 코딩 작업을 동시에 디스패치해요:

# examples/coding_harness_background_agents.yaml

models:
  claude:
    provider: anthropic
    model: claude-sonnet-4-5

agents:
  root:
    model: claude
    description: Orchestrator that fans out coding tasks in parallel
    instruction: |
      Use background agents to run multiple coding tasks at once.
      Dispatch all tasks, then collect results when each finishes.
    sub_agents:
      - claude-coder
      - codex-coder
    toolsets:
      - type: background_agents

  claude-coder:
    description: Frontend specialist (Claude Code)
    harness:
      type: claude-code
      effort: medium

  codex-coder:
    description: Backend specialist (Codex)
    harness:
      type: codex

오케스트레이터는 각 작업에 대해 run_background_agent 를 호출하고, list_background_agents 로 진행 상황을 모니터링하며, view_background_agent 로 결과를 수집해요. 전체 예제는 GitHub 참고.

일반 백그라운드 에이전트 참조는 Background Agents 참고.

참고 (See Also)

  • Multi-Agent Systems — 오케스트레이션 패턴
  • Background Agents — 병렬 작업 디스패치
  • Hooks — 감사 및 정책 강제
  • Agent Configuration — 전체 에이전트 스키마 참조

더 알아보기 (Learn more)