[공식문서읽기] Claude Code를 사용한다면 반드시 알아야하는 7가지 사용 패턴

개요

Claude Code는 단순한 AI 챗봇이 아니다. 파일을 읽고, 명령을 실행하고, 코드를 수정하는 에이전틱 코딩 환경이다. 질문에 답하고 기다리는 게 아니라, 목표를 설명하면 스스로 탐색하고 계획하고 구현한다.
하지만 이 자율성에도 학습 곡선이 있다. Anthropic 내부 팀과 다양한 코드베이스에서 검증된 패턴들을 정리한 공식 베스트 프랙티스를 살펴보자.

---

핵심 원칙: 컨텍스트 윈도우 관리

Claude Code 베스트 프랙티스의 대부분은 하나의 제약에 기반한다. 컨텍스트 윈도우가 빠르게 차오르고, 채워질수록 성능이 떨어진다는 것이다.
컨텍스트 윈도우에는 대화 내용, Claude가 읽은 파일, 명령 실행 결과가 모두 포함된다. 디버깅 세션 하나로 수만 개의 토큰이 소비될 수 있다. 컨텍스트가 70% 차면 정밀도가 떨어지기 시작하고, 90%를 넘으면 응답이 불안정해진다.
컨텍스트 관리 핵심 전략:

• /clear 명령으로 관련 없는 작업 사이에 컨텍스트를 초기화한다
• /compact <지시> 명령으로 대화를 요약하되 중요한 내용은 보존한다
• /btw 명령으로 컨텍스트에 남지 않는 간단한 질문을 할 수 있다
• 서브에이전트에 탐색을 위임하면 메인 컨텍스트를 깔끔하게 유지할 수 있다

---

1. Claude가 스스로 검증할 수 있게 하라

공식 문서에서 강조하는 가장 효과가 큰 단일 전략이다.
테스트를 실행하거나, 스크린샷을 비교하거나, 출력을 검증할 수 있을 때 Claude는 극적으로 더 잘 동작한다. 명확한 성공 기준이 없으면 그럴듯해 보이지만 실제로는 작동하지 않는 코드를 만들 수 있다.
적용 예시:

• 이전: “이메일 주소를 검증하는 함수 구현해줘”
• 이후: “validateEmail 함수를 작성하고, user@example.com은 true, invalid는 false, user@.com은 false인 테스트 케이스를 만들어서 실행까지 해줘”

UI 변경 사항은 Claude in Chrome 확장 프로그램으로 시각적으로 검증할 수 있다. 브라우저 탭을 열고 UI를 테스트하고 코드가 올바르게 동작할 때까지 반복한다.
검증 수단으로는 테스트 스위트, 린터, 특정 결과를 확인하는 Bash 명령 등 무엇이든 가능하다. 검증 체계를 견고하게 만드는 데 투자하라.

---

2. 탐색 먼저, 계획 다음, 코딩 마지막

Claude가 바로 코딩에 들어가면 잘못된 문제를 해결할 수 있다. Plan Mode로 탐색과 실행을 분리하자.
권장 워크플로우 4단계:

1. 탐색: Plan Mode에서 파일을 읽고 질문에 답한다 (코드 변경 없음)
2. 계획: 상세한 구현 계획을 작성한다. Ctrl+G로 계획을 에디터에서 직접 수정할 수 있다
3. 구현: Normal Mode로 전환하여 계획대로 코딩한다
4. 커밋: 설명적인 커밋 메시지와 함께 커밋하고 PR을 생성한다

다만, 범위가 명확하고 변경이 작은 작업(오타 수정, 로그 추가, 변수 이름 변경 등)에는 계획 없이 바로 진행하는 게 더 효율적이다. diff를 한 문장으로 설명할 수 있다면 계획을 건너뛰자.

---

3. 프롬프트에 구체적인 컨텍스트를 제공하라

Claude는 의도를 추론할 수 있지만 마음을 읽지는 못한다. 특정 파일을 참조하고, 제약 조건을 언급하고, 예시 패턴을 가리키자.
효과적인 프롬프트 패턴:

• 범위 지정: “foo.py에 테스트 추가해줘” → “foo.py에서 사용자가 로그아웃한 상태의 엣지 케이스를 커버하는 테스트를 작성해줘. 목(mock) 사용은 피해줘”
• 출처 지정: “ExecutionFactory API가 왜 이상해?” → “ExecutionFactory의 git 히스토리를 살펴보고 API가 어떻게 현재 모습이 되었는지 요약해줘”
• 패턴 참조: “캘린더 위젯 추가해줘” → “홈페이지의 기존 위젯 구현을 살펴봐. HotDogWidget.php가 좋은 예시야. 같은 패턴을 따라서 캘린더 위젯을 만들어줘”
• 증상 기술: “로그인 버그 고쳐줘” → “세션 만료 후 로그인이 실패해. src/auth/의 인증 흐름을 확인하고, 특히 토큰 갱신 부분을 봐줘”

풍부한 컨텍스트 제공 방법:

• @ 기호로 파일을 직접 참조한다
• 이미지를 복사/붙여넣기 또는 드래그 앤 드롭한다
• 문서나 API 레퍼런스 URL을 제공한다
• cat error.log | claude로 파일 내용을 직접 전달한다

---

4. 환경을 올바르게 설정하라

몇 가지 설정만으로 모든 세션에서 Claude Code의 효과를 높일 수 있다.

CLAUDE.md 작성하기

/init 명령으로 프로젝트 구조를 분석한 시작 파일을 생성하고 점진적으로 다듬자.

CLAUDE.md는 모든 대화 시작 시 자동으로 로드된다. Bash 명령, 코드 스타일, 워크플로우 규칙을 포함하되 간결하게 유지해야 한다. 각 줄마다 “이것을 제거하면 Claude가 실수할까?”를 자문하자. 그렇지 않다면 삭제한다.
포함해야 할 것:

• Claude가 추측할 수 없는 Bash 명령
• 기본값과 다른 코드 스타일 규칙
• 테스트 지침과 선호하는 테스트 러너
• 저장소 관례 (브랜치 명명, PR 규칙)

제외해야 할 것:

• 코드를 읽으면 알 수 있는 것
• Claude가 이미 아는 표준 언어 규칙
• 자주 변경되는 정보
• 긴 설명이나 튜토리얼

CLAUDE.md가 너무 길면 중요한 규칙이 노이즈에 묻혀서 Claude가 절반을 무시한다. 코드처럼 관리하고 정기적으로 정리하자.

권한 설정

기본적으로 Claude는 파일 쓰기나 Bash 명령에 허가를 요청한다. 안전하지만 번거롭다. 두 가지 방법으로 중단을 줄일 수 있다:

• 권한 허용 목록: npm run lint나 git commit 같은 안전한 명령을 허용한다
• 샌드박싱: OS 수준의 격리를 활성화하여 Claude가 정해진 범위 안에서 자유롭게 작업한다

CLI 도구 활용

gh, aws, gcloud 같은 CLI 도구는 외부 서비스와 상호작용하는 가장 컨텍스트 효율적인 방법이다. Claude가 모르는 도구도 --help 플래그로 학습시킬 수 있다.

MCP 서버 연결

claude mcp add 명령으로 Notion, Figma, 데이터베이스 등 외부 도구를 연결한다.

훅(Hooks) 설정

CLAUDE.md 지침은 권고사항이지만, 훅은 확정적으로 실행된다. 파일 수정 후 자동 ESLint, 특정 폴더 쓰기 차단 등에 활용한다.

스킬(Skills) 만들기

.claude/skills/ 폴더에 SKILL.md 파일을 추가하여 프로젝트별 도메인 지식과 재사용 가능한 워크플로우를 정의한다.

---

5. 세션을 효과적으로 관리하라

대화는 영속적이고 되돌릴 수 있다. 이 특성을 적극 활용하자.

빠르게 방향을 교정하라

• Esc: Claude를 중간에 멈춘다. 컨텍스트는 보존되므로 방향을 바꿀 수 있다
• Esc + Esc 또는 /rewind: 이전 체크포인트로 되돌린다
• /clear: 관련 없는 작업 사이에 컨텍스트를 초기화한다

같은 문제에 대해 2번 이상 수정을 지시했다면 컨텍스트가 실패한 접근법으로 오염된 것이다. /clear로 초기화하고 배운 내용을 반영한 더 구체적인 프롬프트로 다시 시작하자. 깨끗한 세션과 좋은 프롬프트가 긴 세션의 누적된 수정보다 항상 낫다.

서브에이전트를 활용하라

컨텍스트가 근본적인 제약이므로, 서브에이전트는 가장 강력한 도구 중 하나다.

서브에이전트를 사용해서 우리 인증 시스템이 토큰 갱신을 어떻게 처리하는지,
기존 OAuth 유틸리티 중 재사용할 수 있는 게 있는지 조사해줘.

서브에이전트는 별도의 컨텍스트 윈도우에서 실행되어 코드베이스를 탐색하고 결과만 요약해서 보고한다. 메인 대화를 오염시키지 않는다.

대화를 이어가라

claude --continue    # 가장 최근 대화 이어서 진행
claude --resume      # 최근 대화 목록에서 선택

/rename으로 세션에 설명적인 이름을 붙이면 나중에 찾기 쉽다. 세션을 브랜치처럼 관리하자.

---

6. 자동화하고 확장하라

하나의 Claude로 효과를 보았다면, 병렬 세션과 비대화형 모드로 산출물을 배가시키자.

비대화형 모드

claude -p "프롬프트" 명령으로 CI 파이프라인, pre-commit 훅, 스크립트에 Claude를 통합한다.

# 일회성 쿼리
claude -p "이 프로젝트가 뭘 하는지 설명해줘"

# 스크립트용 구조화된 출력
claude -p "모든 API 엔드포인트 나열" --output-format json

# 실시간 처리용 스트리밍
claude -p "이 로그 파일 분석해줘" --output-format stream-json

병렬 세션

여러 세션을 동시에 실행하는 3가지 방법이 있다:

• Claude Code 데스크톱 앱: 여러 로컬 세션을 시각적으로 관리. 각 세션은 독립된 worktree를 갖는다
• Claude Code on the web: Anthropic의 클라우드 인프라에서 격리된 VM으로 실행
• 에이전트 팀: 공유 작업과 메시징으로 여러 세션을 자동 조율

Writer/Reviewer 패턴도 효과적이다:

• 세션 A(Writer): “API 엔드포인트에 대한 Rate Limiter 구현해줘”
• 세션 B(Reviewer): “Rate Limiter 구현을 리뷰해줘. 엣지 케이스, 경쟁 조건, 기존 미들웨어 패턴과의 일관성을 확인해”
• 세션 A: 리뷰 피드백을 반영하여 수정

대량 작업 분산

대규모 마이그레이션에서는 작업을 병렬로 분배한다:

for file in $(cat files.txt); do
  claude -p "$file을 React에서 Vue로 마이그레이션. 완료 시 OK, 실패 시 FAIL 반환" \
    --allowedTools "Edit,Bash(git commit *)"
done

---

7. 흔한 실패 패턴을 피하라

공식 문서에서 경고하는 대표적인 안티패턴들이다:

• 뒤죽박죽 세션: 하나의 세션에서 관련 없는 작업을 계속 섞는다. 컨텍스트가 불필요한 정보로 가득 찬다 → /clear로 분리하라
• 반복 수정: Claude의 실수를 계속 교정한다. 실패한 접근법으로 컨텍스트가 오염된다 → 2번 실패하면 /clear 후 더 좋은 프롬프트로 다시 시작하라
• 과도한 CLAUDE.md: 너무 길어서 중요한 규칙이 노이즈에 묻힌다 → 과감하게 정리하고, 이미 올바르게 동작하는 지침은 삭제하라
• 검증 부재: 그럴듯해 보이지만 엣지 케이스를 처리하지 못한다 → 항상 테스트, 스크립트, 스크린샷으로 검증하라
• 무한 탐색: 범위 없이 “조사해봐”라고 지시하면 수백 개 파일을 읽으며 컨텍스트를 소진한다 → 범위를 좁히거나 서브에이전트를 사용하라

---

직관을 키워라

이 패턴들은 고정된 규칙이 아니라 출발점이다.
때로는 복잡한 문제에 깊이 파고들고 있어서 컨텍스트를 쌓아두는 것이 맞을 때도 있다. 계획 없이 Claude에게 알아서 해보라고 하는 것이 맞는 탐색적 작업도 있다. 모호한 프롬프트가 Claude의 해석을 먼저 보려는 의도에 정확히 맞을 때도 있다.
Claude가 좋은 결과물을 냈을 때 무엇을 했는지 관찰하자. 프롬프트 구조, 제공한 컨텍스트, 사용한 모드를 기억하자. Claude가 어려워할 때는 왜인지 물어보자. 컨텍스트가 너무 시끄러웠나? 프롬프트가 너무 모호했나? 작업이 한 번에 처리하기엔 너무 컸나?
시간이 지나면 어떤 가이드도 담을 수 없는 직관이 생긴다.

---

마무리

Claude Code 베스트 프랙티스를 한 문장으로 요약하면, “컨텍스트를 아끼고, 검증 수단을 제공하고, 구체적으로 지시하라”이다.
핵심 체크리스트:

• CLAUDE.md를 간결하게 유지하고 정기적으로 정리한다
• 복잡한 작업은 Plan Mode로 탐색→계획→구현→커밋 순서를 따른다
• 파일 참조, 스크린샷, URL 등 구체적인 컨텍스트를 프롬프트에 포함한다
• 테스트, 린터, 스크립트 등 Claude가 스스로 검증할 수 있는 수단을 제공한다
• 관련 없는 작업 사이에 /clear로 컨텍스트를 초기화한다
• 서브에이전트로 탐색 작업을 위임하여 메인 컨텍스트를 보호한다
• 병렬 세션과 비대화형 모드로 생산성을 확장한다

---

참고 자료

• Claude Code Best Practices - 공식 문서
• 7 Claude Code best practices for 2026 - eesel.ai
• How I use Claude Code + my best tips - builder.io
• Claude Code Best Practices - shanraisshan GitHub

이 글은 Claude Code를 활용하여 작성되었습니다.