§06–07 · 학습 챕터

05. Workers · MCP

워커 · MCP · call_worker

워커는 이름만 같지 않고 호출 경로도 다릅니다. Cursor에서 codex는 주로 MCP, gemini는 Mac Terminal + agy입니다. 잘못된 경로로 부르면 타임아웃·FAIL이 납니다.

정본: _shared/runtime-route-matrix.md · _shared/routing.md · backends.json대상: 바이브코더 · 초급 개발자 (기술 용어 + 한글 설명 병행)

챕터 이동chapter-nav

이전·다음 챕터로 이동합니다. 본문은 아래 학습 블록 카드에서 펼칩니다.

04. Task lifecycle / 작업 흐름 · 재진입

홈

Harness MultiAgent 2.1

06 승인 · envelope

01. Harness Orchestrator 02. Install · validate 03. Folder 3 layers 04. Task lifecycle 05. Workers · MCP 06. Approval · envelope 07. Four flavors 08. RUNBOOK 09. KNOT · wiki 10. KNOT · install 11. KNOT · bridge LAB · Phase · Run

전체 학습 블록 카드learn-blocks

학습 블록

Runtime route matrix

cursor host 검증 경로

_shared/runtime-route-matrix.md · _shared/routing.md · backends.json · claude = call_worker.sh claude (Cursor agent shell OK)

문서 코드 본문현재 실습

학습 블록

MCP explained

MCP란?

_shared/runtime-route-matrix.md · _shared/routing.md · backends.json · Model Context Protocol — IDE가 Codex 같은 외부 AI 도구와 표준 방식으로 대화하게 해 주는 통로.

문서 코드 본문 실습

학습 블록

Worker modes

mode 구분

_shared/runtime-route-matrix.md · _shared/routing.md · backends.json · brief.md 상단 frontmatter:

문서 코드 본문 실습

학습 블록

call_worker.sh

디스패처

_shared/runtime-route-matrix.md · _shared/routing.md · backends.json · 오케스트레이터가 셸 명령을 매번 조립하지 않도록 backends.json + 스크립트가 경로를 맞춥니다.

문서 코드 본문 실습

학습 블록

Call types

호출 방식 표

_shared/runtime-route-matrix.md · _shared/routing.md · backends.json · "result_capture": "envelope",

문서 코드 본문 실습

학습 블록

Failure triage

실패 시 점검

_shared/runtime-route-matrix.md · _shared/routing.md · backends.json · bash "$MULTIAGENT_ROOT/_shared/adapters/call_worker.sh" --dry-resolve gemini

문서 코드 본문 실습

학습 블록

Common mistakes

자주 하는 실수

_shared/runtime-route-matrix.md · _shared/routing.md · backends.json · 자주 하는 실수

문서 코드 본문 실습

학습 블록

Checklist

체크리스트

_shared/runtime-route-matrix.md · _shared/routing.md · backends.json · 체크리스트

문서 코드 본문 실습

선택 블록 본문block-detail

Runtime route matrix

cursor host 검증 경로

한 줄 요약 (Phase 83 최종)

claude = call_worker.sh claude          (Cursor agent shell OK)
codex  = MCP primary / CLI fallback     (Orchestrator direct)
gemini = Mac Terminal + agy primary     (agent shell 금지)

worker	mode	primary route	실행 맥락	fallback
`claude`	implement / critique	`call_worker.sh claude <brief>`	Cursor agent shell	—
`codex`	implement / critique	MCP `mcp__codex__codex` (read-only sandbox)	Orchestrator direct	`call_worker.sh codex`
`gemini`	analysis	`call_worker.sh gemini` → `agy`	Mac Terminal.app only	`gemini_api.sh`

gemini — agent shell vs Terminal

context	결과
Cursor agent shell	❌ timeout 300s (run-068, run-069)
Mac Terminal	✅ PASS (run-034, run-069)

운영 규칙: cursor host에서 gemini는 사용자 Mac Terminal runbook만. Orchestrator가 agent shell에서 call_worker.sh gemini를 실행하지 않습니다.

Runbook: runs/run-034-.../TERMINAL-RUNBOOK.md