[Claude Code 마스터] #02 - 작동 원리: Agentic Loop 이해하기
Claude Code는 단순한 챗봇이 아닙니다. “에이전트(Agent)”라는 개념이 핵심인데요, 스스로 판단하고, 도구를 사용하고, 결과를 검증하는 자율적인 작업 루프를 수행합니다. 이번 편에서는 Claude Code의 심장이라 할 수 있는 Agentic Loop를 깊이 있게 이해해봅니다.
완독 시간: 20분 ⭐⭐⭐
🎯 이번에 배울 것
📚 사전 지식
- #01편: 시작하기 - Claude Code 설치 및 기본 사용법
📖 에이전트(Agent)란 무엇인가?
챗봇 vs 에이전트
일반적인 AI 챗봇과 에이전트의 차이를 이해하는 것이 중요합니다:
1
2
3
4
5
6
7
8
9
10
11
┌─────────────────────────────────────────────────────────────────┐
│ 챗봇 vs 에이전트 │
├─────────────────────────────┬───────────────────────────────────┤
│ 일반 챗봇 │ AI 에이전트 │
├─────────────────────────────┼───────────────────────────────────┤
│ 질문 → 답변 │ 목표 → 계획 → 실행 → 검증 │
│ 한 번에 하나의 응답 │ 여러 단계를 자율적으로 수행 │
│ 외부 도구 사용 불가 │ 다양한 도구 활용 │
│ 사용자가 모든 것을 지시 │ 스스로 판단하고 결정 │
│ 결과 검증 불가 │ 결과를 검증하고 수정 │
└─────────────────────────────┴───────────────────────────────────┘
실생활 비유: 인턴 vs 시니어 개발자
일반 챗봇 (인턴처럼)
“이 함수 어떻게 고쳐요?” → 코드 조각 제시 → 사용자가 직접 복사해서 붙여넣기 → 에러 나면 다시 질문
Claude Code (시니어 개발자처럼)
“이 함수 고쳐줘” → 관련 파일들 찾아서 읽음 → 문제 원인 분석 → 수정 코드 작성 → 직접 파일 수정 (승인 후) → 테스트 실행해서 검증 → 문제 있으면 자동 수정
🔄 Agentic Loop의 3단계
Claude Code가 작업을 수행할 때 거치는 핵심 사이클입니다.
전체 흐름도
flowchart LR
A[사용자 요청] --> B[1. Context<br/>맥락 파악]
B --> C[2. Action<br/>행동 수행]
C --> D[3. Verify<br/>결과 검증]
D -->|완료| E[결과 반환]
D -->|추가 작업 필요| B
style A fill:#e1f5fe
style B fill:#fff3e0
style C fill:#e8f5e9
style D fill:#fce4ec
style E fill:#f3e5f5
단계 1: Context (맥락 파악) 🔍
Claude가 가장 먼저 하는 일은 상황을 이해하는 것입니다.
수행하는 작업:
- 프로젝트 구조 파악
- 관련 파일 찾기 및 읽기
- Git 상태 확인
- 의존성 분석
사용하는 도구:
Glob: 파일 패턴으로 검색Grep: 내용으로 검색Read: 파일 읽기LS: 디렉토리 구조 확인
예시:
1
2
3
4
5
6
7
사용자: "인증 관련 버그 고쳐줘"
Claude의 Context 단계:
1. "auth", "login", "authentication" 키워드로 파일 검색
2. 찾은 파일들 읽기
3. 관련 테스트 파일 확인
4. 최근 커밋에서 변경사항 확인
단계 2: Action (행동 수행) ⚡
맥락을 파악한 후 실제 작업을 수행합니다.
수행하는 작업:
- 파일 생성/수정/삭제
- 명령어 실행
- 테스트 수행
사용하는 도구:
Write: 새 파일 생성Edit: 기존 파일 수정Bash: 터미널 명령 실행WebSearch: 웹 검색
예시:
1
2
3
4
5
6
7
사용자: "로그인 함수에 입력 검증 추가해줘"
Claude의 Action 단계:
1. auth.js 파일 열기
2. 입력 검증 로직 작성
3. 파일 수정 (사용자 승인 후)
4. 관련 테스트 추가
단계 3: Verify (결과 검증) ✅
작업이 끝나면 결과를 확인하고 검증합니다.
수행하는 작업:
- 테스트 실행
- 린트/타입 체크
- 빌드 확인
- 변경사항 검토
예시:
1
2
3
4
5
Claude의 Verify 단계:
1. npm test 실행
2. 테스트 통과 확인
3. 실패하면 → 다시 Action 단계로
4. 성공하면 → 결과 보고
Loop의 반복
중요한 점은 이 과정이 반복된다는 것입니다:
flowchart TD
A[테스트 실패] --> B[에러 분석]
B --> C[코드 수정]
C --> D[다시 테스트]
D -->|실패| A
D -->|성공| E[완료!]
실제로 Claude Code에게 “테스트 실패하면 고쳐줘”라고 하면:
- 테스트 실행 → 실패
- 에러 메시지 분석
- 코드 수정
- 테스트 재실행
- 또 실패하면 다시 2번부터 반복
- 성공할 때까지 (또는 한계에 도달할 때까지)
🛠️ 내장 도구(Tools) 알아보기
Claude Code가 실제로 “손”처럼 사용하는 도구들입니다.
도구 카테고리
| 카테고리 | 도구 | 설명 |
|---|---|---|
| 파일 작업 | Read, Write, Edit | 파일 읽기/생성/수정 |
| 검색 | Glob, Grep | 파일명/내용 검색 |
| 실행 | Bash | 터미널 명령 실행 |
| 웹 | WebSearch, WebFetch | 웹 검색, 문서 조회 |
| Git | (Bash 통해) | 버전 관리 작업 |
주요 도구 상세 설명
1. Read (파일 읽기)
1
2
3
4
5
Claude가 "Read" 도구를 사용할 때:
- 파일 전체 또는 특정 라인 범위 읽기
- 이미지 파일도 분석 가능 (멀티모달)
- PDF 파일 읽기 지원
- Jupyter 노트북(.ipynb) 읽기 지원
2. Edit (파일 수정)
1
2
3
4
Claude가 "Edit" 도구를 사용할 때:
- 특정 부분만 정밀하게 수정
- 변경 전/후를 미리보기로 표시
- 사용자 승인 후에만 실제 적용
3. Bash (명령 실행)
1
2
3
4
Claude가 "Bash" 도구를 사용할 때:
- npm, pip, git 등 모든 CLI 도구 사용 가능
- 테스트 실행, 빌드, 서버 시작 등
- 위험한 명령은 별도 승인 필요
4. Glob & Grep (검색)
1
2
3
4
5
6
7
Glob: 파일명 패턴으로 찾기
- "**/*.ts" → 모든 TypeScript 파일
- "src/components/*.tsx" → 특정 폴더의 React 컴포넌트
Grep: 파일 내용으로 찾기
- "function login" → login 함수 찾기
- "TODO" → 모든 TODO 주석 찾기
도구 사용 권한
Claude Code는 안전을 위해 권한 시스템을 갖추고 있습니다:
| 도구 | 기본 권한 | 설명 |
|---|---|---|
| Read, Glob, Grep | 자동 허용 | 읽기 전용이므로 안전 |
| Edit, Write | 승인 필요 | 파일 변경 전 확인 |
| Bash | 명령별 승인 | 위험도에 따라 다름 |
권한 모드 전환 (Shift+Tab):
- Default: 기본 - 수정/실행 시 승인 필요
- Accept Edits: 파일 수정 자동 승인
- Plan Mode: 읽기 전용 (탐색만)
📦 컨텍스트 윈도우 이해하기
컨텍스트 윈도우란?
Claude가 한 번에 “기억”할 수 있는 정보의 양입니다.
1
2
3
4
5
6
7
8
┌─────────────────────────────────────────────────────────────────┐
│ 컨텍스트 윈도우 구성 │
├─────────────────────────────────────────────────────────────────┤
│ 시스템 프롬프트 │ CLAUDE.md │ 대화 기록 │ 파일 내용 │
│ (Claude Code 기본) │ (프로젝트) │ (현재 세션) │ (읽은 것) │
└─────────────────────────────────────────────────────────────────┘
↓
모두 합쳐서 토큰 한도 내
컨텍스트가 가득 차면?
Claude Code는 자동으로 컴팩션(압축)을 수행합니다:
- 오래된 도구 출력 정리: 이전에 읽은 파일 내용 등
- 대화 요약: 긴 대화를 핵심만 추려서
- 중요 정보 유지: 최근 요청과 핵심 코드는 보존
컨텍스트 관리 명령어
1
2
3
/context # 현재 컨텍스트 사용량 확인
/compact # 수동으로 컨텍스트 압축
/clear # 대화 기록 완전 초기화
컨텍스트 관리 팁
1. CLAUDE.md 활용
1
2
3
4
# CLAUDE.md
중요한 규칙은 여기에 작성하면 항상 유지됩니다.
대화 중에 말한 내용은 압축될 수 있지만,
CLAUDE.md 내용은 항상 참조됩니다.
2. 불필요한 출력 줄이기
1
2
❌ "모든 파일 내용 보여줘"
✅ "인증 관련 파일만 보여줘"
3. Subagent 활용 복잡한 탐색 작업은 Subagent에게 위임하면 메인 컨텍스트가 깔끔하게 유지됩니다. (06편에서 자세히)
💾 세션과 체크포인트 관리
세션이란?
Claude Code와의 대화 단위입니다. 프로젝트 디렉토리별로 관리됩니다.
1
2
3
claude # 새 세션 시작
claude -c # 가장 최근 세션 이어하기
claude --resume # 세션 선택해서 이어하기
세션 관리 명령어
| 명령어 | 설명 |
|---|---|
/resume | 이전 세션 목록 보기 및 복원 |
/rename | 현재 세션 이름 지정 |
세션에 이름 붙이기 (권장!)
1
/rename auth-refactoring
나중에 이름으로 쉽게 찾을 수 있습니다:
1
claude --resume auth-refactoring
체크포인트: 안전한 되돌리기
Claude Code는 파일을 수정하기 전에 자동으로 스냅샷을 저장합니다.
flowchart LR
A[원본 파일] -->|Edit 전| B[체크포인트 저장]
B --> C[파일 수정]
C -->|문제 발생| D[Esc 두 번]
D --> E[이전 상태로 복원]
되돌리기 방법:
Esc두 번 누르기 → 이전 체크포인트로- “undo” 또는 “되돌려줘” 요청
- Git을 통한 복원
⚠️ 주의: 체크포인트는 파일 변경만 저장합니다. 외부 시스템(DB, API 등)에 대한 작업은 되돌릴 수 없어요!
🧪 실습: Agentic Loop 관찰하기
실제로 Agentic Loop가 어떻게 동작하는지 관찰해봅시다.
Verbose 모드 켜기
Ctrl+O를 눌러 Verbose 모드를 활성화하면 Claude의 내부 동작을 볼 수 있습니다.
테스트 요청
1
이 프로젝트의 테스트를 실행하고, 실패하는 게 있으면 고쳐줘
관찰 포인트:
- 어떤 순서로 파일을 찾는지
- 어떤 도구를 사용하는지
- 테스트 실패 시 어떻게 재시도하는지
- 몇 번의 Loop를 도는지
📝 오늘 배운 것 정리
✅ 에이전트 = 스스로 판단하고 도구를 사용하는 AI
✅ Agentic Loop = Context(파악) → Action(실행) → Verify(검증) 반복
✅ 내장 도구: Read/Write/Edit(파일), Bash(명령), Glob/Grep(검색)
✅ 컨텍스트 윈도우: Claude의 “작업 기억” - 자동 압축됨
✅ 체크포인트: 파일 수정 전 자동 저장 → Esc 두 번으로 복원
🔗 다음 편 미리보기
이론을 알았으니 실전입니다! 개발자가 매일 하는 작업들을 Claude Code로:
- 새 프로젝트/코드베이스 파악하기
- 버그 찾고 고치기
- 리팩토링하기
- 테스트 작성하기
- PR 만들기
🔗 시리즈 전체 보기
| # | 제목 | 상태 |
|---|---|---|
| 01 | 시작하기: 설치부터 첫 세션까지 | ✅ 완료 |
| 02 | 작동 원리: Agentic Loop 이해하기 | 📖 현재 글 |
| 03 | 일상 워크플로우: 실전 활용법 | 🔜 다음 편 |
| 04 | 메모리 관리: CLAUDE.md 완전 정복 | 예정 |
| 05 | Skills: 나만의 슬래시 명령어 만들기 | 예정 |
| 06 | Subagents: AI 분업 시스템 구축 | 예정 |
| 07 | MCP: 외부 도구 연결하기 | 예정 |
| 08 | IDE 통합: 어디서든 Claude Code | 예정 |
| 09 | GitHub Actions: CI/CD 자동화 | 예정 |
| 10 | 팀 협업: AI 시대의 개발 문화 | 예정 |
🔗 참고 자료
🚀 원리를 이해하면, 활용이 달라집니다!