Claude Code의 작동 방식

1. Claude Code란 무엇인가?

Claude Code는 터미널(명령줄)에서 실행되는 AI 개발 어시스턴트입니다.

단순히 "코드를 짜줘"라고 대답만 하는 채팅 AI가 아닙니다. 직접 파일을 열고, 수정하고, 테스트를 실행하고, Git 커밋까지 할 수 있는 행동하는 AI입니다.

코딩은 물론 다음과 같은 작업도 도와줍니다:

• 문서 작성 및 검토
• 빌드/배포 실행
• 파일 검색 및 정리
• 웹 검색 및 정보 조사

---

2. 핵심 개념: 에이전트 루프

Claude Code의 가장 중요한 개념은 에이전트 루프(Agentic Loop) 입니다.

작업을 받으면 아래 세 단계를 완료될 때까지 반복합니다.

┌──────────────────────────────────────────────────┐
│                                                  │
│  [1단계] 컨텍스트 수집                              │
│          → 관련 파일을 읽고 상황을 파악              │
│                  ↓                               │
│  [2단계] 작업 수행                                 │
│          → 파일 수정, 명령어 실행                   │
│                  ↓                               │
│  [3단계] 결과 검증                                 │
│          → 테스트 실행, 오류 확인                   │
│                  ↓                               │
│         완료? → YES → 종료                        │
│                ↓ NO                              │
│         다시 1단계부터 반복                         │
│                                                  │
└──────────────────────────────────────────────────┘

실제 예시로 이해하기

"테스트가 실패해, 고쳐줘" 라고 입력하면?

1. 테스트를 실행해서 무엇이 실패하는지 확인
2. 오류 메시지를 읽음
3. 관련 소스 파일을 검색해서 찾아냄
4. 파일을 읽고 코드를 이해
5. 코드를 수정
6. 테스트를 다시 실행해서 검증

이 모든 과정을 Claude가 스스로 판단하며 진행합니다. 중간에 방향을 잡아주면 즉시 조정도 가능합니다.

💡 핵심 포인트: 에이전트 루프는 "자율적으로 작동하지만 사용자 입력에 반응"합니다. 언제든지 중단하거나 방향을 바꿀 수 있어요.

---

3. AI의 손과 눈 — 도구(Tools)

도구가 없으면 Claude는 텍스트로만 응답하는 AI입니다. 도구가 있으면 실제로 행동할 수 있는 AI가 됩니다.

도구 종류	할 수 있는 일
📁 파일 작업	코드 읽기, 수정, 새 파일 생성, 이름 변경
🔍 검색	패턴으로 파일 찾기, 정규식으로 내용 검색
⚡ 실행	터미널 명령어, 서버 시작, 테스트, git
🌐 웹	구글 검색, 공식 문서 가져오기, 오류 조회
🧠 코드 인텔리전스	타입 오류 확인, 함수 정의 찾기

각 도구 사용 결과는 루프에 다시 피드백되어 다음 판단의 근거가 됩니다.

내장 도구 외에도 다음으로 기능을 확장할 수 있습니다:

• Skills: Claude가 알 수 있는 지식 확장
• MCP: 외부 서비스 연결 (Google Drive, Slack 등)
• Hooks: 워크플로우 자동화
• Subagents: 작업 위임

---

4. Claude가 볼 수 있는 것

프로젝트 폴더에서 claude를 실행하면 다음에 접근할 수 있습니다.

📂 프로젝트 폴더
  ├── 프로젝트 파일 전체       ← 현재 폴더 + 하위 폴더 모두
  ├── 터미널 명령어 실행 권한   ← 명령줄에서 되는 건 다 가능
  ├── Git 상태               ← 현재 브랜치, 변경 파일, 커밋 내역
  ├── CLAUDE.md              ← "이 프로젝트 규칙" 저장 파일
  └── 자동 메모리             ← 이전 세션에서 기억한 것들

일반 코드 어시스턴트와의 차이

구분	일반 코드 자동완성	Claude Code
볼 수 있는 범위	현재 열린 파일만	프로젝트 전체
파일 수정	제안만	직접 수정
명령어 실행	불가	가능
테스트 실행	불가	가능

💡 예시: "인증 버그를 수정해줘" 라고 하면, 관련 파일을 스스로 찾아서, 여러 파일을 읽고, 조정된 편집을 수행하고, 테스트로 검증하고, 요청하면 커밋까지 합니다.

---

5. 세션으로 작업하기

Claude Code는 작업 내용을 세션(Session) 단위로 저장합니다.

세션의 특징

• 세션은 독립적입니다. 새 세션은 이전 대화 내용 없이 시작됩니다.
• 자동 메모리로 프로젝트 패턴, 선호도를 세션 간에 유지할 수 있습니다.
• 파일 변경 전 스냅샷을 찍어 되돌리기가 가능합니다.

세션 명령어

# 이전 세션 이어서 계속
claude --continue

# 특정 세션 선택해서 재개
claude --resume

# 원본은 그대로, 다른 방향으로 실험
claude --continue --fork-session

세션 재개 vs 포크

[원본 세션] ──────────────────────────────→ (재개)
              │
              └──→ [포크 세션 A] (다른 접근법 시도)
              └──→ [포크 세션 B] (또 다른 시도)

포크는 구글 문서의 "사본 만들기" 와 같습니다. 원본은 그대로 두고 복사본에서 실험할 수 있어요.

⚠️ 주의: 여러 터미널에서 동일한 세션을 동시에 사용하면 대화가 뒤섞일 수 있습니다. 병렬 작업 시에는 --fork-session을 사용하세요.

---

6. 컨텍스트 윈도우 이해하기

컨텍스트 윈도우는 Claude의 단기 기억 같은 개념입니다.

컨텍스트 윈도우에 담기는 것들:

• 대화 기록
• 읽은 파일 내용
• 실행한 명령어 결과
• CLAUDE.md 내용
• 자동 메모리
• 로드된 Skills

대화가 길어지면 오래된 내용이 자동으로 압축/삭제될 수 있습니다.

컨텍스트 관리 팁

# 현재 컨텍스트 사용량 확인
/context

# MCP 서버별 컨텍스트 비용 확인
/mcp

# 대화 압축 (포커스 지정 가능)
/compact focus on the API changes

방법	설명
CLAUDE.md 활용	항상 기억해야 할 규칙을 파일로 저장
/compact 명령	대화 압축으로 공간 확보
Subagents 활용	별도 컨텍스트에서 작업 위임

💡 팁: 대화 초반에 설정한 규칙이 나중에 잊혀질 수 있습니다. 중요한 규칙은 반드시 CLAUDE.md에 저장하세요.

---

7. 안전 장치: 체크포인트와 권한 모드

"AI가 실수로 코드를 망가뜨리면 어떡하지?"라는 걱정, 당연합니다.
두 가지 안전 장치가 있어요.

체크포인트 — 언제든 되돌리기

파일을 수정하기 전에 자동으로 스냅샷을 찍어둡니다.

파일 수정 시작
  ↓
📸 스냅샷 자동 저장
  ↓
파일 수정 완료
  ↓
문제 발생? → Esc 두 번 또는 "취소해줘" → 이전 상태로 복원

⚠️ 주의: 체크포인트는 파일 변경만 다룹니다. 데이터베이스나 API 호출 같은 외부 시스템은 되돌릴 수 없어요.

권한 모드 — Shift+Tab으로 전환

모드	설명	추천 대상
기본	파일 수정/명령 실행 전 항상 물어봄	처음 시작하는 분
편집 자동수락	파일은 그냥 수정, 명령어는 물어봄	중급 사용자
계획 모드	실행 전에 계획만 먼저 보여줌	신중한 작업 시
자동 모드	모두 알아서 판단	경험자, 자동화

---

8. 실전 활용 팁

✅ 처음부터 구체적으로 작성하기

❌ 나쁜 예:
"로그인 버그 수정해"

✅ 좋은 예:
"체크아웃 흐름이 만료된 카드를 가진 사용자에게 오류가 납니다.
관련 코드는 src/payments/ 폴더에 있어요.
먼저 실패하는 테스트를 작성한 다음 수정해주세요."

✅ 중간에 방향 수정하기

완벽한 프롬프트 없어도 됩니다. 대화하면서 조금씩 수정하면 됩니다.

나: "로그인 버그 수정해"
Claude: [조사하고 시도]
나: "그 방향이 아닌 것 같아요. 세션 처리 쪽을 봐주세요."
Claude: [접근 방식 조정]

✅ 검증 가능한 것 함께 제공하기

"validateEmail 함수를 구현해줘.
테스트 케이스: 
- 'user@example.com' → true
- 'invalid' → false  
- 'user@' → false
구현 후 테스트도 바로 실행해줘."

✅ 복잡한 기능은 계획 먼저

1. Shift+Tab 두 번 → 계획 모드 진입
2. "src/auth/를 읽고 OAuth 추가 계획을 세워줘"
3. 계획 검토 후 대화로 개선
4. 계획이 마음에 들면 실행 모드로 전환

✅ 위임하기 (단계별 지시 대신)

❌ 지시하는 방식:
"user.js 열고, validateEmail 함수 찾아서, 정규식 수정해"

✅ 위임하는 방식:
"이메일 유효성 검증 버그가 있어요. 관련 코드는 src/user/에 있습니다.
조사하고 수정해주실 수 있나요?"

---

9. 마무리

Claude Code의 핵심을 한 줄로 요약하면:

"읽고 → 수정하고 → 확인하는 루프를 반복하는, 실제로 행동할 수 있는 AI 개발 어시스턴트"

핵심 정리:

• 에이전트 루프: 컨텍스트 수집 → 작업 수행 → 결과 검증을 반복
• 도구: 파일 작업, 검색, 실행, 웹 등 실제로 행동 가능
• 세션: 대화 단위로 저장, 재개/포크 가능
• 컨텍스트 윈도우: AI의 단기 기억, CLAUDE.md로 중요 규칙 유지
• 안전 장치: 체크포인트(되돌리기) + 권한 모드(제어)

처음에는 계획 모드로 시작해서 Claude의 판단을 확인하고, 신뢰가 쌓이면 자동 모드로 전환하는 방식을 추천합니다.

---

📌 참고 문서: Claude Code 공식 한국어 문서