02-구조

02. 구조 — 파일 형식과 위임 트리거

파일 형식

서브에이전트는 마크다운 + YAML frontmatter다.

---
name: code-reviewer
description: |
  Reviews recently changed files for bugs, design issues, and missing tests.
  Use after edits to provide a second opinion. Use proactively if the user
  asks "is this safe to merge".
model: claude-haiku-4-5
tools: ["Read", "Grep", "Glob", "Bash(git diff*)", "Bash(pnpm test*)"]
---

You are a senior code reviewer. Your job is to find bugs, not to praise.

## How to review
1. List changed files with `git diff --name-only origin/main...HEAD`.
2. For each file, read and look for: null safety, error handling, race conditions, missing tests.
3. Run `pnpm test` if tests exist for the touched files.

## Output
- 🔴 Blocking: <bug>
- 🟡 Should fix: <issue>
- 🟢 Nice to have: <suggestion>

Do not approve. Always end with "Awaiting human decision."

핵심 필드:

• name — 위임 시 부르는 이름. /agents 인터페이스에서도 보임.
• description — 부모가 위임할지 결정하는 트리거. “Use when …” / “Use after …” 패턴.
• model — Haiku로 비용 절감, Opus로 정확도 우선.
• tools — 화이트리스트. 메인보다 좁아야 한다.

위임 트리거

부모 에이전트는 description을 본다. 정확성이 곧 위임 정확성이다. 잘못된 description의 결과:

• 너무 모호 → 위임 안 됨, 또는 엉뚱한 상황에 위임됨.
• 너무 구체 → 거의 안 발화, 사람이 매번 이름을 호출.

/agents 인터페이스

> /agents

이 슬래시 명령은 GUI를 띄워 새 에이전트를 만들거나 편집한다. 처음엔 손으로 .md 파일을 적기보다 /agents로 만드는 게 안전.

위치

스코프	경로
프로젝트	.claude/agents/이름.md
사용자	~/.claude/agents/이름.md

프로젝트 스코프가 우선. 같은 이름이면 프로젝트가 사용자 정의를 가린다.

중첩 금지

서브에이전트는 다른 서브에이전트를 띄울 수 없다. 그래서 Plan 서브에이전트가 Explore를 호출하는 식의 구조는 불가능. 더 복잡한 협업이 필요하면 agent teams(공식 문서의 별도 개념) 또는 OMC /team 패턴을 본다.