클로드코드 05-how-claude-code-works

1. Claude Code 작동 원리

참고: 에이전틱 루프, 내장 도구, 그리고 Claude Code가 프로젝트와 상호작용하는 방식

1.1. 에이전틱 루프 (Agentic Loop)

Claude Code는 세 단계를 반복하며 작업을 수행한다: 컨텍스트 수집 → 행동 수행 → 결과 검증. 이 단계들은 자연스럽게 섞여 있으며, Claude는 파일을 검색하거나 코드를 편집하거나 테스트를 실행하는 등의 도구를 상황에 맞게 사용한다.

[사용자 프롬프트] → [컨텍스트 수집] → [행동 수행] → [결과 검증] → ... 반복 ... → [완료]

이 루프는 요청에 따라 적응한다.

- 질문: 컨텍스트 수집만 필요할 수 있다.
- 버그 수정: 세 단계를 반복하며 진행한다.
- 리팩토링: 검증 단계가 더 많이 필요할 수 있다.

사용자는 언제든 루프를 중단하고 방향을 수정하거나 추가 컨텍스트를 제공할 수 있다.

1.1.1. 모델 (Models)

Claude Code는 Claude 모델을 사용해 코드를 이해하고 추론한다.

- Sonnet: 대부분의 코딩 작업에 적합
- Opus: 복잡한 아키텍처 결정에 강력한 추론 제공

세션 중 /model로 전환하거나 claude --model <name>으로 시작할 수 있다.

1.1.2. 도구 (Tools)

도구가 Claude Code를 에이전틱하게 만든다. 도구 없이는 텍스트만 응답할 수 있지만, 도구가 있으면 실제로 행동할 수 있다.

- 카테고리: Claude가 할 수 있는 일
- 파일 작업: 파일 읽기, 코드 편집, 새 파일 생성, 이름 변경/재구성
- 검색: 패턴으로 파일 찾기, regex로 내용 검색, 코드베이스 탐색
- 실행: 셸 명령어 실행, 서버 시작, 테스트 실행, git 사용
- 웹: 웹 검색, 문서 가져오기, 에러 메시지 조회
- 코드 인텔리전스: 편집 후 타입 에러/경고 확인, 정의로 이동, 참조 찾기

도구는 확장 가능하다. Skills, MCP, Hooks, Subagents 등으로 기능을 확장할 수 있다.

1.2. Claude가 접근할 수 있는 것

claude를 디렉토리에서 실행하면 다음에 접근할 수 있다.

- 프로젝트 파일: 현재 디렉토리 및 하위 디렉토리의 파일
- 터미널: 빌드 도구, git, 패키지 매니저, 시스템 유틸리티 등
- git 상태: 현재 브랜치, uncommitted 변경사항, 최근 커밋 히스토리
- CLAUDE.md: 프로젝트별 지시사항 파일
- Auto memory: Claude가 자동으로 저장한 학습 내역
- 확장 도구: MCP 서버, skills, subagents, Chrome 연동 등

1.3. 세션 관리

Claude Code는 대화를 로컬에 저장한다. 각 메시지, 도구 사용, 결과는 ~/.claude/projects/ 아래에 JSONL 파일로 기록된다.

1.3.1. 세션 특징

- 독립적: 각 새 세션은 새로운 컨텍스트 윈도우로 시작한다. 이전 대화 기록은 자동으로 이어지지 않는다.
- 브랜치 간 작업: 세션은 현재 디렉토리에 묶여 있다. 브랜치를 전환핵도 대화 기록은 유지된다.
- 병렬 세션: git worktree를 사용하면 별도 디렉토리에서 병렬 세션을 실행할 수 있다.

1.3.2. 세션 재개 및 분기

- 명령어/플래그: 기능
- claude --continue (-c): 같은 세션 ID로 이어서 진행
- claude --resume (-r): 이전 대화 재개
- --fork-session: 기존 세션 복사본을 새 세션 ID로 생성
- /branch: 세션 분기

1.4. 컨텍스트 윈도우

Claude의 컨텍스트 윈도우는 대화 기록, 파일 내용, 명령어 출력, CLAUDE.md, auto memory, 로드된 skills, 시스템 지시사항을 담는다.

1.4.1. 컨텍스트가 가득 찰 때

한도에 가까워지면 Claude Code가 자동으로 관리한다.

먼저 오래된 도구 출력을 지운다.
필요하면 대화를 요약한다.
사용자 요청과 핵심 코드 스니펫은 보존한다.

지속적으로 적용해야 할 규칙은 대화가 아닌 CLAUDE.md에 두는 것이 좋다.

참고: /context를 실행하면 현재 어떤 내용이 공간을 차지하고 있는지 확인할 수 있다.

1.4.2. 컨텍스트 관리 팁

- Skills: 필요할 때만 로드된다. disable-model-invocation: true로 설정하면 세션 시작 시 컨텍스트에 들어가지 않는다.
- Subagents: 별도의 새 컨텍스트를 가지므로 주 대화를 부풀리지 않는다.

1.5. 안전 메커니즘

1.5.1. Checkpoints로 되돌리기

Claude가 파일을 편집하기 전에 항상 스냅샷을 만든다. 문제가 생기면 Esc를 두 번 누르거나 /rewind를 실행해 이전 상태로 되돌릴 수 있다.

1.5.2. Permissions로 제어하기

Shift+Tab을 눌러 권한 모드를 전환할 수 있다.

- Default: 파일 편집과 셸 명령어 전에 묻는다.
- Auto-accept edits: 일반적인 파일시스템 명령어는 묻지 않고 실행한다.
- Plan mode: 읽기 전용 도구만 사용해 계획을 세운 뒤 승인받는다.
- Auto mode: 백그라운드 안전 검사로 작업을 평가한다. (연구 프리뷰)

1.6. 효과적으로 사용하기

1.6.1. Claude Code에게 도움 요청

"how do I set up hooks?", "what's the best way to structure my CLAUDE.md?" 등 질문하면 Claude Code가 설명한다.

- /init: 프로젝트용 CLAUDE.md 생성 가이드
- /agents: 커스텀 subagents 설정 도움
- /doctor: 설치 문제 진단

1.6.2. 대화형으로 작업하기

완벽한 프롬프트가 필요 없다. 원하는 것을 말하고 수정하면 된다.

Fix the login bug

Claude가 조사 후 시도하면:

That's not quite right. The issue is in the session handling.

Claude가 접근 방식을 조정한다.

1.6.3. 구체적으로 요청하기

The checkout flow is broken for users with expired cards.
Check src/payments/ for the issue, especially token refresh.
Write a failing test first, then fix it.

1.6.4. 검증 기준 제공하기

Implement validateEmail. Test cases: 'user@example.com' -> true,
'invalid' -> false, 'user@.com' -> false. Run the tests after.

1.6.5. 구현 전 탐색

복잡한 문제는 연구와 코딩을 분리한다. Plan mode(Shift+Tab 두 번)로 먼저 코드베이스를 분석한다.

Read src/auth/ and understand how we handle sessions.
Then create a plan for adding OAuth support.

1.6.6. 위임하기

능력 있는 동료에게 맡기듯이 맥락과 방향을 주고 세부사항은 Claude에게 맡긴다.

The checkout flow is broken for users with expired cards.
The relevant code is in src/payments/. Can you investigate and fix it?