Claude Code 서브에이전트 실전 가이드: 기사와 코드 작업을 안전하게 위임하기

Claude Code 작업이 커질 때 먼저 무너지는 것은 대개 모델 성능이 아닙니다. 작업을 어떻게 나누느냐입니다. 하나의 대화에서 조사, 글쓰기, 번역, 코드 수정, 검증, 리뷰를 모두 처리하면 컨텍스트가 빠르게 무거워집니다. 같은 파일을 여러 번 읽고, 로그가 대화를 채우며, 마지막에는 어떤 파일을 왜 바꿨는지 설명하기 어려워집니다.

서브에이전트는 이런 문제를 줄이기 위한 위임 도구입니다. 여기서 위임은 “알아서 해줘”가 아닙니다. 목표, 편집해도 되는 파일, 건드리면 안 되는 파일, 완료 조건, 반환 형식을 작은 계약처럼 넘기는 방식입니다. 이 계약이 있어야 병렬 작업이 중복 작업으로 변하지 않습니다.

이 글은 ClaudeCodeLab의 실제 기사 제작 흐름을 기준으로 설명합니다. 일본어 canonical 원고를 만들고, 10개 언어로 로컬라이즈하고, 프롬프트 템플릿을 확인하고, 게시 전 리뷰를 수행하는 흐름입니다. 같은 방식은 코드 변경, 문서화, 마이그레이션 계획, 릴리스 준비에도 그대로 적용할 수 있습니다.

서브에이전트란 무엇인가

서브에이전트는 메인 대화와 분리된 컨텍스트에서 움직이는 전문 작업자입니다. 컨텍스트는 Claude가 지금 볼 수 있는 작업 기억입니다. 대화, 읽은 파일, 명령 출력, 프로젝트 규칙, 중간 요약이 여기에 들어갑니다. 대량 검색이나 로그 분석처럼 중간 정보가 많은 일은 서브에이전트가 처리하고, 메인 대화에는 판단에 필요한 요약만 가져오는 편이 안전합니다.

공식 정보는 Claude Code의 Subagents, Memory, Slash commands를 확인하세요. 실무에서 중요한 점은 세 가지입니다. 서브에이전트는 격리된 컨텍스트로 시작하고, 프로젝트용 agent는 .claude/agents/에 둘 수 있으며, 서브에이전트가 너무 긴 결과를 반환하면 메인 대화 컨텍스트도 다시 소모됩니다.

용어	쉬운 설명
서브에이전트	조사, 구현, 번역, 리뷰를 맡는 전문 작업자
컨텍스트	Claude가 현재 보고 있는 작업 기억
disjoint write set	서로 겹치지 않는 편집 파일 범위
explorer	읽기 전용 조사 담당. 원칙적으로 수정하지 않음
worker	지정된 파일만 수정하는 실행 담당
handoff contract	범위, 금지 사항, 완료 조건, 반환 형식을 적은 작업 계약

언제 위임해야 하는가

서브에이전트는 많을수록 좋은 기능이 아닙니다. 작은 수정까지 위임하면 각 agent가 컨텍스트를 다시 모으느라 더 느려집니다. 기준은 “컨텍스트를 분리할 가치가 있는가”와 “편집 범위를 겹치지 않게 나눌 수 있는가”입니다.

작업	위임 적합도	이유
한 글을 10개 언어로 로컬라이즈	적합	언어별 파일이 분리되어 있고 검토 기준이 명확함
큰 코드베이스에서 기존 패턴 조사	적합	검색 결과 전체가 아니라 지도만 필요함
한 파일의 오탈자 수정	부적합	조율 비용이 작업보다 큼
인증 모듈 전반 리팩터링	조건부	explorer로 영향 범위를 먼저 확인해야 함
요구사항이 불명확한 새 기능	아직 이름	메인 대화에서 요구사항을 먼저 좁혀야 함

실무 기준은 간단합니다. 중간 출력이 많고, worker별 파일 범위를 명확히 제한할 수 있고, 결과를 표나 체크리스트로 받을 수 있을 때만 위임합니다.

핵심 패턴: explorer, worker, reviewer

큰 작업을 할 때는 여러 편집 agent부터 띄우지 않습니다. 먼저 explorer가 읽기 전용으로 조사합니다. 관련 파일, 기존 관례, 리스크, 권장 write set을 정리합니다. 그 다음 worker가 서로 다른 파일 범위를 수정합니다. 마지막으로 reviewer나 verification agent가 읽기 전용으로 결과를 확인합니다.

flowchart TD
  A["Main: goal and constraints"] --> B["Explorer: read only, map scope"]
  B --> C["Main: decide disjoint write sets"]
  C --> D["Worker: canonical article or code module"]
  C --> E["Worker: localized files or separate module"]
  D --> F["Reviewer: quality, metadata, verification"]
  E --> F
  F --> G["Main: final checks and handoff"]

이 순서를 지키면 가장 흔한 실패를 피할 수 있습니다. 즉, 여러 agent가 같은 파일을 읽고 같은 부분을 고치는 상황입니다.

사례 1: 다국어 기사 제작

ClaudeCodeLab 기사에서는 일본어 canonical 원고를 먼저 확정한 뒤 전체 내용을 로컬라이즈하는 방식이 안전합니다. canonical은 기준 원고입니다. 기준 원고가 얇으면 모든 번역도 얇아집니다. 반대로 기준 원고에 실전 예시, 실패 사례, 템플릿, CTA가 들어 있으면 각 언어도 내용의 깊이를 유지할 수 있습니다.

역할	편집 가능 파일	작업
ja-worker	site/src/content/blog/claude-code-subagent-patterns.mdx	기준 구조, 예시, 프롬프트, CTA 작성
western-locale-worker	blog-en, blog-es, blog-fr, blog-de, blog-pt	요약하지 않고 자연스럽게 로컬라이즈
asia-locale-worker	blog-zh, blog-ko, blog-hi, blog-id	독자에게 자연스러운 용어로 조정
review-agent	10개 slug 파일, 읽기 전용	frontmatter, 문자 깨짐, 링크, 코드 펜스, 게시 리스크 확인

번역 agent에 그대로 붙일 수 있는 프롬프트입니다.

Use a translation subagent for the assigned locale files only.

Source:
- Japanese canonical file: site/src/content/blog/claude-code-subagent-patterns.mdx

Allowed write set:
- site/src/content/blog-en/claude-code-subagent-patterns.mdx
- site/src/content/blog-es/claude-code-subagent-patterns.mdx

Rules:
- Do not summarize. Localize the full guide.
- Keep frontmatter valid and preserve heroImage.
- Use natural SEO terms for each language.
- Keep prompt templates copy-pasteable.
- Do not edit Japanese or other locale files.

Return:
- Files changed
- Localization choices
- Any terms that may need human review
- Checks performed

사례 2: 기사 속 코드 예시 검증

글을 쓰는 agent와 검증 agent는 역할을 분리하는 편이 좋습니다. writer는 설명과 흐름을 만들고, verification agent는 코드 블록을 추출해 문법, 경로, 복사 가능성을 확인합니다.

---
name: article-reviewer
description: Reviews ClaudeCodeLab articles for originality, implementation detail, SEO, and publication risk.
tools: Read, Grep, Glob
---

You review article drafts critically.
Check whether the draft has concrete examples, pitfalls, working prompts,
official links, internal links, and a clear CTA.
Return findings first, then a short pass/fail recommendation.

이 예시는 .claude/agents/article-reviewer.md 같은 파일로 둘 수 있습니다. name은 고유해야 하고, description에는 언제 이 agent를 써야 하는지 써야 합니다. 긴 운영 정책을 prompt 안에 모두 넣기보다, 장기 규칙은 CLAUDE.md나 팀 체크리스트에 두는 편이 좋습니다. 관련 내용은 컨텍스트 관리 가이드와 CLAUDE.md 베스트 프랙티스를 함께 보세요.

사례 3: 코드 수정을 겹치지 않는 write set으로 나누기

코드 작업에서도 같은 원칙을 씁니다. 예를 들어 블로그 사이트에서 기사 카드, OGP 이미지 생성, 관련 글 로직을 동시에 고쳐야 한다고 합시다. 서로 관련은 있지만 파일은 분리할 수 있습니다.

We will use three workers with disjoint write sets.

Worker A:
- May edit: site/src/components/BlogCard.astro
- Must not edit: layouts, pages, content files
- Goal: improve card metadata rendering only

Worker B:
- May edit: site/src/pages/og/[...slug].png.ts
- Must not edit: components or article files
- Goal: verify OGP title and hero behavior

Worker C:
- May edit: site/src/lib/relatedPosts.ts
- Must not edit: components, pages, content files
- Goal: improve related-post selection without changing routes

All workers return a handoff receipt with changed files, reasoning, tests, and risks.

“UI를 병렬로 개선해줘”는 약한 지시입니다. “이 파일만 고치고, 이 파일은 건드리지 말고, 이 증거를 반환하라”가 강한 지시입니다.

사례 4: 읽기 전용 리뷰와 검증

마지막 agent는 읽기 전용인 경우가 많습니다. reviewer는 독자 가치, SEO, 중복, 빠진 실패 사례를 봅니다. verification agent는 metadata, 링크, 명령, 코드 펜스, 빌드 리스크를 봅니다.

Use a review subagent in read-only mode.

Scope:
- Read only these 10 localized files for slug claude-code-subagent-patterns.
- Do not edit anything.

Review checklist:
- description is 120 characters or fewer
- updatedDate is 2026-06-02
- heroImage is retained
- each locale is a full localized article, not a thin summary
- at least 3 concrete use cases are present
- pitfalls and failure modes are concrete
- code fences are balanced
- official external links and internal links are present
- CTA is natural and relevant

Return findings by severity with file paths and line numbers where possible.

다국어 게시에서는 이 단계가 특히 중요합니다. 한 언어만 날짜가 낡았거나, 코드 펜스가 닫히지 않았거나, CTA가 빠진 일이 쉽게 생깁니다. 코드 변경에서는 Claude Code 코드 리뷰 체크리스트와 함께 쓰면 좋습니다.

복사해서 쓰는 위임 템플릿

메인 대화에서 먼저 사용하는 orchestration prompt입니다.

You are the orchestrator. Before using subagents, create a delegation plan.

Goal:
- [one sentence goal]

Hard constraints:
- Work only on: [exact files or directories]
- Do not edit: [out of scope]
- Preserve: [metadata, public API, routes, screenshots, etc.]
- Verification required: [commands or manual checks]

Ask explorer agents to read first. Do not start workers until write sets are disjoint.
For every worker, define:
- allowed write set
- forbidden files
- expected output
- done condition

Final response must include:
- changed files
- checks run
- remaining risks

읽기 전용 조사에는 이 템플릿을 사용합니다.

Use an explorer subagent in read-only mode.

Task:
- Map the current state of [feature/article/slug].
- Find existing conventions, related files, internal links, and quality gaps.

Rules:
- Do not edit files.
- Prefer search and targeted reads over full-directory dumps.
- Return only the useful summary, not raw command output.

Return:
- Files that matter
- Existing patterns to follow
- Risks or unclear requirements
- Suggested write sets for workers

수정 worker에는 이 템플릿을 사용합니다.

Use a worker subagent for this isolated edit.

Allowed write set:
- [file 1]
- [file 2]

Forbidden:
- Do not edit files outside the allowed write set.
- Do not stage, commit, push, deploy, or rewrite unrelated changes.
- If the task requires another file, stop and report why.

Implementation goal:
- [specific behavior or article quality outcome]

Return a handoff receipt:
- Files changed
- Summary of changes
- Commands or checks run
- Evidence of success
- Remaining risk

실패 패턴과 회피 방법

첫 번째 실패는 경계를 만들기 전에 병렬화하는 것입니다. “글을 더 좋게 만들어줘”라고 여러 worker에게 주면 모두 제목, 도입, 예시, CTA를 수정합니다. 결과는 많아 보이지만 통합 비용이 커집니다.

두 번째 실패는 반환 결과가 너무 긴 것입니다. 서브에이전트는 작업 중에는 메인 컨텍스트를 보호하지만, 최종 결과가 돌아오면 그 내용도 컨텍스트가 됩니다. 원시 로그 대신 결정, 표, 체크 결과만 요구하세요.

세 번째 실패는 handoff contract가 약한 것입니다. “자연스럽게 번역”만으로는 부족합니다. “요약 금지”, “frontmatter 유지”, “실패 사례 유지”, “현지 SEO 용어 사용”, “원어민 확인이 필요한 표현 반환”까지 써야 합니다.

네 번째 실패는 구현자가 자기 가정을 그대로 검증하게 하는 것입니다. reviewer에게는 의심하면서 읽고, 제약과 결과의 불일치를 먼저 찾으라고 지시합니다.

다섯 번째 실패는 agent 정의 파일이 언제 로드되는지 잊는 것입니다. .claude/agents/에 새 파일을 만든 뒤에는 새 세션에서 확인하는 편이 안전합니다. 재사용할 agent는 긴 일회성 prompt보다 짧은 파일 정의가 운영하기 쉽습니다.

컨텍스트 예산 규칙

서브에이전트가 컨텍스트를 아끼려면 반환량을 제한해야 합니다.

Context budget rule:
- Explorer returns at most 20 bullets and 1 table.
- Worker returns changed files, decisions, and checks only.
- Reviewer returns findings by severity, no full rewritten article.
- Logs longer than 80 lines must be summarized.
- If uncertainty remains, ask one focused question instead of dumping raw output.

산출물은 길어도 됩니다. 하지만 handoff는 짧아야 합니다. 둘을 섞으면 메인 대화가 원고, 번역 메모, 검증 로그로 금방 꽉 찹니다.

복사해서 만드는 읽기 전용 리뷰어

가장 안전한 첫 subagent는 읽기 전용 리뷰어입니다. 아래 스크립트는 .claude/agents/article-reviewer.md를 만듭니다. 초안을 읽고 위험을 지적할 수는 있지만 직접 수정하지 못하므로, 공개 전 품질 점검용으로 쓰기 좋습니다.

mkdir -p .claude/agents
cat > .claude/agents/article-reviewer.md <<'EOF'
---
name: article-reviewer
description: Reviews ClaudeCodeLab articles for originality, implementation detail, SEO, and publication risk.
tools: Read, Grep, Glob
---

Review the assigned files only. Do not edit.

Checklist:
- title and description match the search intent
- intro gives a concrete reader problem in the first three lines
- examples, pitfalls, official links, internal links, and CTA are present
- code fences are balanced and labeled
- the article is not a thin summary or duplicated from another page

Return:
- findings by severity
- pass/fail recommendation
- one highest-leverage fix
EOF

위임 체크리스트

# Subagent Delegation Checklist

## Before delegation
- [ ] Goal is one sentence.
- [ ] In-scope files are listed explicitly.
- [ ] Out-of-scope files and actions are listed explicitly.
- [ ] Explorer runs before worker when scope is unclear.
- [ ] Write sets do not overlap.

## During work
- [ ] Each worker edits only allowed files.
- [ ] Large outputs are summarized.
- [ ] Any need to expand scope is reported before editing.
- [ ] Prompts include done conditions.

## Review
- [ ] Reviewer runs in read-only mode.
- [ ] Metadata and links are checked.
- [ ] Code fences and commands are checked.
- [ ] Localization is full, not summarized.
- [ ] Remaining risks are written in the handoff.

실제로 적용해 본 결과

ClaudeCodeLab 기사 개선에서 가장 효과가 컸던 것은 번역 속도가 아니라 역할 분리였습니다. canonical 원고, 로케일 worker, 읽기 전용 reviewer를 나누자 “한 언어만 깊고 나머지는 요약”인 문제가 줄었습니다. 각 worker에게 요약 금지, CTA 유지, 검증 결과 반환을 명시하니 게시 전 리뷰도 훨씬 구체적이었습니다.

팀에 Claude Code를 도입한다면 서브에이전트를 마법 같은 자동화가 아니라 작업 설계 패턴으로 가르치는 것이 좋습니다. ClaudeCodeLab은 이런 위임 계약, 리뷰 기준, 컨텍스트 습관을 팀용 training과 product templates로 정리하고 있습니다.