부팅 시퀀스

부팅 시퀀스 개요

사용자가 claude 명령을 실행하는 순간부터 첫 번째 응답을 받기까지, Claude Code는 일련의 초기화 단계를 거칩니다. 이 과정을 이해하면 설정 문제를 진단하고 동작을 예측하는 데 도움이 됩니다.

$ claude [flags] [prompt]
       ↓
  [1] 런타임 검사
       ↓
  [2] 설정 로딩
       ↓
  [3] 환경 변수 초기화
       ↓
  [4] MCP 서버 연결
       ↓
  [5] 도구 등록
       ↓
  [6] UI 초기화
       ↓
  [7] SessionStart 이벤트
       ↓
  REPL 루프 진입

단계별 상세 설명

1단계: 런타임 환경 검사

Claude Code는 Bun 런타임 위에서 동작하며, npm 배포 시 Node.js 18 이상 호환을 요구합니다. 시작 시 가장 먼저 실행 환경을 검사합니다.

# 버전 미충족 시 오류 메시지
Error: Claude Code requires Node.js 18 or higher.
Current version: v16.20.0

검사 항목:

런타임 버전 (Node.js 18+ 또는 Bun)
필수 환경 변수 존재 여부 (ANTHROPIC_API_KEY)
네트워크 접근 가능 여부 (API 엔드포인트)
병렬 프리페치: MDM 설정과 macOS Keychain 자격 증명을 동시에 미리 로드하여 시작 시간을 단축합니다

2단계: 설정 파일 로딩

설정은 4개 레이어 로 나뉘며, 나중에 로딩된 설정이 이전 설정을 덮어씁니다.

| 순서 | 레이어 | 경로 | 용도 | |------|--------|------|------| | 1 | managed | /etc/claude/settings.json | 기업 관리자 정책 | | 2 | user | ~/.claude/settings.json | 개인 전역 설정 | | 3 | project | .claude/settings.json | 프로젝트 공유 설정 | | 4 | local | .claude/settings.local.json | 로컬 전용 설정 (gitignore) |

// .claude/settings.json 예시
{
  "permissions": {
    "allow": ["Bash(git:*)", "Read(**)"],
    "deny": ["Bash(rm -rf *)"]
  },
  "model": "claude-opus-4-5"
}

우선순위 원칙: local > project > user > managed. 개발자가 로컬에서 실험적 설정을 적용해도 관리자 정책을 우선 덮어쓸 수 없습니다. 반대로 managed 레이어가 최하위 우선순위이므로, 상위 레이어에서 언제든 재정의할 수 있습니다.

3단계: 환경 변수 초기화

설정 로딩 후 환경 변수를 읽어 동작 모드를 결정합니다.

| 환경 변수 | 기본값 | 설명 | |----------|--------|------| | CLAUDE_CODE_SIMPLE | "" | Bash/Read/Edit만 사용하는 최소 모드 | | ANTHROPIC_API_KEY | 필수 | Anthropic API 인증 키 | | CLAUDE_CODE_MAX_OUTPUT | 32000 | 최대 출력 문자 수 | | DISABLE_AUTOUPDATER | "" | 자동 업데이트 비활성화 |

CLAUDE_CODE_SIMPLE=1 로 설정하면 파일·셸 도구만 남기고 나머지를 비활성화합니다. CI 환경이나 제한된 컨텍스트에서 유용합니다.

Remote Control은 환경 변수로 켜는 실행 모드가 아니라, 공식 문서에 안내된 CLI·슬래시 명령으로 로컬 세션을 다른 기기에서 제어하는 연구 미리보기 기능입니다. 원격 제어가 필요하면 기능의 버전 요구·로그인·작업공간 신뢰 조건을 공식 문서에서 확인합니다.

4단계: MCP 서버 연결

설정 파일에 선언된 MCP (Model Context Protocol) 서버들을 순차적으로 연결합니다.

// MCP 서버 설정 예시
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    }
  }
}

연결 실패한 MCP 서버는 경고만 출력 하고 계속 진행합니다
연결된 서버의 도구는 mcp__<서버명>__<도구명> 패턴으로 등록됩니다

5단계: 도구 등록

내장 도구와 MCP 도구를 등록하고, 각 도구의 isEnabled() 메서드를 호출해 현재 환경에서 사용 가능한지 확인합니다.

// 도구 등록 흐름 (단순화)
const tools = [
  new ReadTool(),
  new EditTool(),
  new BashTool(),
  ...mcpTools,
].filter(tool => tool.isEnabled())

지역 제한이 있거나 환경 조건이 맞지 않으면 도구가 등록 목록에서 제외됩니다.

6단계: UI 초기화

실행 모드에 따라 두 가지 경로로 분기합니다.

대화형 모드 (기본):

React/Ink 기반 터미널 UI 초기화
  → 입력 필드, 상태 표시줄, 도구 실행 패널 렌더링
  → 키보드 단축키 바인딩
  → REPL 루프 시작

비대화형 모드 (--print 또는 stdin):

stdout/stderr 파이프 설정
  → 스트리밍 또는 단일 출력 모드 선택
  → 프롬프트를 직접 처리하고 종료

7단계: SessionStart 훅 이벤트

모든 초기화가 완료되면 SessionStart 훅 이벤트가 발생합니다. 이 시점에 등록된 훅이 있으면 실행됩니다.

// SessionStart 훅 설정 예시
{
  "hooks": {
    "SessionStart": [{
      "command": "echo 'Session started: $(date)' >> ~/.claude/sessions.log"
    }]
  }
}

부팅 문제 진단

| 증상 | 원인 | 해결 방법 | |------|------|-----------| | API key not found | ANTHROPIC_API_KEY 미설정 | .env 또는 셸 프로필에 키 추가 | | MCP 서버 연결 실패 | 서버 명령어 오류 또는 포트 충돌 | /mcp 명령으로 연결 상태 확인 | | 도구 목록이 예상과 다름 | isEnabled() 필터 또는 CLAUDE_CODE_SIMPLE | /tools 명령으로 활성 도구 확인 | | 설정이 적용되지 않음 | 레이어 우선순위 오해 | 더 높은 우선순위 레이어에서 설정 확인 |