Claude 3.7 Sonnet과 Claude Code 첫 만남 — 확장 사고와 터미널 코딩 에이전트
2025년 2월 24일 Anthropic이 발표한 Claude 3.7 Sonnet과 Claude Code를 한 달 가까이 써본 첫 경험 기록입니다. extended thinking의 토큰 예산 제어, CLAUDE.md와 허가 모드 설계, 계획→구현→테스트 워크플로를 정리한 입문 가이드.
Claude 3.7 Sonnet과 Claude Code 첫 만남 — 확장 사고와 터미널 코딩 에이전트
2025년 2월 24일, 두 개의 발표
Anthropic이 2025년 2월 24일 발표한 두 가지는 각각 다른 이야기처럼 보이지만 사실 한 방향이었습니다. 하나는 Claude 3.7 Sonnet, “시장에 나온 최초의 하이브리드 추론 모델”을 표방한 새 모델이고, 다른 하나는 이 모델을 실제 코드베이스에 투입하는 터미널 기반 에이전트 Claude Code(리서치 프리뷰)입니다.
먼저 모델부터 짚고 가겠습니다. Claude 3.7 Sonnet의 설계 철학은 경쟁 추론 모델들과 다릅니다. 빠른 답변용 모델과 긴 사고용 모델을 따로 두는 대신, 하나의 모델이 두 모드를 오간다는 것. 기본 모드에서는 기존 3.5 Sonnet의 업그레이드판처럼 즉답하고, extended thinking 모드에서는 답하기 전에 스스로를 돌아보며 단계적으로 생각합니다. 이 사고 과정은 claude.ai에서 그대로 펼쳐져 보이고, 가격은 이전 세대와 동일한 입력 1백만 토큰당 $3, 출력 $15입니다(사고 토큰도 출력에 포함됩니다).
Extended thinking: 사고에 예산을 걸다
이 모델을 API로 쓸 때 가장 인상적인 부분은 생각할 양을 토큰 예산으로 지정할 수 있다는 점입니다. “이 문제에 대해 생각하되, N 토큰을 넘기지 마라”고 지시하면 모델이 그 예산 안에서 사고를 조절합니다. 예산은 최대 출력 한도(128K 토큰)까지 자유롭게 설정할 수 있어서, 속도와 비용, 품질 사이의 트레이드오프를 호출 단위로 고를 수 있습니다.
실제 호출은 이런 형태입니다.
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-3-7-sonnet-20250219",
"max_tokens": 20000,
"thinking": {
"type": "enabled",
"budget_tokens": 10000
},
"messages": [
{
"role": "user",
"content": "재귀 하강 파서 구현을 검토하고 놓치기 쉬운 경계 케이스를 알려줘"
}
]
}'
budget_tokens이 사고 전용 예산이고, 응답 본문은 max_tokens 안에서 나옵니다. 같은 API로 기본 모드와 확장 모드를 오가니, 추론이 필요한 요청과 그냥 빠른 요청을 한 모델로 처리할 수 있습니다. 체감상 “무조건 오래 생각하는 모델”이 아니라 “필요할 때만 오래 생각하는 모델”에 가깝습니다. 문서의 상세한 파라미터 규칙은 extended thinking 가이드에 정리되어 있습니다.
Claude Code: 터미널에 사는 협업자
Claude Code는 Anthropic의 “첫 번째 에이전틱 코딩 도구”로, 리서치 프리뷰로 공개되었습니다. IDE 플러그인이나 웹 서비스가 아니라 터미널에서 사는 도구라는 점이 특징입니다. 발표문의 표현을 빌리면 코드를 검색하고 읽고, 파일을 수정하고, 테스트를 작성·실행하고, GitHub에 커밋과 푸시를 하고, 커맨드라인 도구를 쓰되 모든 단계에서 사람을 루프 안에 유지합니다.
설치는 발표 시점 기준 npm 한 줄입니다.
npm install -g @anthropic-ai/claude-code
그다음은 프로젝트 루트에서 claude를 실행하면 됩니다. 첫 실행에서 로그인하고, 이후로는 대화형 프롬프트에서 자연어로 작업을 시킵니다. 공식 발표에서는 초기 테스트에서 “수동이라면 45분 이상 걸렸을 작업을 한 번의 패스로 완료한 사례가 있다”고 밝혔고, 저도 이 도구를 블로그 저장소와 작은 사이드 프로젝트에 걸어두고 한 달 가까이 써봤습니다.
CLAUDE.md: 프로젝트의 기억
Claude Code를 쓰기 시작하면 제일 먼저 만나는 개념이 CLAUDE.md입니다. 프로젝트 루트에 두는 안내 문서로, Claude가 세션을 시작할 때마다 먼저 읽습니다. 무엇을 적으면 좋은지 제 경험을 정리하면 이렇습니다.
# CLAUDE.md 예시 구성
- 프로젝트 개요: Astro 5 + MDX 한국어 기술 블로그
- 주요 명령: npm run dev(개발 서버), npm run build(빌드), npx astro check(타입 검사)
- 규칙: 본문은 합니다체, 코드 펜스는 언어 명시, 프론트matter 형식 준수
- 주의: src/content/posts 외 파일은 건드리지 말 것
핵심은 Claude가 매번 물어보게 될 것을 미리 적어두는 것입니다. 빌드 명령, 테스트 명령, 컨벤션, 하지 말아야 할 일. /init 명령을 실행하면 코드베이스를 훑어 초안을 만들어주니, 거기서 다듬는 방식으로 시작하는 게 빠릅니다. 재미있는 건 Claude Code 자체 저장소에도 CLAUDE.md가 있다는 것인데, 도구를 만드는 팀도 같은 방식으로 일하고 있구나 싶어 신뢰가 갔습니다.
허가 모드: 루프 안의 사람
에이전트 도구의 가장 무서운 부분은 “마음대로 파일을 고치고 명령을 실행하는 것”입니다. Claude Code는 이 지점을 허가(permission) 시스템으로 다룹니다. 파일 수정, bash 명령 실행 같은 민감한 동작 앞에서는 매번 허가를 요청하고, “이 명령은 다시 묻지 않기”로 승인한 것들은 허용 목록에 저장해 다음부터는 묻지 않습니다.
한 달을 쓰면서 익힌 안전한 사용 습관은 이렇습니다.
- 작업 전
git status로 시작 상태를 확인하고, 실험은 브랜치를 만들어서 - 허가 요청이 뜨면 명령을 읽고 승인할 것. 익숙해지면 무심코 엔터를 누르게 됩니다
- 의도와 다른 방향으로 진행하면 즉시 중단하고 원인을 말로 설명하기
- 허용 목록은 프로젝트별 설정으로 관리해서 팀과 공유할 수 있는 범위로
에이전트를 믿는 대신 과정을 보는 도구로 쓴다, 는 자세가 생각보다 중요했습니다.
실전 워크플로: 계획 → 구현 → 테스트
제가 정착한 사용법은 세 단계입니다. 예시는 블로그에 검색 기능을 붙이는 사이드 작업입니다.
1단계, 계획. 먼저 코드베이스를 읽게 하고 계획을 세우게 합니다. “이 저장소에 클라이언트 사이트 검색을 추가하고 싶어. 지금 구조에서 어디를 어떻게 손대면 좋을지 계획만 먼저 제안해줘.” 이렇게 하면 Claude가 관련 파일을 찾아 읽고, 몇 가지 안을 비교해 제안합니다. 이 단계에서 파일을 고치지 않게 하는 게 포인트입니다. 계획을 읽고 이상하면 이때 잡습니다. 대부분의 삐걱거림은 계획 단계의 오해에서 시작했습니다.
2단계, 구현. 계획이 마음에 들면 하나씩 실행을 시킵니다. “1번 안으로 진행해. 컴포넌트 추가 → 기존 레이아웃에 붙이기 순서로.” 파일을 수정할 때마다 diff가 보이고, 허가를 요청합니다. 큰 작업을 한 번에 시키기보다 파일 몇 개 단위로 쪼개는 게 결과가 좋았습니다.
3단계, 테스트. 마지막은 확인입니다. “npm run build 실행해서 에러 없는지 확인하고, 방금 추가한 페이지가 빌드 산출물에 있는지도 봐줘.” Claude Code가 직접 명령을 실행하고 결과를 읽어 다음 판단에 활용합니다. 빌드가 깨지면 로그를 보고 스스로 고치려 시도하는데, 여기서도 수정은 허가를 받아 진행됩니다.
이 루프의 좋은 점은 제가 검토하는 단위가 코드 한 줄 한 줄에서 “계획과 결과”로 옮겨졌다는 것입니다. 물론 diff는 여전히 읽습니다. 다만 어디를 볼지 아는 상태로 보게 되니 리뷰의 밀도가 달라집니다.
벤치마크를 읽는 눈
발표와 함께 공개된 SWE-bench Verified(실제 GitHub 이슈를 해결하는 벤치마크) 결과는 화려하지만, 수치를 그대로 비교하면 안 됩니다. Anthropic의 부록 설명에 따르면 Claude 3.7 Sonnet은 최소한의 스캐폴딩으로 63.7%를 기록했고, 여러 번 병렬 시도를 하고 회귀 테스트로 나쁜 패치를 거르는 “high compute” 설정에서는 70.3%까지 올라갑니다(둘 다 실제로 풀리는 489개 문제 기준). 즉 같은 모델이라도 에이전트 설계와 테스트 시점 컴퓨트에 따라 결과가 크게 달라집니다. Claude Code 같은 도구를 평가할 때는 모델 성적표와 에이전트 스캐폴딩을 분리해서 봐야 한다는 좋은 사례입니다.
한 달 써본 소감
잘 맞았던 작업은 예상대로 탐색과 반복이 많은 것들이었습니다. 남의 코드베이스 구조 파악, 오래된 유틸리티 정리, 테스트 코드 작성, 빌드 깨진 원인 추적. 특히 “이 함수를 어디서 쓰는지 다 찾아줘” 류의 작업이 즐거웠습니다. 반면 정교한 UX 설계나 취향이 필요한 작업은 여전히 제 몫이었고, 세션이 길어지면 초반 맥락을 흐리는 경우도 있어 작업 단위를 짧게 유지하는 편이 좋았습니다.
도구 자체는 리서치 프리뷰답게 거친 부분도 있습니다. 다만 “터미널에서 자연어로 코드베이스를 다룬다”는 경험 자체가 충분히 새로워서, 이 도구가 가리키는 방향을 이해하는 데 한 달이 아깝지 않았습니다.
마치기
Claude 3.7 Sonnet은 “생각의 양을 예산으로 고를 수 있는 모델”이었고, Claude Code는 “그 생각을 내 터미널과 저장소에서 쓰게 해주는 도구”였습니다. 둘을 함께 쓰면서 코딩 작업의 단위가 에디터의 편집에서 계획-실행-검증의 루프로 옮겨가는 걸 느꼈습니다. 아직 프리뷰라 완성도를 두고 말할 단계는 아니지만, 허가 모드와 CLAUDE.md라는 설계가 “에이전트를 어떻게 안전하게 쓸까”라는 질문에 대한 초기 답으로 꽤 그럴듯하다는 생각입니다. 이 도구가 어떻게 자랄지 지켜보면서, 저는 계획 세우기와 검증 루프를 다듬어 가려고 합니다.
레퍼런스
- Claude 3.7 Sonnet and Claude Code (Anthropic 발표) — 2025-02-24 공식 발표문, 가격과 벤치마크 부록 포함
- Extended thinking 가이드 — budget_tokens 규칙과 사용법
- Claude Code GitHub 저장소 — 설치 방법과 저장소 구성
- Claude Code 공식 문서 — 개요, 설치, 인증 안내
- Claude 모델 목록 — claude-3-7-sonnet-20250219 모델 식별자 확인