목차
이 글은 Anthropic 엔지니어링 블로그에 2025년 4월 게재된 “Claude Code: Best practices for agentic coding” 을 읽고, 내용을 정리한 글입니다. 원문: https://www.anthropic.com/engineering/claude-code-best-practices
한 줄로 말하면 #
Claude Code 잘 쓰는 비결은 똑똑한 프롬프트가 아니라, ‘검증 장치를 붙이는 것’과 ‘컨텍스트를 깨끗하게 유지하는 것’이다.
어떤 문제를 해결하려 했나 #
Claude Code를 처음 쓰는 사람들이 자주 빠지는 함정이 있습니다.
“로그인 버그 좀 고쳐줘” → 고쳐주는 척하다가 엉뚱한 파일을 건드림 “그건 됐고, 아 그럼 이번엔 README 좀 정리해줘” → 또 어딘가 이상한 결과 “다시 로그인 버그로 돌아가서…” → 이젠 앞에서 뭐 했는지도 헷갈림
처음엔 잘 되던 게 점점 산으로 갑니다. 사람들은 “AI가 코딩을 못하나 보네” 결론을 내리지만, 사실은 다른 문제입니다.
Claude Code는 챗봇이 아니라 자율 에이전트입니다. 파일을 읽고, 명령을 실행하고, 코드를 고치고, 결과를 다시 봅니다. 디버깅 한 세션에 토큰 수만 개가 쉽게 소비되고, 컨텍스트 창이 가득 차면 성능이 눈에 띄게 떨어집니다.
이 글은 Anthropic 내부 팀이 모은 “Claude Code 잘 쓰는 패턴"을 정리합니다. 핵심은 컨텍스트라는 자원을 어떻게 관리하느냐에 거의 모든 이야기가 걸려 있다는 점입니다.
해결책: 세 가지 핵심 원칙 #
원문에는 십여 개 권장사항이 나오지만, 입문자에게 가장 큰 차이를 만드는 세 가지를 골랐습니다.
1. 검증할 수 있게 만들기 (가장 큰 한 방) #
원문이 “가장 큰 한 방(single highest-leverage thing)” 이라고 못 박은 원칙입니다.
테스트, 스크린샷, 기대 출력 — 뭐든 Claude가 자기 결과를 스스로 확인할 수 있는 기준을 함께 줘야 합니다.
| 전략 | Before (모호) | After (검증 가능) |
|---|---|---|
| 테스트 케이스 제공 | “이메일 검증 함수 만들어줘” | “validateEmail 함수 작성. [email protected] → true, invalid → false. 구현 후 테스트 실행” |
| UI 시각 검증 | “대시보드 좀 더 예쁘게” | “[스크린샷 첨부] 이대로 구현. 결과 스크린샷 찍어 비교 후 차이점 수정” |
| 근본 원인 해결 | “빌드 깨졌어” | “이 에러로 빌드 실패: [에러 붙여넣기]. 근본 원인 고치고 빌드 성공 확인. 에러 숨기지 마” |
검증 장치가 없으면 Claude가 그럴듯한데 안 돌아가는 코드를 내놓습니다. 결국 사용자가 일일이 손으로 확인해야 하니, 모든 실수마다 사람이 붙어야 합니다.
2. 탐색 → 계획 → 구현 → 커밋 #
작업을 시작하자마자 코드를 짜라고 시키지 마세요. 잘못된 문제를 풀어버리는 결과가 나옵니다. 원문은 4단계 워크플로를 권장합니다.
[탐색] (Plan mode)
"src/auth 폴더 읽고 세션 처리 방식을 이해해줘"
↓
[계획] (Plan mode)
"Google OAuth 추가하려면 어디 고쳐야 해? 계획 만들어줘"
↓
[구현] (Default mode)
"네 계획대로 OAuth 구현. 콜백 핸들러 테스트 작성, 테스트 실행, 실패 수정"
↓
[커밋]
"의미 있는 메시지로 커밋하고 PR 열어줘"요점은 탐색·계획 단계에서는 코드를 건드리지 않는 것입니다. Plan mode에서 충분히 이해한 뒤에야 손을 대면, 잘못된 방향으로 한참 가다 되돌리는 일이 줄어듭니다.
단, 모든 작업에 4단계가 필요한 건 아닙니다. 변경 내용을 한 문장으로 설명할 수 있다면 계획을 건너뛰세요. 오타 수정이나 변수 이름 바꾸기에 plan mode를 쓰는 건 과합니다.
3. 컨텍스트는 가장 귀한 자원 #
이 모든 권장의 뿌리에는 컨텍스트 창 관리라는 한 가지 제약이 있습니다.
| 증상 | 원인 | 처방 |
|---|---|---|
| 앞 지시를 잊어버림 | 컨텍스트 창 가득 참 | /clear 로 초기화 |
| 같은 실수 반복 | 실패한 시도가 컨텍스트 오염 | 두 번 고쳐도 안 되면 /clear 후 더 좋은 프롬프트로 재시작 |
| 코드베이스 탐색에 토큰 폭발 | 메인 세션이 파일을 다 읽음 | 서브에이전트에게 조사 위임 |
원문이 강조하는 “두 번 고쳐서 안 되면 /clear 한다” 규칙은 직관과 반대입니다. 사람은 보통 “조금만 더 설명하면 되겠지"라고 생각하지만, 실은 누적된 오답이 정답을 가리는 상태라서 새 세션이 더 빠릅니다.
CLAUDE.md 파일에 프로젝트 규칙을 적어두면 매 세션 자동으로 불러옵니다. 단, 너무 길면 Claude가 핵심 규칙을 무시합니다. “이 줄을 빼면 Claude가 실수할까?” 를 기준으로 가지치기하세요.
핵심 결론 #
Claude Code 결과가 별로일 때 사람들은 본능적으로 “모델이 부족하다” 거나 “프롬프트를 더 잘 짜야지” 라고 생각합니다. Anthropic이 정리한 답은 다릅니다.
“AI 성능의 문제인 줄 알았는데, 사실은 우리가 컨텍스트와 검증을 관리하지 못한 게 문제였다.”
똑똑한 프롬프트 한 줄보다, 검증 가능한 환경 + 깨끗한 컨텍스트가 훨씬 큰 차이를 만듭니다.
내 작업에 적용한다면 #
Claude Code는 코딩 도구라고만 생각하기 쉽지만, 두 원칙(검증·컨텍스트)은 다른 영역에도 그대로 옮겨갑니다.
시나리오 1 — 일반적인 데이터 분석 과정 #
분석가가 Claude Code로 데이터 작업을 시킬 때 가장 흔한 실수는 “검증 없이 한 세션에서 다 하기” 입니다.
[흔한 실수 흐름]
"이 CSV 분석해줘" → "그건 됐고 시각화 다른 색으로" → "다시 분석해줘"
→ 컨텍스트 오염 + 결과 신뢰 못함
[best practice 적용]
[검증 장치 마련]
"테스트 데이터 5행과 기대 결과를 먼저 정의. 코드는 그 결과를 재현해야 함"
[탐색 → 계획]
Plan mode로 "데이터 구조 파악 → 분석 방법 후보 3개 제시" 후 결정
[구현]
계획 확정 후에만 코드 작성, 테스트로 자동 검증
[세션 분리]
새 데이터셋 / 다른 분석으로 넘어갈 땐 /clear핵심: 분석은 데이터마다 맥락이 완전히 다릅니다. 한 세션을 길게 끌고 가면 앞 데이터셋의 가정이 다음 작업에 새어 들어갑니다.
시나리오 2 — 웹 사이트를 자동으로 운영할 때 #
자동화된 콘텐츠 운영은 “사람이 안 보는 사이 잘못된 게 발행되는 위험” 이 본질입니다. 검증과 컨텍스트 분리가 그대로 안전장치가 됩니다.
[흔한 실수 흐름]
한 세션에서 글 작성 + 이미지 생성 + 배포 + 모니터링 다 시키기
→ 후반부엔 앞 규칙 다 잊어버림
[best practice 적용]
[검증 장치]
발행 전 자동 검사 (스타일 가이드, 깨진 링크, SEO 메타) 스크립트 강제
[CLAUDE.md에 운영 규칙 박기]
- 톤 가이드, 금지 표현, 이미지 출처 규칙
- 매 세션 자동 로드 → 누락 방지
[작업 단위로 세션 분리]
"글 작성 세션", "검수 세션", "배포 세션" 따로 운영
→ 컨텍스트 격리로 실수 누적 차단
[자동 모드 + 권한 화이트리스트]
비대화형(claude -p)으로 정해진 작업만 실행핵심: 자동 운영은 한 세션에 모든 책임을 몰면 사고가 납니다. “한 세션 = 한 책임” 으로 쪼개고, 각 단계 사이에 자동 검증을 끼워넣는 것이 원문 권장과 정확히 같은 패턴입니다.
Anthropic 엔지니어링 블로그를 오래된 순서대로 읽고 정리합니다.
