클로드 코드의 정석 첫 번째 편. AI 코딩 도구를 써본 적은 있어도, 진짜 **"일"**을 시켜본 적이 있는가에서 시작합니다. ↵
이번엔 Claude Code가 왜 다른 도구와 다른지, 그리고 어떤 구조로 돌아가는지를 봅니다.
📎 출처: 이 글은 인프런 「클로드 코드의 정석 — 실전 에이전틱 엔지니어링」(실용주의개발) 강의를 수강 후, 제가 공부하며 이해한 방향으로 재구성한 것입니다. 설치·요금 부분은 강의 범위 밖이라 Anthropic 공식 문서를 참고해 보강했습니다.
🎯 1. "다음 줄 뭐야?"에서 "이 작업 끝내놔"로
Anthropic 공식 문서의 정의는 짧습니다. 터미널에서 살면서, 코드베이스를 이해하고, 자연어 명령으로 코딩을 빠르게 해주는 에이전트형 도구. 여기에 이 도구의 성격이 거의 다 들어 있어요.
- 터미널에서 동작 — IDE 채팅창이 아니라, 실제로 명령어를 치는 자리에서 같이 일합니다
- 코드베이스 이해 — 커서 주변 몇 줄이 아니라 프로젝트 디렉터리 전체를 읽습니다
- 에이전트형 — 한 번 답하고 끝나는 게 아니라, 목표를 향해 스스로 움직입니다
저는 세 번째가 제일 크다고 봤습니다.
자동완성 도구에 던지는 질문은 "다음 줄 뭐야?"인데, 에이전트에 던지는 질문은 "이 작업 끝내놔"거든요.
도구가 좋아진 게 아니라 질문의 단위 자체가 달라진 겁니다.
💡 그래서 이 강의를 "Claude Code 사용법"이 아니라 "일 맡기는 법" 강의로 읽기로 했어요. 단축키를 외우는 게 아니라, 맡기고 · 검증하고 · 권한을 통제하는 법을 배우는 쪽에 가깝다고 이해했습니다.
🔁 2. 에이전틱 루프 — 수집 → 행동 → 검증
Claude Code는 에이전틱 루프(agentic loop) 위에서 돕니다.
모델이 추론하고, 도구가 행동하고, 그 결과가 다시 루프에 입력돼 다음 결정을 만듭니다.
챗봇처럼 대화하는 게 아니라 루프를 돌면서 스스로 판단하고 행동하는 구조예요.
루프는 크게 세 단계입니다.
컨텍스트를 수집하고, 행동하고, 결과를 검증합니다.
검증에서 실패하면 다시 수집으로 돌아가고, 성공하면 완료하고 보고합니다.
중요한 건 모든 작업이 세 단계를 다 도는 건 아니라는 점입니다.
작업 성격에 따라 루프의 모양이 달라집니다.
- "결제 로직 어떻게 돌아가?" — 컨텍스트 수집만으로 끝납니다
- "동시성 버그 잡아줘" — 세 단계를 여러 번 반복합니다
- "Spring Boot 2.x → 3.x 마이그레이션" — 검증 단계가 유난히 길어집니다
그리고 자료에서 제일 인상 깊었던 문장이 하나 있습니다.
사용자도 루프의 일부라는 것.
언제든 끼어들어 컨텍스트를 더 주거나 방향을 틀 수 있습니다.
💡 "인라인 어시스턴트는 내가 루프를 돌리고, 에이전트는 자기가 루프를 돌린다"로 외웠습니다.
기존 도구에서는 읽고 · 고치고 · 돌려보는 걸 제가 반복했는데,
여기서는 그 반복을 넘겨주고 저는 방향과 검증만 잡는 자리로 옮겨 앉는 셈이에요.
🧠 3. 루프를 굴리는 두 축 — 모델과 도구
Claude Code는 에이전틱 하네스입니다.
언어 모델 위에 도구·컨텍스트 관리·실행 환경을 입혀 만든 코딩 에이전트라는 뜻이에요.
하네스를 뜯어보면 결국 추론하는 두뇌와 행동하는 손발 두 축입니다.
① 모델 — 추론하는 두뇌
Claude 모델이 코드를 읽고 작업을 추론합니다.
언어를 가리지 않고(Java, Kotlin, Python, SQL 등) 컴포넌트 사이의 연결 관계를 파악하고, 복잡한 작업을 단계로 쪼개 실행합니다.
강의에서 "클로드가 판단한다"는 표현이 나오면 여기를 가리키는 겁니다.
모델 특성 적합한 작업
| Haiku | 빠른 응답 | 간단한 질문 · 코드 자동완성 |
| Sonnet | 속도와 품질의 균형 | 대부분의 코딩 작업 |
| Opus | 깊은 추론 | 복잡한 아키텍처 결정 |
모델은 세션 중에도 바꿀 수 있고, 시작할 때 지정할 수도 있습니다.
세션 중에 바꾸기
/model
시작할 때 지정하기
claude --model opus② 도구 — 행동하는 손발
도구가 없으면 텍스트로만 응답하는 챗봇에 불과합니다.
도구가 붙는 순간 Claude는 행동하기 시작해요.
도구는 크게 다섯 묶음입니다.
- 파일 작업 — 읽기 · 쓰기 · 편집
- 검색 — 코드와 심볼 탐색
- 실행 — 빌드 · 테스트 · 명령
- 웹 — 검색과 페이지 열람
- 확장 레이어 — MCP · Skills · Hooks · Subagents
말로만 보면 감이 잘 안 오는데, 실제 흐름 하나를 따라가 보면 두 축이 어떻게 맞물리는지 보입니다.
💡 "모델은 두뇌, 도구는 손발, CLAUDE.md는 사규"로 정리했어요.
셋 중 하나만 빠져도 에이전트가 안 됩니다.
두뇌만 있으면 챗봇이고, 손발만 있으면 스크립트고, 사규가 없으면 매번 처음부터 설명해야 하니까요.
🗂️ 4. Claude가 보는 범위 — 횡단 작업의 근거
claude 명령을 실행하면 Claude는 아래 범위에 접근합니다.
이 목록이 "왜 파일을 가로지르는 작업이 가능한가"에 대한 답이에요.
- 프로젝트 — 현재 디렉터리와 그 하위 파일 전체
- 터미널 — Gradle, Maven, git, Docker, kubectl 같은 명령
- git 상태 — 브랜치, 미커밋 변경사항, 히스토리
- CLAUDE.md — 프로젝트별 규칙·컨벤션. 매 세션 자동 로드됩니다
- Auto memory — MEMORY.md의 첫 200줄 또는 25KB
- 확장 — MCP 서버, Skills, Subagents, Claude in Chrome
여기서 제가 밑줄 그은 건 CLAUDE.md가 매 세션 자동 로드된다는 대목입니다.
프로젝트 규칙을 매번 프롬프트로 설명할 필요가 없다는 뜻이거든요.
💡 접근 범위가 곧 능력의 상한이자 위험의 범위라고 이해했어요. 프로젝트 전체를 보니까 횡단 작업이 되는 건데, 뒤집으면 프로젝트 전체를 건드릴 수도 있다는 얘기입니다. 권한 통제가 왜 따로 배워야 하는 영역인지 여기서 납득했습니다.
🌐 5. 어디서 돌리든 루프는 같다 — 실행 환경 vs 인터페이스
처음에 헷갈렸던 게 "실행 환경"과 "인터페이스"였습니다.
둘은 다른 축이에요. 실행 환경은 코드가 실제로 어디서 도는가이고, 인터페이스는 내가 어디로 들어가는가입니다.
실행 환경 코드 실행 위치 쓰는 시점
| 로컬 | 내 머신 | 기본값. 파일·도구·환경에 전부 접근 |
| 클라우드 | Anthropic 관리 VM | 로컬에 없는 레포, 작업 위임 시 |
| 리모트 컨트롤 | 내 머신 | 웹 UI로 로컬 전체를 처리 |
인터페이스는 터미널 · 데스크톱 앱 · IDE 익스텐션 · claude.ai/code · Slack · CI/CD로 여러 갈래인데, 어떤 인터페이스를 쓰더라도 밑에서 도는 에이전틱 루프는 동일합니다.
💡 "터미널에서 배운 게 IDE에서도 그대로 쓰인다"는 뜻이니까, 인터페이스 고르느라 시작을 미룰 이유가 없습니다.
위 아래는 갈아 끼워도 가운데는 고정이에요.
⚙️ 6. 개발 환경 구축 — 설치부터 로그인까지
여기서부터 두 단원은 강의 범위 밖입니다.
개념만 알고 넘어가면 막상 손이 안 떨어질 것 같아서, Anthropic 공식 문서를 보고 정리해 붙였습니다.
먼저 요구사항부터.
- 운영체제 — macOS 13 이상, Windows 10 1809 이상, Ubuntu 20.04 이상 등
- 하드웨어 — RAM 4GB 이상, x64 또는 ARM64
- 네트워크 — 인터넷 연결 필수
설치는 네이티브 설치 스크립트가 권장입니다.
이 방식은 백그라운드에서 자동 업데이트까지 됩니다.
macOS · Linux · WSL
curl -fsSL https://claude.ai/install.sh | bash
Windows PowerShell
irm https://claude.ai/install.ps1 | iex
Homebrew를 쓴다면 (자동 업데이트는 안 됩니다)
brew install --cask claude-code
설치 확인
claude --version
claude doctor
npm으로도 설치할 수 있는데(npm install -g @anthropic-ai/claude-code), 이 경우 Node.js 22 이상이 필요합니다.
설치가 끝나면 작업할 프로젝트 폴더에서 claude를 실행합니다.
브라우저가 열리면서 로그인 절차가 진행돼요.
ANTHROPIC_API_KEY 환경변수가 이미 있으면 브라우저 대신 그 키를 쓸지 한 번 물어봅니다.
⚠️ 계정 조건을 미리 확인하세요.
공식 문서 기준 Claude Code는 Pro · Max · Team · Enterprise 또는 Console(API) 계정이 필요하고,
무료 claude.ai 플랜은 포함되지 않습니다.
Amazon Bedrock · Google Cloud · Microsoft Foundry 같은 서드파티 프로바이더를 통해 쓰는 길도 따로 있습니다.
💡 설치 자체는 한 줄이라 5분이면 끝납니다. 진짜 관문은 설치가 아니라 계정과 요금입니다.
💰 7. 요금 구조 — 구독이냐 종량제냐
Claude Code의 비용은 크게 두 갈래입니다.
claude.ai 계정으로 쓰는 구독 플랜과, Console(API) 또는 클라우드 프로바이더로 쓰는 종량제예요.
어느 쪽으로 로그인했느냐에 따라 과금 방식이 갈립니다.
먼저 구독 플랜입니다. 모든 유료 플랜에 Claude Code가 포함돼 있습니다.
플랜 가격 ('26.08.01 기준)
| Pro | 월 $20 (연간 결제 시 월 $17) | 개인용 시작점 |
| Max | 월 $100부터 | Pro 대비 5배 또는 20배 사용량 |
| Team (표준 좌석) | 좌석당 월 $25 (연간 $20) | 팀 단위 |
| Team (프리미엄 좌석) | 좌석당 월 $125 (연간 $100) | 좌석 등급이 높을수록 사용량이 큼 |
| Enterprise | 좌석 요금 + API 요율 | 사용량이 모델·작업에 따라 변동 |
종량제는 감이 잘 안 잡히는데, 공식 문서가 실측 범위를 밝혀두고 있어서 참고가 됐습니다.
엔터프라이즈 도입 사례 기준 개발자 1인당 활성일 평균 약 $13, 월 $150~250 수준이고, 사용자의 90%가 하루 $30 미만이라고 합니다.
구독 플랜을 쓴다면 알아둘 게 하나 더 있습니다.
사용량 한도가 5시간 롤링 윈도우와 주간 윈도우 두 겹으로 걸리고, 이 한도는 모델과 무관하게 공유됩니다.
한도에 걸렸을 때 /model로 모델을 바꿔도 풀리지 않는다는 뜻이에요.
쓰는 만큼 새는 구조라, 아껴 쓰는 습관이 곧 비용 관리입니다. 문서가 짚는 것 중 바로 적용할 만한 건 이 정도였어요.
- /usage — 현재 사용량과 플랜 한도를 확인
- /clear — 상관없는 작업으로 넘어갈 때 컨텍스트를 비웁니다. 대화가 길어질수록 매 요청이 비싸집니다
- 모델 고르기 — 대부분의 코딩 작업은 Sonnet으로 충분하고, Opus는 복잡한 설계 판단에 아껴 씁니다
- 안 쓰는 MCP 서버 정리 — 컨텍스트를 차지합니다
💡 "긴 세션 = 비싼 세션"으로 이해했어요.
Claude Code는 매 요청마다 대화 전체를 다시 보내기 때문에 하루 종일 켜둔 창에 한 줄 물어봐도 그동안 쌓인 맥락 전체가 따라갑니다. 작업이 바뀌면 /clear가 가장 싸게 먹히는 습관 같습니다.
▲ 출처: 위 요금·플랜 정보는 2026년 8월 기준입니다. 최신 값은 Claude 요금제 페이지에서 확인하세요.
⚖️ 8. 그래서 내 일은 어떻게 바뀌나
여기까지가 구조였고, 이제 그래서 뭐가 달라지는가입니다.
강의는 먼저 프로덕션에서 실제로 굴러가고 있다는 사례를 듭니다.
- Stripe — 엔지니어 1,370명 도입. Scala → Java 마이그레이션 1만 줄을 예상 2주에서 4일에 완료
- Rakuten — 여러 세션을 병렬로 돌려 기능 배포를 평균 24일에서 5일로 단축
- Ramp — 인시던트 조사와 비엔지니어의 자연어 데이터 질의로 조사 시간 80% 감소
수치를 그대로 받아들이기보다, "프로덕션 환경에서 실제로 굴러가고 있다"는 사실이 핵심이라고 강의에서는 말합니다.
또, 직군별로 보면 공통점이 하나 나옵니다. 전부 여러 파일을 가로지르는 작업이라는 것.
- 프론트엔드 — 디자인 토큰 하나 바꾸면 컴포넌트 수십 개, API 응답 구조가 바뀌면 타입·fetcher·컴포넌트·스토리북이 연쇄로 따라옵니다
- 백엔드 — 컬럼 하나 추가에 엔티티·DTO·매퍼·마이그레이션 SQL·테스트가 줄줄이, 성능 이슈면 컨트롤러부터 쿼리까지 훑어야 합니다
- 1인 개발자 — 프론트·백·인프라·결제·어드민을 혼자 봅니다. "5일이면 될 것"이 파일 사이 연결고리에서 시간이 빠져나갑니다
파일 하나 안에서 끝나는 일이 거의 없다는 것. Claude Code가 가장 빛나는 지점이 바로 그 교차점입니다.
1인 개발자에게는 혼자 일하던 사람에게 페어 프로그래밍 동료가 생기는 것에 가깝고요.
그래서 역할은 어떻게 바뀔까요?
"엔지니어링이 사라진다"가 아니라, 진짜 엔지니어링에만 집중할 수 있는 환경이 만들어지는 것.
타이핑하는 사람에서 설계·판단하고 검증·책임지는 사람으로 옮겨 갑니다.
줄어드는 건 인증 boilerplate, CRUD 반복, 폼 validation, DB 연결 설정, 디자인 토큰 일괄 변경 같은 것들이고요.
자질구레한 일에 시달리지 않아도 돼서 코딩이 그 어느 때보다 즐겁다.
— Boris Cherny, Claude Code 책임자
💡 줄어드는 것 목록이 곧 "내가 지금 뭘 넘겨줄 수 있는가" 체크리스트더군요.
✍️ 마무리 & 다음 단계
정리하면 Claude Code는 언어 모델 위에 도구·컨텍스트·실행 환경을 입힌 에이전틱 하네스이고, 수집 → 행동 → 검증 루프를 스스로 돌면서 여러 파일을 가로지르는 작업을 끝냅니다.
인터페이스가 무엇이든 이 루프는 같고, 개발자의 자리는 타이핑에서 설계·판단·검증 쪽으로 옮겨 갑니다.
그리고 강의의 마지막 문장이 이 시리즈 전체의 전제이기도 합니다.
"AI를 잘 쓴다"는 건 ChatGPT에 코드 짜달라고 하는 수준이 아니라, 에이전트에게 일을 맡기는 법 · 검증하는 법 · 컨텍스트를 주는 법 · 권한을 통제하는 법이고, 이건 전부 따로 배워야 하는 영역이라는 것.
개념은 여기까지고, 다음부터는 직접 굴려볼 차례입니다.
📎 출처: 이 글은 인프런 「클로드 코드의 정석 — 실전 에이전틱 엔지니어링」(실용주의개발) 강의를 수강 후, 개인 학습 목적으로 이해한 방향에 따라 재구성한 것입니다. 강의 자료의 슬라이드·원문은 포함하지 않았습니다. 개발 환경 구축·요금 구조는 Claude Code 공식 문서(© Anthropic)와 Claude 요금제 페이지를 참고했으며 2026년 8월 기준입니다. 잘못 이해한 부분이 있다면 댓글로 알려주세요. 🙏
'새로운, 신나게 > AI Agent, 공부하는 중' 카테고리의 다른 글
| [Agent Skills 완전정복 #8] 내 에이전트에 스킬 기능 붙이기 (클라이언트 구현) (0) | 2026.07.10 |
|---|---|
| [Agent Skills 완전정복 #7] 스킬에 스크립트 넣기 (0) | 2026.07.09 |
| [Agent Skills 완전정복 #6] 스킬 품질 평가하기 — eval로 검증하고 개선하기 (0) | 2026.07.07 |
| [Agent Skills 완전정복 #5] 스킬이 '제 때' 불려오게 하는 법 — description 최적화 (0) | 2026.07.06 |
| [Agent Skills 완전정복 #4] 잘 만드는 스킬의 원칙 (0) | 2026.07.05 |
