Claude Code 베스트 프랙티스

환경 설정부터 병렬 세션으로 확장하기까지, Claude Code를 최대한 활용하기 위한 팁과 패턴을 정리했습니다.

Claude Code는 에이전트형 코딩 환경입니다. 질문에 답하고 가만히 기다리는 챗봇과 달리, Claude Code는 파일을 읽고, 명령을 실행하고, 코드를 고치며, 문제를 스스로 풀어 나갑니다. 그동안 여러분은 지켜보거나, 방향을 다시 잡아 주거나, 아예 자리를 비워도 됩니다.

이렇게 되면 일하는 방식 자체가 바뀝니다. 직접 코드를 짜고 Claude에게 검토를 맡기는 대신, 원하는 바를 설명하면 Claude가 만드는 방법을 찾아냅니다. Claude가 탐색하고, 계획하고, 구현합니다.

다만 이런 자율성에도 익혀야 할 부분은 남아 있습니다. Claude는 여러분이 알고 있어야 할 몇 가지 제약 안에서 동작합니다.

이 가이드는 Anthropic 내부 팀들과, 다양한 코드베이스·언어·환경에서 Claude Code를 쓰는 엔지니어들 사이에서 효과가 입증된 패턴을 다룹니다. 에이전트 루프가 내부적으로 어떻게 동작하는지는 How Claude Code works 문서를 참고하세요.

대부분의 베스트 프랙티스는 하나의 제약에서 출발합니다. Claude의 컨텍스트 윈도는 금세 가득 차고, 채워질수록 성능이 떨어진다는 점입니다.

Claude의 컨텍스트 윈도에는 대화 전체가 담깁니다. 모든 메시지, Claude가 읽은 모든 파일, 모든 명령 출력이 여기 들어갑니다. 그런데 이것이 순식간에 가득 찰 수 있습니다. 디버깅 세션 한 번, 또는 코드베이스 탐색 한 번만으로도 수만 개의 토큰을 만들어 내고 소비할 수 있습니다.

이것이 중요한 이유는 컨텍스트가 차오를수록 LLM 성능이 떨어지기 때문입니다. 컨텍스트 윈도가 가득 차 가면 Claude가 앞선 지시를 "잊거나" 실수를 더 많이 하기 시작할 수 있습니다. 컨텍스트 윈도는 가장 신경 써서 관리해야 할 자원입니다. 세션이 실제로 어떻게 채워지는지 보려면, 시작 시 무엇이 로드되고 파일을 한 번 읽을 때마다 비용이 얼마나 드는지 보여 주는 인터랙티브 둘러보기를 확인하세요. 커스텀 상태 표시줄로 컨텍스트 사용량을 계속 추적할 수 있으며, 토큰 사용을 줄이는 전략은 Reduce token usage 문서를 참고하세요.

Claude에게 자기 작업을 검증할 방법을 주세요

Claude가 직접 돌릴 수 있는 검사를 마련해 주세요. 테스트, 빌드, 비교용 스크린샷 같은 것 말입니다. 이것이 곁에서 지켜봐야 하는 세션과, 자리를 떠도 되는 세션을 가르는 차이입니다.

Claude는 작업이 끝난 것처럼 보이면 멈춥니다. 직접 돌릴 검사가 없으면 "끝난 것 같다"가 유일한 신호이고, 결국 여러분이 검증 루프 역할을 떠맡게 됩니다. 여러분이 알아채기 전까지는 어떤 실수든 그대로 남는 셈입니다. 합격/불합격이 나오는 무언가를 쥐어 주면, 루프가 스스로 닫힙니다. Claude가 작업을 하고, 검사를 돌리고, 결과를 읽고, 검사가 통과할 때까지 반복합니다.

여기서 검사란 Claude가 대화 안에서 읽을 수 있는 신호를 돌려주는 것이면 무엇이든 됩니다. 테스트 스위트, 빌드 종료 코드, 린터, 출력을 픽스처와 diff하는 스크립트, 디자인과 비교할 브라우저 스크린샷 등입니다.

전략	개선 전	개선 후
검증 기준을 제시하기	"이메일 주소를 검증하는 함수를 구현해 줘"	"validateEmail 함수를 작성해 줘. 예시 테스트 케이스: user@example.com은 true, invalid는 false, user@.com은 false. 구현한 뒤 테스트를 실행해 줘"
UI 변경을 시각적으로 검증하기	"대시보드를 더 보기 좋게 만들어 줘"	"[스크린샷 붙여넣기] 이 디자인을 구현해 줘. 결과의 스크린샷을 찍어 원본과 비교하고, 차이점을 나열한 뒤 고쳐 줘"
증상이 아니라 근본 원인을 다루기	"빌드가 실패하고 있어"	"이 에러로 빌드가 실패해: [에러 붙여넣기]. 고친 다음 빌드가 성공하는지 확인해 줘. 에러를 억누르지 말고 근본 원인을 해결해 줘"

검사가 마련되면, 그 검사가 멈춤을 얼마나 강하게 통제할지 정하세요.

단일 프롬프트로: 위 표처럼, 같은 메시지 안에서 검사를 돌리고 반복하라고 Claude에게 요청합니다.
세션 전반에 걸쳐: 검사를 /goal 조건으로 설정합니다. 매 턴이 끝날 때마다 별도의 평가자가 다시 검사하고, 조건이 충족될 때까지 Claude가 계속 작업합니다.
결정적 게이트로: Stop 훅이 여러분의 검사를 스크립트로 실행하여, 통과할 때까지 턴이 끝나는 것을 막습니다. Claude Code는 8번 연속으로 막히면 훅을 무시하고 턴을 종료합니다.
제2의 의견으로: 검증 서브에이전트나 자기 결과를 스스로 점검하는 동적 워크플로를 두면, 새로운 모델이 그 결과를 반박하려 시도하게 됩니다. 작업을 한 에이전트가 채점까지 맡지 않도록 하는 셈입니다.

각 단계는 설정 수고와 여러분의 주의를 맞바꿉니다. 프롬프트 방식은 어떤 작업에든 지금 바로 적용됩니다. /goal과 Stop 훅 방식은, 여러분이 지켜보지 않는 무인 실행이 끝까지 제대로 완료되게 해 줍니다.

Claude가 성공했다고 단언하는 대신 증거를 보여 주게 하세요. 테스트 출력, 실행한 명령과 그 반환값, 결과 스크린샷 같은 것 말입니다. 증거를 검토하는 편이 검증을 직접 다시 돌리는 것보다 빠르고, 지켜보지 않았던 세션에도 그대로 통합니다.

먼저 탐색하고, 그다음 계획하고, 그다음 코딩하세요

엉뚱한 문제를 푸는 일을 막으려면, 조사·계획을 구현과 분리하세요.

Claude를 곧장 코딩에 투입하면 엉뚱한 문제를 푸는 코드가 나올 수 있습니다. 플랜 모드를 활용해 탐색과 실행을 분리하세요.

권장 워크플로는 네 단계로 이루어집니다.

탐색(Explore)

플랜 모드로 들어갑니다. Claude는 코드를 바꾸지 않고 파일을 읽으며 질문에 답합니다.

read /src/auth and understand how we handle sessions and login.
also look at how we manage environment variables for secrets.

계획(Plan)

상세한 구현 계획을 만들어 달라고 요청합니다.

I want to add Google OAuth. What files need to change?
What's the session flow? Create a plan.

Ctrl+G를 누르면 계획이 텍스트 에디터에서 열려, Claude가 진행하기 전에 직접 편집할 수 있습니다.

구현(Implement)

플랜 모드를 빠져나와 Claude가 코드를 작성하게 하고, 자신의 계획과 대조해 검증하도록 합니다.

implement the OAuth flow from your plan. write tests for the
callback handler, run the test suite and fix any failures.

커밋(Commit)

설명이 담긴 메시지로 커밋하고 PR을 만들어 달라고 요청합니다.

commit with a descriptive message and open a PR

플랜 모드는 유용하지만, 오버헤드도 따릅니다.

오타 수정, 로그 한 줄 추가, 변수 이름 바꾸기처럼 범위가 분명하고 수정이 작은 작업이라면, 그냥 바로 해 달라고 하세요.

계획이 가장 유용한 때는 접근 방식이 불확실할 때, 변경이 여러 파일에 걸칠 때, 또는 수정하려는 코드에 익숙하지 않을 때입니다. diff를 한 문장으로 설명할 수 있다면 계획은 건너뛰세요.

프롬프트에 구체적인 맥락을 담으세요

지시가 정확할수록 나중에 바로잡을 일이 줄어듭니다.

Claude는 의도를 추론할 수 있지만, 마음을 읽지는 못합니다. 구체적인 파일을 가리키고, 제약을 언급하고, 참고할 예시 패턴을 짚어 주세요.

전략	개선 전	개선 후
작업 범위를 좁히기. 어떤 파일을, 어떤 상황을, 어떤 테스트 선호를 다룰지 명시합니다.	"foo.py에 테스트를 추가해 줘"	"foo.py에 대해 사용자가 로그아웃된 엣지 케이스를 다루는 테스트를 작성해 줘. mock은 피해 줘."
출처를 가리키기. 질문에 답이 될 만한 출처로 Claude를 안내합니다.	"ExecutionFactory의 api는 왜 이렇게 이상해?"	"ExecutionFactory의 git 히스토리를 훑어보고 그 api가 어떻게 지금에 이르렀는지 요약해 줘"
기존 패턴을 참조하기. 코드베이스 안의 패턴을 짚어 줍니다.	"캘린더 위젯을 추가해 줘"	"홈 페이지에 기존 위젯들이 어떻게 구현돼 있는지 보고 패턴을 파악해 줘. HotDogWidget.php가 좋은 예시야. 그 패턴을 따라, 사용자가 월을 고르고 앞뒤로 페이지를 넘겨 연도를 선택할 수 있는 새 캘린더 위젯을 구현해 줘. 코드베이스에서 이미 쓰는 라이브러리 외에는 쓰지 말고 처음부터 만들어 줘."
증상을 기술하기. 증상, 원인이 있을 법한 위치, 그리고 "고쳐진" 상태가 어떤 것인지 제시합니다.	"로그인 버그를 고쳐 줘"	"세션이 타임아웃된 뒤 로그인이 실패한다는 사용자 제보가 있어. src/auth/의 인증 흐름, 특히 토큰 갱신을 확인해 줘. 문제를 재현하는 실패 테스트를 먼저 작성한 뒤 고쳐 줘"

탐색 중이라 방향을 다시 잡을 여유가 있을 때는 모호한 프롬프트도 쓸모가 있습니다. "이 파일에서 뭘 개선하면 좋을까?" 같은 프롬프트는 여러분이 물어볼 생각조차 못 했던 것들을 드러내 줄 수 있습니다.

풍부한 콘텐츠를 제공하세요

@로 파일을 참조하고, 스크린샷·이미지를 붙여넣고, 데이터를 직접 파이프로 넘기세요.

Claude에게 풍부한 데이터를 건네는 방법은 여러 가지입니다.

코드가 어디 있는지 설명하는 대신 @로 파일을 참조하세요. Claude가 응답 전에 그 파일을 읽습니다.
이미지를 그대로 붙여넣으세요. 복사/붙여넣기 하거나 프롬프트에 끌어다 놓으면 됩니다.
문서와 API 레퍼런스의 URL을 주세요. 자주 쓰는 도메인은 /permissions로 허용 목록에 넣으세요.
cat error.log | claude를 실행해 파일 내용을 직접 파이프로 넘기세요.
Claude가 필요한 것을 스스로 가져오게 하세요. Bash 명령, MCP 도구, 또는 파일 읽기로 맥락을 직접 끌어오라고 지시하면 됩니다.

환경을 설정하세요

몇 가지 설정만 해 두면 모든 세션에서 Claude Code가 눈에 띄게 더 효과적으로 동작합니다. 확장 기능 전반과 각각을 언제 써야 하는지는 Extend Claude Code 문서를 참고하세요.

효과적인 CLAUDE.md 작성하기

/init을 실행하면 현재 프로젝트 구조를 기반으로 초기 CLAUDE.md 파일이 생성됩니다. 이후 시간을 들여 다듬어 나가세요.

CLAUDE.md는 Claude가 모든 대화의 시작에 읽는 특별한 파일입니다. Bash 명령, 코드 스타일, 워크플로 규칙을 담으세요. 이렇게 하면 Claude가 코드만으로는 추론할 수 없는 지속적인 맥락을 갖게 됩니다.

/init 명령은 코드베이스를 분석해 빌드 시스템, 테스트 프레임워크, 코드 패턴을 감지하여, 다듬어 나갈 든든한 토대를 만들어 줍니다.

CLAUDE.md 파일에 정해진 형식은 없지만, 짧고 사람이 읽기 좋게 유지하세요. 예를 들면 다음과 같습니다.

# Code style
- Use ES modules (import/export) syntax, not CommonJS (require)
- Destructure imports when possible (eg. import { foo } from 'bar')

# Workflow
- Be sure to typecheck when you're done making a series of code changes
- Prefer running single tests, and not the whole test suite, for performance

CLAUDE.md는 매 세션 로드되므로, 폭넓게 적용되는 것만 담으세요. 가끔만 관련 있는 도메인 지식이나 워크플로는 스킬을 쓰세요. Claude가 필요할 때만 불러오므로 매 대화를 비대하게 만들지 않습니다.

간결하게 유지하세요. 각 줄마다 이렇게 자문해 보세요. "이 줄을 지우면 Claude가 실수를 하게 될까?" 그렇지 않다면 잘라 내세요. 비대해진 CLAUDE.md는 Claude가 정작 중요한 지시를 무시하게 만듭니다!

✅ 포함	❌ 제외
Claude가 추측할 수 없는 Bash 명령	Claude가 코드를 읽어서 알아낼 수 있는 것
기본값과 다른 코드 스타일 규칙	Claude가 이미 아는 표준 언어 관례
테스트 지침과 선호하는 테스트 러너	상세한 API 문서(대신 문서를 링크)
저장소 에티켓(브랜치 명명, PR 관례)	자주 바뀌는 정보
프로젝트에 특화된 아키텍처 결정	긴 설명이나 튜토리얼
개발 환경의 특이점(필요한 환경 변수)	코드베이스를 파일별로 설명한 것
흔히 빠지는 함정이나 직관에 어긋나는 동작	"깨끗한 코드를 작성하라" 같은 자명한 관행

규칙을 넣어 두었는데도 Claude가 원치 않는 행동을 계속한다면, 파일이 너무 길어서 그 규칙이 묻히고 있을 가능성이 큽니다. CLAUDE.md에 답이 있는 내용을 Claude가 되묻는다면, 표현이 모호할 수 있습니다. CLAUDE.md를 코드처럼 다루세요. 문제가 생기면 검토하고, 정기적으로 가지치기하고, Claude의 행동이 실제로 달라지는지 관찰하며 변경을 시험하세요.

강조 표현(예: "IMPORTANT"나 "YOU MUST")을 더해 지시 준수도를 높일 수 있습니다. CLAUDE.md를 git에 체크인해 두면 팀이 함께 기여할 수 있습니다. 이 파일은 시간이 갈수록 가치가 누적됩니다.

CLAUDE.md 파일은 @path/to/import 문법으로 다른 파일을 가져올 수 있습니다.

See @README.md for project overview and @package.json for available npm commands.

# Additional Instructions
- Git workflow: @docs/git-instructions.md
- Personal overrides: @~/.claude/my-project-instructions.md

CLAUDE.md 파일은 여러 위치에 둘 수 있습니다.

홈 폴더(~/.claude/CLAUDE.md): 모든 Claude 세션에 적용됩니다.
프로젝트 루트(./CLAUDE.md): git에 체크인해 팀과 공유합니다.
프로젝트 루트(./CLAUDE.local.md): 개인용 프로젝트별 메모입니다. 팀과 공유되지 않도록 이 파일을 .gitignore에 추가하세요.
상위 디렉터리: root/CLAUDE.md와 root/foo/CLAUDE.md가 모두 자동으로 끌려오는 모노레포에 유용합니다.
하위 디렉터리: 해당 디렉터리의 파일을 읽을 때 Claude가 하위 CLAUDE.md를 필요에 따라 끌어옵니다.

권한 설정하기

자동(auto) 모드로 분류기가 승인을 처리하게 하거나, /permissions로 특정 명령을 허용 목록에 넣거나, /sandbox로 OS 수준 격리를 적용하세요. 각 방법 모두 통제권은 여러분이 쥔 채로 끼어드는 횟수를 줄여 줍니다.

기본적으로 Claude Code는 시스템을 변경할 수 있는 동작(파일 쓰기, Bash 명령, MCP 도구 등)에 대해 권한을 요청합니다. 안전하지만 번거롭습니다. 열 번째 승인쯤이면 사실 검토라기보다 그냥 눌러 넘기는 상태가 됩니다. 이런 방해를 줄이는 방법은 세 가지입니다.

자동 모드: 별도의 분류기 모델이 명령을 검토하여 위험해 보이는 것만 막습니다. 권한 범위 확대, 알 수 없는 인프라, 적대적 콘텐츠가 유발한 동작 등입니다. 작업의 큰 방향은 신뢰하지만 단계마다 클릭해 넘기고 싶지 않을 때 가장 좋습니다.
권한 허용 목록: npm run lint나 git commit처럼 안전하다고 아는 특정 도구를 허용합니다.
샌드박싱: 파일 시스템과 네트워크 접근을 제한하는 OS 수준 격리를 켜서, 정해진 경계 안에서 Claude가 더 자유롭게 작업하도록 합니다.

권한 모드, 권한 규칙, 샌드박싱에 대해 더 알아보세요.

CLI 도구 활용하기

외부 서비스와 상호작용할 때는 gh, aws, gcloud, sentry-cli 같은 CLI 도구를 쓰라고 Claude Code에 일러 주세요.

CLI 도구는 외부 서비스와 상호작용하는 가장 컨텍스트 효율적인 방법입니다. GitHub를 쓴다면 gh CLI를 설치하세요. Claude는 이슈 생성, PR 열기, 댓글 읽기에 이 도구를 어떻게 쓰는지 알고 있습니다. gh가 없으면 Claude는 GitHub API를 쓸 수 있지만, 인증되지 않은 요청은 종종 레이트 리밋에 걸립니다.

Claude는 이미 알지 못하는 CLI 도구도 잘 배웁니다. Use 'foo-cli-tool --help' to learn about foo tool, then use it to solve A, B, C. 같은 프롬프트를 시도해 보세요.

MCP 서버 연결하기

claude mcp add를 실행해 Notion, Figma, 또는 데이터베이스 같은 외부 도구를 연결하세요.

MCP 서버를 쓰면 이슈 트래커의 기능을 구현하게 하고, 데이터베이스를 질의하고, 모니터링 데이터를 분석하고, Figma의 디자인을 통합하고, 워크플로를 자동화하도록 Claude에 요청할 수 있습니다.

훅(hook) 설정하기

예외 없이 매번 반드시 일어나야 하는 동작에는 훅을 쓰세요.

훅은 Claude 워크플로의 특정 지점에서 스크립트를 자동으로 실행합니다. 권고에 그치는 CLAUDE.md 지시와 달리, 훅은 결정적이며 그 동작이 일어남을 보장합니다.

Claude가 훅을 대신 작성해 줄 수 있습니다. "모든 파일 편집 후 eslint를 실행하는 훅을 작성해 줘"나 "migrations 폴더에 쓰기를 막는 훅을 작성해 줘" 같은 프롬프트를 시도해 보세요. 훅을 직접 손으로 구성하려면 .claude/settings.json을 편집하고, 구성된 내용을 살펴보려면 /hooks를 실행하세요.

스킬 만들기

.claude/skills/에 SKILL.md 파일을 만들어 Claude에게 도메인 지식과 재사용 가능한 워크플로를 부여하세요.

스킬은 프로젝트·팀·도메인에 특화된 정보로 Claude의 지식을 확장합니다. Claude는 관련이 있을 때 스킬을 자동으로 적용하며, /skill-name으로 직접 호출할 수도 있습니다.

스킬을 만들려면 .claude/skills/에 SKILL.md가 담긴 디렉터리를 추가하세요.

---
name: api-conventions
description: REST API design conventions for our services
---
# API Conventions
- Use kebab-case for URL paths
- Use camelCase for JSON properties
- Always include pagination for list endpoints
- Version APIs in the URL path (/v1/, /v2/)

스킬은 직접 호출하는 반복 워크플로도 정의할 수 있습니다.

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---
Analyze and fix the GitHub issue: $ARGUMENTS.

1. Use `gh issue view` to get the issue details
2. Understand the problem described in the issue
3. Search the codebase for relevant files
4. Implement the necessary changes to fix the issue
5. Write and run tests to verify the fix
6. Ensure code passes linting and type checking
7. Create a descriptive commit message
8. Push and create a PR

/fix-issue 1234를 실행해 호출합니다. 부작용이 있어 수동으로만 실행하고 싶은 워크플로에는 disable-model-invocation: true를 쓰세요.

커스텀 서브에이전트 만들기

.claude/agents/에 특화된 어시스턴트를 정의해, Claude가 격리된 작업을 위임할 수 있게 하세요.

서브에이전트는 자체 컨텍스트와 자체 허용 도구 집합 안에서 동작합니다. 파일을 많이 읽거나 특화된 집중이 필요한 작업을, 메인 대화를 어지럽히지 않고 처리할 때 유용합니다.

---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
model: opus
---
You are a senior security engineer. Review code for:
- Injection vulnerabilities (SQL, XSS, command injection)
- Authentication and authorization flaws
- Secrets or credentials in code
- Insecure data handling

Provide specific line references and suggested fixes.

서브에이전트를 쓰라고 Claude에 명시적으로 일러 주세요. "이 코드의 보안 이슈를 서브에이전트로 검토해 줘"처럼요.

플러그인 설치하기

/plugin을 실행해 마켓플레이스를 둘러보세요. 플러그인은 별도 설정 없이 스킬, 도구, 통합 기능을 더해 줍니다.

플러그인은 스킬, 훅, 서브에이전트, MCP 서버를 커뮤니티와 Anthropic이 제공하는 하나의 설치 단위로 묶습니다. 타입이 있는 언어로 작업한다면 코드 인텔리전스 플러그인을 설치해, Claude에게 정확한 심벌 탐색과 편집 후 자동 오류 감지 기능을 부여하세요.

스킬, 서브에이전트, 훅, MCP 중에서 무엇을 고를지에 대한 안내는 Extend Claude Code 문서를 참고하세요.

효과적으로 소통하세요

Claude Code와 소통하는 방식은 결과의 품질에 큰 영향을 미칩니다.

코드베이스에 관해 질문하세요

시니어 엔지니어에게 묻듯 Claude에게 물어보세요.

새 코드베이스에 적응할 때는 Claude Code를 학습과 탐색에 활용하세요. 동료 엔지니어에게 던질 법한 질문을 그대로 Claude에게 물어볼 수 있습니다.

로깅은 어떻게 동작하나요?
새 API 엔드포인트는 어떻게 만드나요?
foo.rs의 134번째 줄에 있는 async move { ... }는 무슨 일을 하나요?
CustomerOnboardingFlowImpl은 어떤 엣지 케이스를 처리하나요?
이 코드는 왜 333번째 줄에서 bar()가 아니라 foo()를 호출하나요?

이런 식으로 Claude Code를 쓰면 효과적인 적응(온보딩) 워크플로가 됩니다. 적응 속도를 높이고 다른 엔지니어의 부담을 줄여 줍니다. 특별한 프롬프팅은 필요 없습니다. 그냥 직접 물어보세요.

Claude가 여러분을 인터뷰하게 하세요

규모가 큰 기능이라면 Claude가 먼저 여러분을 인터뷰하게 하세요. 최소한의 프롬프트로 시작해, AskUserQuestion 도구로 인터뷰해 달라고 요청하세요.

Claude는 여러분이 아직 생각하지 못한 것들을 물어봅니다. 기술적 구현, UI/UX, 엣지 케이스, 트레이드오프 같은 것들 말입니다.

I want to build [brief description]. Interview me in detail using the AskUserQuestion tool.

Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs. Don't ask obvious questions, dig into the hard parts I might not have considered.

Keep interviewing until we've covered everything, then write a complete spec to SPEC.md.

명세가 완성되면 새 세션을 시작해 그것을 실행하세요. 새 세션은 구현에만 온전히 집중하는 깨끗한 컨텍스트를 갖게 되고, 여러분에게는 참조할 작성된 명세가 생깁니다.

가장 쓸모 있는 명세는 자체 완결적입니다. 관련된 파일과 인터페이스의 이름을 명시하고, 무엇이 범위 밖인지를 밝히며, 기능이 동작함을 입증하는 엔드투엔드 검증 단계로 마무리합니다. 명세를 정밀하게 다듬는 데 쓴 시간은, 구현을 지켜보는 데 쓴 시간보다 더 큰 보상으로 돌아옵니다.

세션을 관리하세요

대화는 지속되며 되돌릴 수 있습니다. 이 점을 적극 활용하세요!

일찍, 자주 방향을 바로잡으세요

Claude가 길을 벗어나는 것이 보이는 즉시 바로잡으세요.

가장 좋은 결과는 촘촘한 피드백 루프에서 나옵니다. Claude가 가끔 첫 시도에 문제를 완벽하게 풀기도 하지만, 빠르게 바로잡는 편이 대체로 더 나은 해법을 더 빨리 만들어 냅니다.

Esc: Esc 키로 Claude를 동작 중간에 멈춥니다. 컨텍스트는 보존되므로 방향을 다시 잡을 수 있습니다.
Esc + Esc 또는 /rewind: Esc를 두 번 누르거나 /rewind를 실행해 되감기 메뉴를 열면, 이전의 대화·코드 상태를 복원하거나 선택한 메시지에서부터 요약할 수 있습니다.
"Undo that": Claude에게 변경을 되돌리게 합니다.
/clear: 서로 무관한 작업 사이에 컨텍스트를 리셋합니다. 무관한 컨텍스트가 쌓인 긴 세션은 성능을 떨어뜨릴 수 있습니다.

한 세션에서 같은 문제로 두 번 넘게 바로잡았다면, 컨텍스트가 실패한 시도들로 어질러진 상태입니다. /clear를 실행하고, 그동안 배운 것을 반영한 더 구체적인 프롬프트로 새로 시작하세요. 더 나은 프롬프트로 시작한 깨끗한 세션은, 바로잡기가 누적된 긴 세션을 거의 언제나 능가합니다.

컨텍스트를 적극적으로 관리하세요

서로 무관한 작업 사이에는 /clear를 실행해 컨텍스트를 리셋하세요.

Claude Code는 컨텍스트 한계에 가까워지면 대화 기록을 자동으로 압축(compact)하여, 중요한 코드와 결정을 보존하면서 공간을 확보합니다.

긴 세션 동안 Claude의 컨텍스트 윈도는 무관한 대화, 파일 내용, 명령으로 가득 찰 수 있습니다. 이는 성능을 떨어뜨리고 때로 Claude의 주의를 흐트러뜨립니다.

작업 사이에 /clear를 자주 써서 컨텍스트 윈도를 통째로 리셋하세요.
자동 압축이 발동하면, Claude는 코드 패턴, 파일 상태, 핵심 결정 등 가장 중요한 것들을 요약합니다.
더 세밀하게 다루려면 /compact Focus on the API changes처럼 /compact 를 실행하세요.
대화의 일부만 압축하려면 Esc + Esc나 /rewind로 메시지 체크포인트를 선택한 뒤, Summarize from here(여기서부터 요약)나 Summarize up to here(여기까지 요약)를 고르세요. 전자는 그 지점부터의 메시지를 압축하면서 앞선 컨텍스트는 그대로 두고, 후자는 앞선 메시지를 압축하면서 최근 것은 온전히 둡니다. Restore vs. summarize 문서를 참고하세요.
"When compacting, always preserve the full list of modified files and any test commands" 같은 지시를 CLAUDE.md에 넣어 압축 동작을 커스터마이즈하면, 중요한 맥락이 요약 과정에서 살아남도록 할 수 있습니다.
컨텍스트에 남길 필요가 없는 간단한 질문에는 /btw를 쓰세요. 답이 닫을 수 있는 오버레이로 나타나며 대화 기록에는 절대 들어가지 않으므로, 컨텍스트를 키우지 않고도 세부 사항을 확인할 수 있습니다.

조사에는 서브에이전트를 쓰세요

"use subagents to investigate X"로 조사를 위임하세요. 서브에이전트는 별도 컨텍스트에서 탐색하므로, 메인 대화는 구현에 집중하도록 깨끗하게 유지됩니다.

컨텍스트가 근본적인 제약인 만큼, 서브에이전트는 손에 쥔 가장 강력한 도구 중 하나입니다. Claude가 코드베이스를 조사할 때는 파일을 많이 읽고, 그것이 모두 컨텍스트를 소비합니다. 서브에이전트는 별도의 컨텍스트 윈도에서 동작하며 요약을 보고합니다.

Use subagents to investigate how our authentication system handles token
refresh, and whether we have any existing OAuth utilities I should reuse.

서브에이전트는 코드베이스를 탐색하고, 관련 파일을 읽고, 발견한 내용을 보고합니다. 이 모든 과정이 메인 대화를 어지럽히지 않습니다.

Claude가 무언가를 구현한 뒤 검증에도 서브에이전트를 쓸 수 있습니다.

use a subagent to review this code for edge cases

체크포인트로 되감기

여러분이 보내는 모든 프롬프트는 체크포인트를 만듭니다. 대화, 코드, 또는 둘 다를 이전 체크포인트로 복원할 수 있습니다.

Claude는 변경 전마다 파일 스냅숏을 자동으로 남기므로, 체크포인트가 파일을 복원할 수 있습니다. Escape를 두 번 누르거나 /rewind를 실행해 되감기 메뉴를 여세요. 대화만 복원, 코드만 복원, 둘 다 복원, 또는 선택한 메시지에서부터 요약 중에서 고를 수 있습니다. 자세한 내용은 Checkpointing 문서를 참고하세요.

모든 수를 신중히 계획하는 대신, 위험해 보이는 시도를 해 보라고 Claude에게 말할 수 있습니다. 잘 안 되면 되감아서 다른 접근을 시도하면 됩니다. 체크포인트는 세션을 넘어 유지되므로, 터미널을 닫았다가 나중에 다시 되감을 수 있습니다.

체크포인트는 Claude가 가한 변경만 추적하며, 외부 프로세스는 추적하지 않습니다. 이것이 git을 대체하지는 않습니다.

대화 이어 가기

/rename으로 세션에 이름을 붙이고, 브랜치처럼 다루세요. 작업 줄기마다 각자의 지속적인 컨텍스트를 갖게 됩니다.

Claude Code는 대화를 로컬에 저장하므로, 작업이 여러 차례에 걸쳐 이어지더라도 맥락을 다시 설명할 필요가 없습니다. claude --continue를 실행해 가장 최근 세션을 이어받거나, claude --resume으로 목록에서 고르세요. oauth-migration처럼 설명이 담긴 이름을 붙여 두면 나중에 찾기 쉽습니다. 이어 가기, 브랜치 분기, 명명을 위한 전체 기능은 Manage sessions 문서를 참고하세요.

자동화하고 확장하세요

Claude 하나를 능숙하게 다루게 되면, 병렬 세션·비대화형 모드·팬아웃 패턴으로 결과물을 배가할 수 있습니다.

여기까지는 모두 사람 한 명, Claude 하나, 대화 하나를 전제로 했습니다. 하지만 Claude Code는 수평으로 확장됩니다. 이 절의 기법들은 더 많은 일을 해내는 방법을 보여 줍니다.

비대화형 모드 실행하기

CI, 프리커밋 훅, 스크립트에서 claude -p "prompt"를 쓰세요. 스트리밍 JSON 출력이 필요하면 --output-format stream-json --verbose를 더하세요.

claude -p "your prompt"로 세션 없이 Claude를 비대화형으로 실행할 수 있습니다. 비대화형 모드는 Claude를 CI 파이프라인, 프리커밋 훅, 또는 어떤 자동화 워크플로에든 통합하는 방법입니다. 출력 형식 덕분에 결과를 프로그램으로 파싱할 수 있습니다. 일반 텍스트, JSON, 스트리밍 JSON 중에서 고르세요.

# One-off queries
claude -p "Explain what this project does"

# Structured output for scripts
claude -p "List all API endpoints" --output-format json

# Streaming for real-time processing
claude -p "Analyze this log file" --output-format stream-json --verbose

여러 Claude 세션 실행하기

여러 Claude 세션을 병렬로 실행해 개발 속도를 높이고, 격리된 실험을 돌리고, 복잡한 워크플로를 시작하세요.

직접 얼마나 조율할지에 맞춰 병렬 방식을 고르세요.

워크트리(Worktrees): 격리된 git 체크아웃에서 별도의 CLI 세션을 돌려, 편집이 서로 충돌하지 않게 합니다.
데스크톱 앱: 여러 로컬 세션을 각각 자체 워크트리에서 시각적으로 관리합니다.
Claude Code on the web: Anthropic이 관리하는 클라우드 인프라의 격리된 VM에서 세션을 돌립니다.
에이전트 팀(Agent teams): 공유 작업, 메시징, 팀 리드를 갖춘 여러 세션을 자동으로 조율합니다.

작업을 병렬화하는 것 외에도, 여러 세션은 품질 중심 워크플로를 가능하게 합니다. 새로운 컨텍스트는 코드 리뷰의 질을 높입니다. Claude가 방금 작성한 코드에 치우치지 않기 때문입니다.

예를 들어, 작성자/리뷰어(Writer/Reviewer) 패턴을 써 보세요.

세션 A (작성자)	세션 B (리뷰어)
`Implement a rate limiter for our API endpoints`
	`Review the rate limiter implementation in @src/middleware/rateLimiter.ts. Look for edge cases, race conditions, and consistency with our existing middleware patterns.`
`Here's the review feedback: [Session B output]. Address these issues.`

테스트로도 비슷하게 할 수 있습니다. 한 Claude가 테스트를 작성하게 한 뒤, 다른 Claude가 그 테스트를 통과시키는 코드를 작성하게 하면 됩니다.

파일들에 걸쳐 팬아웃하기

각 작업마다 claude -p를 호출하는 루프를 돌리세요. 배치 작업의 권한 범위는 --allowedTools로 제한하세요.

대규모 마이그레이션이나 분석에서는 여러 병렬 Claude 호출에 작업을 분산할 수 있습니다.

작업 목록 생성하기

마이그레이션이 필요한 모든 파일을 Claude에게 나열하게 합니다(예: list all 2,000 Python files that need migrating).

목록을 도는 스크립트 작성하기

for file in $(cat files.txt); do
  claude -p "Migrate $file from React to Vue. Return OK or FAIL." \
    --allowedTools "Edit,Bash(git commit *)"
done

몇 개 파일로 시험한 뒤 규모를 키워 실행하기

처음 2~3개 파일에서 잘못되는 부분을 보며 프롬프트를 다듬은 뒤, 전체 집합에 돌리세요. --allowedTools 플래그는 Claude가 할 수 있는 일을 제한하는데, 무인으로 실행할 때 특히 중요합니다.

Claude를 기존 데이터/처리 파이프라인에 통합할 수도 있습니다.

claude -p "<your prompt>" --output-format json | your_command

개발 중 디버깅에는 --verbose를 쓰고, 프로덕션에서는 끄세요.

자동 모드로 자율 실행하기

백그라운드 안전 검사를 곁들인 중단 없는 실행에는 자동 모드를 쓰세요. 분류기 모델이 명령 실행 전에 검토하여, 권한 범위 확대·알 수 없는 인프라·적대적 콘텐츠가 유발한 동작을 막으면서 일상적인 작업은 프롬프트 없이 진행하게 합니다.

claude --permission-mode auto -p "fix all lint errors"

-p 플래그를 쓴 비대화형 실행에서는, 분류기가 동작을 거듭 막으면 자동 모드가 중단됩니다. 기댈 사용자가 없기 때문입니다. 임계값은 when auto mode falls back 문서를 참고하세요.

적대적 검토 단계를 추가하세요

작업을 완료로 간주하기 전에, 서브에이전트가 새 컨텍스트에서 diff를 검토하고 빠진 부분을 보고하게 하세요.

Claude가 무인으로 오래 작업할수록, 일을 끝났다고 셈하기 전 독립적인 점검이 더 중요해집니다. 새 서브에이전트 컨텍스트에서 도는 리뷰어는 변경을 만들어 낸 추론 과정은 보지 못한 채 diff와 여러분이 준 기준만 보므로, 결과를 그 자체로 평가합니다.

정확성 점검에는 번들로 제공되는 /code-review 스킬을 실행하세요. 이 스킬은 현재 diff의 버그를 새 서브에이전트에서 검토해 그 결과를 세션으로 돌려줍니다. 대신 계획과 diff를 대조하려면, 검토 프롬프트를 직접 작성하세요. 점검할 작업, 그것을 대조할 계획, 그리고 무엇을 발견 사항으로 칠지를 명시하세요.

Use a subagent to review the rate limiter diff against PLAN.md. Check that
every requirement is implemented, the listed edge cases have tests, and
nothing outside the task's scope changed. Report gaps, not style preferences.

리뷰어가 서브에이전트로 돌기 때문에, 구현 중인 세션이 빠진 부분을 직접 전달받아, 창 사이로 결과를 복사해 옮기는 일 없이 고치고 다시 검토할 수 있습니다. 더 긴 자율 실행에서는 에이전트 팀이 이 루프를 여러 작업에 걸쳐 이어 가는 동안, 여러분은 기록된 발견 사항을 군데군데 점검하면 됩니다.

빠진 부분을 찾으라고 지시받은 리뷰어는, 작업이 견실할 때조차 대개 무언가를 보고합니다. 그렇게 하라고 요청받았기 때문입니다. 모든 발견 사항을 좇으면 과잉 설계로 이어집니다. 불필요한 추상화 계층, 방어적 코드, 일어날 수 없는 케이스를 위한 테스트 같은 것들 말입니다. 정확성이나 명시된 요구사항에 영향을 주는 빠진 부분만 표시하라고 리뷰어에게 일러 주고, 나머지는 선택 사항으로 취급하세요.

흔한 실패 패턴을 피하세요

다음은 자주 저지르는 실수들입니다. 일찍 알아차리면 시간을 아낄 수 있습니다.

잡동사니 세션. 한 작업으로 시작했다가 무관한 것을 묻고, 다시 첫 작업으로 돌아옵니다. 컨텍스트가 무관한 정보로 가득 찹니다.

해법: 서로 무관한 작업 사이에 /clear를 실행하세요.

거듭되는 바로잡기. Claude가 뭔가를 틀리게 하고, 여러분이 바로잡고, 여전히 틀리고, 또 바로잡습니다. 컨텍스트가 실패한 접근들로 오염됩니다.

해법: 두 번 바로잡아도 실패하면 /clear하고, 배운 것을 반영한 더 나은 초기 프롬프트를 작성하세요.

과하게 명시된 CLAUDE.md. CLAUDE.md가 너무 길면, 중요한 규칙이 소음에 묻혀 Claude가 절반을 무시합니다.

해법: 가차 없이 가지치기하세요. 그 지시 없이도 Claude가 이미 올바르게 한다면, 지우거나 훅으로 바꾸세요.

신뢰-검증 간극. Claude가 그럴듯해 보이지만 엣지 케이스를 처리하지 못하는 구현을 내놓습니다.

해법: 언제나 검증 수단(테스트, 스크립트, 스크린샷)을 제공하세요. 검증할 수 없다면, 출시하지 마세요.

끝없는 탐색. 범위를 정하지 않고 Claude에게 무언가를 "조사"해 달라고 합니다. Claude가 수백 개 파일을 읽으며 컨텍스트를 채웁니다.

해법: 조사 범위를 좁게 잡거나 서브에이전트를 써서, 탐색이 메인 컨텍스트를 잡아먹지 않게 하세요.

직관을 길러 가세요

이 가이드의 패턴은 불변의 법칙이 아닙니다. 대체로 잘 통하는 출발점일 뿐, 모든 상황에 최적은 아닐 수 있습니다.

때로는 컨텍스트가 쌓이도록 두는 편이 낫습니다. 하나의 복잡한 문제에 깊이 들어가 있어 그 히스토리가 값질 때 말입니다. 때로는 계획을 건너뛰고 Claude가 알아서 하게 두는 편이 낫습니다. 작업이 탐색적일 때 말입니다. 때로는 모호한 프롬프트가 정확히 맞습니다. 제약을 걸기 전에 Claude가 문제를 어떻게 해석하는지 보고 싶을 때 말입니다.

무엇이 통하는지에 주의를 기울이세요. Claude가 훌륭한 결과를 냈을 때, 여러분이 무엇을 했는지 살펴보세요. 프롬프트 구조, 제공한 맥락, 사용한 모드 같은 것들 말입니다. Claude가 헤맬 때는 왜 그런지 물어보세요. 컨텍스트가 너무 어수선했나요? 프롬프트가 너무 모호했나요? 작업이 한 번에 처리하기엔 너무 컸나요?

시간이 지나면 어떤 가이드도 담아낼 수 없는 직관이 길러집니다. 언제 구체적이어야 하고 언제 열어 두어야 하는지, 언제 계획하고 언제 탐색해야 하는지, 언제 컨텍스트를 비우고 언제 쌓이도록 두어야 하는지를 알게 됩니다.