Claude Code는 단순히 언어 모델과 채팅하는 도구가 아니라, 모델의 추론과 도구의 행동을 결합하고 컨텍스트와 권한을 총괄하는 **에이전트 런타임 하네스(Agentic Harness)**입니다. 모델이 상황을 파악하여 계획을 세우면 에이전트가 로컬 환경에서 도구를 실행하고, 그 모든 상호작용 과정이 세션(Session) 단위로 관리됩니다.
서브에이전트나 Agent Teams 같은 고급 다중 에이전트 기능도 모두 이 기본 런타임 위에서 동작합니다. 세션이 대화를 어떻게 기억하고 복원하는지, CLAUDE.md 지침이 어떤 우선순위로 로드되는지, settings.json과 **권한 모드(Permission Mode)**가 보안 경계를 어떻게 방어하는지를 이해하면 복잡한 에이전트 협업 환경도 명확하게 제어할 수 있습니다.
1. 에이전트 루프와 세션 런타임
Claude Code의 핵심 동작 원리는 **컨텍스트 수집(Gather Context) → 행동(Take Action) → 결과 확인(Verify Results)**의 3단계 루프입니다. 이 에이전트 루프가 지속해서 회전하며 작업을 완수하고, 사용자는 작업 도중 언제든 끼어들어 방향을 조정할 수 있습니다.
이 루프가 동작하는 단일 실행 단위를 **세션(Session)**이라고 부르며, 다음과 같은 런타임 성질을 지닙니다.
- 로컬 파일시스템 기반 영속화: 대화 기록, 도구 호출 파라미터, 실행 결과는
~/.claude/projects/디렉터리 아래 프로젝트별 JSONL 파일로 실시간 기록됩니다. 이 영속 기록 덕분에 작업을 되감거나(rewind), 중단된 세션을 재개(resume)하고, 특정 시점에서 대화를 분기(fork)할 수 있습니다. - 세션 간 완전한 독립성: 각 세션은 이전 대화의 오염 없이 완전히 **새로운 컨텍스트 창(Context Window)**으로 시작합니다. 세션 간 지식 공유는 사용자 지침 파일인 CLAUDE.md와 자동 영구 메모리(Auto Memory)를 통해서만 제한적으로 이어집니다.
- 디렉터리 바인딩: 세션은 실행된 현재 작업 디렉터리에 종속됩니다.
/resume선택기는 기본적으로 현재 저장소(또는 worktree)에 속한 세션 목록을 보여 주며, 브랜치를 전환하더라도 대화 세션 기록 자체는 작업 공간에 보존됩니다. - 체크포인트와 안전 복구: 코드 편집 직전의 파일 상태를 자동으로 스냅숏하므로, 에이전트가 잘못된 수정을 진행했을 때
Esc를 두 번 누르면 로컬 파일시스템 상태를 즉시 이전 체크포인트로 되돌릴 수 있습니다.
공식 문서에서는 서브에이전트와 대비되는 개념으로 사용자가 터미널에서 직접 대화하는 주 창을 **메인 대화(Main Conversation)**라고 부릅니다. 서브에이전트는 메인 대화가 격리된 하위 작업을 맡기는 대상이며, 메인 대화의 컨텍스트 창과는 독립적으로 실행됩니다.
2. 지침 주입 계층: CLAUDE.md
CLAUDE.md는 프로젝트 규약, 빌드 및 테스트 방식, 개인 코딩 스타일 등 에이전트가 상시 준수해야 하는 지침을 정의하는 마크다운 파일입니다. 세션이 시작될 때마다 시스템 프롬프트의 일부로 로드되어 모델의 컨텍스트에 주입됩니다.
이 지침 파일은 조직, 개인, 프로젝트 수준에 따라 4가지 계층으로 관리됩니다.
| 계층 구분 | 권장 위치 | 적용 대상 및 용도 |
|---|---|---|
| Managed policy | 시스템 공용 경로 (macOS /Library/Application Support/ClaudeCode/, Linux /etc/claude-code/, Windows C:\Program Files\ClaudeCode\) | 조직 전체 구성원이 공통 준수해야 하는 보안 정책 및 표준 규약 |
| User instructions | ~/.claude/CLAUDE.md | 현재 머신의 모든 프로젝트에 적용되는 개발자 개인 지침 |
| Project instructions | ./CLAUDE.md 또는 ./.claude/CLAUDE.md | 소스 컨트롤(Git)로 공유되어 팀원 모두에게 적용되는 저장소 전용 규칙 |
| Local instructions | ./CLAUDE.local.md | 현재 프로젝트에서 나만 사용하는 개인 지침 (.gitignore 대상) |
지침 파일은 다음과 같은 원칙으로 로드됩니다.
- 상향식(Bottom-up) 탐색과 병합: 현재 작업 디렉터리부터 파일시스템 루트까지 상위 디렉터리를 거슬러 올라가며 존재하는 모든
CLAUDE.md와CLAUDE.local.md를 읽어 들입니다. 상위 파일이 먼저 읽히고 하위 파일이 나중에 이어 붙으므로, 작업 디렉터리와 가까운 구체적인 지침이 뒤쪽에 배치되어 모델에 더 강하게 전달됩니다. - 하위 디렉터리 지연 로딩: 작업 디렉터리 하위에 있는
CLAUDE.md는 세션 시작 시 읽지 않으며, 에이전트가 해당 하위 디렉터리의 파일을 읽거나 수정하는 시점에 필요에 따라 동적으로 로드됩니다. - 모듈화: 긴 규칙은
@path/to/rules.md문법으로 외부 파일을 임포트하거나.claude/rules/디렉터리에 파일 패턴(paths:)을 지정해 특정 언어나 모듈을 다룰 때만 로드되도록 최적화할 수 있습니다.
Claude Code 공식 문서, Memory
Claude Code는 CLAUDE.md를 **강제 설정이 아니라 프롬프트 컨텍스트(Context, not enforced configuration)**로 취급합니다. 모델이 반드시 따라야 하는 절대적 제약이나 보안 차단은 프롬프트 지침이 아니라 권한 규칙이나 훅(Hooks)으로 강제해야 합니다.
3. 환경 설정 스택과 우선순위: settings.json
settings.json은 사용할 모델, 자동 승인 대상 명령, 환경 변수 등 에이전트의 런타임 동작을 규정하는 엄격한 JSON 설정 파일입니다. 주석이나 끝자리 쉼표(Trailing comma)를 허용하지 않는 표준 JSON 형식을 요구합니다.
설정 파일은 적용 범위에 따라 나뉘며, 여러 위치에서 동일한 설정 키가 충돌할 경우 다음 우선순위 스택에 따라 상위 설정이 하위 설정을 덮어씁니다.
- Managed settings: 기업 및 조직 정책 파일 (
managed-settings.json) - Command line: 세션 시작 시 준 CLI 플래그 (
--settings <file>) - Project local: 프로젝트 내 로컬 전용 설정 (
.claude/settings.local.json) - Shared project: 저장소에 커밋되어 팀이 공유하는 설정 (
.claude/settings.json) - User: 개발자 개인 전역 설정 (
~/.claude/settings.json)
단, permissions.allow 같은 배열 형태의 리스트 키는 상위 설정이 하위를 덮어쓰지 않고 하나로 안전하게 합쳐집니다(Merge).
env 블록과 프로세스 환경 상속
settings.json 안의 env 키는 세션 및 Claude Code가 실행하는 모든 하위 셸 프로세스에 전파할 환경 변수를 정의합니다.
{
"env": {
"DISABLE_AUTO_COMPACT": "1",
"ANTHROPIC_BASE_URL": "https://proxy.example.com"
}
}- 셸 환경 변수 오버라이드:
env블록에 명시된 환경 변수는 터미널 셸에서export된 기존 변수보다 우선하여 적용됩니다. - 보안 격리: 저장소 코드에서 시스템 핵심 변수를 조작하는 위험을 막기 위해,
CLAUDE_CONFIG_DIR,HOME, 시스템 핵심 디렉터리 변수는 프로젝트 설정 파일에서 정의하더라도 보안상 무시됩니다. - 자격 증명 주의:
env블록은 평문 JSON으로 저장되므로 API 토큰이나 비밀번호 같은 민감한 자격 증명을 직접 적지 않고 별도의 인증 헬퍼(apiKeyHelper)를 사용하는 것이 권장됩니다.
4. 보안 경계: 권한 모드와 세부 규칙
Claude Code는 터미널 명령과 파일시스템 수정을 수행하므로, 사용자의 명시적 승인 없이 에이전트가 자율적으로 실행할 수 있는 행동 범위를 통제하는 보안 경계를 갖추고 있습니다.
6단계 권한 모드 (Permission Mode)
상황에 따라 세션의 자율성 수준을 조절할 수 있습니다.
| 권한 모드 | UI 표시 라벨 | 무승인 자동 실행 허용 범위 |
|---|---|---|
default | Manual | 파일 읽기 및 탐색만 허용 (편집이나 명령어 실행은 매번 승인 확인) |
acceptEdits | Edit automatically | 파일 읽기, 파일 편집, 흔한 파일시스템 조작 명령(mkdir, mv 등)을 작업 공간 내에서 자동 허용 |
plan | Plan | 파일 읽기 및 코드 조사만 허용 (수정 계획이 승인될 때까지 모든 쓰기 차단) |
auto | Auto | 작업 공간 내 대부분의 작업을 허용하되, 별도의 안전 분류 모델이 위험 명령을 자동 판별하여 차단 |
dontAsk | 없음 (비대화형) | 사전 승인된 도구만 실행하고, 사용자 질문이 필요한 상황은 즉시 실패 처리 (CI/자동화 스크립트용) |
bypassPermissions | Bypass | 모든 승인 생략 (완전히 격리된 일회용 컨테이너나 가상머신 환경 전용) |
세션 진행 중에는 Shift+Tab 단축키로 권한 모드를 빠르게 전환할 수 있습니다. 단, 자율성이 높은 auto나 bypassPermissions 모드는 보안을 위해 프로젝트 공용 설정이 아닌 사용자 개인 설정(~/.claude/settings.json)이나 명령행 플래그를 통해서만 활성화할 수 있습니다.
도구별 권한 규칙 평가 체계
권한 모드가 세션 전체의 기본 자율성을 결정한다면, settings.json의 **권한 규칙(Permissions Rules)**은 개별 도구 호출에 대한 정밀한 접근 제어를 수행합니다.
규칙은 Tool 또는 Tool(패턴) 형태로 작성하며, 다음과 같이 Deny → Ask → Allow의 고정된 우선순위로 평가됩니다.
{
"permissions": {
"allow": [
"Bash(npm run test *)",
"Bash(npm run lint)"
],
"deny": [
"Read(./.env*)",
"Bash(rm -rf *)"
]
}
}- Deny 절대 우선의 원칙: 규칙의 구체성과 상관없이
deny규칙이allow보다 항상 먼저 평가됩니다. 프로젝트 설정에서 특정 명령을allow했더라도, 상위나 하위 설정에서deny되어 있다면 예외 없이 실행이 차단됩니다. - 권한 모드 무력화 불가: 가장 자율적인
bypassPermissions모드라 하더라도 명시적으로 설정된deny규칙을 우회할 수는 없습니다. - 신뢰 검증(Trust): 프로젝트 설정 파일(
.claude/settings.json)의allow규칙은 사용자가 해당 작업 공간을 신뢰(Trust)하기 전까지는 활성화되지 않으며,deny규칙만 즉시 유효하게 적용됩니다.
연관 노트와 구현
이 기본 구조 위에서 동작하는 상위 확장 체계와 비용 관리, 작업 공간 격리 방법은 아래 글에서 이어집니다.
- Claude Code 확장 단위: 스킬, 서브에이전트, 플러그인이 각각 어느 런타임 레이어를 확장하는가
- Claude Code Agent Teams와 Subagent 차이점: 세션 구조 위에서 구현되는 단일 세션 위임과 다중 인스턴스 협업의 차이
- 컨텍스트 창과 토큰 비용: 에이전트 루프가 회전할 때 대화 기록이 컨텍스트 창과 API 비용에 미치는 영향
- git worktree: 디렉터리에 묶이는 세션 구조를 활용해 서로 다른 브랜치에서 안전하게 병렬 에이전트를 격리하는 기법