커맨드 시스템

사용자가 /로 시작하는 입력을 하면 커맨드 시스템이 활성화됩니다. Claude Code의 커맨드 시스템은 단순한 디스패치 테이블이 아닙니다 — 3가지 실행 전략, 동적 등록, 가용성 게이팅, 캐시 관리를 포함하는 완전한 프레임워크입니다.

커맨드 시스템의 핵심 구성요소:

• CommandBase: 모든 커맨드의 기본 계약 (11개 필드)
• 3가지 실행 타입: local, local-jsx, prompt
• 등록 파이프라인: 정적 → 동적 → 필터
• 가용성 게이팅: 컨텍스트에 따른 커맨드 활성화/비활성화

local 커맨드

local 커맨드는 순수 TypeScript 함수로 실행됩니다. REPL 상태를 직접 변경하거나, 설정을 수정하거나, 즉각적인 부수 효과를 발생시킵니다. AI 모델 호출이 필요 없는 작업에 사용됩니다.

// local 커맨드: 즉시 실행, 모델 호출 없음
const clearCommand: LocalCommand = {
  type: 'local',
  name: 'clear',
  description: '대화 기록을 초기화합니다',
  execute(context) {
    context.clearConversation()
    return { success: true }
  }
}

local-jsx 커맨드

local-jsx 커맨드는 React 컴포넌트를 반환합니다. 대화상자, 설정 화면, 인터랙티브 위자드 등 UI가 필요한 커맨드에 사용됩니다. 반환된 JSX는 Ink 렌더링 엔진을 통해 터미널에 표시됩니다.

// local-jsx 커맨드: React 컴포넌트 반환
const settingsCommand: LocalJsxCommand = {
  type: 'local-jsx',
  name: 'settings',
  description: '설정 화면을 표시합니다',
  render(context) {
    return <SettingsDialog onClose={context.dismiss} />
  }
}

prompt 커맨드

prompt 커맨드는 사용자 입력을 AI 모델에 전달하기 전에 프롬프트를 변환합니다. 사용자가 입력한 내용에 시스템 프롬프트를 추가하거나, 특정 컨텍스트를 주입하거나, 모델의 동작을 조정합니다.

// prompt 커맨드: 사용자 입력을 프롬프트로 변환
const reviewCommand: PromptCommand = {
  type: 'prompt',
  name: 'review',
  description: '코드 리뷰를 수행합니다',
  buildPrompt(userInput, context) {
    return `다음 코드를 리뷰해주세요:\n${context.selectedCode}\n\n사용자 요청: ${userInput}`
  }
}

모든 커맨드는 CommandBase 인터페이스를 구현해야 합니다. 이 계약은 커맨드의 정체성, 실행 방식, 가용성 조건을 정의합니다.

interface CommandBase {
  name: string              // 고유 식별자 (/name으로 호출)
  type: CommandType          // 'local' | 'local-jsx' | 'prompt'
  description: string       // 사용자에게 표시되는 설명
  aliases: string[]          // 대체 이름 목록
  isAvailable: AvailFn       // 현재 컨텍스트에서 사용 가능 여부
  isHidden: boolean          // 자동완성에서 숨길지 여부
  argDescription: string    // 인수 설명
  userFacingName: string    // UI에 표시되는 이름
  category: string          // 그룹화 카테고리
  requiredFeatures: Feature[] // 필요한 기능 플래그
  priority: number          // 자동완성 정렬 우선순위
}

정적 등록

빌드 타임에 알려진 커맨드들이 정적으로 등록됩니다. commands/ 디렉토리의 각 파일이 하나의 커맨드를 export하며, 레지스트리에 자동으로 수집됩니다.

동적 등록

런타임에 추가되는 커맨드입니다. 프로젝트의 .claude/commands/ 디렉토리에서 커스텀 커맨드를 로드하거나, MCP 서버에서 제공하는 커맨드를 등록합니다. 동적 커맨드는 정적 커맨드와 동일한 CommandBase 계약을 따릅니다.

필터 적용

등록된 모든 커맨드에 대해 isAvailable()과 requiredFeatures를 체크하여 현재 컨텍스트에서 사용 가능한 커맨드만 남깁니다.

// 등록 파이프라인 흐름
function getAvailableCommands(context: CommandContext): Command[] {
  const staticCmds = getStaticCommands()
  const dynamicCmds = getDynamicCommands(context.projectRoot)
  const allCmds = [...staticCmds, ...dynamicCmds]

  return allCmds
    .filter(cmd => cmd.requiredFeatures.every(f => feature(f)))
    .filter(cmd => cmd.isAvailable(context))
    .sort((a, b) => b.priority - a.priority)
}

사용자가 /를 입력하면 REPL은 일반 텍스트 모드에서 커맨드 모드로 전환됩니다. 자동완성이 활성화되고, 사용 가능한 커맨드 목록이 표시됩니다.

// REPL 입력 처리 — 커맨드 디스패치
function handleInput(input: string): void {
  if (input.startsWith('/')) {
    const [name, ...args] = input.slice(1).split(' ')
    const cmd = registry.resolve(name) // 이름 + 별칭으로 조회
    if (!cmd) { showUnknownCommand(name); return }

    switch (cmd.type) {
      case 'local':     cmd.execute(context);          break
      case 'local-jsx': mountDialog(cmd.render(context)); break
      case 'prompt':    sendToModel(cmd.buildPrompt(args, context)); break
    }
  }
}

캐시 관리

동적 커맨드의 로드 결과는 캐시됩니다. 프로젝트 루트가 변경되거나 .claude/commands/ 디렉토리의 파일이 변경되면 캐시가 무효화됩니다. 이를 통해 매 입력마다 파일시스템을 읽지 않으면서도 최신 커맨드 목록을 유지합니다.

브릿지와 원격 모드

브릿지 모드에서는 커맨드가 원격 프로세스로 전달됩니다. local과 local-jsx 커맨드는 로컬에서 실행되지만, prompt 커맨드는 원격 세션의 모델에 전달됩니다. 원격 모드에서는 일부 로컬 커맨드가 비활성화됩니다.