[Claude Code] 에이전틱 루프와 EPIC 워크플로우 구축하기

1. 도입부 (Introduction)

소프트웨어 엔지니어링 생태계는 빠르게 변화하고 있다. 단순히 코드를 자동으로 완성해 주는 '익스텐션(Autocomplete)'의 시대를 넘어, 이제는 스스로 오류를 진단하고 코드를 작성한 뒤, 테스트 빌드를 수행하고 결과까지 검증하여 Git 커밋과 PR(Pull Request)까지 완료하는 '에이전틱 코딩(Agentic Coding)'의 시대가 도래했다.

그 패러다임 변화의 중심에 서 있는 것이 바로 Claude Code다. 웹 브라우저의 대화형 채팅창이나 IDE 플러그인의 한계를 극복하고, 개발자의 터미널 환경에 완전히 녹아들어 운영체제 파일 시스템을 직접 탐색하고 제어하는 이 도구는 백엔드 개발자들의 작업 생산성을 비약적으로 증가시킨다.

하지만 Claude Code를 가볍게 설치하고 기본 설정으로 사용하다 보면 금세 두 가지 장벽에 부딪히게 된다. 하나는 강력한 로컬 제어 권한을 어떻게 조율할 것인가에 대한 보안적 한계이고, 다른 하나는 질문이 누적될수록 기하급수적으로 늘어나는 토큰 요금(비용 폭탄) 문제다. 터미널 기반 AI 에이전트의 기본적인 기동 메커니즘을 명확하게 이해하지 않고 무작정 사용했다가는 유의미한 결과물 없이 엄청난 비용만 지불하게 될 수 있다.

이 글에서는 Claude Code의 내부 동작 아키텍처인 '에이전틱 루프(Agentic Loop)'부터 시작하여, 최적의 모델 구성 전략인 opusplan, 실제 작업 속도를 극대화하는 표준 워크플로우(EPIC Cycle), 그리고 실무에서 토큰 비용을 80% 이상 절감할 수 있는 구체적인 컨텍스트 조율 기법을 심층적으로 분석한다. 공부하며 정리해 둔 이 학습 노트가 여러분의 터미널 환경을 진정한 지능형 인프라로 전환하는 확실한 이정표가 되기를 바란다.

 

2. 주요 특징 및 핵심 로직 (Main Features & Logic)

Claude Code의 가장 큰 특징은 단순히 사용자의 텍스트 질문에 답변을 생성하는 것에 그치지 않고, 로컬 터미널 내부에서 독자적인 명령 수행 능력을 가진다는 점이다. 이는 내부에 구현된 에이전틱 루프(Agentic Loop)가 끊임없이 순환하며 결과물과 환경을 스스로 재평가하기 때문에 가능하다.

2.1 에이전틱 루프 (Agentic Loop)의 동작 메커니즘

전통적인 LLM 통신 방식은 사용자가 요청하면 즉시 답변을 반환하고 대기하는 일회성(Stateless/Passive) 구조다. 반면 Claude Code는 목표를 설정받으면 스스로 다음 단계의 행동을 계획하고, 적절한 도구(Command, API 등)를 사용해 실행한 뒤, 그 결과를 받아 다시 평가하는 폐루프 상태 머신(Closed-loop State Machine)을 가진다.

 

2.2 설정 범위(Scope)와 계층형 상속(Inheritance) 구조

Claude Code는 매우 세밀하게 나뉘어 있는 범위(Scope) 시스템을 통해 설정 파일이 관리된다. 이 계층 구조를 오해하면 로컬 프로젝트와 글로벌 시스템 간의 충돌이 발생하여 보안 규칙이나 비용 제한 기능이 오동작할 위험이 있다.

범위	물리적 저장소 위치	영향을 미치는 타킷 범위	팀 및 저장소 내 공유 여부
Managed	시스템 수준 managed-settings.json	머신 내 모든 사용자와 모든 프로젝트	예 (IT 부서나 시스템 관리자가 일괄 배포)
User	사용자 홈 디렉토리 ~/.claude/	해당 사용자의 모든 개발 프로젝트	아니오 (로컬 사용자 개인용)
Project	프로젝트 내 .claude/	해당 저장소(Repository) 내 모든 협업자	예 (Git에 커밋되어 팀원 간 동기화)
Local	.claude/settings.local.json	현재 디렉토리에서 해당 사용자에게만 적용	아니오 (.gitignore에 자동 등록되어 비공개)

 

 

3. 상세 가이드 및 심층 분석 (Detailed Guide)

3.1 모델 구성 및 별칭(Model Aliases)의 실체

Claude Code는 사용 목적에 맞춰 최적의 모델 버전을 지정할 수 있는 다양한 별칭을 제공한다. 이를 제대로 매핑하지 않으면 과도한 요금이 청구되거나 추론 성능이 극도로 저하되는 부작용을 겪을 수 있다.

• best: 현재 사용 가능한 모델 중 가장 똑똑한 성능을 내는 하이엔드 모델을 지정한다. (현재 Claude 3.5 Opus 또는 동급의 최신 추론 모델로 자동 포인팅된다.)
• sonnet: 일상적인 코딩, 디버깅, 테스트 케이스 작성 등 대부분의 업무에 기본 권장되는 최적의 균형 모델이다. 속도가 매우 빠르고 단위 토큰당 가격이 합리적이다.
• opus: 고도의 추론 및 전체 시스템 아키텍처 재구성 등 극한의 지능이 필요한 작업에 사용된다.
• haiku: 단순 오타 수정, 파일 일괄 리네이밍, 간단한 로그 포맷 정리 등 극도의 비용 효율과 속도가 최우선일 때 선택한다.
• sonnet[1m] / opus[1m]: 최대 100만 토큰에 달하는 대규모 컨텍스트 윈도우(Large Context Window)를 활성화하여 한 번에 수백 개의 소스 코드를 메모리에 올려놓고 정밀 분석을 수행할 수 있게 만든 특별 모드다.
• opusplan: 스프링 및 고도의 백엔드 개발에 가장 유용한 핵심 모드다. 초기 기획과 방향 설정(Plan Mode) 단계에서는 지능이 높은 Opus 모델을 동원해 빈틈없는 설계도를 작성하고, 실제 파일을 수정하고 셸 명령을 때리는 실행 단계(Execute Mode)에서는 경쾌하고 저렴한 Sonnet 모델로 자동 스위칭해 준다

 

 

3.2 EPIC (Explore-Plan-Implement-Commit) 개발 워크플로우의 완성

Claude Code를 사용할 때 가장 권장되는 표준 개발 프로세스는 'EPIC 사이클'이다. 이 흐름을 어기고 곧바로 "어디 수정해 줘" 식의 단답형 명령을 내리면, 에이전트가 로컬 환경의 다른 연관 의존성(Dependency)을 무시한 채 코드를 짜깁기하여 빌드를 완전히 파괴하는 결과로 이어지기 십상이다.

1단계: 탐색 (Explore - 정보 수집)

무작정 코딩을 지시하기 전, 에이전트가 해당 프로젝트의 디렉토리 구조와 설계 표준을 완전히 학습하도록 환경 조사를 지시해야 한다.

# 나쁜 예시
"Spring Security 로그인 처리하는 메서드 하나 만들어줘"

# 권장 예시 (Explore 지시)
"현재 프로젝트 내에서 인증 및 로그인을 담당하는 파일들을 추적해서 읽어줘.
아직 절대로 코드를 변경하거나 구현을 시작하지 말고, 로깅이 설계된 방식과 데이터 흐름만 요약해서 브리핑해줘."

이 단계에서 https://gitingest.com/ 같은 오픈소스 도구를 함께 사용하면 프로젝트 전체의 경량화된 요약본을 사전에 준비하여 에이전트에게 공급함으로써 정보 수집의 완성도를 배가할 수 있다.

 

2단계: 계획 수립 (Plan)

에이전트에게 구체적인 요구사항을 설명하고, 작업에 들어가기 전 수정 대상 파일과 변경 세부 로직에 대한 "계획서" 작성을 요청한다.

"구글 OAuth2 인증을 도입하려고 한다. 어떤 파일들이 변경되어야 하는지 분석하고, 
세션이 끊겼을 때의 리다이렉션 예외 처리 흐름을 포함하여 구체적인 구현 계획(Plan)을 도출해줘."

계획서가 터미널에 출력되면 바로 실행을 확정 짓지 말고, Ctrl+G 단축키를 눌러 텍스트 에디터에서 해당 계획서의 오타나 도메인 정책을 직접 수동으로 가공한 뒤 에이전트에게 최종 실행을 위임하는 설계의 합을 맞추는 것이 핵심이다.

 

3단계: 구현 및 자가 검증 (Implement)

계획이 확정되면 에이전트가 실제 코드 블록을 작성한다. 이때 가장 중요한 것은 단순 수정을 넘어 로컬 빌드 및 단위 테스트까지 에이전트가 완수하도록 셸 스크립트 도구를 위임하는 것이다.

"이전 계획에 맞춰 구글 OAuth2 플로우를 구현해줘. 
콜백 핸들러에 대한 단위 테스트 코드를 신규 작성하고, 로컬 테스트 런을 돌려서 성공할 때까지 오류를 자가 수정해줘."

에이전트는 이 과정에서 컴파일 에러나 테스트 실패 로그가 수신될 때마다 추론-수정-재테스트의 내부 순환(Self-Healing Loop)을 자동으로 전개하여 무결점의 코드를 수렴해 낸다.

 

4단계: 커밋 및 제출 (Commit)

수정이 성공적으로 종료되면, 수정한 코드들을 기반으로 의미 있는 Git 커밋 메시지를 생성하고 최종 풀 리퀘스트(PR)를 준비한다.

"작업 완료되었으니 수정한 내용의 핵심 맥락을 기술적으로 요약하여 Conventional Commits 스타일로 Git 커밋을 생성하고 원격 브랜치에 푸시해줘."

 

 

3.3 컨텍스트 포화(Context Saturation) 및 비용 최적화 극대화 기법

Claude Code를 현업에서 실무적으로 사용할 때 가장 주의해야 할 리스크는 매 요청마다 누적되는 컨텍스트(토큰) 비용이다.

에이전트는 질문의 맥락과 로컬 파일들의 상태를 계속해서 자기 대화 이력(Context Window)에 집어넣는다. 질문을 20번 넘게 지속적으로 이어나가면, 이전 대화 내용과 수정된 파일 히스토리가 엄청난 크기로 쌓여 단 한 문장의 추가 질문을 던졌을 뿐인데 매번 5만~10만 토큰이 넘게 증발(프롬프트 캐싱 비용 포함)하게 된다. 이를 컨텍스트 포화(Context Saturation) 현상이라 부른다.

이 비용 폭탄을 안전하게 예방하고 효율을 뽑아내기 위한 4대 핵심 액션 플랜을 정리한다.

1) 주기적인 세션 축소 및 정리 (/compact & /clear 의 조화)

작업이 진행되면서 이전 변경 이력들이 지저분하게 쌓이면 상태 표시줄의 비용 소모율이 빠르게 증가한다. 이때 두 가지 원자적인 명령어로 메모리를 즉시 리셋해야 한다.

• /compact: 이전까지 나눴던 방대한 대화 기록과 코드 수정 디테일을 에이전트가 스스로 일목요연한 핵심 요약본(Summary)으로 가공하여 컨텍스트에 덮어쓴다. 불필요한 날것의 긴 대화 로그를 날려버려 컨텍스트 용량을 최대 70%까지 줄이면서도 작업의 연계성은 그대로 살려준다.
• /clear: 특정 기능 구현(예: 회원 가입 API 빌드 완수)이 완전히 끝났다면 미련 없이 세션을 폭파해야 한다. 이전 대화 기록을 완전히 메모리에서 날려보내 완전히 제로(0)에 가까운 상태로 초기화함으로써 다음 태스크 진행 시 기동 비용을 최소화시킨다.

 

2) 정밀한 컨텍스트 무시 설정 (.claudeignore 및 claudeMdExcludes 튜닝)

프로젝트 규모가 클수록 불필요한 바이너리 파일, 빌드 결과물, 미디어 파일, 혹은 거대한 라이브러리 폴더(node_modules, build, target 등)가 에이전트의 파일 스캔 대상에 포함되어 토큰을 포식하게 된다. 반드시 프로젝트 루트 디렉토리에 .claudeignore를 배치하여 장벽을 쳐두어야 한다.

# .claudeignore - 불필요한 대규모 컨텍스트 진입 원천 차단
node_modules/
.git/
build/
target/
*.log
*.png
*.jpg
*.svg
dist/
package-lock.json
yarn.lock

 

3) 서브에이전트(Subagents) 패턴의 영리한 도입

모든 작업을 메인 대화창(Main Thread)에서 다 처리하려 하면 메인 컨텍스트가 과도한 로그로 오염된다. 복잡한 오류 분석이나 레퍼런스 조사는 임시 하위 실행체인 서브에이전트에게 외주를 주듯이 따로 떼어내 명령해야 한다.

# 메인 스레드 컨텍스트를 전혀 파괴하지 않는 세련된 서브에이전트 위임 명령
"서브에이전트 하나 띄워서, 현 빌드에 추가된 타사 라이브러리 보안 충돌 로그를 정밀 조사해 달라고 해줘. 
조사가 끝나면 최종 결론 한 문장과 조치 방법만 메인 창으로 요약해서 돌려주고 세션은 종료해줘."

이렇게 하면 서브에이전트가 내부적으로 수백 줄의 보안 코드를 읽으며 발생시킨 방대한 토큰 소모는 서브세션과 함께 소멸되고, 메인 창에는 오직 정제된 한 줄의 해결책(인사이트)만 남게 되어 비용을 엄청나게 격리해 낼 수 있다.

 

4) 프롬프트 캐싱(Prompt Caching)을 살리는 질문 패턴 설계

Anthropic API의 프롬프트 캐싱 메커니즘은 요청 간의 내용이 유사하게 중복될 때 시스템에서 해당 토큰의 단가를 90% 가까이 깎아주는 획기적인 기능이다. 이를 위해서는 대화의 시작 시점에 변하지 않는 무거운 뼈대(CLAUDE.md의 상세한 규칙 정보, 시스템 아키텍처 다이어그램 등)를 확실히 박아놓아 에이전트가 변치 않는 캐시 블록(Cache Block)을 유지하도록 설계하는 것이 매우 중요하다

 

4. 실전 팁 및 고급 설정 (Practical Tips)

4.1 사용자 정의 출력 스타일(Custom Output Style)의 구현

단순히 코드만 전달받는 것을 넘어, 본인의 취향이나 교육 목적에 맞춘 전용 '코딩 멘토' 역할을 수행하도록 Claude Code를 커스터마이징할 수 있다. 프로젝트 루트 내에 Frontmatter 문법을 포함하여 마크다운 규격으로 프롬프트 규칙서를 저장하면 된다.

---
name: TechMentor
description: 아키텍처 원리를 상세히 설명해 주는 시니어 개발자 교육 스타일
keep-coding-instructions: true
---

# 테크 멘토 가이드라인 (TechMentor Style Instructions)
당신은 현업 경력 15년 차의 아주 친절하고 뼈대 깊은 시니어 백엔드 아키텍트입니다. 
단순히 소스 코드를 복사해서 던져주는 기계적 코딩 방식은 철저히 거부합니다.

## 핵심 강령
1. 새로운 리팩토링이나 코드 구현 결과를 제시할 때마다, 해당 디자인 패턴이나 클래스 설계를 왜 채택했는지 기술적 관점을 상세히 설명하세요.
2. 상태 코드 및 분산 트래픽 처리에 대한 수학적 모델링이나 복잡도 연산이 필요하다면 반드시 $LaTeX$ 수식 표기법($...$ 또는 $$...$$)을 정밀 도입하여 학문적 엄밀함을 더하세요.
3. 코드 내부에는 실무에서 부작용(Side Effect)을 예방하기 위해 준수해야 할 주의사항들을 한국어 주석으로 라인별로 정교하게 달아두어야 합니다.

 

4.2 훅(Hooks)과 MCP(Model Context Protocol)를 활용한 지속적 통합 자동화

Claude Code의 성능을 극한으로 올리는 종착지는 로컬 워크플로우에 자동화 파이프라인(Hooks)을 이식하는 것이다.

MCP (Model Context Protocol) 연동 예시

MCP를 설정하여 Sentry나 GitHub Issue Tracker 같은 서드파티 도구를 Claude Code에 연동하면, 터미널 세션 내부에서 다음과 같이 실시간 오류 모니터링 분석을 도구로 위임할 수 있다.

// ~/.claude.json 또는 프로젝트 내 .mcp.json 설정 파일
{
  "mcpServers": {
    "sentry-error-analyzer": {
      "command": "npx",
      "args": ["-y", "@sentry/mcp-server"],
      "env": {
        "SENTRY_AUTH_TOKEN": "your_sentry_api_token_here",
        "SENTRY_ORG": "my-backend-team"
      }
    }
  }
}

 

Git Commit 전 자동화 훅(Pre-Commit Hook) 구현

커밋이 수행되기 전, 프로젝트에 존재할지도 모르는 스프링 및 데이터베이스 안티 패턴을 자동으로 선제 탐색하도록 셸 훅을 심어보자.

# .claude/hooks/pre-commit-audit.sh
#!/bin/bash
echo "🚀 [Claude Hooks] 커밋 생성 전 코드 정적 정합성 무결성 검증을 실시합니다."

# Python 정적 분석 스크립트를 돌려 백엔드 아키텍처 위배 여부 판독
python3 scripts/audit_architecture_integrity.py

if [ $? -ne 0 ]; then
    echo "❌ [Error] 아키텍처 안티 패턴 감지: @Transactional이 유실되었거나 Controller가 Repository를 직접 참조하고 있습니다."
    exit 1
fi

echo "✅ [Success] 정적 코드 검증을 무결하게 통과했습니다. 커밋 승인!"
exit 0

이러한 훅을 연동해 두면 에이전트가 스스로 코딩 후 커밋을 날릴 때, 정의해 둔 물리적 검사 수칙을 단 한 번이라도 통과하지 못하면 커밋 작업이 차단(Rejection)되어 품질 수준이 낮은 코드가 원격 리포지토리에 머지되는 대형 참사를 인프라 단위에서 방지할 수 있다.

 

 

5. 마무리 (Conclusion)

Claude Code는 단순한 'AI 보조 비서'가 아니다. 터미널이라는 개발자의 가장 일차적이고 핵심적인 개발 생태계 내부에 직접 안착하여, 운영체제 리소스를 직접 휘두르며 자율적으로 문제를 사냥하는 '독립형 개발 에이전트'다.

에이전트가 지닌 4단계 순환 아키텍처인 에이전틱 루프의 원리를 가슴속에 새기고, 단계적 개발 방식인 EPIC Cycle을 규칙적으로 엄수하며, /compact와 /clear, 그리고 .claudeignore를 생활화하여 비용(토큰) 누수 지점을 제어해 내는 백엔드 개발자만이 이 최강의 무기를 안전하게 지배할 수 있다.

단순 채팅 기반의 AI 활용법에 아쉬움을 느끼고 있었다면, 지금 당장 여러분의 로컬 터미널에 Claude Code를 내려받고 이 가이드에서 언급한 opusplan과 커스텀 훅 시스템을 입혀보자. 

 

#ClaudeCode #클로드코드 #에이전트 #LLM #토큰최적화 #opusplan #MCP #Git자동화 #프롬프트엔지니어링 #백엔드개발