Cmd. /agents
서브에이전트 설정을 생성·편집·삭제하는 탭형 관리 인터페이스를 여는 명령
핵심 요약
/agents는 서브에이전트 설정을 관리하는 탭형 인터페이스(Running·Library 탭)를 열며, 백그라운드 세션을 다루는 Agent View(claude agents)와는 다른 기능입니다./agents인터페이스로 만든 서브에이전트는 즉시 사용 가능하지만, 디스크 파일을 직접 편집하면 세션 재시작이 필요합니다.- 서브에이전트 scope 우선순위는 managed →
--agents→ 프로젝트.claude/agents/→~/.claude/agents/→ 플러그인 순입니다. - 플러그인 서브에이전트는 보안상
hooks·mcpServers·permissionModefrontmatter 필드를 지원하지 않습니다.
명령어 원본 선언
/agents공식 설명 요약
공식 문서의 한 줄 정의는 "Manage agent configurations"(서브에이전트 설정 관리)입니다.
/agents는 서브에이전트(subagent) 설정을 관리하는 탭형 인터페이스를 엽니다. 공식 문서 기준으로 탭은 두 개입니다.
- Running 탭: 현재 살아 있는 서브에이전트를 보여주며, 열거나(open) 중지(stop)할 수 있습니다.
- Library 탭: 사용 가능한 모든 서브에이전트(내장·user·project·plugin)를 보고, 새 서브에이전트를 가이드형 설정 또는 Claude 생성으로 만들고, 기존 설정과 도구 접근 권한을 편집하고, 커스텀 서브에이전트를 삭제하며, 동일 이름이 중복될 때 어떤 것이 활성인지 확인합니다.
공식 문서는 /agents를 서브에이전트를 만들고 관리하는 권장 방법으로 안내합니다. /agents 인터페이스로 만든 서브에이전트는 세션을 재시작하지 않아도 바로 쓸 수 있습니다(반면 디스크의 파일을 직접 고치면 세션을 재시작해야 반영됩니다).
/agents 명령과 Agent View는 다른 기능입니다
/agents(슬래시 명령)는 서브에이전트 설정을 관리합니다. 반면 백그라운드 세션을
한 화면에서 띄우고 관리하는 Agent View는 셸에서 claude agents를 실행하거나
세션 안에서 /background(별칭 /bg)를 쓰거나 빈 입력에서 ←를 눌러 엽니다.
실행/입력 대기/완료 세션, attach·peek·rename·pin·stop/delete, 디렉터리 grouping,
PR 필터, dispatch 문법은 모두 claude agents(Agent View)의 기능이며,
/agents 슬래시 명령의 기능이 아닙니다. 자세한 내용은 아래 "관련 기능: Agent View" 절을 보세요.
최소 지원 버전
/agents슬래시 명령은 초기부터 제공된 내장 명령으로, 공식 명령 목록에 별도 최소 버전 표시가 없습니다.- 단, 함께 쓰는 일부 기능에는 버전 요건이 있습니다.
- Agent View(
claude agents)는 research preview이며 v2.1.139 이상이 필요합니다. - 포크 서브에이전트(
CLAUDE_CODE_FORK_SUBAGENT)는 v2.1.117 이상이 필요합니다.
- Agent View(
사용법
/agents/agents는 인자를 받지 않으며 실행하면 곧바로 탭형 관리 인터페이스가 열립니다. 인터페이스 안에서 다음을 할 수 있습니다.
- Library 탭에서 Create new agent를 선택해 새 서브에이전트를 만듭니다(가이드형 설정 또는 Generate with Claude).
- 저장 위치(scope)를 고릅니다: Personal(
~/.claude/agents/, 모든 프로젝트) 또는 프로젝트(.claude/agents/). - 도구 접근(예: read-only tools만), 모델, 색상, 메모리 scope를 설정합니다.
- 설정 요약에서
s또는Enter로 저장하거나,e로 저장 후 에디터에서 파일을 엽니다.
좋은 사용 예
/agents로 코드 리뷰 전용 서브에이전트를 만들고 read-only 도구만 부여- Library 탭에서 기존 서브에이전트의 도구 권한·모델을 편집
- Running 탭에서 지금 실행 중인 서브에이전트를 확인하고 불필요한 인스턴스를 stop
서브에이전트 저장 위치(scope)
| 위치 | scope | 우선순위 | 생성 방법 |
|---|---|---|---|
| Managed settings | 조직 전체 | 1 (최상) | managed settings 배포 |
--agents CLI 플래그 | 현재 세션 | 2 | Claude Code 실행 시 JSON 전달 |
.claude/agents/ | 현재 프로젝트 | 3 | /agents 또는 수동 |
~/.claude/agents/ | 모든 프로젝트 | 4 | /agents 또는 수동 |
플러그인 agents/ 디렉터리 | 플러그인 활성 범위 | 5 (최하) | 플러그인 설치 |
같은 이름이 여러 위치에 있으면 우선순위가 높은 위치가 이깁니다.
비슷한 명령어 추천
| 명령어 | 차이점 | 언제 선택 |
|---|---|---|
/agents | 서브에이전트 설정 생성·편집·삭제 | 서브에이전트를 정의/관리할 때 |
/background(별칭 /bg) | 현재 세션을 백그라운드 에이전트로 분리(Agent View) | 터미널을 비우고 세션을 계속 돌릴 때 |
/tasks | 현재 세션의 백그라운드 작업 목록 | 진행 중인 백그라운드 작업 확인 |
/batch <지시> | 대규모 변경을 5~30개 단위로 분해해 worktree별 병렬 실행(번들 Skill) | 코드베이스 전반 병렬 작업 |
관련 기능: Agent View (claude agents)
아래 내용은 /agents 슬래시 명령이 아니라 Agent View(셸의 claude agents, 또는 세션의 /background·/bg·←)에 해당합니다. 여러 백그라운드 세션을 한 화면에서 dispatch하고 상태를 추적하는 기능이며, **research preview(v2.1.139+)**입니다.
Agent View dispatch 문법
| 입력 | 동작 |
|---|---|
<agent-name> <prompt> | 첫 단어가 커스텀 서브에이전트 이름이면 그 서브에이전트를 세션의 main agent로 실행 |
@<agent-name> | prompt 중간에서도 서브에이전트를 명시 선택 |
@<repo> | Agent View를 연 상위 디렉터리의 특정 repository로 dispatch |
/<command> | skill 또는 slash command를 prompt로 dispatch |
! <command> | 모델 호출 없이 shell command를 background job으로 실행 |
#<number> 또는 PR URL | 해당 PR을 이미 처리 중인 session이 있으면 그 session 선택 |
Shift+Enter | dispatch 후 즉시 attach |
claude agents
claude --bg --agent code-reviewer "review PR 1234"
claude --bg --exec 'pytest -x'Agent View 관련 변경 이력
v2.1.143: background session의 worktree isolation을 끄는worktree.bgIsolation: "none"설정이 추가되었습니다.v2.1.142~v2.1.143:claude agents가--add-dir,--settings,--mcp-config,--plugin-dir,--permission-mode,--model,--effort,--dangerously-skip-permissions를 받아 dispatch session 기본값을 설정합니다(--allow-dangerously-skip-permissions는 v2.1.143+).v2.1.141:claude agents --cwd <path>로 특정 디렉터리 하위 세션만 보기.v2.1.139: Agent View가 research preview로 추가되었습니다.claude agents로 모든 session의 working/needs input/completed 상태를 관리합니다.
활용 사례
- 조사 전용·리뷰 전용 서브에이전트를
/agents로 표준화해 팀과 공유(프로젝트 scope를 버전 관리에 커밋) - read-only 도구만 가진 리뷰어 서브에이전트를 만들어 안전한 위임 경계 설정
- (Agent View) 대규모 리팩터링에서 파일군별 담당을 백그라운드 세션으로 분리해 병렬 진행
- (Agent View) 테스트·빌드·long-running shell command를 row로 띄우고 attach 없이 관찰
주의사항
/agents는 서브에이전트 설정 관리 전용입니다. 실행 중인 백그라운드 세션을 관리하려면claude agents(Agent View)나/tasks를 쓰세요.- 디스크의 서브에이전트 파일을 직접 고치면 세션 시작 시점에만 로드되므로 재시작해야 합니다.
/agents인터페이스로 만든 서브에이전트는 곧바로 반영됩니다. - 한 scope 안에서 두 파일이 같은
name을 선언하면 경고 없이 하나만 남고 나머지는 버려집니다.name은 트리 전체에서 고유하게 유지하세요. - 플러그인 서브에이전트는 보안상
hooks,mcpServers,permissionModefrontmatter 필드를 지원하지 않습니다(로드 시 무시됨). - (Agent View) session을 delete하면 Claude가 만든 worktree도 삭제될 수 있습니다. 보존할 변경은 먼저 merge/push/commit하세요.
worktree.bgIsolation: "none"을 쓰면 background session이 working copy를 직접 편집하므로 worktree가 불가능한 repo에만 제한적으로 쓰세요.
출처
- Claude Code Docs — Commands: https://code.claude.com/docs/en/commands
- Create custom subagents: https://code.claude.com/docs/en/sub-agents
- Manage multiple agents with agent view: https://code.claude.com/docs/en/agent-view