Cmd. /agents
v2.1.198 이후 서브에이전트 파일 생성·편집 방법을 안내하는 명령과 Agent View의 차이를 설명합니다.
핵심 요약
- 현재 버전에서는 subagent 관리 방법 안내
- 입력 위치·지원 조건을 확인한 뒤 아래 실행 예를 사용합니다.
역할
현재 버전에서는 subagent 관리 방법 안내
/agents사용 조건
| 항목 | 기준 |
|---|---|
| 입력 위치 | 실행 중인 CLI의 입력창 |
| 종류 | 내장 명령 |
| 상태 | 현재 공식 표 |
| 별칭 | — |
| 공식 최소 버전 | 명시되지 않음 |
| 검증 기준 | 2026-09-22 · Claude Code 2.1.278 |
v2.1.198+에서는 관리 안내를 출력합니다. 대화형 생성 화면은 v2.1.197 이하의 동작입니다.
사용 예
/agents안내를 확인한 뒤 다음처럼 일반 대화로 요청합니다.
프로젝트 .claude/agents/에 읽기 전용 코드 리뷰용 서브에이전트를 만들어줘.
변경 범위와 테스트 누락을 점검하고, 파일을 수정하지 않도록 설정해줘.생성된 frontmatter의 name, description, tools, model과 본문 지침을 검토한 뒤 해당 서브에이전트 사용을 요청합니다.
관련 명령 선택
| 명령어 | 역할 |
|---|---|
/agents | 정의 파일을 만들고 관리하는 방법 안내 |
claude agents | 백그라운드 세션을 모아 보고 관리 |
/tasks | 현재 대화의 백그라운드 작업 확인 |
/subtask <task> | 현재 대화 맥락을 상속한 하위 작업 위임 |
실행 결과와 유지 범위
현재 버전에서는 서브에이전트 관리 방법을 안내합니다. 실제 정의는 프로젝트 또는 사용자 agents 디렉터리의 파일로 관리합니다.
현재 /agents는 서브에이전트 관리 방법을 안내합니다. Claude에게 필요한 역할·도구·모델·저장 위치를 알려 정의 파일을 작성하게 하거나 직접 편집하세요.
v2.1.197 이하에서는 Running·Library 탭과 생성 마법사를 열었습니다. 이 화면을 전제로 한 과거 사용법은 현재 버전에 적용되지 않습니다.
서브에이전트 저장 위치
| 위치 | scope | 우선순위 |
|---|---|---|
| Managed settings의 agents | 조직 | 1 |
--agents JSON | 현재 세션 | 2 |
.claude/agents/ | 프로젝트 | 3 |
~/.claude/agents/ | 사용자 | 4 |
플러그인의 agents/ | 플러그인 활성 범위 | 5 |
프로젝트·사용자 agents 디렉터리가 세션 시작 때 이미 존재했다면 파일 변경을 몇 초 안에 감지합니다. 다음 경우에는 재시작해야 합니다.
- 세션 시작 후 처음 만든 agents 디렉터리
--add-dir또는/add-dir로 추가한 디렉터리의 agents 파일--disable-slash-commands로 시작한 세션
플러그인 서브에이전트의 hooks, mcpServers, permissionMode 필드는 무시됩니다. 필요한 경우 사용자·프로젝트 정의로 옮겨 검토하세요.
관련 기능: 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 상태를 관리합니다.
주의사항
백그라운드 세션 삭제와 서브에이전트 정의 파일 편집은 별개입니다. Agent View에서 세션을 삭제하기 전 해당 worktree에 보존할 변경이 있는지 확인하세요.
공식 근거
전체 명령 목록 · 검증 범위 · 이 명령의 변경 기록