4장 §1-A

Sub-Agent Usage Details — Claude-Focused

Claude Code / Claude Desktop App에서 서브에이전트를 정의하고, 호출하고, 병렬·자동화 단위로 확장하는 방법을 Claude 계열에 한정해 정리한 상세 문서 | 공통 개념은 4장 §1 레퍼런스에서, Antigravity 계열은 4장 §1-B Antigravity 중심에서 다룬다.

대상 버전Claude Code / Claude Desktop App 2026-07 릴리스 — Antigravity 대응은 §1-B 참조

참조 문서 URLcode.claude.com/docs/en/sub-agents

문서 수집일2026-07-14

버전 확인 방법Claude Code/App: claude --version

1. 서브에이전트 정의하기

Claude Desktop App과 Claude Code는 프로젝트 폴더 아래에 마크다운 파일 하나로 서브에이전트 하나를 미리 정의한다. Claude Desktop App과 Claude Code는 같은 파일을 공유한다 — 둘 다 .claude/agents/*.md를 완전히 같은 방식으로 인식한다.

Claude Desktop App .claude/agents/*.md

프로젝트 루트의 .claude/agents/ 폴더에 마크다운 파일을 두면 Claude Desktop App에서도 자동으로 커스텀 서브에이전트로 인식된다. name이 나중에 subagent_type으로 참조하는 식별자가 된다. Claude Code(CLI)에서도 완전히 같은 파일이 완전히 같은 방식으로 동작한다 — 둘은 같은 서브에이전트 정의 포맷을 공유한다.

---
name: reviewer
description: 텍스트 파일의 오탈자와
  논리적 허점을 검토한다.
tools: Read, Grep
model: sonnet
---

너는 리뷰어 역할이다. 주어진 파일을
읽고 개선점을 목록으로 정리해 보고한다.

Claude Code (CLI) — Claude Desktop App과 동일한 .claude/agents/*.md

Claude Desktop App에서 쓴 것과 완전히 같은 .claude/agents/*.md 파일을 그대로 인식한다. Desktop App과 CLI 사이에 서브에이전트 정의 방식의 차이는 없다.

frontmatter 필드	Claude Desktop App / Claude Code (.claude/agents)
`name`	필수. `subagent_type` 값과 일치해야 호출 가능
`description`	이 에이전트가 언제 쓰이는지 설명, 자동 트리거 판단에 참고됨
`tools`	사용 가능한 툴 목록, 생략 시 기본 세트 상속
`model`	`sonnet` / `opus` / `haiku` 등 별칭 지정

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

Claude Desktop App과 Claude Code 모두 Agent 툴(문서에서는 Task 툴로도 불림)을 호출해 별도의 컨텍스트를 가진 서브에이전트를 띄운다.

Claude Desktop App Agent(Task) 툴

Claude Desktop App에서도 메인 세션은 Agent 툴(문서에서는 Task 툴로도 불림)을 호출해 별도의 컨텍스트를 가진 서브에이전트를 띄운다. 서브에이전트는 메인 세션의 대화 기록을 보지 못하므로, prompt에 필요한 배경을 자족적으로 담아야 한다. Claude Code(CLI)도 같은 Agent/Task 툴을 그대로 쓴다 — 채팅창에 자연어로 요청하면 내부적으로 아래와 같은 형태로 호출된다.

Agent(
  description   = "인증 모듈 리뷰",
  prompt         = "src/auth/login.ts의 세션
    만료 처리 로직을 검토하고 버그를 찾아줘.",
  subagent_type  = "reviewer"
)

Claude Code (CLI) — Claude Desktop App과 동일한 Agent(Task) 툴

Claude Desktop App과 완전히 같은 Agent/Task 툴 호출 방식이다. 터미널에서 자연어로 요청하면 동일한 방식으로 서브에이전트가 스폰된다.

3. 병렬 실행

Claude 계열은 두 가지 방식으로 병렬 실행을 지원한다.

Claude Desktop App Agent Teams — in-process

Claude Desktop App에서도 실험적 기능인 Agent Teams를 켜면 여러 팀메이트가 병렬로 작업한다. 다만 Desktop App에서는 teammateMode: in-process만 쓸 수 있고, 일부 키보드 내비게이션(Shift+Down 등)이 제한된다. Claude Code(CLI)에서도 같은 in-process 모드가 그대로 동작하며, CLI에서는 추가로 tmux 분할 창을 쓰는 tmux 모드도 고를 수 있다.

같은 디렉터리·Workspace에서 여러 에이전트를 동시에 돌리면 "인지적 중첩(cognitive overlap)"이 발생할 수 있다 — 한 에이전트가 같은 폴더에서 작업 중인 다른 에이전트의 결과를 자기 작업 맥락으로 착각(hallucination)하는 문제다. 작업 디렉터리나 worktree로 에이전트를 분리하는 것이 권장 관행이다.

Claude Code (CLI) — 한 메시지에 여러 Agent 호출

서로 의존성이 없는 작업이 여러 개 있다면, 한 메시지 안에 Agent 호출을 여러 개 나란히 담아 동시에 실행할 수 있다. Claude Code는 이 호출들을 병렬로 디스패치한다.

Agent(description="API 문서 초안 작성",
  prompt="...", subagent_type="writer")
Agent(description="테스트 커버리지 점검",
  prompt="...", subagent_type="reviewer")

항목	Claude Desktop App	Claude Code (CLI)
병렬 실행 단위	Agent Teams (in-process만)	한 메시지 내 다중 Agent 호출 / Agent Teams(in-process + tmux)

4. 자동화/훅

Claude 계열에서 자동화·훅의 차이점은 App과 Code 사이에 있다.

Claude Desktop App — 훅 미발화

.claude/settings.json에 PostToolUse/TeammateIdle/TaskCompleted 훅을 정의해도 Claude Desktop App에서는 자동으로 발화하지 않는다. 훅이 하던 일(예: 감사 스크립트 실행)은 세션이 끝난 뒤 수동으로 실행해야 한다. Claude Code(CLI)에서는 같은 설정 파일의 훅이 이벤트에 맞춰 자동으로 발화한다 — 자동화 게이트가 필요한 팀은 이 지점에서 명령줄 인터페이스(CLI)를 선택하는 것이 합리적이다.

Claude Code (CLI) — 훅 자동 발화

.claude/settings.json의 PostToolUse/TeammateIdle/TaskCompleted 훅이 파일 저장·작업 완료 같은 이벤트에 맞춰 자동으로 실행된다.

{
  "hooks": {
    "PostToolUse": [
      { "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "bun scripts/audit.ts" }] }
    ]
  }
}

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

참고 링크

Claude Code/App 2026-07 기준 | 2026년 7월

← 이전

4장 §1 · 레퍼런스

4장 §1

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

4장 §2-A · 실습