핵심 정리

/agents

.claude/agents/reviewer.md
~/.claude/agents/researcher.md

name + description + tools + prompt

구성 방식

subagent는 별도 맥락에서 일하는 작업자다

Claude Code의 subagent는 메인 대화와 분리된 컨텍스트에서 특정 작업을 처리합니다. 큰 탐색 결과, 로그, 파일 내용이 메인 세션을 오염시키지 않도록 따로 읽고 요약만 돌려주는 구조입니다. 코드 리뷰, 테스트 조사, 보안 점검처럼 반복되는 관점이 있다면 subagent로 분리하기 좋습니다.

메인 세션
  -> 목표와 최종 판단 유지

subagent
  -> 탐색, 리뷰, 조사, 반복 작업 담당
  -> 결과 요약을 메인 세션으로 반환

모든 작업을 subagent로 보내는 것이 목표는 아닙니다. 단일 파일 수정처럼 맥락이 작고 판단이 이어져야 하는 작업은 메인 세션에서 처리하는 편이 단순합니다.

/agents가 기본 관리 표면이다

subagent는 Markdown 파일로 직접 만들 수 있지만, Claude Code 안에서는 /agents가 기본 관리 표면입니다. 생성, 수정, 삭제, 실행 중인 agent 확인, tools 권한 조정을 한 곳에서 처리할 수 있습니다.

---
name: code-reviewer
description: Reviews code for correctness, security, and maintainability.
tools: Read, Grep, Glob
model: sonnet
---

Review changed files and report concrete findings with file references.
Do not edit files.

description은 Claude가 언제 이 subagent를 쓸지 판단하는 핵심 신호입니다. "코드 리뷰 전문가"처럼 넓은 설명보다 "변경된 파일에서 correctness, security, maintainability 문제를 찾을 때 사용"처럼 호출 조건이 보이는 설명이 좋습니다.

project와 user 범위는 공유 기준으로 나눈다

프로젝트 전용 subagent는 .claude/agents/에 두고 저장소에 커밋할 수 있습니다. 팀이 같은 리뷰 기준이나 테스트 조사 기준을 공유해야 한다면 project 범위가 맞습니다. 개인적으로 여러 프로젝트에서 쓰는 agent는 ~/.claude/agents/에 두면 됩니다.

.claude/agents/
  -> 이 저장소 팀 규칙
  -> 커밋 가능

~/.claude/agents/
  -> 개인 작업 습관
  -> 다른 프로젝트에도 적용

같은 이름의 subagent가 여러 범위에 있으면 우선순위가 생기므로, 팀에서 쓰는 이름은 충돌하지 않게 짧고 명확하게 정하는 편이 좋습니다.

언제 나눌까

주의할 점

description이 모호하면 Claude가 엉뚱한 시점에 subagent를 호출하거나, 호출하지 않아야 할 작업까지 위임할 수 있습니다. 이름보다 호출 조건과 금지 조건을 더 구체적으로 적어야 합니다.