/로 시작하는 특수 명령어를 사용하여 Claude Code 세션을 제어하는 방법을 제공합니다. 이러한 명령어는 SDK를 통해 전송되어 컨텍스트 압축, 컨텍스트 사용량 나열 또는 사용자 정의 명령어 호출과 같은 작업을 수행할 수 있습니다. 대화형 터미널 없이 작동하는 명령어만 SDK를 통해 전달할 수 있으며, system/init 메시지에 세션에서 사용 가능한 명령어가 나열됩니다.
사용 가능한 슬래시 명령어 발견
Claude Agent SDK는 시스템 초기화 메시지에서 사용 가능한 슬래시 명령어에 대한 정보를 제공합니다. 세션이 시작될 때 이 정보에 접근합니다:슬래시 명령어 전송
슬래시 명령어를 프롬프트 문자열에 포함하여 일반 텍스트처럼 전송합니다./compact와 같이 대화 기록에 작용하는 명령어는 작업할 이전 메시지가 필요하므로, 아래 예제에서는 먼저 질문을 한 다음 같은 대화에 대한 후속 명령어로 명령어를 전송합니다:
쿼리는 오류 결과로 끝날 수 있습니다. 예를 들어 작업이 완료되기 전에
maxTurns / max_turns 제한에 도달한 경우입니다. 최종 결과 메시지는 is_error: true를 가지며 success 대신 error_max_turns와 같은 오류 서브타입을 가집니다.해당 최종 결과 메시지를 생성한 후 SDK는 CLI 프로세스가 0이 아닌 코드로 종료되기 때문에 오류를 발생시킵니다.명령어가 제한에 도달할 수 있는 경우 TypeScript에서는 루프를 try/catch로 감싸거나 Python에서는 try/except로 감싸십시오. 단일 메시지 입력에 표시된 대로 하거나, 작업이 완료될 수 있도록 maxTurns를 충분히 높게 설정하십시오. Python에서는 Exception을 캐치하십시오: SDK는 오류 결과를 일반 Exception으로 표시합니다.일반적인 슬래시 명령어
/compact - 대화 기록 압축
/compact 명령어는 이전 메시지를 요약하면서 중요한 컨텍스트를 보존하여 대화 기록의 크기를 줄입니다. 압축을 수행하려면 최소 두 번의 이전 교환이 있는 기존 대화가 필요합니다. 이 예제는 먼저 대화를 진행한 후 압축을 수행하고 결과를 보고하는 compact_boundary 시스템 메시지를 읽습니다:
compact_boundary 메시지는 압축이 실행되었을 때만 도착합니다. 요약할 내용이 없으면 /compact는 대신 이유를 보고합니다. 실행은 여전히 success 결과로 끝나고, compact_boundary 메시지는 발생하지 않으며, 결과 텍스트에 메시지가 포함됩니다. 예를 들어 짧은 단일 교환 후 Not enough messages to compact.입니다. 새로운 일회성 query() 호출은 빈 컨텍스트로 시작하므로 이 패턴을 이전 턴이 있는 세션에서 사용하세요. 예를 들어 스트리밍 입력 모드에서 또는 세션을 재개할 때입니다./clear - 대화 컨텍스트 초기화
/clear 명령어는 대화를 빈 컨텍스트로 초기화하므로 이후의 프롬프트는 이전 대화 기록 없이 시작됩니다. 이전 대화는 디스크에 남아 있으며 세션 ID를 resume 옵션에 전달하여 돌아갈 수 있습니다.
이는 단일 연결을 통해 여러 프롬프트를 보내는 스트리밍 입력 모드에서 유용합니다. 일회성 query() 호출의 경우 각 호출은 이미 빈 컨텍스트로 시작하므로 /clear를 보내는 것은 실질적인 효과가 없습니다. 대신 새로운 query()를 시작하세요.
SDK의
/clear는 Claude Code v2.1.117 이상이 필요합니다. 이전 버전에서는 slash_commands에서 생략됩니다.사용자 정의 슬래시 명령어 만들기
기본 제공 슬래시 명령어를 사용하는 것 외에도 SDK를 통해 사용 가능한 자신만의 사용자 정의 명령어를 만들 수 있습니다. 사용자 정의 명령어는 서브에이전트가 구성되는 방식과 유사하게 특정 디렉토리의 마크다운 파일로 정의됩니다..claude/commands/ 디렉토리는 레거시 형식입니다. 권장되는 형식은 .claude/skills/<name>/SKILL.md이며, 이는 동일한 슬래시 명령어 호출(/name)과 Claude의 자율적 호출을 지원합니다. 현재 형식은 Skills를 참조하세요. CLI는 두 형식을 모두 계속 지원하며, 아래 예제는 .claude/commands/에 대해 정확합니다.파일 위치
사용자 정의 슬래시 명령어는 범위에 따라 지정된 디렉토리에 저장됩니다:- 프로젝트 명령어:
.claude/commands/- 현재 프로젝트에서만 사용 가능 (레거시;.claude/skills/선호) - 개인 명령어:
~/.claude/commands/- 모든 프로젝트에서 사용 가능 (레거시;~/.claude/skills/선호)
파일 형식
각 사용자 정의 명령어는 마크다운 파일이며:- 파일명(
.md확장자 제외)이 명령어 이름이 됩니다 - 파일 내용이 명령어의 기능을 정의합니다
- 선택적 YAML frontmatter가 구성을 제공합니다
기본 예제
프로젝트에.claude/commands 디렉토리가 없으면 생성한 후 .claude/commands/refactor.md를 생성합니다:
/refactor 명령어를 만듭니다.
Frontmatter 포함
.claude/commands/security-check.md 생성:
SDK에서 사용자 정의 명령어 사용
파일 시스템에서 정의되면 사용자 정의 명령어는 SDK를 통해 자동으로 사용 가능합니다:고급 기능
인수 및 플레이스홀더
사용자 정의 명령어는 플레이스홀더를 사용하여 동적 인수를 지원합니다:.claude/commands/fix-issue.md 생성:
Bash 명령어 실행
사용자 정의 명령어는 bash 명령어를 실행하고 출력을 포함할 수 있습니다:.claude/commands/git-commit.md 생성:
파일 참조
@ 접두사를 사용하여 파일 내용을 포함합니다:
.claude/commands/review-config.md 생성:
네임스페이싱을 통한 조직화
더 나은 구조를 위해 명령어를 하위 디렉토리에 구성합니다:실용적인 예제
풀 리퀘스트 리뷰 명령어
.claude/commands/review-pr.md를 생성합니다:
Claude Code에는 번들된
code-review 및 verify 스킬이 포함되어 있습니다. 예를 들어 .claude/commands/code-review.md와 같이 사용자 정의 명령어의 이름을 이 중 하나로 지정하면, 사용자 정의 명령어가 번들된 스킬을 가리고 slash_commands는 이름을 한 번만 나열합니다.테스트 러너 명령어
.claude/commands/test.md 생성:
참고 항목
- Slash Commands - 완전한 슬래시 명령어 문서
- SDK의 서브에이전트 - 서브에이전트를 위한 유사한 파일 시스템 기반 구성
- TypeScript SDK 참조 - 완전한 API 문서
- SDK 개요 - 일반 SDK 개념
- CLI 참조 - 명령줄 인터페이스