Quick Reference
subagent는 main session의 대화 history를 그대로 받지 않는 별도 context 작업자입니다. 독립적인 조사·리뷰처럼 결과를 요약해 돌려받으면 되는 일을 맡기고, 잦은 왕복·같은 파일의 미세 조정·최종 통합은 main session에 남깁니다. background subagent는 더 좁은 built-in tool 집합으로 실행되지만, 권한 요청은 현재 main session으로 올라옵니다.
| 작업 성격 | 먼저 선택 | context·권한 경계 |
|---|---|---|
| 짧은 수정과 대화형 조정 | main session | 지금까지의 대화 context를 유지합니다. |
| 긴 탐색·로그 조사·독립 리뷰 | 읽기 전용 subagent | 새 context에서 시작하고 요약만 반환합니다. |
| 결과를 즉시 받아 다음 판단을 해야 함 | foreground subagent | main conversation이 기다리며 승인 요청도 즉시 처리합니다. |
| 독립적으로 오래 조사·검사 | background subagent | 작은 built-in tool 집합으로 실행되고 권한 요청은 main session에 표시됩니다. |
| 서로 다른 파일의 병렬 구현 | subagent + worktree | context 격리와 파일 격리는 별도입니다. |
---
name: code-reviewer
description: "변경된 파일의 correctness와 보안 위험을 읽기 전용으로 검토할 때 사용합니다."
tools: Read, Grep, Glob, Bash(git diff *)
---
파일 위치와 근거가 있는 finding만 보고합니다. 파일을 수정하지 않습니다.무엇이 전달되는가
일반 named subagent는 새 context window에서 시작합니다. main session의 전체 history, 이미 호출한 skill, 읽어 둔 파일은 자동으로 보이지 않습니다. Claude가 만든 delegation prompt, agent 자신의 prompt와 환경 정보, CLAUDE.md 계층, parent session 시작 시점의 Git status snapshot은 전달됩니다. main session의 auto memory와 output style은 전달되지 않습니다. built-in Explore와 Plan agent는 CLAUDE.md와 Git status도 건너뛰므로, 반드시 지켜야 하는 좁은 탐색 규칙은 위임 prompt에도 다시 적습니다.
subagent도 기본적으로 하위 subagent를 만들 수 있으며, 기본 깊이는 main session 아래 세 단계입니다. 다만 모든 위임을 계층화하면 결과 경로와 tool 범위가 불투명해지므로, 주 작업을 나눠야 할 때만 사용합니다. 읽기 전용 reviewer처럼 하위 작업을 만들 필요가 없는 agent는 Agent를 tools에서 빼거나 disallowedTools에 넣습니다. main session이 결과를 받았다고 해서 그 결과가 검증된 사실이 되는 것은 아니므로, 파일·명령·인용을 다시 확인합니다.
main: "현재 diff의 test 위험만 찾아 줘. 파일은 수정하지 마."
-> reviewer: 새 context에서 diff와 관련 파일 조사
-> main: finding의 파일·행·재현 조건을 다시 확인
-> main: 수정·테스트·통합을 결정foreground와 background
foreground subagent는 완료될 때까지 main conversation을 막고, 필요한 permission prompt를 사용자에게 전달합니다. background subagent는 main이 계속 일할 수 있게 하며, permission prompt도 main session에 표시합니다. 다만 background에는 foreground보다 작은 built-in tool 집합이 적용되므로, 같은 agent 정의라도 실행 위치에 따라 가능한 도구가 달라질 수 있습니다. 이 차이는 속도 옵션이 아니라 실행 가능 작업의 범위를 바꿉니다.
| 상황 | foreground | background |
|---|---|---|
| 권한을 새로 승인해야 함 | 적합 | main session에서 승인 가능 |
| 결과를 기다린 뒤 다음 판단 | 적합 | 완료 알림 후 검토 |
| 긴 읽기 전용 조사 | 가능 | 적합 |
| 파일 수정·외부 전송 | 사용자 승인과 ownership 필요 | tool 축소·공유 working tree·승인 대상을 함께 확인 |
| 결과가 매우 김 | main context 부담 | 요약·산출물 형식을 미리 제한 |
@ mention은 특정 subagent를 한 작업에 실행하도록 지정하고, --agent <name>은 main session 자체를 그 agent의 system prompt·tool 제한·model로 시작합니다. 같은 이름이 plugin과 local 범위에 겹치면 scoped name으로 구분합니다.
자주 틀리는 부분
subagent의 도구 제한을 보안 경계로 과신하면 안 됩니다. background 작업도 권한 요청은 올리지만 tool 집합이 축소되고, worktree가 없으면 여러 작업자가 같은 working tree를 수정할 수 있습니다. 읽기 전용 agent부터 시작하고, 쓰기 작업은 파일 ownership·branch·통합 담당자를 정한 뒤 맡깁니다.
권장 분업
1. main session이 목표·제외 범위·완료 조건을 쓴다.
2. subagent는 독립 조사와 근거 수집을 한다.
3. main session이 결과를 재검증하고 수정·테스트를 결정한다.
4. 병렬 수정은 worktree와 파일 ownership까지 분리한다.참고 링크
2 sources