Agentic Loop 작동 원리

들어가며

이전 차시에서 Claude Code의 첫 번째 코딩 세션을 진행했다. 프로젝트를 분석하고, 코드를 수정하고, Git으로 변경사항을 관리하는 과정을 경험했다.

이 과정에서 Claude Code가 파일을 스스로 찾고, 읽고, 수정하고, 테스트까지 실행하는 모습을 봤을 것이다. 일반적인 AI 챗봇은 질문에 답변만 하고 끝나지만, Claude Code는 목표를 달성할 때까지 자율적으로 작업을 반복한다.

이번 차시에서는 이 자율 실행 메커니즘의 핵심인 Agentic Loop의 작동 원리를 다룬다.

Agentic Loop란

일반 AI와 Agentic AI의 차이

일반적인 AI 챗봇은 한 번의 질문에 한 번의 답변을 반환하고 끝난다.

사용자 질문 → AI 응답 → 종료

Claude Code는 다르다. 사용자의 요청을 받으면 목표를 달성할 때까지 여러 단계를 반복적으로 수행한다.

사용자 요청 → [컨텍스트 수집 → 행동 → 결과 검증] → 반복 → 최종 응답

이 반복 실행 구조를 Agentic Loop라고 한다. Claude Code가 “에이전트”로 불리는 이유가 바로 이 루프 때문이다.

세 가지 단계

공식 문서에 따르면, Claude Code는 작업을 수행할 때 세 가지 단계를 거친다.

1. 컨텍스트 수집(Gather Context): 파일을 검색하고 읽어서 코드를 이해한다
2. 행동(Take Action): 파일을 수정하거나 명령을 실행한다
3. 결과 검증(Verify Results): 테스트를 실행하거나 빌드를 확인해서 작업 결과를 검증한다

이 세 단계는 명확하게 분리되지 않는다. 서로 자연스럽게 섞이면서 진행된다. 코드를 읽다가 수정이 필요하면 바로 수정하고, 수정 후 바로 테스트를 실행하는 식이다.

요청의 종류에 따라 루프의 형태도 달라진다.

• 코드 질문: 컨텍스트 수집만으로 끝날 수 있다
• 버그 수정: 세 단계를 여러 번 반복한다
• 리팩토링: 검증 단계에 많은 시간을 쓴다

Claude는 이전 단계에서 얻은 정보를 바탕으로 다음에 무엇을 할지 판단한다. 수십 개의 작업을 연결하면서 필요에 따라 방향을 수정한다.

Agentic Harness

Agentic Loop를 가능하게 하는 두 가지 핵심 구성 요소가 있다.

• 모델(Model): 코드를 이해하고 추론하는 역할. 어떤 파일을 읽을지, 어떻게 수정할지 판단한다
• 도구(Tool): 실제 행동을 수행하는 역할. 파일 읽기, 코드 수정, 명령 실행 등을 담당한다

Claude Code는 이 두 요소를 연결하는 에이전틱 하네스(Agentic Harness) 역할을 한다. 도구, 컨텍스트 관리, 실행 환경을 제공해서 언어 모델을 코딩 에이전트로 만드는 것이다.

도구가 없으면 Claude는 텍스트로만 응답할 수 있다. 도구가 있기 때문에 파일을 읽고, 코드를 수정하고, 명령을 실행할 수 있다. 각 도구 사용의 결과는 루프에 다시 피드백되어 Claude의 다음 판단에 영향을 미친다.

도구 실행 흐름

도구 카테고리

Claude Code의 내장 도구는 크게 다섯 가지 카테고리로 나뉜다.

주요 내장 도구

공식 도구 레퍼런스에서 자주 사용하는 핵심 도구를 정리하면 다음과 같다.

읽기 전용 도구(Read, Glob, Grep)는 권한 없이 자동 실행된다. 파일을 변경하거나 명령을 실행하는 도구(Edit, Write, Bash)는 사용자 승인이 필요하다.

이 외에도 TaskCreate, TaskUpdate, CronCreate, ToolSearch, Skill 등 다양한 도구가 있다. 전체 목록은 Tools reference에서 확인할 수 있다.

실제 도구 실행 예시

“실패하는 테스트를 수정해줘”라고 요청했을 때 Claude가 도구를 사용하는 흐름을 보자.

1. [Bash] npm test          → 테스트 실행, 실패 내역 확인
2. [Read] 에러 출력          → 에러 메시지 분석
3. [Grep] 관련 소스 파일 검색  → 문제 위치 파악
4. [Read] 소스 파일 읽기      → 코드 이해
5. [Edit] 소스 파일 수정      → 버그 수정
6. [Bash] npm test          → 테스트 재실행으로 검증

각 도구 사용이 Claude에게 새로운 정보를 제공하고, 그 정보가 다음 단계를 결정한다. 이것이 Agentic Loop의 실제 동작이다.

도구 선택의 자율성

Claude는 프롬프트와 이전 단계에서 얻은 정보를 바탕으로 어떤 도구를 사용할지 스스로 결정한다. 사용자가 “어떤 파일을 읽어라”, “어떤 명령을 실행해라”라고 일일이 지시할 필요가 없다.

예를 들어 “로그인 버그를 수정해줘”라고만 요청하면, Claude는 다음 과정을 자율적으로 수행한다.

루프 1: 파일 탐색

[Glob] src/**/*login*.ts
→ 로그인 관련 파일 발견
  - src/pages/Login.tsx
  - src/services/auth.ts
  - src/hooks/useLogin.ts

루프 2: 코드 분석

[Read] src/pages/Login.tsx
[Read] src/services/auth.ts
→ 버그 위치 파악: auth.ts의 validatePassword 함수

루프 3: 코드 수정

[Edit] src/services/auth.ts
→ 버그 수정 (사용자 승인 필요)

루프 4: 검증

[Bash] npm test -- auth.test.ts
→ 테스트 통과 확인

사용자는 결과를 확인하고 승인만 하면 된다.

에러 처리와 자동 복구

Claude는 에러가 발생하면 자동으로 원인을 분석하고 수정을 시도한다.

[Bash] npm run build
→ 오류: TypeScript 타입 에러

[자동 분석]
→ 타입 불일치 발견

[Edit] src/utils/helper.ts
→ 타입 수정

[Bash] npm run build
→ 성공

자동으로 해결할 수 없는 에러가 발생하면 사용자에게 도움을 요청한다.

"이 에러를 해결하려면 환경 변수 DATABASE_URL이 필요합니다.
설정 방법을 알려주시겠습니까?"

병렬 도구 실행

독립적인 작업은 병렬로 실행해서 시간을 절약한다.

순차 실행 (의존성이 있는 경우):

[Read] src/utils/helper.ts    → 먼저 읽기
  ↓
[Edit] src/utils/helper.ts    → 그 다음 수정

병렬 실행 (독립적인 경우):

[Read] src/componentA.tsx  ─┐
[Read] src/componentB.tsx  ─┤ 동시 실행
[Read] src/componentC.tsx  ─┘

파일을 수정하려면 먼저 읽어야 하므로 순차 실행이 필요하다. 하지만 여러 파일을 읽기만 하는 경우 병렬로 동시에 처리한다.

사용자 개입

Agentic Loop는 완전히 자율적이지만 사용자도 루프의 일부다. 언제든 Claude의 작업을 중단하고 방향을 바꿀 수 있다.

• 중단: 작업 중 Enter를 눌러 입력하면 Claude가 현재 작업을 멈추고 새 입력에 반응한다
• 방향 전환: “그게 아니라 세션 처리 쪽이 문제야”라고 하면 Claude가 접근 방식을 변경한다
• 승인/거부: 파일 수정이나 명령 실행 시 y(승인), n(거부), e(편집)를 선택할 수 있다

Claude가 끝날 때까지 기다리거나 처음부터 다시 시작할 필요가 없다. 대화하듯이 방향을 잡아가면 된다.

컨텍스트 관리

컨텍스트 윈도우란

컨텍스트 윈도우는 Claude가 한 번에 참조할 수 있는 정보의 총량이다. 대화 기록, 읽은 파일 내용, 명령 실행 결과 등이 모두 이 공간에 쌓인다.

컨텍스트 윈도우의 크기는 모델에 따라 다르다. 기본적으로 200K 토큰을 지원한다.

컨텍스트에 자동으로 로드되는 것

세션이 시작되면 다음 항목이 자동으로 컨텍스트에 로드된다.

이후 사용자의 프롬프트와 Claude의 도구 사용 결과가 계속 쌓인다.

컨텍스트가 채워지는 과정

실제 작업에서 컨텍스트가 어떻게 채워지는지 보자.

1단계: 세션 시작 (~8,000 토큰)

시스템 프롬프트, CLAUDE.md, 메모리 등이 자동 로드된다.

2단계: 사용자 프롬프트 (~50 토큰)

"인증 버그를 수정해줘. 토큰 갱신 후 401 에러가 발생해"

3단계: 파일 읽기 (5,00010,000 토큰)

Claude가 관련 파일을 읽으면서 컨텍스트가 빠르게 증가한다.

[Read] src/api/auth.ts        → ~2,400 토큰
[Read] src/lib/tokens.ts      → ~1,100 토큰
[Read] src/middleware.ts       → ~1,800 토큰
[Read] src/auth.test.ts       → ~1,600 토큰
[Grep] "refreshToken"         → ~600 토큰

파일 읽기가 컨텍스트 사용량의 대부분을 차지한다. 구체적인 프롬프트를 작성하면 Claude가 더 적은 파일만 읽어서 효율적이다.

4단계: 수정 및 검증

[Edit] src/api/auth.ts        → ~400 토큰
[Edit] src/auth.test.ts       → ~600 토큰
[Bash] npm test               → ~1,200 토큰

5단계: 최종 응답

Claude의 분석 및 결과 설명     → ~800 토큰

자동 압축 (Compaction)

컨텍스트가 한계에 가까워지면 Claude Code가 자동으로 압축을 수행한다.

압축 순서는 다음과 같다.

1. 오래된 도구 출력 제거: 이전에 읽은 파일 내용, 명령 실행 결과 등을 먼저 제거한다
2. 대화 요약: 필요하면 이전 대화 내용을 요약한다

사용자의 요청과 핵심 코드 조각은 보존된다. 하지만 대화 초반의 상세한 지시사항은 손실될 수 있다.

수동으로 압축할 수도 있다.

# 수동 압축
> /compact

# 특정 주제에 집중해서 압축
> /compact API 변경사항에 집중해줘

현재 컨텍스트 사용량을 확인하려면 /context 명령을 사용한다.

> /context

컨텍스트 관리 전략

CLAUDE.md에 중요한 규칙 기록

대화 기록에 의존하지 말고, 반복적으로 필요한 규칙은 CLAUDE.md에 작성한다. CLAUDE.md는 매 세션 시작 시 자동으로 로드되고, 압축 후에도 유지된다.

# CLAUDE.md
- 테스트는 반드시 vitest로 실행한다
- 커밋 메시지는 Conventional Commits 형식을 따른다
- src/generated/ 디렉토리는 수정하지 않는다

CLAUDE.md에 Compact Instructions 추가

CLAUDE.md에 “Compact Instructions” 섹션을 추가하면 압축 시 어떤 내용을 보존할지 제어할 수 있다.

## Compact Instructions
- API 엔드포인트 변경사항을 항상 기억할 것
- 현재 작업 중인 브랜치 정보를 유지할 것

스킬로 필요할 때만 로드

스킬은 기본적으로 한 줄 설명만 컨텍스트에 로드된다. 전체 내용은 Claude가 실제로 사용할 때만 로드된다. 수동으로만 호출하는 스킬에는 disable-model-invocation: true를 설정하면 설명도 컨텍스트에 포함되지 않는다.

서브에이전트로 컨텍스트 분리

서브에이전트는 자체적인 컨텍스트 윈도우를 가진다. 메인 대화와 완전히 분리되어 작업하고, 완료되면 요약만 반환한다.

리서치처럼 많은 파일을 읽어야 하는 작업은 서브에이전트에 위임하면 메인 컨텍스트가 비대해지는 것을 방지할 수 있다.

> 이 프로젝트의 인증 시스템을 분석해줘

Claude → [Agent] 서브에이전트 생성
  서브에이전트: 20개 파일 읽기, 분석
  → 메인에 요약만 반환 (~500 토큰)

서브에이전트를 사용하지 않았다면 20개 파일의 전체 내용이 메인 컨텍스트에 쌓였을 것이다.

세션 간 컨텍스트

각 세션은 독립적이다. 새 세션은 이전 세션의 대화 기록을 갖지 않는다. 세션 간에 지식을 유지하는 방법은 두 가지다.

• Auto Memory: Claude가 작업 중 학습한 패턴, 선호도 등을 자동으로 MEMORY.md에 저장한다. 다음 세션에서 자동으로 로드된다
• CLAUDE.md: 프로젝트 규칙과 컨벤션을 직접 작성해서 매 세션마다 로드한다

이전 세션을 이어서 작업하려면 claude -c로 세션을 재개할 수 있다. 이 경우 이전 대화의 전체 컨텍스트가 복원된다.

정리

핵심 요점

1. Agentic Loop: Claude Code는 컨텍스트 수집, 행동, 결과 검증을 반복하면서 목표를 달성한다. 일반 AI 챗봇의 일회성 응답과 근본적으로 다른 방식이다

2. 도구 기반 실행: 도구가 Claude Code를 에이전트로 만든다. 파일 작업, 검색, 실행, 웹, 코드 인텔리전스 다섯 가지 카테고리의 도구를 자율적으로 조합해서 사용한다

3. 컨텍스트 윈도우: Claude가 참조할 수 있는 정보의 총량이다. 시스템 프롬프트, CLAUDE.md, 대화 기록, 도구 실행 결과가 모두 이 공간에 쌓인다

4. 자동 압축: 컨텍스트가 한계에 도달하면 자동으로 오래된 도구 출력을 제거하고 대화를 요약한다. /compact로 수동 압축도 가능하다

5. 컨텍스트 관리: CLAUDE.md에 중요한 규칙을 기록하고, 서브에이전트로 리서치 작업을 분리하면 컨텍스트를 효율적으로 사용할 수 있다

확인해볼 링크

• How Claude Code works - Claude Code
• Tools reference - Claude Code
• Explore the context window - Claude Code
• Create custom subagents - Claude Code

다음 단계

다음 차시에서는 Claude Code의 내장 도구를 하나씩 살펴본다. Read, Edit, Write, Bash, Glob, Grep 각 도구의 상세한 사용법과 도구 조합 전략을 다룬다.

참고 자료

• How Claude Code works - Claude Code
• Tools reference - Claude Code
• Explore the context window - Claude Code
• Create custom subagents - Claude Code