Claude Code 상세 사용법 13: 서브에이전트로 컨텍스트 분리하기 | DAKER 커뮤니티

Claude Code 상세 사용법 13: 서브에이전트로 컨텍스트 분리하기

Claude Code 공식 Subagents 문서는 서브에이전트를 "특정 작업을 처리하는 전문 AI assistant"로 설명한다. 핵심은 멋진 역할극이 아니라 컨텍스트 절약이다. 로그, 검색 결과, 후보 파일처럼 본 대화에 오래 남길 필요가 없는 재료는 별도 컨텍스트에서 읽게 하고, 본 세션에는 요약과 근거만 돌려받는다.

아래 Mermaid는 본 세션과 서브에이전트 사이의 책임 분리를 나타낸다. 본 세션은 목표와 결정권을 유지하고, 서브에이전트는 넓은 탐색과 근거 수집을 짧은 보고서로 되돌리는 구조다.

1. 위임할 일과 남길 일을 나눈다

서브에이전트에 잘 맞는 일은 범위가 넓지만 독립적인 조사다.

반대로 최종 제품 판단, 사용자 경험 결정, 실제 패치 방향 선택은 본 세션에 남기는 편이 낫다. 서브에이전트는 결정을 대체하는 존재가 아니라 조사 비용을 줄이는 역할이다.

2. description이 라우터다

공식 문서 기준으로 서브에이전트 파일은 Markdown frontmatter와 본문 프롬프트로 구성된다. 필수 필드는 name과

5. 결과는 짧고 검증 가능해야 한다

좋은 서브에이전트 보고서는 길지 않다.

Use the review-risk-scanner agent.
Return only:
1. top 5 risks
2. exact files and evidence
3. tests or commands to verify
4. assumptions

이렇게 받으면 본 세션은 넓은 탐색을 다시 읽지 않고 바로 결정할 수 있다.

Senior takeaway: Claude Code 서브에이전트는 "AI를 여러 명으로 늘리는 기능"보다 "컨텍스트와 권한을 분리하는 설계 도구"에 가깝다. 반복 조사 역할을 작게 정의하고, read-only 권한과 보고 형식을 고정하면 바이브코딩의 대화 품질이 오래 유지된다.description이다. 특히 description은 Claude가 언제 이 에이전트에 위임할지 판단하는 기준이므로 "좋은 코드리뷰어"보다 "변경 후 보안, 테스트 누락, 위험 파일을 읽기 전용으로 점검할 때 사용"처럼 조건을 써야 한다.

---
name: review-risk-scanner
description: 변경된 파일을 읽기 전용으로 검토해 보안, 테스트 누락, 회귀 위험을 찾을 때 사용
tools: Read, Glob, Grep
model: sonnet
---

본문에는 보고 형식을 고정한다.

파일별 위험, 근거, 신뢰도, 다음 검증 명령만 보고한다.
수정 제안은 하되 파일은 편집하지 않는다.
모르는 내용은 추측하지 말고 확인할 명령을 남긴다.

3. 도구 권한은 좁게 시작한다

서브에이전트는 기본적으로 본 세션에서 가능한 도구와 MCP 도구를 상속할 수 있다. 그래서 처음에는 read-only 도구만 주는 편이 안전하다. 코드 리뷰, 조사, 문서 점검 에이전트는 Read, Glob, Grep만으로도 충분한 경우가 많다. Bash가 필요하면 허용 명령을 좁히고, 수정이 필요하면 본 세션에서 패치를 적용한다.

4. 범위를 프로젝트와 사용자로 나눈다

프로젝트 전용 역할은 .claude/agents/에 두면 팀과 함께 버전 관리할 수 있다. 여러 프로젝트에서 반복해서 쓰는 개인 역할은 ~/.claude/agents/에 둔다. 공식 Subagents 문서에 따르면 같은 이름이 겹치면 우선순위가 적용되므로 name은 전역적으로 알아보기 쉽게 짓는 것이 좋다.

Redirecting to Claude Code 상세 사용법 13: 서브에이전트로 컨텍스트 분리하기 | DAKER 커뮤니티...