Claude Code는 터미널에서 코드를 직접 읽고 고치고 명령을 실행하면서, 마치 짝 프로그래머처럼 일하는 코딩 에이전트입니다. 이 페이지에서는 Claude Code가 “요청을 받아 맥락을 살피고, 행동하고, 결과를 검증하는” 에이전틱 루프 (agentic loop)를 어떻게 스스로 반복하는지를 처음부터 차근차근 살펴봅니다.

정보

한 줄 요약: Claude Code는 추론하는 모델과 행동하는 도구를 묶어 “맥락 수집 → 행동 → 결과 검증"을 스스로 반복하는 터미널 네이티브 코딩 에이전트입니다. MoAI-ADK의 세 가지 핵심도 모두 이 루프에서 출발합니다.

Claude Code는 터미널 (terminal)에서 동작하는 에이전틱 어시스턴트입니다. 코딩에 특히 강하지만, 명령줄에서 할 수 있는 일이라면 문서 작성, 빌드 실행, 파일 검색, 주제 조사까지 폭넓게 도와줍니다.

핵심 개념은 에이전틱 하네스 (agentic harness)입니다. 하네스란 기본 모델을 둘러싸고 실행을 조율하는 시스템으로, 모델이 어떻게 생각하고 계획할지, 어떤 도구를 부를지, 컨텍스트를 어떻게 관리할지, 산출물을 어디에 저장하고 결과를 어떻게 평가할지를 결정하는 계층입니다. Claude Code는 모델인 Claude를 감싸 도구와 컨텍스트 관리, 실행 환경을 붙입니다. 덕분에 텍스트만 만들어 내던 언어 모델이 실제로 코드베이스를 다루는 코딩 에이전트가 됩니다. MoAI-ADK가 말하는 “코드를 직접 쓰는 대신 에이전트가 잘 일할 환경을 설계한다"는 하네스 엔지니어링이 바로 이 개념의 연장선입니다.

작업을 맡기면 Claude는 세 단계를 거칩니다. 다만 이 단계들은 명확히 분리되기보다 서로 섞여 하나의 흐름으로 이어집니다.

요청 → 맥락 수집(gather context) → 행동(take action) → 결과 검증(verify results) → 반복

루프는 요청 성격에 맞게 적응합니다. 코드베이스 관련 질문은 맥락 수집만으로 끝날 수 있고, 버그 수정은 세 단계를 여러 번 순환하며, 리팩터링은 검증에 많은 비중을 둘 수 있습니다. Claude는 직전 단계에서 배운 것을 토대로 다음 행동을 결정하고, 수십 개의 동작을 이어 붙이면서 스스로 방향을 교정합니다.

flowchart TD
    A[사용자 요청] --> B[맥락 수집
파일 검색·읽기]
    B --> C[행동
편집·명령 실행]
    C --> D[결과 검증
테스트·출력 확인]
    D -->|작업 미완료| B
    D -->|작업 완료| E[완료]
    F[사용자 개입
언제든 중단·조정] -.-> B
    F -.-> C
    F -.-> D

사용자도 이 루프의 일부입니다. 언제든 작업을 중단(Esc)하거나, 멈추지 않고 교정 메시지를 보내(Enter) 방향을 바꿀 수 있습니다. Claude는 자율적으로 일하면서도 입력에 계속 반응합니다.

에이전틱 루프는 추론하는 모델 (model)과 행동하는 도구 (tools)라는 두 요소가 합쳐져 돌아갑니다. 여기에 대화와 파일이 담기는 컨텍스트, 그리고 행동을 통제하는 권한이 더해집니다.

Claude Code는 Claude 모델로 코드를 이해하고 작업을 추론합니다. 어떤 언어의 코드든 읽고 구성 요소가 어떻게 연결되는지 파악하며, 복잡한 작업은 단계로 쪼개 실행합니다. 상황에 맞는 모델을 골라 쓸 수 있습니다.

세션 중에는 /model 명령으로, 시작할 때는 claude --model <name>으로 모델을 바꿉니다.

팁

모델마다 effort (추론 깊이) 수준을 low · medium · high · xhigh · max로 조절할 수 있습니다. ultrathink 같은 키워드는 곧 effort: xhigh와 Adaptive Thinking (모델이 스스로 추론 토큰을 할당하는 방식)으로 이어집니다. 과거처럼 고정된 토큰 예산(budget_tokens)을 직접 지정하는 방식은 더 이상 권장하지 않습니다.

서브에이전트를 띄울 때는 부모 세션의 모델을 그대로 물려받기 때문에, 작업 성격에 맞춰 다른 모델이 필요하면 스폰할 때 model 값으로 명시하는 것이 좋습니다.

도구가 있어야 Claude는 텍스트 응답을 넘어 실제로 행동할 수 있습니다. 기본 도구는 크게 다섯 범주로 나뉩니다.

이 외에도 서브에이전트(subagent)를 만들어 작업을 나누거나, 사용자에게 질문을 보내는 오케스트레이션 도구가 있습니다. 각 도구 사용은 새로운 정보를 돌려주고, 그 정보가 다음 결정으로 이어지는 흐름이 곧 에이전틱 루프입니다.

정보

서브에이전트의 기본 동작 (Claude Code 2.1.219+): 서브에이전트는 기본적으로 백그라운드에서 돕니다. 결과가 곧 필요할 때만 앞으로 나오고, 그래도 권한 프롬프트는 메인 세션에 그대로 표시됩니다(2.1.186+부터는 어느 서브에이전트가 묻는지 이름까지 보입니다). 서브에이전트는 기본적으로 깊이 3까지 중첩 생성될 수 있고, 환경변수 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1로 한 단계까지만 허용할 수 있습니다.

디렉터리에서 claude를 실행하는 순간 Claude는 다음 정보에 접근합니다.

• 프로젝트: 현재 디렉터리와 하위 디렉터리의 파일 (권한이 있으면 그 밖의 파일도)
• 터미널: 빌드 도구, git, 패키지 매니저 등 명령줄에서 할 수 있는 모든 작업
• git 상태: 현재 브랜치, 커밋되지 않은 변경, 최근 커밋 이력
• CLAUDE.md: 매 세션 알아야 할 프로젝트별 규칙과 컨벤션을 담는 마크다운 파일
• 자동 메모리 (auto memory): 작업하며 학습한 패턴과 선호를 자동 저장 (MEMORY.md의 앞부분이 세션 시작 시 로드)
• 확장 기능: 설정한 MCP 서버, 스킬, 서브에이전트 등

컨텍스트 윈도우가 가득 차면 Claude가 알아서 압축합니다. 이때 초반 도구 호출 결과부터 정리하고, 그다음 남은 정보를 요약합니다. MCP 도구 정의는 명시적으로 요청하기 전까지 로드를 미루므로 필요한 도구만 그때 올라옵니다.

행동을 통제하는 권한 모델은 아래 권한 모델 절에서 다룹니다.

에이전틱 루프와 도구, 기능은 어디서 쓰든 동일합니다. 달라지는 것은 코드가 실행되는 위치와 상호작용하는 방식입니다.

터미널, 데스크톱 앱, IDE 확장 (VS Code·JetBrains), claude.ai/code 웹, 원격 제어, Slack, CI/CD 파이프라인으로 접근할 수 있습니다. 인터페이스는 보고 다루는 방식만 바꿀 뿐, 그 아래 에이전틱 루프는 똑같습니다.

Claude Code는 작업하는 동안 대화를 ~/.claude/projects/ 아래 JSONL 파일로 로컬 저장합니다. 덕분에 세션을 되감거나(rewind) 이어가거나(resume) 분기할(fork) 수 있습니다.

• 세션은 독립적: 새 세션은 빈 컨텍스트 윈도우로 시작하며, 이전 대화 이력을 가져오지 않습니다. 세션 간에 유지하려면 자동 메모리와 CLAUDE.md를 씁니다.
• 이어가기·분기: claude --continue나 claude --resume은 같은 세션 ID로 이어 붙이고, --fork-session이나 /branch는 이력을 새 세션 ID로 복사합니다.

컨텍스트 윈도우 (context window)에는 대화 이력, 파일 내용, 명령 출력, CLAUDE.md, 자동 메모리, 로드된 스킬, 시스템 지시가 담깁니다. 작업이 진행되며 컨텍스트가 차오르면 Claude가 자동으로 압축(compaction)하는데, 이때 초반 지시가 사라질 수 있습니다. 항상 지켜야 할 규칙은 대화 이력이 아니라 CLAUDE.md에 담아두고, /context로 무엇이 자리를 차지하는지 확인합니다.

Claude에는 두 가지 안전장치가 있습니다. 파일 변경을 되돌리는 체크포인팅과, 묻지 않고 할 수 있는 행동의 범위를 정하는 권한입니다.

모든 파일 편집은 되돌릴 수 있습니다. Claude는 파일을 편집하기 전에 현재 내용을 스냅샷으로 저장합니다. 문제가 생기면 Esc를 두 번 눌러 이전 상태로 되감거나 되돌려 달라고 요청하면 됩니다.

체크포인팅은 세션 안에서만 유효하고 git과 별개이며, 파일 변경만 다룹니다. 데이터베이스·API·배포처럼 원격에 영향을 주는 행동은 되돌릴 수 없어서, Claude는 외부에 부작용을 남기는 명령을 실행하기 전에 먼저 묻습니다.

Shift+Tab을 눌러 권한 모드를 순환합니다.

.claude/settings.json에서 특정 명령을 미리 허용하면 매번 묻지 않습니다. npm test나 git status처럼 신뢰하는 명령에 유용하며, 설정 범위는 조직 전체 정책부터 개인 선호까지 지정할 수 있습니다.

서브에이전트는 부모 세션의 권한 모드를 그대로 이어받습니다. 부모가 자동 수락 편집 모드면 서브에이전트도 같은 모드로 실행되며, 과거 버전에서 쓰던 spawn-time 권한 모드 지정은 2.1.213부터 무시됩니다.

Claude Code가 인라인 코드 어시스턴트와 다른 지점은 두 가지입니다.

• 터미널 네이티브 (terminal-native): 명령줄에서 할 수 있는 모든 작업, 즉 빌드·테스트·git·패키지 매니저를 직접 다룹니다.
• 대규모 코드베이스 전체 인지: 현재 파일만 보는 것이 아니라 프로젝트 전체를 봅니다. “인증 버그를 고쳐줘"라고 하면 관련 파일을 검색하고, 여러 파일을 읽어 맥락을 파악하고, 파일에 걸친 일관된 편집을 한 뒤, 테스트로 검증하고, 요청하면 커밋까지 합니다.

이 페이지에서 본 에이전틱 루프는 MoAI-ADK 세 가지 핵심이 공통으로 딛고 서는 바닥입니다.

• 토크노믹스: 루프가 돌 때마다 컨텍스트와 토큰이 소비됩니다. MoAI-ADK는 작업 단계마다 맞는 모델과 추론 깊이를 배정하고, 컨텍스트를 다이어트하며, 예산을 시스템이 지키게 해 같은 루프를 더 적은 비용으로 돌립니다.
• 에이전틱 루프 엔지니어링: “맥락 수집 → 행동 → 결과 검증"의 반복을 사람이 매번 지켜보는 대신, 완료 조건(/goal)과 진단 루프(/moai loop)로 루프 자체를 설계 대상으로 삼습니다.
• 에이전틱 하네스: 권한 모델, CLAUDE.md, 도구 구성 같은 이 페이지의 요소들이 곧 하네스의 부품입니다. MoAI-ADK는 이 부품들 위에 SPEC 워크플로우와 에이전트 카탈로그를 얹습니다.

• 기능 한눈에 보기
• MoAI-ADK란?

• How Claude Code works
• Extend Claude Code (Features overview)

팁

복잡한 작업은 곧장 코드로 들어가지 말고, Shift+Tab을 두 번 눌러 계획 모드에서 코드베이스를 먼저 분석하게 하세요. 계획을 검토하고 다듬은 뒤 구현을 맡기면 첫 시도부터 결과가 훨씬 정확해집니다.