4장 §1

4장 §1 · 하네스 기반 멀티 에이전트 팀 활용

Claude Code / Claude Desktop App / Antigravity CLI / Antigravity(Desktop) / Codex CLI / Codex Desktop App 여섯 도구에서 서브에이전트(또는 그에 해당하는 작업)를 정의하고, 호출하고, 병렬·자동화 단위로 확장하는 방법을 나란히 정리한 레퍼런스 | 공식 문서: Claude Code — Subagents · Antigravity CLI — Getting Started · Antigravity CLI — Using · Antigravity — Agent Manager · Codex

대상 버전Claude Code 2026-09 릴리스 / Antigravity CLI (agy) 1.1.0+ / Antigravity 2.0 / Codex CLI·Desktop App

참조 문서 URLcode.claude.com/docs/en/sub-agents · antigravity.google/docs/cli/getting-started · antigravity.google/docs/cli/using · Claude Code (Agent Manager) · developers.openai.com/codex

문서 수집일2026-09-12

버전 확인 방법Claude Code/App: claude --version · Antigravity CLI: agy --version 또는 세션 안에서 /usage · Antigravity Desktop: 앱 내 정보 화면 · Codex CLI: codex --version · Codex Desktop App: 앱 내 정보 화면

개정 시 확인 사항Claude Code Agent Teams와 Antigravity CLI/Agent Manager 모두 빠르게 변화하는 기능이라 플래그명·명령·UI 구성이 릴리스마다 바뀔 수 있으니 최신 릴리스 노트를 우선 확인. Codex에 네이티브 서브에이전트 도구가 추가됐는지도 재확인

2026-06-18을 기점으로 Google은 개인(Free/Pro/Ultra) 사용자 대상 Gemini CLI 서비스를 종료했고, 그 자리를 Antigravity CLI(agy)가 대체했다. 이 장은 그 이전에는 Gemini 명령줄 인터페이스(CLI)를 기준으로 작성됐으나, 현재 시점 기준으로 Antigravity CLI/데스크톱(Desktop)으로 전면 갱신했다. 자세한 도구별 특성 비교는 도구 비교를 참고한다.

개요 — 전체 구조

하네스 기반 멀티 에이전트 팀 활용 (Desktop 앱을 기준으로, CLI는 동일 개념의 대안으로 병기)
├── 서브에이전트/역할 정의하기
│   ├── Claude Desktop App / Claude Code    .claude/agents/*.md (YAML frontmatter, 사전 정의 — 둘 다 동일)
│   ├── Antigravity(Desktop) / CLI  사전 정의 파일 없음 — 오케스트레이터가 목표를 보고 동적 생성
│   └── Codex Desktop App / CLI     agents/<name>.md를 읽기 전용 역할 컨텍스트로 참조 (둘 다 동일)
├── 서브에이전트 호출/위임하기
│   ├── Claude Desktop App / Claude Code    Agent(Task) 툴 — description / prompt / subagent_type
│   ├── Antigravity(Desktop)/CLI    Agent Manager UI(Desktop) · /goal, /agent, /agents 패널(CLI)
│   └── Codex Desktop App/CLI       없음 — PM이 세션 내에서 역할을 순차적으로 전환
├── 병렬 실행
│   ├── Claude Desktop App                  Agent Teams(in-process만)
│   ├── Claude Code                 Agent Teams(in-process/tmux) + 한 메시지에 여러 Agent 호출
│   ├── Antigravity Desktop         Agent Manager — Workspace별 에이전트 (Local/New Worktree Mode)
│   ├── Antigravity CLI             세션 내부 병렬 서브에이전트 + 세션 간(터미널 여러 개) 병렬
│   └── Codex Desktop App/CLI       세션 내부 병렬 없음 — 여러 창/터미널로 세션 간 병렬만 가능
└── 자동화/훅
    ├── Claude Desktop App                  훅 미발화 — 수동 실행 필요
    ├── Claude Code                 PostToolUse/TeammateIdle/TaskCompleted 훅 자동 발화
    ├── Antigravity Desktop         해당 없음 — GUI 중심
    ├── Antigravity CLI             agy -p "프롬프트"(비대화형 CI용), agy inspect(설정 확인)
    └── Codex Desktop App/CLI       훅 스위트 미실행 — CODEX.md 지침을 PM이 프롬프트로 자체 강제

에이전트 팀 구성 예시

1. 서브에이전트 정의하기 — 사전 정의 vs 동적 생성

Anthropic 계열(Claude Desktop App/Claude Code)은 프로젝트 폴더 아래에 마크다운 파일 하나로 서브에이전트 하나를 미리 정의해 둔다. Google 계열(Antigravity Desktop/CLI)은 별도의 정의 파일이 없다 — 오케스트레이터가 주어진 목표를 보고 그때그때 서브에이전트를 만든다. OpenAI 계열(Codex Desktop App/CLI)은 네이티브 서브에이전트 자체가 없어, 워크스페이스 공통 폴더의 agents/<name>.md를 PM이 읽기 전용 역할 컨텍스트로 참조한다. 아래에서는 Claude Desktop App과 Antigravity(Desktop)를 기준으로 먼저 설명하고, 각각의 CLI 대응과 Codex를 이어서 소개한다.

Claude 계열의 구체적인 정의·호출 방식은 §1-A Claude 중심에서, Antigravity 계열의 구체적인 방식은 §1-B Antigravity 중심에서, Codex 계열의 구체적인 방식은 §1-C Codex 중심에서 다룬다.

frontmatter 필드	Claude Desktop App / Claude Code (.claude/agents)	Antigravity (Desktop/CLI)	Codex (Desktop/CLI)
`name`	필수. `subagent_type` 값과 일치해야 호출 가능	해당 없음 — 정의 파일 자체가 없고, 오케스트레이터가 실행 시점에 역할·툴 범위를 스스로 판단해 서브에이전트를 생성한다	호출 개념이 없음 — `agents/<name>.md`는 PM이 참고하는 읽기 전용 역할 문서일 뿐, frontmatter 필드가 실행에 관여하지 않는다
`description`	이 에이전트가 언제 쓰이는지 설명, 자동 트리거 판단에 참고됨
`tools`	사용 가능한 툴 목록, 생략 시 기본 세트 상속
`model`	`sonnet` / `opus` / `haiku` 등 별칭 지정

Antigravity(Desktop/CLI)에는 "서브에이전트 정의 파일"이라는 개념 자체가 없다 — 초급 실습에서 Antigravity 쪽에 Claude Desktop App/Code의 reviewer.md와 똑같은 예제를 억지로 만들면 사실과 어긋난다. Antigravity의 "입문 실습"은 파일을 만드는 것이 아니라 목표를 주고 오케스트레이터가 알아서 작업을 쪼개는 과정을 관찰하는 것이다. Codex(Desktop/CLI)는 한 걸음 더 나아가 서브에이전트 호출 자체가 없다 — "Codex에서 reviewer 서브에이전트를 호출한다"는 표현은 틀렸다. PM이 agents/reviewer.md를 참고해 그 역할처럼 사고할 뿐이다.

2. 서브에이전트 호출/위임하기

Anthropic 계열(Claude Desktop App/Claude Code)은 Agent/Task 툴로 별도 컨텍스트의 서브에이전트를 스폰한다. Google 계열(Antigravity Desktop/CLI)은 Agent Manager UI 또는 슬래시 커맨드로 에이전트에게 목표를 위임한다. OpenAI 계열(Codex Desktop App/CLI)은 "호출"이라는 동작 자체가 없다 — PM이 같은 세션 안에서 역할을 순차적으로 전환하며 작업을 이어간다.

Claude 계열의 구체적인 호출 방식은 §1-A 섹션 2에서, Antigravity 계열의 구체적인 방식은 §1-B 섹션 2에서, Codex 계열의 순차 역할 전환 방식은 §1-C 섹션 2에서 다룬다.

3. 병렬 실행 — 6가지 도구 비교

여섯 도구 모두 어떤 형태로든 여러 작업을 동시에 진행할 수 있지만, 방식이 다르다. Claude 계열은 Agent Teams / 다중 Agent 호출, Antigravity 계열은 Agent Manager / 세션 간 병렬을 사용한다. Codex 계열은 세션 내부 병렬을 지원하지 않으며, 여러 창·터미널로 세션 자체를 나누는 것만 가능하다.

같은 디렉터리·Workspace에서 여러 에이전트를 동시에 돌리면 "인지적 중첩(cognitive overlap)"이 발생할 수 있다 — 한 에이전트가 같은 폴더에서 작업 중인 다른 에이전트의 결과를 자기 작업 맥락으로 착각(hallucination)하는 문제다. Workspace나 worktree로 에이전트를 분리하는 것이 권장 관행이며, 예외적으로 넘어갈 수 있는 사소한 문제가 아니다. Codex는 애초에 세션 내부 병렬이 없으므로 이 문제 자체가 발생하지 않는다.

Claude 계열의 병렬 실행 방식은 §1-A 섹션 3에서, Antigravity 계열의 병렬 실행 방식은 §1-B 섹션 3에서, Codex 계열의 세션 간 병렬 방식은 §1-C 섹션 3에서 다룬다.

항목	Antigravity (Desktop)	Claude Desktop App	Antigravity CLI (agy)	Claude Code (CLI)	Codex (Desktop/CLI)
병렬 실행 단위	워크스페이스별 독립 에이전트	Agent Teams (in-process만)	세션 내부 + 세션 간(터미널 여러 개)	한 메시지 내 다중 Agent 호출 / Agent Teams(in-process + tmux)	세션 내부 병렬 없음 / 여러 창·터미널로 세션 간 병렬만 가능

4. 자동화/훅 — 무엇이 자동으로 발화하는가

Claude Code(CLI)는 이벤트 훅(PostToolUse/TeammateIdle/TaskCompleted)을 자동 발화하지만, Claude Desktop App과 Antigravity 데스크톱(Desktop)은 훅을 자동 발화하지 않는다. Antigravity 명령줄 인터페이스(CLI)는 agy -p로 비대화형 실행, agy inspect로 설정 점검을 제공한다. Codex(Desktop/CLI)는 워크스페이스 훅 스위트를 전혀 실행하지 않으며, CODEX.md에 적힌 지침을 PM이 매 세션 스스로 인지하고 실행하는 프롬프트 자체 강제 방식으로 대신한다.

Claude 계열의 자동화/훅 세부는 §1-A 섹션 4에서, Antigravity 계열의 자동화/훅 세부는 §1-B 섹션 4에서, Codex 계열의 프롬프트 자체 강제 방식은 §1-C 섹션 4에서 다룬다.

실무 팁: Antigravity에는 계산된 작업량(work done)에 기반한, 주기적으로 갱신되는 사용량 쿼터가 있다. 정확한 수치는 계정·플랜마다 다를 수 있으므로 여러 에이전트를 장시간 병렬로 돌리는 작업을 계획할 때는 이 점을 감안하는 편이 안전하다.

Agent Teams와 Agent Manager 모두 빠르게 발전 중인 기능이다 — 플래그명, 기본 동작, UI 구성이 릴리스마다 바뀔 수 있으므로 프로덕션 워크플로우에 의존하기 전에 최신 릴리스 노트를 확인하라.

참고 링크

Claude Code 2026-09 · Antigravity CLI 1.1.0+ · Antigravity 2.0 · Codex CLI/Desktop App 기준 | 2026년 9월

← 이전

3장 · 가드레일

도구 선택

Claude (A) Antigravity (B) Codex (C)