네 명의 주자가 모두 올림픽 수준의 선수인 계주 경기를 상상해 보십시오. 빠르고, 기술적으로 완벽하며, 경험이 풍부합니다. 이제 아무도 그들에게 달리기 순서, 배턴 전달 프로토콜, 누가 먼저 배턴을 잡아야 하는지를 말해주지 않았다고 상상해 보십시오. 어떤 일이 벌어질까요? 누군가 출발합니다. 아마 맞는 사람일 수도 있고, 아닐 수도 있습니다. 배턴은 잘못된 방향으로 전달됩니다. 두 명의 주자가 동시에 같은 지점에 도달합니다. 팀은 훌륭합니다. 하지만 경기는 혼돈 그 자체입니다. 이것이 바로 설정을 생략했을 때 발생하는 멀티 에이전트 AI 오케스트레이션 (Multi-agent AI orchestration)의 정확한 문제입니다. Website: https://stack.cardor.dev/ahk

오케스트레이션 격차 (The orchestration gap)
구조화된 멀티 에이전트 워크플로우 (Multi-agent workflow)를 위한 표준 설정은 다음과 같습니다:

Lead (리드) — 작업을 분해하고, 계획하며, 위임합니다.
Explorer (익스플로러) — 코드베이스를 읽고 매핑하며, 절대 쓰지는 않습니다.
Builder (빌더) — 계획을 구현합니다.
Reviewer (리뷰어) — 검증하고, 승인하거나, 차단합니다.

네 개의 특화된 역할입니다. 깔끔한 관심사 분리 (Separation of concerns)입니다.

흔히 발생하는 실수 — 저희의 자체 materializer에서도 발견했던 것인데 — 는 .claude/mcp.json 파일에 default_agent: "lead"를 넣는 것입니다. 해당 필드는 Claude Code의 설정 명세 (config spec)에 존재하지 않습니다. 이는 조용히 무시되며, 여러분의 세션은 Claude가 결정하는 임의의 지점에서 시작됩니다. OpenCode는 opencode.json에서 default_agent를 사용합니다: { "default_agent" : "lead" , "compaction" : { "auto" : true , "prune" : true , "reserved" : 10000 } }. 이는 올바르게 매핑됩니다. 또한 OpenCode는 긴 오케스트레이션 (orchestrated) 세션 동안 컨텍스트 윈도우 (context window) 압박을 관리하기 위한 압축 (compaction) 설정을 노출합니다. 이는 lead, explorer, builder, reviewer가 모두 동일한 실행 과정에서 이력을 축적할 때 유용합니다. Codex CLI에는 직접적인 default_agent 필드가 없습니다. 대신, Codex는 default라는 이름의 내장 에이전트 (built-in agent)를 제공합니다. 여러분은 리드 에이전트 (lead agent)의 지침과 name = "default"를 포함한 .codex/agents/default.toml 파일을 생성함으로써 이를 재정의할 수 있습니다. Codex는 그 시점부터 이를 진입점 (entry point)으로 사용하게 됩니다.

name = "default"
sandbox_mode = "read-only"
description = """ harness backlog로부터 전체 작업을 오케스트레이션하려면 이 에이전트를 사용하십시오: 작업을 계획으로 분해하고, explorer, builder, reviewer에게 순차적으로 위임하십시오. """ developer_instructions = """

Lead Agent

당신은 리드 에이전트입니다. 당신의 역할은 한 번에 하나의 작업에 대해 워크플로 (workflow)를 오케스트레이션하는 것입니다. 당신은 조정하며, 직접 구현하지는 않습니다.
...
"""

두 번째 문제: 강제성이 없는 역할 (roles without enforcement)
시작 에이전트를 올바르게 설정하는 것이 전투의 절반이라면, 나머지 절반은 릴레이가 시작된 후 각 에이전트가 자신의 영역(lane)을 벗어나지 않도록 보장하는 것입니다. 지침 (instructions)이 도움이 되긴 하지만, 지침은 결국 텍스트일 뿐입니다. "src/ 외부의 소스 파일을 읽지 마십시오"라는 지침을 받은 builder는 이를 막을 장치가 없다면 여전히 파일을 읽을 수 있습니다. "절대 파일을 쓰지 마십시오"라는 지침을 받은 explorer는 그것이 가장 빠른 길이라고 판단하면 여전히 파일을 쓸 수 있습니다. 프롬프트 (prompt)가 약간만 어긋나거나 예외 상황 (edge case)이 발생하면 계약 (contract)은 깨집니다. 바로 이 지점에서 역할별 샌드박싱 (per-role sandboxing)이 실질적인 역할을 수행합니다.

Claude Code는 각 에이전트의 .md 파일의 프론트매터 (frontmatter) 필드로 permissionMode를 노출합니다:

---

name : explorer
permissionMode : plan

plan 모드는 세션을 읽기 전용 계획 모드 (read-only planning mode)로 전환하며, 파일 쓰기 및 편집은 도구 (tool) 수준에서 차단됩니다. 이는 지시 (instruction)가 아니라 강제 (enforcement)입니다. builder의 경우 다음과 같습니다:

---

name : builder
permissionMode : acceptEdits

acceptEdits는 변경 사항마다 확인 프롬프트를 띄우지 않고 파일 편집을 자동 승인함을 의미합니다. 이는 구현이 주 업무인 에이전트에게 적합한 절충안 (tradeoff)입니다. Codex CLI는 에이전트별 TOML 파일에서 sandbox_mode를 사용합니다:

explorer.toml

name = "explorer"
sandbox_mode = "read-only"

builder.toml

name = "builder"
sandbox_mode = "workspace-write"

우리의 네 가지 역할에 걸친 전체 매트릭스 (matrix)는 다음과 같습니다:

에이전트	Claude Code permissionMode	Codex sandbox_mode
lead	plan	read-only
explorer	plan	read-only
builder	acceptEdits	workspace-write
reviewer	plan	read-only

이것이 정신 건강뿐만 아니라 토큰을 아껴주는 이유

여기에는 정확성을 넘어선 경제적 논거가 있습니다. 오케스트레이션 (orchestration)의 기본 설정이 잘못되면, 매 세션 시작 시 컨텍스트 (context)를 재설정하느라 토큰을 낭비하게 됩니다. Lead는 자신을 다시 소개해야 합니다. 잘못된 에이전트가 어색하게 업무를 인계합니다. 모델은 업무를 수행하는 대신 워크플로 (workflow) 상에서 자신이 어디에 있는지 파악하는 데 턴 (turn)을 소비합니다. 그러면 당신은 다시 프롬프트를 입력하고, 내용을 명확히 하고, 어쩌면 다시 시작해야 할지도 모릅니다.

기본 설정이 올바르면, 첫 번째 턴부터 이미 올바른 위치에 배치됩니다. Lead가 작업을 맡아 분해하고, explorer에게 바통을 넘깁니다. Explorer는 코드베이스 (codebase)를 매핑하고, builder에게 넘깁니다. Builder는 구현하고, reviewer에게 넘깁니다. 깔끔한 체인 (chain)입니다. 재정립 (re-orientation)이 필요 없습니다. 첫 번째 세션 초안이 바로 제대로 된 결과물이 됩니다.

모델의 지능은 동일합니다. 첫 시도에서 출력 품질을 바꾸는 것은 바로 설정 (setup)입니다. 모델이 더 똑똑해져서가 아니라, 시작 위치를 추측할 필요가 없기 때문에 더 예측 가능한 동작, 더 적은 반복, 더 적은 토큰 낭비가 가능해지는 것입니다.

비교 항목	Claude Code	OpenCode	Codex CLI
에이전트 파일 (Agent files)	.claude/agents/*.md	.opencode/agents/*.md	.codex/agents/*.toml
파일 형식 (File format)	Markdown + YAML frontmatter	Markdown + YAML frontmatter	TOML
기본 에이전트 필드 (Default agent field)	settings.json 내 agent	opencode.json 내 default_agent	default.toml을 통한 내장 기능 오버라이드 (Override)
역할별 권한 (Per-role permissions)	frontmatter 내 permissionMode — (전역 전용)	TOML 내 sandbox_mode	MCP 설정 파일 (MCP config file)
MCP 설정 (MCP config file)	.claude/mcp.json	opencode.json	.codex/config.toml
압축 설정 (Compaction config)	노출되지 않음 (Not exposed)	compaction.{auto,prune,reserved}	해당 없음 (Not applicable)

종합하기 (Putting it together)

이 모든 과정은 agent-harness-kit에서 자동화됩니다. 단 한 번의 명령으로 여러분이 선택한 어떤 제공자(Provider)에 대해서도 에이전트, MCP 설정, 기본 에이전트 연결, 샌드박스(sandbox) 설정 등 전체 구조를 스캐폴딩(scaffolding)할 수 있습니다:

npx ahk init --provider codex-cli
npx ahk init --provider claude-code
npx ahk init --provider opencode

매터리얼라이저(Materializer)는 어떤 필드를 어떤 파일에 어떤 형식으로 작성해야 하는지 알고 있습니다. 세 개의 서로 다른 문서 페이지를 대조하거나, 6개월이 지난 후에야 mcp.json의 default_agent 키가 아무런 역할도 하지 않고 있었다는 사실을 깨닫는 일 없이 정확한 기본값을 얻을 수 있습니다.

릴레이(Relay) 비유의 유효성

다시 주자들 이야기로 돌아가 보겠습니다. 바톤(baton) 문제는 능력이 아니라 프로토콜(protocol)의 문제입니다. 프로토콜을 산문(prose)이 아닌 설정(config)으로 정의하십시오. 각 주자는 적절한 권한을 가지고, 적절한 순서에 따라, 자신의 레인에서 달립니다. 릴레이 경기는 스스로 진행됩니다. 당신은 그저 경주를 지켜보기만 하면 됩니다.

agent-harness-kit로 제작됨 — 구조화된 멀티 에이전트 AI 워크플로우를 위한 제공자 중립적(provider-agnostic) 스캐폴딩.