부팅 시퀀스

부팅 시퀀스 개요

사용자가 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_REMOTE	""	원격 실행 모드 활성화
CLAUDE_CODE_SIMPLE	""	Bash/Read/Edit만 사용하는 최소 모드
ANTHROPIC_API_KEY	필수	Anthropic API 인증 키
CLAUDE_CODE_MAX_OUTPUT	32000	최대 출력 문자 수
DISABLE_AUTOUPDATER	""	자동 업데이트 비활성화

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

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 명령으로 활성 도구 확인
설정이 적용되지 않음	레이어 우선순위 오해	더 높은 우선순위 레이어에서 설정 확인