4장 §2-B

4장 §2-B · 멀티 에이전트 팀 실습

빈 실습 폴더에서 시작해 Antigravity(Desktop)/Antigravity CLI 위주로 시나리오를 따라해보는 실습 가이드 — Desktop 앱을 기준으로 안내하고 CLI 대응을 이어서 소개한다  |  ← 4장 §1 레퍼런스 문서로 돌아가기

대상 버전/범위Antigravity CLI (agy) 1.1.0+, Antigravity 2.0 — Antigravity를 중심으로 안내하며, Claude Desktop App/Code 대응은 4장 §2-A를 참조
이 파일의 목적서브에이전트 정의·호출, 순차 파이프라인, 동적 팀 구성·워크플로우 조합, 병렬 실행을 Antigravity(Desktop)/Antigravity CLI 위주로 손으로 따라해보는 4단계 실습 제공
레퍼런스 문서4장 §1 공통 · 4장 §1-A Claude 상세 · 4장 §1-B Antigravity 상세 — 각 시나리오에서 링크로 연결됩니다
작성일2026년 7월 14일
이 과정 전체가 따르는 원칙 — 특정 도구 하나에 맞춰 실습을 익히면 다른 도구로 옮길 때 처음부터 다시 배워야 한다. 그래서 아래 모든 시나리오는 먼저 서브에이전트의 역할을 도구 중립적인 AGENTS.md 명세로 적고, 그 같은 명세를 Antigravity 계열에서는 자연어 목표로 "구현"하는 순서를 따른다(2장 §5 AGENTS.md 참고). Claude 계열에서의 대응 방식은 4장 §2-A에서 다룬다. 정의는 하나, 실행 방식만 도구별로 다르다는 원칙을 손으로 확인하는 것이 이 실습의 핵심 목표다.

준비: 필요한 프로그램 설치

아래 실습은 Antigravity(Desktop)와 Antigravity CLI(agy)를 중심으로 진행된다. 로컬 환경에 이 도구들이 아직 없다면, 이 핸드북에 함께 담아 둔 환경 설정 자동화 도구인 setup 가이드가 이 장의 실습에 정확히 필요한 구성을 자동으로 설치해준다. 안내에 따라 스크립트를 내려받아 로컬에서 실행하면 된다.

📦 설치 전 확인 사항

스크립트를 실행하기 전에 사전 설치 체크리스트를 먼저 읽어본다. 이 문서에는 다음 전제 조건이 정리되어 있다.

  • Antigravity 사용을 위한 Google 계정 (개별 API 키가 아니라 구독제/계정 기반 플랜이어야 한다)
  • gh auth login을 진행할 수 있는 GitHub 계정
  • 최소 5GB의 여유 디스크 공간
  • 관리자(admin) 또는 sudo 권한
GitHub 계정이 아직 없다면
① 브라우저에서 github.com/signup에 접속한다.
② 이메일 주소, 비밀번호, 사용자 이름(username)을 입력한다 — username은 나중에 저장소 URL(github.com/<username>/...)에 그대로 쓰이므로 신중히 정한다.
③ 자동 가입 방지를 위한 퍼즐/코드 인증을 통과한다.
④ 가입 시 입력한 이메일로 온 인증 메일을 열어 이메일 인증을 완료한다 — 이 단계를 건너뛰면 이후 gh auth login이나 저장소 생성이 막힐 수 있다.
⑤ 무료(Free) 플랜으로 가입하면 충분하다 — 이 핸드북의 실습·PR 연습에는 유료 플랜이 필요 없다.
가입이 끝나면 GitHub CLI(gh)가 위 설치 스크립트에 포함돼 함께 설치되고, 아래 gh auth login 명령으로 터미널을 그 계정과 연결한다. 
gh auth login
# 안내에 따라: GitHub.com 선택 → HTTPS 선택 → 브라우저로 로그인(권장) 선택
# 브라우저가 열리면 방금 만든 계정으로 로그인하고 인증 코드를 확인한다

Windows에서 설치하기

이 핸드북의 경로 표기가 Windows 기준이므로, Windows 사용자는 아래 명령으로 5throck/setup 저장소를 클론한 뒤, PowerShell을 관리자 권한으로 실행해서 이어지는 명령을 돌린다.

PowerShell을 관리자 권한으로 여는 법
① 시작 메뉴를 열고 PowerShell을 검색한다.
② 검색 결과의 "Windows PowerShell"을 마우스 우클릭한다.
③ 나오는 메뉴에서 "관리자 권한으로 실행"을 선택한다.
④ 사용자 계정 컨트롤(UAC) 창이 뜨면 "예"를 눌러 승인한다.
창 제목 표시줄에 관리자: Windows PowerShell처럼 "관리자"가 붙어 있으면 제대로 연 것이다. winget 설치 등 일부 단계는 관리자 권한 없이 실행하면 오류가 나거나 조용히 건너뛰어질 수 있다. 
git clone https://github.com/5throck/setup.git
cd ./setup
powershell -ExecutionPolicy Bypass -File .\setup-windows.ps1
# 선택 옵션: -WSL2, -WezTerm, -Docker, -Force (이미 설치된 도구도 재설치)

스크립트가 끝나면 터미널을 완전히 닫았다가 다시 열어야 PATH 변경 사항이 적용된다.

macOS / Linux에서 설치하기

아래 명령으로 5throck/setup 저장소를 클론해서 사용한다. macOS는 setup-mac.sh, Linux는 setup-linux.sh를 실행하며, 둘 다 --wezterm, --docker 선택 플래그를 지원한다.

git clone https://github.com/5throck/setup.git

# macOS
cd ./setup && bash setup-mac.sh

# Linux
cd ./setup && bash setup-linux.sh

설치 검증하기

운영체제와 무관하게 setup-common.ts를 bun으로 실행하면 설치 상태를 점검하는 체크리스트 표가 출력된다. 모든 항목이 ✅로 표시되면 아래 실습을 진행할 준비가 된 것이다.

cd ./setup && bun setup-common.ts

이 프로젝트가 설치하는 도구 중 이 장의 실습과 직접 관련된 것은 다음과 같다. Antigravity(Desktop), agy(Antigravity CLI), 그리고 이후 장에서 쓰이는 gh(GitHub CLI)까지 함께 설치된다.

Antigravity CLI(agy)는 별도 런타임 설치가 필요 없는 단일 컴파일 바이너리다 — 압축 해제 후 PATH에 넣기만 하면 바로 실행된다. 옛 자료에 남아 있는 "Gemini 명령줄 인터페이스(CLI)를 npm으로 전역 설치" 같은 안내는 더 이상 유효하지 않다. 최신 설치 방법은 antigravity.google/docs/cli/getting-started에서 확인한다.
설치 중 문제가 생기면 Windows 기준 %USERPROFILE%\workshop-setup-logs\ 폴더에 로그가 남는다. 문제를 해결할 때 이 로그부터 확인한다.
● 초급 Getting Started Antigravity(Desktop)에서 목표를 주고 동적 생성을 관찰하는 첫 단계
G-1 초급 첫 커스텀 서브에이전트 만들고 호출하기
하네스를 처음 써보는 개발자가 실습 전용 빈 폴더 harness-lab/를 새로 만들고, reviewer 역할을 도구 중립적인 AGENTS.md 명세로 먼저 적어 둔 뒤, Antigravity(Desktop)에서 자연어 목표로 "구현"해 호출해본다. 이 폴더는 실습 전용이므로 다른 프로젝트 파일과 섞이지 않는다.
사용 요소
AGENTS.md (2장) 서브에이전트 정의하기 서브에이전트 호출하기
단계별 실행
  1. ① 실습 폴더 생성 및 진입

    현재 폴더 아래 harness-lab 폴더를 새로 만들고 그 안으로 이동한다. 이후 모든 명령은 이 폴더 안에서 실행한다.

    mkdir -p harness-lab
cd harness-lab
  2. ② 공통 역할 명세 작성 — AGENTS.md

    Claude나 Antigravity, 그 외 AGENTS.md 표준을 지원하는 어떤 도구로 열어도 같은 의미로 읽히도록, reviewer 역할을 도구 종속적인 표현 없이 순수 텍스트로 적는다. 이 파일 하나가 "무엇을 하는 역할인가"의 유일한 원본이 되고, 아래 Antigravity는 이 원본을 자연어 목표로 구현할 뿐이다. macOS/Linux/Git Bash에서는 아래 명령을 그대로 쓴다.

    cat > AGENTS.md << 'EOF'
## Agent: reviewer

역할: 텍스트 파일의 오탈자, 논리적 허점, 개선점을 검토한다.
입력: 검토 대상 텍스트 파일 경로
출력: 오탈자 · 논리적 허점 · 개선점 목록
권한: 읽기 전용 — 파일을 직접 수정하지 않는다.
EOF

    Windows PowerShell에서는 cat 명령 자체는 Get-Content의 별칭으로 파일 읽기에 그대로 쓸 수 있다. 다만 << 'EOF'처럼 여러 줄을 직접 넣는 heredoc 문법은 지원하지 않으므로, 같은 내용은 따옴표 있는 here-string(@'...'@)으로 만들어 Set-Content로 파일에 쓴다.

    @'
## Agent: reviewer

역할: 텍스트 파일의 오탈자, 논리적 허점, 개선점을 검토한다.
입력: 검토 대상 텍스트 파일 경로
출력: 오탈자 · 논리적 허점 · 개선점 목록
권한: 읽기 전용 — 파일을 직접 수정하지 않는다.
'@ | Set-Content AGENTS.md
Antigravity (Desktop) — 같은 AGENTS.md 명세를 자연어 목표로 구현

Antigravity는 .claude/agents 같은 사전 정의 파일 개념이 없다. 대신 방금 작성한 AGENTS.md를 워크스페이스에 그대로 둔 채, 같은 명세를 목표 프롬프트에 담아 준다.

  1. ① 검토 대상 파일 미리 준비 (터미널) 
    echo "이 프로젝트는 매우 좋다. 이것은 아주 좋다." > notes.txt
  2. ② Antigravity Agent Manager에서 Workspace 생성

    Agent Manager를 열고 harness-lab/ 폴더(AGENTS.md가 이미 들어있는 폴더)를 가리키는 새 Workspace를 하나 만든다.

  3. ③ 목표 지시 — Workspace 채팅창에 아래 문장을 그대로 붙여넣고 전송 
    AGENTS.md에 적힌 reviewer 역할 명세대로 notes.txt를 검토해줘.
    Workspace를 맡은 에이전트가 AGENTS.md를 읽고, 그 안의 역할/입력/출력/권한 명세를 그대로 목표로 삼아 필요한 작업(파일 읽기, 개선점 정리)을 스스로 판단해 수행한다. AGENTS.md가 "무엇을 검토 기준으로 삼는가"의 유일한 원본이므로, 검토 기준(오탈자·논리적 허점·개선점)은 이 명세에 의해 결정된다.

Antigravity CLI(agy)에서도 같은 개념으로 실습할 수 있다 — 사전 정의 파일 없이 /goal로 목표만 준다.

cd harness-lab && agy
/goal notes.txt 파일을 검토하고 개선점을 요약해줘
Antigravity는 정의 파일이 없으므로 Claude 계열처럼 tools 필드로 사전 권한 제한을 할 수는 없다. 대신 목표 프롬프트 자체를 "읽고 요약만 해줘"처럼 명확히 좁히는 것이 안전하다. AGENTS.md에 적힌 권한: 읽기 전용 명세도 오케스트레이터에게 권한 경계를 알려주는 역할을 한다.
● 중급 Daily Workflow 메인 세션이 오케스트레이터가 되어 writer와 reviewer 두 전문 에이전트를 순서대로 지휘하는 실무 패턴
D-1 중급 writer → reviewer 2단계 파이프라인
G-1을 마친 실무자가 같은 harness-lab/ 폴더에서, 두 번째 역할 writer도 G-1과 같은 방식으로 AGENTS.md에 먼저 명세한 뒤, Antigravity(Desktop)에서 자연어 목표로 구현한다. writer가 먼저 초안을 쓰고 reviewer가 그 결과를 비평하는 파이프라인을 오케스트레이터가 순서를 지켜 지휘하게 한다.
사용자 요청 writer.md 초안 작성 수정 요청 시 writer로 되돌아감 reviewer.md 피드백/승인 최종 결과물 완성
사용 요소
AGENTS.md (2장) 서브에이전트 정의하기 서브에이전트 호출하기
단계별 실행
  1. 공통 역할 명세 추가 — AGENTS.md에 writer 항목 이어쓰기

    G-1에서 만든 같은 AGENTS.md에 writer 역할을 이어서 적는다. reviewer 항목은 그대로 두고 아래 내용만 추가한다. macOS/Linux/Git Bash에서는 아래 명령을 그대로 쓴다.

    cat >> AGENTS.md << 'EOF'

## Agent: writer

역할: 주어진 주제로 3~5문장 분량의 짧은 초안을 작성한다.
입력: 주제, 저장할 파일 경로
출력: 초안 텍스트 파일
권한: 쓰기 허용 — 지정된 파일에만 저장한다.
handoff_to: reviewer (초안 완료 후 검토로 이어짐)
EOF

    Windows PowerShell에서는 here-string을 Add-Content로 이어붙인다(Set-Content는 파일을 덮어쓰므로 반드시 Add-Content를 써야 reviewer 항목이 지워지지 않는다).

    @'

## Agent: writer

역할: 주어진 주제로 3~5문장 분량의 짧은 초안을 작성한다.
입력: 주제, 저장할 파일 경로
출력: 초안 텍스트 파일
권한: 쓰기 허용 — 지정된 파일에만 저장한다.
handoff_to: reviewer (초안 완료 후 검토로 이어짐)
'@ | Add-Content AGENTS.md
Antigravity (Desktop) — 같은 AGENTS.md 명세 두 개를 한 목표로 오케스트레이터가 스스로 분해

Antigravity는 사전에 writer/reviewer 파일을 나눠 정의하지 않는다. 대신 AGENTS.md에 이미 적어 둔 두 역할 명세(reviewer는 G-1에서, writer는 방금)를 그대로 참조하게 한다. G-1에서 만든 같은 Workspace의 채팅에서 이어서 진행한다.

  1. ① 2단계 목표 지시 — Workspace 채팅창에 아래 문장을 그대로 붙여넣고 전송 
    AGENTS.md의 writer 명세대로 draft.txt에 '원격 근무의 장점' 주제 초안을 먼저 작성하고, 완료되면 AGENTS.md의 reviewer 명세대로 그 초안을 검토해줘. 두 단계를 순서대로 진행해.
    오케스트레이터가 AGENTS.md의 handoff_to: reviewer 관계를 읽고 목표를 "초안 작성 → 검토"의 두 하위 작업으로 스스로 쪼갠 뒤, 초안 작성이 끝난 뒤에야 검토 작업을 시작한다. 순서 조율의 책임이 사용자가 아니라 오케스트레이터 내부에 있다는 점이 특징이다 — 다만 "무엇을 검토 기준으로 삼는가"는 AGENTS.md가 유일한 원본이다.

Antigravity CLI(agy)에서도 같은 목표를 한 번에 줄 수 있다. /goal로 전체 파이프라인을 한 문장에 담으면 오케스트레이터가 알아서 분해하고, 필요하면 /agent로 검토 단계를 백그라운드에 맡긴 채 다른 작업을 이어갈 수도 있다.

agy
/goal draft.txt에 '원격 근무의 장점' 주제로 초안을 먼저 쓰고,
완료되면 그 초안을 검토해서 개선점을 요약해줘
D-2 중급 요청에 따라 팀 구성과 워크플로우가 달라지는 것 관찰하기
2장 §4b에서 다룬 "동적 팀 구성"과 "다양한 워크플로우 조합"을 직접 눈으로 확인하는 시나리오다. D-1에서 만든 writer·reviewer 두 역할 명세는 그대로 두고, 요청의 성격만 바꿔가며 오케스트레이터가 실제로 어떤 작업을, 몇 번, 어떤 순서로 수행하는지 관찰한다 — 서브에이전트 정의는 한 번도 새로 만들지 않는다는 점이 핵심이다.
사용 요소
동적 팀 구성과 다양한 워크플로우
Antigravity (Desktop) — 목표 자연어만으로도 같은 유연성이 드러난다

Antigravity는 애초에 서브에이전트를 동적으로 생성하는 방식이므로, 이 유연성이 더 직접적으로 드러난다. D-1에서 쓰던 같은 Workspace 채팅에서 이어서 진행한다.

  1. ① 단순 목표 지시 
    draft.txt의 오탈자만 훑어봐줘.
    오케스트레이터는 이번 요청에 작성 역할이 필요 없다고 판단해 검토 역할 하나만 즉석에서 구성한다. AGENTS.md에 두 역할이 정의돼 있어도, 실제로 투입되는 구성은 요청마다 오케스트레이터가 그때그때 결정한다는 것을 보여주는 가장 단순한 예다.
  2. ② 복합 목표 지시 
    draft2.txt에 '4일 근무제' 주제로 새 초안을 먼저 쓰고, 완료되면 그 초안을 문법 관점과 논리 관점 두 가지로 각각 독립적으로 동시에 검토해줘.
    오케스트레이터가 ①에서는 검토 역할 하나만 즉석에서 구성하고, ②에서는 작성 역할 하나와 검토 역할 둘(서로 다른 관점)을 새로 구성한다. 사전에 정의된 서브에이전트 파일이 아예 없으므로, "이번 작업에 맞는 팀을 매번 새로 짠다"는 원칙이 더 선명하게 드러난다.
①과 ②를 나란히 비교하면 "AGENTS.md에 어떤 역할을 정의해 뒀는가"와 "이번 작업에 실제로 투입되는 구성이 무엇인가"가 서로 다른 층위라는 게 뚜렷해진다. 전자는 AGENTS.md에 미리 고정돼 있지만, 후자는 매 요청마다 오케스트레이터가 새로 결정한다.
함께 보기: 2장 §4b — 동적 팀 구성과 다양한 워크플로우, 4장 §1 레퍼런스 — 병렬 실행
● 고급 Power User writer와 reviewer를 독립적인 두 파일에 대해 동시에 돌리는 병렬 운영 — Agent Manager 활용
P-1 고급 독립 작업 병렬 실행 — Agent Manager
D-1까지 마친 숙련자가 서로 의존하지 않는 두 개의 독립적인 작업(topic-a.txt, topic-b.txt 초안 작성)을 Antigravity(Desktop) Agent Manager에서 병렬로 돌려본다.
사용 요소
병렬 실행 — 팀 단위로 확장하기 병렬 실행
Antigravity (Desktop) — Agent Manager, Workspace별 에이전트 1개

Antigravity를 열고 Agent Manager에서 harness-lab/을 가리키는 Project를 하나 준비한다. 이번에는 하나의 Workspace에 두 에이전트를 몰아넣지 않고, 서로 다른 Workspace 두 개를 만들어 각각 에이전트를 하나씩 배정한다.

  1. ① Workspace A 생성

    New Worktree Mode로 Workspace를 하나 만든다.

  2. ② Workspace A 채팅창에 아래 문장을 그대로 붙여넣고 전송 
    topic-a.txt에 '재택근무' 주제로 3~5문장 초안을 작성해줘.
  3. ③ Workspace B 생성

    별도의 Workspace를 하나 더 만든다(New Worktree Mode 권장). Workspace A의 에이전트와는 완전히 분리된 인스턴스다.

  4. ④ Workspace B 채팅창에 아래 문장을 그대로 붙여넣고 전송 
    topic-b.txt에 '4일 근무제' 주제로 3~5문장 초안을 작성해줘.
  5. ⑤ Inbox에서 두 에이전트 진행 상황 확인

    두 에이전트가 각자의 Workspace에서 동시에 작업하는 동안, Inbox에서 승인이나 피드백이 필요한 메시지가 오는지 확인하고 필요하면 응답한다.

두 에이전트를 같은 Workspace에 함께 배정하지 않는다 — 같은 폴더를 공유하면 한 에이전트가 다른 에이전트의 작업 맥락을 자기 것으로 착각하는 "인지적 중첩(cognitive overlap)"이 발생할 수 있다. Workspace 또는 worktree로 반드시 분리하는 것이 Antigravity의 권장 관행이다.

Antigravity CLI(agy)에서도 데스크톱의 Agent Manager 대신 터미널을 여러 개 띄워 같은 효과를 낼 수 있다 — 한 터미널에서 agy로 topic-a.txt 작업을, 다른 터미널에서 별도 agy 세션으로 topic-b.txt 작업을 동시에 진행한다(세션 간 병렬). 서로 다른 파일을 건드리는 한 두 세션은 충돌하지 않는다.

함께 보기: 4장 §1 레퍼런스 — 병렬 실행

Antigravity CLI (agy) 1.1.0+ · Antigravity 2.0 기준 | 2026년 7월 14일 작성
← 4장 §2-A Claude 중심 실습으로

4장 §2
Claude (A) Antigravity (B) Codex (C)