Claude Code 내부 구조

왜 내부를 알아야 하는가

Claude Code는 에이전틱 코딩의 사실상 표준 하네스다. 하지만 대부분의 사용자는 이 도구를 블랙박스로 사용한다 — “프롬프트를 넣으면 코드가 나온다.”

하네스 엔지니어는 다르다. 블랙박스를 열어 왜 이렇게 설계되었는지 이해하고, 그 원리를 자신의 시스템에 적용한다. Claude Code의 내부를 이해하면:

• 4주차 루프 패러다임: Query Engine의 턴 루프가 Ralph Loop의 기반임을 파악
• 5주차 컨텍스트 관리: auto-compaction이 Context Rot을 방지하는 실제 메커니즘을 이해
• 6주차 인스트럭션 튜닝: CLAUDE.md 계층이 “Sign” 메타포의 구현체임을 인식
• 7주차 멀티에이전트: Agent 도구의 worktree 격리가 역할 분리의 기술적 토대임을 학습

이 문서는 공식 문서, CLI 동작 관찰, 시스템 프롬프트 분석, MCP 공개 스펙을 바탕으로 구성했다.

---

1. 시스템 아키텍처 개관

Claude Code는 듀얼 레이어 구조다:

• 오케스트레이션 레이어: 세션 관리, 커맨드 라우팅, LLM 상호작용 (60+ 모듈)
• 실행 레이어: API 통신, 도구 실행, 터미널 렌더링, 보안 (다중 크레이트 워크스페이스)

SYSTEM ARCHITECTURE

CLI / REPL사용자 인터페이스

Commands Dispatcher15+ 슬래시 커맨드 — /help, /status, /compact, /cost …

Query Engine대화 루프, 턴 관리, 예산 제어

Tool Registry (40개 도구)Base + Plugin + Runtime(MCP)

Permission Enforcer3모드 × 4레이어 인가 게이트

Bash / File I/O / MCP / LSP / Sandbox실제 시스템 조작

OS / 파일시스템 / 네트워크하드웨어 경계

설계 철학

오케스트레이션 레이어는 빠른 실험에 최적화 — 세션 관리, 프롬프트 조립, 도구 라우팅을 유연하게 변경. 실행 레이어는 안전성과 성능에 최적화 — 샌드박스, 퍼미션 체크, 파일 I/O를 엄격하게 보장. 에이전틱 시스템에서 “빠른 실험 레이어”와 “신뢰 가능한 실행 레이어”를 분리하는 패턴은 범용적이다.

---

2. Bootstrap & Session Lifecycle

7단계 부트스트랩

Claude Code 세션은 “터미널을 열면 바로 시작”이 아니다. 7단계 초기화를 거친다:

1. Prefetch — 환경 변수, 인증 토큰 사전 로드
2. Warning Handler — 경고 핸들러 등록 (trust prompt 감지)
3. CLI Parse — 명령줄 인수 파싱 및 검증
4. Concurrent Setup — workspace 탐색과 commands 로드를 병렬 실행
5. Deferred Init — 지연 초기화 (MCP 서버 연결, 플러그인 로드)
6. Mode Routing — 실행 모드 결정 (REPL / one-shot / resume / headless)
7. Query Engine Loop — 대화 루프 진입

FastPath 최적화

모든 단계를 매번 실행하는 것은 아니다. 단순 명령(claude --version)은 FastPath로 조기 종료하여, 전체 초기화를 건너뛴다.

세션 영속화

• 세션 상태는 .claude/sessions/ 에 JSON으로 저장
• --resume latest로 마지막 세션 복원
• 세션 간 상태 공유는 파일 시스템을 통해서만: CLAUDE.md, MEMORY.md, 상태 추적 파일
• 이것이 Ralph 루프의 “세션 종료 → 새 세션에서 상태 파일 읽기” 패턴의 기술적 토대

강의 연결

주차	연결
4주차	Ralph 루프의 “세션 시작 → 작업 → 종료 → 새 세션” 사이클이 이 lifecycle 위에서 동작
5주차	세션 영속화 메커니즘이 Context Rot 방지의 기반 — 새 세션은 깨끗한 컨텍스트에서 시작

---

3. Query Engine — 대화 루프의 심장

사용자 메시지를 받아 도구를 실행하고 응답을 생성하는 반복 루프. Claude Code의 핵심 엔진이다.

설정 기본값

파라미터	기본값	설명
max_turns	8	1회 쿼리당 최대 턴 수 (도구 호출 1회 = 1턴)
max_budget_tokens	2,000	턴당 토큰 예산 상한
compact_after_turns	12	자동 compaction 트리거 기준
ConversationRuntime max	16	내부 반복 상한

턴 루프 흐름

QUERY ENGINE TURN LOOP

사용자 입력

↓

시스템 프롬프트 조립CLAUDE.md + 도구 목록 + 세션 상태

↓

세션 히스토리에 메시지 추가

↓

턴 루프 (max 16)

API 스트리밍 호출 (SSE)

↓

응답 파싱 — 도구 호출 감지?

Yes퍼미션 확인 → 도구 실행 → 결과를 세션에 추가 → 다음 턴

No텍스트 응답 → 루프 종료

↓

최종 렌더링 + 토큰 사용량 기록

시스템 프롬프트 아키텍처 — 29블록 동적 조립

턴 루프의 첫 단계인 “시스템 프롬프트 조립”은 단순한 정적 문자열이 아니다. 29개 컴포넌트를 조건부로 조립하는 동적 컨텍스트 엔진이다.

Always vs Conditional 블록

29개 중 11개는 매 세션 무조건 포함되는 Always 블록, 18개는 기능 플래그로 켜고 끄는 Conditional 블록이다.

구분	블록 수	주요 블록
Always	11	Intro, System Rules, Doing Tasks, Executing Actions with Care, Using Your Tools, Tone and Style, Output Efficiency, Shell Shortcut, Environment Info, Summarize Tool Results 등
Conditional	18	Agent Tool, Skills, Memory, MCP Instructions, Git Status, Effort Level, Verification Agent 등

Always 블록만으로 Claude Code의 기본 성격이 완성된다 — Intro에서 모델 정체성을 잡고, System Rules에서 도구 규칙을 세우고, Doing Tasks에서 코딩 철학을 심는다. Conditional 블록은 기능 플래그 하나로 런타임에 프롬프트 형태가 완전히 달라진다.

배치 순서 = 우선순위

블록의 물리적 배치 순서가 모델의 행동 우선순위를 결정한다. 분기점은 Cache Boundary Marker다.

SYSTEM PROMPT BLOCK LAYOUT

Always 블록 (캐시 가능 영역)정체성 → 규칙 → 도구 사용법 → 톤 순서. 매 API 호출마다 동일하게 캐시

↓

SYSTEM_PROMPT_DYNAMIC_BOUNDARY이 마커 위 = 글로벌 캐시 영역 / 아래 = 세션별 동적 영역

↓

Conditional 블록 (동적 영역)Agent Tool, Skills, Memory, MCP Instructions — 세션별로 빠지거나 들어감

↓

Git Status + Append System Prompt의도적으로 맨 마지막 배치 — 사용자 커스텀이 기존 규칙 위에 덮어쓸 수 있는 구조

Variation — 동일 블록, 다른 콘텐츠

상당수 블록은 varies 태그를 가진다. 같은 블록이 맥락에 따라 다른 텍스트를 담는다:

블록	조건 A	조건 B
Intro	output_style 미설정 → “소프트웨어 엔지니어링을 돕는 에이전트”	설정 시 → “Output Style에 따라 응답하는 에이전트”
Output Efficiency	내부 사용자 → “사람을 위해 쓰고 있다고 생각하라”	외부 사용자 → “요점만 말하라, 가장 단순한 접근부터”
Agent Tool	fork 모드 on → “자기 복제본을 백그라운드 실행”	off → “전문 에이전트를 생성”
Environment Info	일반 → 모델명·버전 표시	undercover 모드 → 모델 정보 전체 은닉

같은 모델, 다른 에이전트

6개 코딩 에이전트의 시스템 프롬프트를 비교한 연구에서, 프롬프트를 서로 바꿔 끼우면 동일 모델이라도 작업 방식이 완전히 달라졌다. 신경 써야 할 건 모델 선택이 아니라 매 순간 무엇을 보여주느냐다.

실무 설계 패턴 4가지

1. 캐시 경계 설계 — SYSTEM_PROMPT_DYNAMIC_BOUNDARY 마커 하나로 글로벌 캐시와 동적 영역을 분리. API 호출마다 반복되는 Always 블록을 캐시해 비용을 절감한다.

2. Verification Agent — 파일 3개 이상 수정하면 독립 검증 에이전트를 먼저 띄우라는 Conditional 블록. 자기 검증을 프롬프트 레벨에서 강제한 설계.

3. Microcompact + Summarize Tool Results — 오래된 도구 결과를 자동 삭제하되, 중요 정보는 먼저 텍스트로 기록하라는 지시가 짝으로 동작. Anthropic의 tool result clearing 전략이 코드로 구현된 것.

4. Effort Level (구 Token Budget) — --effort 플래그로 low / medium / high / max 4단계를 지정한다. 낮은 단계는 빠르고 저렴하며, 높은 단계는 복잡한 문제에 깊은 추론을 제공한다. max는 Opus 4.6 전용으로 사고 토큰에 제한을 두지 않는다. /effort 커맨드, CLAUDE_CODE_EFFORT_LEVEL 환경변수, 설정 파일의 effortLevel 필드로도 제어 가능. 비용 상한은 별도로 --max-budget-usd로 분리되었다.

강의 연결

주차	연결
5주차	Cache Boundary = 토큰 효율 극대화. Microcompact = Context Rot의 프롬프트 레벨 방어
6주차	Always 블록 = “Sign” 메타포의 뼈대. Variation = 인스트럭션 튜닝의 실제 메커니즘
7주차	Verification Agent = 멀티에이전트 자기검증 패턴의 프롬프트 구현
12주차	Effort Level = 비용/품질 트레이드오프의 런타임 제어. --max-budget-usd로 비용 상한 분리

TurnResult — 턴 결과 캡처

매 턴마다 7개 요소를 기록한다:

1. input — 원본 프롬프트
2. response — 생성된 응답
3. slash commands — 감지된 슬래시 커맨드
4. invoked tools — 호출된 도구 목록
5. permission blocks — 거부된 퍼미션
6. token usage — input/output/cache 토큰 수
7. termination reason — completed | max_turns_reached | max_budget_reached

스트리밍 이벤트 프로토콜

API 응답은 SSE(Server-Sent Events)로 전달된다. 6종 이벤트:

이벤트	시점
message_start	응답 시작
command_match	슬래시 커맨드 감지
tool_match	도구 호출 감지
permission_denial	퍼미션 거부
message_delta	텍스트 청크 스트리밍
message_stop	응답 완료

강의 연결

주차	연결
4주차	Ralph 루프의 “실행 → 검증 → 재시도”가 Query Engine 턴 루프 위에서 동작. max_turns가 백프레셔의 한 형태
5주차	compact_after_turns와 토큰 예산이 Context Rot 방지의 1차 방어선
12주차	TurnResult의 7요소가 텔레메트리 설계의 출발점

---

4. Tool System — 40개 도구의 3-Layer 구성

Claude Code가 실제로 “행동”할 수 있는 이유. 도구 없는 LLM은 텍스트만 생성하지만, 도구가 있는 LLM은 파일을 수정하고, 명령을 실행하고, 외부 서비스를 호출한다.

도구 카테고리

Shell (2)

도구	기능
Bash	샌드박스 셸 실행. timeout 최대 600초, 출력 16KiB 절삭, UTF-8 경계 보정
PowerShell	Windows 셸. 동일한 안전 장치 적용

File I/O (4)

도구	기능
Read	line-windowed 읽기. 10MB 상한, 바이너리 감지, PDF/이미지/노트북 지원
Write	전체 파일 쓰기. structured patch hunk 반환, git diff 생성
Edit	문자열 치환 편집. old_string → new_string. 비고유 매칭 시 실패
NotebookEdit	Jupyter 셀 조작. replace, insert, delete

Search (3)

도구	기능
Glob	파일 패턴 매칭. 최대 100결과, mtime 정렬
Grep	ripgrep 기반 정규식 검색. 13개 파라미터 (컨텍스트, 멀티라인, 타입 필터 등)
ToolSearch	deferred 도구 스키마 조회. 이름/키워드 검색 → JSON 스키마 반환

Web (2)

도구	기능
WebFetch	URL 콘텐츠 추출. HTML→Markdown 변환, 15분 캐시
WebSearch	웹 검색. 도메인 필터링 지원

Agent (2)

도구	기능
Agent	서브에이전트 스폰. 모델 선택(sonnet/opus/haiku), worktree 격리, 백그라운드 실행
Skill	미리 정의된 스킬 로드. 여러 도구 호출을 조합한 워크플로우

Task/Session (6)

도구	기능
TodoWrite	태스크 리스트 관리. id/content/status/priority
Sleep	실행 일시 정지 (duration_ms)
SendUserMessage	사용자에게 메시지 전달 (첨부파일, 상태 표시)
Config	에이전트 설정 읽기/쓰기
StructuredOutput	기계 파싱 가능한 JSON 출력
REPL	언어별 실행 환경 (Python, Node.js 등)

3-Layer 구성

도구는 세 겹으로 합성된다:

TOOL 3-LAYER COMPOSITION

Layer 1: Base컴파일 타임 정적 정의40개 빌트인 도구 — ToolSpec(이름, 설명, JSON schema, 필요 퍼미션)

↓이름 충돌 검사

Layer 2: Plugin사용자 설치 확장hook 기반 lifecycle: pre_tool_use → 실행 → post_tool_use / post_tool_use_failure

↓이름 충돌 검사

Layer 3: RuntimeMCP 서버 동적 등록mcp__{server}__{tool} 네이밍 — 서버 연결 시 자동 등록

핵심 설계 결정:

• 상위 레이어 도구가 하위와 이름 충돌 시 등록 거부 — 빌트인 도구의 안정성 보장
• simple mode에서는 Bash, FileRead, FileEdit 3개만 노출 — 최소 권한 원칙
• 거부된 도구는 시스템 프롬프트에서 아예 제거 — LLM이 존재 자체를 모름

도구 숨기기 vs. 실행 거부

도구를 시스템 프롬프트에서 제거하는 것(Layer 1 필터링)과 실행 시 퍼미션을 거부하는 것(Layer 4 enforcement)은 다른 보안 레이어다. 전자는 LLM이 도구의 존재를 모르게 하고, 후자는 알더라도 실행을 차단한다. 방어심층(defense-in-depth) 패턴이다.

강의 연결

주차	연결
3주차	MCP 서버가 Layer 3에서 도구를 동적으로 등록하는 메커니즘
6주차	simple mode의 도구 필터링 = 인스트럭션 튜닝의 기계적 구현
7주차	서브에이전트에게 allowedTools로 접근 가능한 도구를 제한 → 역할 분리

---

5. Permission Model — 3모드 x 4레이어

에이전트의 행동 범위를 제어하는 결정론적 게이트. 2주차 거버넌스와 3주차 TBAC의 실제 구현이다.

3 Permission Modes

모드	허용 범위	용도
ReadOnly	읽기/검색만	코드 분석, 설명 요청
WorkspaceWrite (기본)	워크스페이스 내 쓰기 + 샌드박스 명령	일반 개발
DangerFullAccess	전체 접근	시스템 관리 (위험)

4중 보안 레이어

1. Deny List (도구 은닉) — 도구를 시스템 프롬프트에서 제거. LLM이 존재를 모름. frozenset 기반 O(1) 매칭 + 접두사 스캔.
2. Permission Policy (도구별 오버라이드) — BTreeMap으로 도구마다 필요 모드 지정. 예: bash → DangerFullAccess.
3. CLI Mode Preset — --permission-mode 플래그로 세션 전체 모드 설정.
4. Workspace Boundary (파일 경계) — 파일 쓰기 시 symlink escape 차단, ../ 탈출 검증, canonical path 비교, 바이너리 파일 감지.

인가 흐름

AUTHORIZATION FLOW

authorize(tool_name, input)

↓

모드 조회tool → required_mode

↓

Allow즉시 통과

Deny사유 반환 (tool, active_mode, required_mode, reason)

Prompt사용자에게 승인 요청 → Allow/Deny 결정

Bash 특별 처리

ReadOnly 허용	차단
ls, cat, grep, git status, find, wc	rm -rf, mkfs, reboot, chmod, 파이프 체인

위험 명령은 휴리스틱 위험도 점수로 평가되며, allowlist에 있는 안전 명령만 ReadOnly에서 통과.

강의 연결

주차	연결
2주차	Governance-as-Code의 실제 코드 구현
3주차	TBAC(Tool-Based Access Control)의 런타임 시행
6주차	퍼미션 제약 = 에이전트 행동 교정의 기계적 수단

---

6. Context Management & Compaction

장기 실행 세션에서 Context Rot을 방지하는 메커니즘. 5주차의 이론을 Claude Code가 어떻게 구현하는지 보여준다.

CLAUDE.md 3레벨 계층

우선순위가 높은 것이 낮은 것을 override:

우선순위	경로	범위
3 (높음)	<workspace>/CLAUDE.md	워크스페이스 로컬 (개인)
2	<project>/.claude/CLAUDE.md	프로젝트 (팀 공유)
1 (낮음)	~/.claude/CLAUDE.md	사용자 전역 (모든 프로젝트)

크기 제한:

• 단일 instruction 파일: 최대 4,000자 (MAX_INSTRUCTION_FILE_CHARS)
• 전체 instruction 합산: 최대 12,000자 (MAX_TOTAL)

이 외에 MEMORY.md (영속 기억)과 AGENTS.md (에이전트 역할 정의)가 시스템 프롬프트에 추가된다.

Auto-Compaction 알고리즘

대화가 길어지면 자동으로 압축한다:

AUTO-COMPACTION ALGORITHM

트리거턴 수 > compact_after_turns (기본 12)

↓

보존최근 4개 메시지 유지

↓

압축 대상 (나머지)

• Markdown → plaintext 변환
• 중복 도구 결과 제거
• 타임스탬프/메타데이터 제거
• 토큰 상한 10,000까지 절삭

↓

결과요약 프롬프트 + 최근 4개 메시지로 재구성

수동 트리거: /compact 명령

Microcompact + Summarize Tool Results

Auto-compaction 외에 Microcompact 메커니즘이 있다. 오래된 도구 결과를 자동 삭제하되, 삭제 전 중요 정보를 먼저 텍스트로 기록하라는 Summarize Tool Results 지시가 짝으로 동작한다. Anthropic 공식 블로그의 tool result clearing 전략이 코드로 구현된 것이다. 컨텍스트 윈도우를 점진적으로, 안전하게 회수하는 패턴.

토큰 추적과 비용 계산

매 API 호출마다 4종 토큰을 추적:

토큰 종류	설명
input_tokens	입력 토큰
cache_creation_input_tokens	캐시 생성 토큰
cache_read_input_tokens	캐시 읽기 토큰
output_tokens	출력 토큰

모델별 가격 (1M 토큰당):

모델	Input	Output
Sonnet	$3	$15
Haiku	$1	$5
Opus	$5	$25

/cost 명령으로 세션 누적 비용을 실시간 확인할 수 있다.

강의 연결

주차	연결
5주차	Context Rot 방지의 실제 구현. auto-compaction = 결정론적 컨텍스트 관리
6주차	CLAUDE.md 3레벨 계층 = “Sign” 메타포의 구현체. 전역/프로젝트/로컬 제약
12주차	토큰 추적이 비용 최적화 텔레메트리의 기초

---

7. MCP Integration

외부 도구와 데이터 소스를 표준 프로토콜로 연결하는 레이어. 3주차에서 배우는 MCP 이론이 Claude Code 내부에서 어떻게 구현되는지 보여준다.

6종 Transport

Transport	통신 방식	용도	설정
Stdio	stdin/stdout	로컬 프로세스 (가장 일반적)	command, args, env
SSE	HTTP 스트리밍	원격 서버	URL, headers
HTTP	REST	표준 API	URL, headers
WebSocket	양방향	실시간 통신	URL
SDK	인프로세스	네트워크 없음	직접 호출
ClaudeAiProxy	프록시	claude.ai 호스팅 서버	래핑 URL

서버 Lifecycle 상태머신

MCP SERVER LIFECYCLE

Configured

↓spawn process (Stdio) 또는 connect (HTTP/WS)

Initializing

↓JSON-RPC initialize 핸드셰이크 (프로토콜 버전 협상)

Connected

↓tools/list + resources/list (도구/리소스 발견)

In Use

↓shutdown signal 또는 오류

Terminated

JSON-RPC 2.0 프로토콜

MCP는 JSON-RPC 2.0을 와이어 프로토콜로 사용한다:

// 요청
{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}

// 응답
{"jsonrpc": "2.0", "id": 1, "result": {"tools": [...]}}

// 에러
{"jsonrpc": "2.0", "id": 1, "error": {"code": -32600, "message": "Invalid request"}}

주요 메서드:

• initialize — 핸드셰이크, capability 협상
• tools/list — 사용 가능한 도구 목록
• tools/call — 도구 실행
• resources/list — 리소스 목록
• resources/read — 리소스 읽기

도구 네이밍 규칙

MCP 서버의 도구는 네이밍 규칙으로 식별된다:

mcp__{normalized_server_name}__{tool_name}

예: mcp__my_database__query, mcp__github__create_pull_request

claude.ai 호스팅 서버는 "claude.ai " 접두사 사용: mcp__claude_ai_GitHub__search_code

설정 3-소스 계층

SETTINGS 3-SOURCE HIERARCHY

~/.claude/settings.json사용자 전역

↓deep merge

<project>/.claude/settings.json프로젝트

↓deep merge

.claude/settings.local.json로컬 (gitignore)

• 가장 구체적인 설정이 우선
• FNV-1a 해싱으로 중복 서버 감지 — 같은 서버가 여러 레벨에 정의되어도 1회만 연결
• OAuth 설정 포함 가능: client_id, callback_port, auth_server_metadata_url

Degraded Mode

MCP 서버 일부가 실패해도 나머지는 정상 운영:

실패 유형	분류	대응
프로세스 시작 실패	startup	다른 서버 정상 운영
핸드셰이크 실패	handshake	재연결 시도
설정 오류	config	오류 메시지 + skip
부분 시작	partial	가용 도구만 등록

Graceful Degradation

이것은 마이크로서비스의 circuit breaker 패턴과 동일한 원리다. 한 MCP 서버의 장애가 전체 시스템을 다운시키지 않는다. 에이전틱 시스템 설계에서 필수적인 패턴.

강의 연결

주차	연결
3주차	MCP 프로토콜의 실제 구현. transport 선택, lifecycle 관리, degraded mode
7주차	MCP로 에이전트별 도구 접근 권한을 차등 부여

---

8. Agent Orchestration

Claude Code의 멀티에이전트 실행 모델. 7주차 멀티에이전트 SDLC의 기술적 기반이다.

Agent 도구 — 서브에이전트 스폰

Agent 도구로 독립 프로세스를 생성한다:

파라미터	설명
prompt	서브에이전트에게 전달할 작업 설명
model	모델 선택: sonnet (표준), opus (복잡), haiku (경량)
isolation: "worktree"	git worktree에서 격리 실행 — 부모 작업 영역에 영향 없음
run_in_background	비동기 실행, 완료 시 알림
mode	퍼미션 모드 (plan, auto, default 등)

서브에이전트는 부모 컨텍스트를 모른다

서브에이전트는 독립적 프롬프트로 작동한다. 부모 세션의 대화 히스토리나 변수에 접근할 수 없다. 따라서 프롬프트에 충분한 컨텍스트를 포함해야 한다. 이것은 마이크로서비스 간 명시적 계약(API contract)과 같은 원리다.

Task Packet — 구조화된 작업 전달

자연어 프롬프트 대신 구조화된 패킷으로 에이전트에게 작업을 지시:

TaskPacket {
  objective:         "사용자 인증 모듈 리팩터링"
  scope:             Module           // Workspace | Module | SingleFile | Custom
  branch_policy:     "feature/auth-refactor"
  acceptance_tests:  ["pytest tests/auth/", "mypy src/auth/"]
  commit_policy:     "conventional commits"
  escalation_policy: "3회 실패 시 중단 후 보고"
}

이점: 자연어의 모호성 제거, 로깅/재시도/변환이 가능, 에이전트 간 계약 명확화.

Team & Cron 레지스트리

기능	도구	설명
팀 생성	TeamCreate	에이전트 팀 구성, 태스크 ID 할당
팀 삭제	TeamDelete	팀 해체
주기 실행	CronCreate	cron 표현식 + 핸들러로 스케줄 등록
주기 조회	CronList	활성 스케줄 목록
주기 삭제	CronDelete	스케줄 해제

Team은 여러 Task를 조율하고, Cron은 /loop 같은 주기적 실행의 기반이다.

강의 연결

주차	연결
4주차	Cron 레지스트리 = /loop 명령의 스케줄링 기반
7주차	Agent 도구 + worktree 격리 = 멀티에이전트 파이프라인의 기술적 토대
8-9주차	Task Packet = 플래너→코더→QA 간 아티팩트 계약

---

9. 설정 시스템

Claude Code의 동작을 결정하는 설정 계층.

Config 우선순위

높은 것이 낮은 것을 override:

1. Runtime CLI flags — --permission-mode, --model, --allowedTools (최우선)
2. Local config — .claude/settings.local.json (gitignore, 개인)
3. Project config — .claude/settings.json 또는 .claude.json (팀 공유)
4. User config — ~/.claude/settings.json (전역)
5. Compiled defaults — 코드에 내장된 기본값 (최하위)

Feature-Gated 서브시스템

설정으로 활성화/비활성화되는 기능들:

서브시스템	설정 키	설명
Hooks	hooks	도구 호출 이벤트에 셸 명령 트리거
Plugins	plugins	확장 플러그인 활성화
MCP	mcpServers	MCP 서버 연결 설정
OAuth	oauth	OAuth 인증 설정
Sandbox	sandbox	파일시스템 격리 모드

API 클라이언트 설정

항목	기본값
Base URL	https://api.anthropic.com
API Version	2023-06-01
Max retries	2
Initial backoff	200ms
Max backoff	2s
Retryable codes	408, 409, 429, 500, 502, 503, 504

인증 방식 4종: None, ApiKey, BearerToken, ApiKey+Bearer. 환경변수 ANTHROPIC_API_KEY 또는 ~/.claude/credentials.json에서 로드.

---

정리 — 7개 레이어와 강의 맵

레이어	핵심 개념	가장 관련된 주차
Bootstrap & Session	7단계 초기화, 세션 영속화	4주차 (루프 lifecycle)
Query Engine	턴 루프, 예산 제어, TurnResult, 29블록 시스템 프롬프트 조립	4주차, 5주차, 6주차
Tool System	40도구, 3-Layer, ToolSpec	3주차 (MCP), 7주차
Permission Model	3모드, 4중 보안, Bash 안전	2주차, 6주차
Context Management	CLAUDE.md 계층, compaction, 토큰 추적	5주차, 6주차, 12주차
MCP Integration	6 transport, lifecycle, degraded mode	3주차
Agent Orchestration	서브에이전트, worktree, Task Packet	7주차, 8-9주차