Claude Code 모범 사례

환경 구성부터 병렬 세션 확장까지, Claude Code를 최대한 활용하기 위한 팁과 패턴.

Claude Code는 에이전트형 코딩 환경입니다. 질문에 답하고 기다리는 챗봇과 달리, Claude Code는 파일을 읽고, 명령을 실행하고, 변경을 수행하며, 여러분이 지켜보거나 방향을 수정하거나 자리를 비우는 동안에도 자율적으로 문제를 해결합니다.

이는 작업 방식을 바꿉니다. 직접 코드를 작성하고 Claude에게 리뷰를 요청하는 대신, 원하는 것을 설명하면 Claude가 구현 방법을 스스로 파악합니다. Claude가 탐색하고, 계획하고, 구현합니다.

하지만 이러한 자율성에도 학습 곡선이 있습니다. Claude는 여러분이 이해해야 할 특정 제약 조건 안에서 작동합니다.

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

대부분의 모범 사례는 하나의 제약 조건에 기반합니다: Claude의 컨텍스트 윈도우는 빠르게 채워지며, 채워질수록 성능이 저하됩니다.

Claude의 컨텍스트 윈도우는 모든 메시지, Claude가 읽는 모든 파일, 모든 명령 출력을 포함한 전체 대화를 담고 있습니다. 그러나 이는 빠르게 채워질 수 있습니다. 단일 디버깅 세션이나 코드베이스 탐색만으로도 수만 개의 토큰이 생성되고 소비될 수 있습니다.

이것이 중요한 이유는 컨텍스트가 채워질수록 LLM 성능이 저하되기 때문입니다. 컨텍스트 윈도우가 가득 차면 Claude가 이전 지시를 "잊어버리거나" 실수가 늘어날 수 있습니다. 컨텍스트 윈도우는 관리해야 할 가장 중요한 리소스입니다. 커스텀 상태 표시줄로 컨텍스트 사용량을 지속적으로 추적하고, 토큰 사용량을 줄이는 전략은 토큰 사용량 줄이기를 참고하세요.

Claude에게 작업을 검증할 수단을 제공하세요

팁:

테스트, 스크린샷 또는 예상 출력을 포함하여 Claude가 스스로 확인할 수 있게 하세요. 이것이 가장 효과적인 단 하나의 방법입니다.

Claude는 자신의 작업을 검증할 수 있을 때, 즉 테스트를 실행하고 스크린샷을 비교하고 출력을 검증할 수 있을 때 극적으로 더 나은 성능을 발휘합니다.

명확한 성공 기준이 없으면, 올바르게 보이지만 실제로는 작동하지 않는 결과물을 생성할 수 있습니다. 여러분이 유일한 피드백 루프가 되며, 모든 실수에 여러분의 주의가 필요합니다.

전략	이전	이후
검증 기준 제공	"이메일 주소를 검증하는 함수를 구현해줘"	"validateEmail 함수를 작성해. 예시 테스트 케이스: [email protected]은 true, invalid는 false, [email protected]은 false. 구현 후 테스트를 실행해"
UI 변경 사항을 시각적으로 검증	"대시보드를 더 보기 좋게 만들어줘"	"[스크린샷 붙여넣기] 이 디자인을 구현해. 결과물의 스크린샷을 찍어서 원본과 비교해. 차이점을 나열하고 수정해"
증상이 아닌 근본 원인을 해결	"빌드가 실패해"	"빌드가 이 에러로 실패해: [에러 붙여넣기]. 수정하고 빌드가 성공하는지 확인해. 에러를 억제하지 말고 근본 원인을 해결해"

UI 변경 사항은 Claude in Chrome 확장 프로그램을 사용하여 검증할 수 있습니다. 브라우저에서 새 탭을 열고, UI를 테스트하고, 코드가 작동할 때까지 반복합니다.

검증은 테스트 스위트, 린터 또는 출력을 확인하는 Bash 명령일 수도 있습니다. 검증을 견고하게 만드는 데 투자하세요.

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

팁:

잘못된 문제를 해결하는 것을 피하기 위해 조사와 계획을 구현과 분리하세요.

Claude가 바로 코딩에 들어가면 잘못된 문제를 해결하는 코드를 생성할 수 있습니다. Plan Mode를 사용하여 탐색과 실행을 분리하세요.

권장 워크플로는 네 단계로 구성됩니다:

Step 1: 탐색

Plan Mode에 진입합니다. Claude는 파일을 읽고 변경 없이 질문에 답합니다.

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

Step 2: 계획

Claude에게 상세한 구현 계획을 작성하도록 요청합니다.

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

Ctrl+G를 눌러 Claude가 진행하기 전에 텍스트 편집기에서 계획을 직접 편집할 수 있습니다.

Step 3: 구현

Normal Mode로 전환하고 Claude가 계획에 따라 코딩하도록 합니다.

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

Step 4: 커밋

Claude에게 설명적인 메시지로 커밋하고 PR을 생성하도록 요청합니다.

commit with a descriptive message and open a PR

참고:

Plan Mode는 유용하지만 오버헤드도 추가됩니다.

범위가 명확하고 수정이 작은 작업(오타 수정, 로그 한 줄 추가, 변수 이름 변경 등)의 경우 Claude에게 바로 수행하도록 요청하세요.

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

프롬프트에 구체적인 컨텍스트를 제공하세요

팁:

지시가 정확할수록 수정 횟수가 줄어듭니다.

Claude는 의도를 추론할 수 있지만 마음을 읽을 수는 없습니다. 특정 파일을 참조하고, 제약 조건을 언급하고, 예시 패턴을 지정하세요.

전략	이전	이후
작업 범위를 지정하세요. 어떤 파일, 어떤 시나리오, 테스트 선호도를 명시하세요.	"foo.py에 대한 테스트를 추가해줘"	"foo.py에 사용자가 로그아웃된 엣지 케이스를 커버하는 테스트를 작성해. mock은 피해줘."
출처를 지정하세요. Claude를 질문에 답할 수 있는 소스로 안내하세요.	"ExecutionFactory는 왜 이렇게 이상한 API를 가지고 있어?"	"ExecutionFactory의 git 히스토리를 살펴보고 API가 어떻게 현재 형태가 되었는지 요약해줘"
기존 패턴을 참조하세요. Claude를 코드베이스의 패턴으로 안내하세요.	"캘린더 위젯을 추가해줘"	"홈 페이지에서 기존 위젯이 어떻게 구현되었는지 확인해서 패턴을 파악해. HotDogWidget.php가 좋은 예시야. 그 패턴을 따라 사용자가 월을 선택하고 앞뒤로 페이지네이션하여 연도를 선택할 수 있는 새 캘린더 위젯을 구현해. 코드베이스에 이미 사용된 라이브러리 외에는 다른 라이브러리 없이 처음부터 구현해."
증상을 설명하세요. 증상, 가능한 위치, "수정된" 상태가 어떤 것인지 제공하세요.	"로그인 버그를 고쳐줘"	"사용자들이 세션 타임아웃 후 로그인이 실패한다고 보고해. src/auth/의 인증 흐름, 특히 토큰 갱신을 확인해. 문제를 재현하는 실패 테스트를 작성하고 수정해"

모호한 프롬프트는 탐색 중이고 방향을 수정할 여유가 있을 때 유용할 수 있습니다. "이 파일에서 무엇을 개선하겠어?"와 같은 프롬프트는 여러분이 생각지 못한 것들을 발견할 수 있습니다.

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

팁:

@를 사용하여 파일을 참조하거나, 스크린샷/이미지를 붙여넣거나, 데이터를 직접 파이프하세요.

Claude에게 풍부한 데이터를 제공하는 여러 방법이 있습니다:

@로 파일 참조: 코드 위치를 설명하는 대신 사용합니다. Claude가 응답하기 전에 파일을 읽습니다.
이미지 직접 붙여넣기: 프롬프트에 이미지를 복사/붙여넣기하거나 드래그 앤 드롭합니다.
URL 제공: 문서 및 API 참조용. /permissions를 사용하여 자주 사용하는 도메인을 허용 목록에 추가합니다.
데이터 파이프: cat error.log | claude를 실행하여 파일 내용을 직접 전송합니다.
Claude가 필요한 것을 직접 가져오도록 하기: Bash 명령, MCP 도구 또는 파일 읽기를 통해 Claude가 직접 컨텍스트를 가져오도록 합니다.

환경을 설정하세요

몇 가지 설정 단계로 Claude Code를 모든 세션에서 훨씬 더 효과적으로 만들 수 있습니다. 확장 기능과 각각의 사용 시기에 대한 전체 개요는 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는 매 세션마다 로드되므로 전반적으로 적용되는 내용만 포함하세요. 특정 상황에서만 관련 있는 도메인 지식이나 워크플로에는 skills를 대신 사용하세요. Claude가 필요할 때 로드하므로 모든 대화를 부풀리지 않습니다.

간결하게 유지하세요. 각 줄마다 다음을 자문하세요: "이것을 제거하면 Claude가 실수를 하게 될까?" 그렇지 않다면 삭제하세요. 비대해진 CLAUDE.md 파일은 Claude가 실제 지시를 무시하게 만듭니다!

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

규칙이 있음에도 Claude가 원하지 않는 행동을 계속한다면, 파일이 너무 길어서 규칙이 묻히고 있을 수 있습니다. Claude가 CLAUDE.md에 답이 있는 질문을 한다면, 표현이 모호할 수 있습니다. 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 파일을 불러옴

권한 설정하기

팁:

/permissions을 사용하여 안전한 명령을 허용 목록에 추가하거나, /sandbox로 OS 수준 격리를 설정하세요. 이렇게 하면 제어권을 유지하면서 중단을 줄일 수 있습니다.

기본적으로 Claude Code는 시스템을 수정할 수 있는 작업(파일 쓰기, Bash 명령, MCP 도구 등)에 대해 권한을 요청합니다. 이는 안전하지만 번거롭습니다. 열 번째 승인 이후에는 더 이상 제대로 검토하지 않고 그냥 클릭하게 됩니다. 이러한 중단을 줄이는 두 가지 방법이 있습니다:

권한 허용 목록: 안전하다고 아는 특정 도구를 허용합니다 (npm run lint나 git commit 등)
샌드박싱: 파일 시스템과 네트워크 접근을 제한하는 OS 수준 격리를 활성화하여, Claude가 정의된 경계 내에서 더 자유롭게 작업할 수 있게 합니다

또는 --dangerously-skip-permissions를 사용하여 lint 에러 수정이나 보일러플레이트 생성과 같은 제한된 워크플로에서 모든 권한 확인을 우회할 수 있습니다.

주의:

Claude가 임의의 명령을 실행하도록 허용하면 데이터 손실, 시스템 손상 또는 프롬프트 인젝션을 통한 데이터 유출이 발생할 수 있습니다. --dangerously-skip-permissions는 인터넷 접근이 없는 샌드박스에서만 사용하세요.

권한 설정하기 및 샌드박싱 활성화하기에서 자세히 읽어보세요.

CLI 도구 사용하기

팁:

외부 서비스와 상호작용할 때 Claude Code에게 gh, aws, gcloud, sentry-cli 같은 CLI 도구를 사용하도록 알려주세요.

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 서버를 통해 Claude에게 이슈 트래커에서 기능 구현, 데이터베이스 쿼리, 모니터링 데이터 분석, Figma 디자인 통합, 워크플로 자동화 등을 요청할 수 있습니다.

훅 설정하기

팁:

예외 없이 매번 실행되어야 하는 작업에는 훅을 사용하세요.

훅은 Claude 워크플로의 특정 지점에서 스크립트를 자동으로 실행합니다. 권고 사항인 CLAUDE.md 지시와 달리, 훅은 결정적이며 작업이 반드시 실행되는 것을 보장합니다.

Claude가 훅을 작성해줄 수 있습니다. "Write a hook that runs eslint after every file edit" 또는 *"Write a hook that blocks writes to the migrations folder."*와 같은 프롬프트를 시도해 보세요. /hooks를 실행하여 대화형으로 설정하거나, .claude/settings.json을 직접 편집하세요.

스킬 생성하기

팁:

.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에게 서브에이전트를 사용하도록 명시적으로 지시하세요: "Use a subagent to review this code for security issues."

플러그인 설치하기

팁:

/plugin을 실행하여 마켓플레이스를 탐색하세요. 플러그인은 별도의 설정 없이 스킬, 도구 및 통합을 추가합니다.

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

스킬, 서브에이전트, 훅, MCP 중 선택하는 가이드는 Claude Code 확장하기를 참고하세요.

효과적으로 소통하기

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

코드베이스에 대해 질문하기

팁:

시니어 엔지니어에게 물어볼 것과 같은 질문을 Claude에게 하세요.

새로운 코드베이스에 온보딩할 때, Claude Code를 학습과 탐색에 활용하세요. 다른 엔지니어에게 물어볼 것과 같은 질문을 Claude에게 할 수 있습니다:

로깅은 어떻게 작동해?
새 API 엔드포인트는 어떻게 만들어?
foo.rs의 134번째 줄에서 async move { ... }는 무엇을 해?
CustomerOnboardingFlowImpl은 어떤 엣지 케이스를 처리해?
333번째 줄에서 이 코드가 왜 bar() 대신 foo()를 호출해?

이런 방식으로 Claude Code를 사용하면 효과적인 온보딩 워크플로가 되어, 적응 시간을 단축하고 다른 엔지니어의 부담을 줄입니다. 특별한 프롬프트 기법이 필요 없습니다: 직접적으로 질문하세요.

Claude가 여러분을 인터뷰하도록 하기

팁:

큰 기능의 경우, 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는 컨텍스트 한계에 도달하면 자동으로 대화 기록을 압축하여 중요한 코드와 결정을 보존하면서 공간을 확보합니다.

긴 세션 동안 Claude의 컨텍스트 윈도우가 관련 없는 대화, 파일 내용, 명령으로 채워질 수 있습니다. 이는 성능을 저하시키고 때로는 Claude를 산만하게 만듭니다.

작업 사이에 /clear를 자주 사용하여 컨텍스트 윈도우를 완전히 초기화하세요
자동 압축이 트리거되면, Claude는 코드 패턴, 파일 상태, 주요 결정 등 가장 중요한 것을 요약합니다
더 세밀한 제어를 위해 /compact <instructions>를 실행하세요, 예: /compact Focus on the API changes
대화의 일부만 압축하려면, Esc + Esc 또는 /rewind를 사용하여 메시지 체크포인트를 선택하고 Summarize from here를 선택하세요. 이전 컨텍스트는 유지하면서 해당 지점부터의 메시지를 압축합니다.
CLAUDE.md에 "When compacting, always preserve the full list of modified files and any test commands"와 같은 지시를 추가하여 압축 동작을 커스터마이즈하여 중요한 컨텍스트가 요약 과정에서 살아남도록 하세요

조사에 서브에이전트 사용하기

팁:

"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가 수행하는 모든 작업은 체크포인트를 생성합니다. 이전 체크포인트의 대화, 코드 또는 둘 다 복원할 수 있습니다.

Claude는 변경 전에 자동으로 체크포인트를 생성합니다. Escape를 두 번 누르거나 /rewind를 실행하여 되감기 메뉴를 엽니다. 대화만 복원, 코드만 복원, 둘 다 복원, 또는 선택한 메시지부터 요약을 할 수 있습니다. 자세한 내용은 체크포인팅을 참고하세요.

모든 움직임을 신중하게 계획하는 대신, Claude에게 위험한 시도를 하도록 할 수 있습니다. 작동하지 않으면 되감고 다른 접근법을 시도하세요. 체크포인트는 세션 간에 유지되므로 터미널을 닫아도 나중에 되감기가 가능합니다.

주의:

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

대화 이어가기

팁:

claude --continue를 실행하여 이전에 멈춘 곳에서 계속하거나, --resume으로 최근 세션 중에서 선택하세요.

Claude Code는 대화를 로컬에 저장합니다. 작업이 여러 세션에 걸칠 때, 컨텍스트를 다시 설명할 필요가 없습니다:

claude --continue    # Resume the most recent conversation
claude --resume      # Select from recent conversations

/rename을 사용하여 "oauth-migration" 또는 "debugging-memory-leak"과 같은 설명적인 이름을 세션에 부여하여 나중에 찾을 수 있게 하세요. 세션을 브랜치처럼 취급하세요: 서로 다른 작업 흐름이 별도의 영구적인 컨텍스트를 가질 수 있습니다.

자동화 및 확장

하나의 Claude에 능숙해지면, 병렬 세션, 비대화형 모드, 팬아웃 패턴으로 출력을 배가하세요.

지금까지의 모든 내용은 한 명의 사람, 하나의 Claude, 하나의 대화를 전제로 합니다. 하지만 Claude Code는 수평으로 확장됩니다. 이 섹션의 기법들은 더 많은 것을 수행할 수 있는 방법을 보여줍니다.

비대화형 모드 실행

팁:

CI, pre-commit 훅 또는 스크립트에서 claude -p "prompt"를 사용하세요. 스트리밍 JSON 출력을 위해 --output-format stream-json을 추가하세요.

claude -p "your prompt"로 Claude를 세션 없이 비대화형으로 실행할 수 있습니다. 비대화형 모드는 Claude를 CI 파이프라인, pre-commit 훅 또는 모든 자동화된 워크플로에 통합하는 방법입니다. 출력 형식을 통해 결과를 프로그래밍 방식으로 파싱할 수 있습니다: 일반 텍스트, 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

여러 Claude 세션 실행

팁:

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

병렬 세션을 실행하는 세 가지 주요 방법이 있습니다:

Claude Code 데스크톱 앱: 여러 로컬 세션을 시각적으로 관리합니다. 각 세션은 자체 격리된 worktree를 가집니다.
웹에서의 Claude Code: Anthropic의 보안 클라우드 인프라에서 격리된 VM으로 실행합니다.
에이전트 팀: 공유 작업, 메시징, 팀 리더와 함께 여러 세션의 자동 조정.

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

예를 들어, Writer/Reviewer 패턴을 사용합니다:

세션 A (Writer)	세션 B (Reviewer)
`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 호출에 작업을 분배할 수 있습니다:

Step 1: 작업 목록 생성

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

Step 2: 목록을 순회하는 스크립트 작성

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

Step 3: 몇 개 파일로 테스트한 후 전체 규모로 실행

처음 2-3개 파일에서 잘못된 점을 기반으로 프롬프트를 다듬은 후, 전체 세트에 실행합니다. --allowedTools 플래그는 Claude가 할 수 있는 것을 제한하며, 이는 무인으로 실행할 때 중요합니다.

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

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

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

안전한 자율 모드

claude --dangerously-skip-permissions를 사용하여 모든 권한 확인을 우회하고 Claude가 중단 없이 작업하도록 합니다. lint 에러 수정이나 보일러플레이트 코드 생성과 같은 워크플로에 적합합니다.

주의:

Claude가 임의의 명령을 실행하도록 허용하는 것은 위험하며, 데이터 손실, 시스템 손상 또는 데이터 유출(예: 프롬프트 인젝션 공격을 통해)이 발생할 수 있습니다. 이러한 위험을 최소화하려면, 인터넷 접근이 없는 컨테이너에서 --dangerously-skip-permissions를 사용하세요.

샌드박싱(/sandbox)을 활성화하면, 더 나은 보안과 함께 유사한 자율성을 얻을 수 있습니다. 샌드박스는 모든 확인을 우회하는 대신 사전에 경계를 정의합니다.

일반적인 실패 패턴 피하기

다음은 흔한 실수들입니다. 일찍 인식하면 시간을 절약할 수 있습니다:

종합 선물 세트 세션. 하나의 작업으로 시작했다가 관련 없는 것을 물어보고, 다시 첫 번째 작업으로 돌아갑니다. 컨텍스트가 관련 없는 정보로 가득 찹니다.

해결: 관련 없는 작업 사이에 /clear를 사용하세요.
반복적인 수정. Claude가 잘못하고, 수정하고, 여전히 잘못하고, 다시 수정합니다. 컨텍스트가 실패한 접근법으로 오염됩니다.

해결: 두 번 수정에 실패한 후에는, /clear하고 학습한 내용을 반영한 더 나은 초기 프롬프트를 작성하세요.
과도하게 명세된 CLAUDE.md. CLAUDE.md가 너무 길면, 중요한 규칙이 노이즈에 묻혀 Claude가 절반을 무시합니다.

해결: 과감하게 정리하세요. Claude가 지시 없이도 이미 올바르게 수행하고 있다면, 삭제하거나 훅으로 전환하세요.
신뢰 후 검증 격차. Claude가 그럴듯해 보이지만 엣지 케이스를 처리하지 않는 구현을 생성합니다.

해결: 항상 검증(테스트, 스크립트, 스크린샷)을 제공하세요. 검증할 수 없다면 배포하지 마세요.
끝없는 탐색. 범위를 지정하지 않고 Claude에게 무언가를 "조사"하도록 요청합니다. Claude가 수백 개의 파일을 읽어 컨텍스트를 채웁니다.

해결: 조사 범위를 좁게 설정하거나, 서브에이전트를 사용하여 탐색이 메인 컨텍스트를 소비하지 않도록 하세요.

직관을 키우세요

이 가이드의 패턴은 고정불변이 아닙니다. 일반적으로 잘 작동하는 출발점이지만, 모든 상황에 최적은 아닐 수 있습니다.

때로는 하나의 복잡한 문제에 깊이 빠져 있어 기록이 가치 있기 때문에 컨텍스트가 누적되도록 해야 합니다. 때로는 작업이 탐색적이기 때문에 계획을 건너뛰고 Claude가 스스로 파악하도록 해야 합니다. 때로는 문제를 제약하기 전에 Claude가 어떻게 해석하는지 보고 싶기 때문에 모호한 프롬프트가 정확히 맞습니다.

무엇이 효과적인지 주의를 기울이세요. Claude가 훌륭한 결과물을 생성했을 때, 여러분이 한 것을 관찰하세요: 프롬프트 구조, 제공한 컨텍스트, 사용했던 모드. Claude가 어려움을 겪을 때, 왜 그런지 물어보세요. 컨텍스트가 너무 시끄러웠나요? 프롬프트가 너무 모호했나요? 작업이 한 번에 처리하기에 너무 컸나요?

시간이 지나면, 어떤 가이드도 담을 수 없는 직관이 발달합니다. 언제 구체적이어야 하고 언제 개방적이어야 하는지, 언제 계획하고 언제 탐색해야 하는지, 언제 컨텍스트를 정리하고 언제 누적시켜야 하는지 알게 될 것입니다.

Claude Code 모범 사례

환경 구성부터 병렬 세션 확장까지, Claude Code를 최대한 활용하기 위한 팁과 패턴.

하지만 이러한 자율성에도 학습 곡선이 있습니다. Claude는 여러분이 이해해야 할 특정 제약 조건 안에서 작동합니다.

대부분의 모범 사례는 하나의 제약 조건에 기반합니다: Claude의 컨텍스트 윈도우는 빠르게 채워지며, 채워질수록 성능이 저하됩니다.

Claude에게 작업을 검증할 수단을 제공하세요

팁:

테스트, 스크린샷 또는 예상 출력을 포함하여 Claude가 스스로 확인할 수 있게 하세요. 이것이 가장 효과적인 단 하나의 방법입니다.

전략	이전	이후
검증 기준 제공	"이메일 주소를 검증하는 함수를 구현해줘"	"validateEmail 함수를 작성해. 예시 테스트 케이스: [email protected]은 true, invalid는 false, [email protected]은 false. 구현 후 테스트를 실행해"
UI 변경 사항을 시각적으로 검증	"대시보드를 더 보기 좋게 만들어줘"	"[스크린샷 붙여넣기] 이 디자인을 구현해. 결과물의 스크린샷을 찍어서 원본과 비교해. 차이점을 나열하고 수정해"
증상이 아닌 근본 원인을 해결	"빌드가 실패해"	"빌드가 이 에러로 실패해: [에러 붙여넣기]. 수정하고 빌드가 성공하는지 확인해. 에러를 억제하지 말고 근본 원인을 해결해"

검증은 테스트 스위트, 린터 또는 출력을 확인하는 Bash 명령일 수도 있습니다. 검증을 견고하게 만드는 데 투자하세요.

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

팁:

잘못된 문제를 해결하는 것을 피하기 위해 조사와 계획을 구현과 분리하세요.

Claude가 바로 코딩에 들어가면 잘못된 문제를 해결하는 코드를 생성할 수 있습니다. Plan Mode를 사용하여 탐색과 실행을 분리하세요.

권장 워크플로는 네 단계로 구성됩니다:

Step 1: 탐색

Plan Mode에 진입합니다. Claude는 파일을 읽고 변경 없이 질문에 답합니다.

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

Step 2: 계획

Claude에게 상세한 구현 계획을 작성하도록 요청합니다.

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

Ctrl+G를 눌러 Claude가 진행하기 전에 텍스트 편집기에서 계획을 직접 편집할 수 있습니다.

Step 3: 구현

Normal Mode로 전환하고 Claude가 계획에 따라 코딩하도록 합니다.

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

Step 4: 커밋

Claude에게 설명적인 메시지로 커밋하고 PR을 생성하도록 요청합니다.

commit with a descriptive message and open a PR

참고:

Plan Mode는 유용하지만 오버헤드도 추가됩니다.

범위가 명확하고 수정이 작은 작업(오타 수정, 로그 한 줄 추가, 변수 이름 변경 등)의 경우 Claude에게 바로 수행하도록 요청하세요.

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

프롬프트에 구체적인 컨텍스트를 제공하세요

팁:

지시가 정확할수록 수정 횟수가 줄어듭니다.

Claude는 의도를 추론할 수 있지만 마음을 읽을 수는 없습니다. 특정 파일을 참조하고, 제약 조건을 언급하고, 예시 패턴을 지정하세요.

전략	이전	이후
작업 범위를 지정하세요. 어떤 파일, 어떤 시나리오, 테스트 선호도를 명시하세요.	"foo.py에 대한 테스트를 추가해줘"	"foo.py에 사용자가 로그아웃된 엣지 케이스를 커버하는 테스트를 작성해. mock은 피해줘."
출처를 지정하세요. Claude를 질문에 답할 수 있는 소스로 안내하세요.	"ExecutionFactory는 왜 이렇게 이상한 API를 가지고 있어?"	"ExecutionFactory의 git 히스토리를 살펴보고 API가 어떻게 현재 형태가 되었는지 요약해줘"
기존 패턴을 참조하세요. Claude를 코드베이스의 패턴으로 안내하세요.	"캘린더 위젯을 추가해줘"	"홈 페이지에서 기존 위젯이 어떻게 구현되었는지 확인해서 패턴을 파악해. HotDogWidget.php가 좋은 예시야. 그 패턴을 따라 사용자가 월을 선택하고 앞뒤로 페이지네이션하여 연도를 선택할 수 있는 새 캘린더 위젯을 구현해. 코드베이스에 이미 사용된 라이브러리 외에는 다른 라이브러리 없이 처음부터 구현해."
증상을 설명하세요. 증상, 가능한 위치, "수정된" 상태가 어떤 것인지 제공하세요.	"로그인 버그를 고쳐줘"	"사용자들이 세션 타임아웃 후 로그인이 실패한다고 보고해. src/auth/의 인증 흐름, 특히 토큰 갱신을 확인해. 문제를 재현하는 실패 테스트를 작성하고 수정해"

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

팁:

@를 사용하여 파일을 참조하거나, 스크린샷/이미지를 붙여넣거나, 데이터를 직접 파이프하세요.

Claude에게 풍부한 데이터를 제공하는 여러 방법이 있습니다:

@로 파일 참조: 코드 위치를 설명하는 대신 사용합니다. Claude가 응답하기 전에 파일을 읽습니다.
이미지 직접 붙여넣기: 프롬프트에 이미지를 복사/붙여넣기하거나 드래그 앤 드롭합니다.
URL 제공: 문서 및 API 참조용. /permissions를 사용하여 자주 사용하는 도메인을 허용 목록에 추가합니다.
데이터 파이프: cat error.log | claude를 실행하여 파일 내용을 직접 전송합니다.
Claude가 필요한 것을 직접 가져오도록 하기: Bash 명령, MCP 도구 또는 파일 읽기를 통해 Claude가 직접 컨텍스트를 가져오도록 합니다.

환경을 설정하세요

효과적인 CLAUDE.md 작성하기

팁:

/init을 실행하여 현재 프로젝트 구조를 기반으로 초기 CLAUDE.md 파일을 생성한 다음, 시간이 지나면서 다듬으세요.

/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가 추측할 수 없는 Bash 명령	Claude가 코드를 읽어서 알 수 있는 것
기본값과 다른 코드 스타일 규칙	Claude가 이미 알고 있는 표준 언어 규칙
테스트 지침 및 선호하는 테스트 러너	상세한 API 문서 (대신 문서 링크를 제공)
저장소 에티켓 (브랜치 네이밍, PR 규칙)	자주 변경되는 정보
프로젝트 고유의 아키텍처 결정	긴 설명이나 튜토리얼
개발 환경 특이사항 (필수 환경 변수)	코드베이스의 파일별 설명
일반적인 함정이나 직관적이지 않은 동작	"깨끗한 코드를 작성하라"와 같은 자명한 관행

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 파일을 불러옴

권한 설정하기

팁:

/permissions을 사용하여 안전한 명령을 허용 목록에 추가하거나, /sandbox로 OS 수준 격리를 설정하세요. 이렇게 하면 제어권을 유지하면서 중단을 줄일 수 있습니다.

권한 허용 목록: 안전하다고 아는 특정 도구를 허용합니다 (npm run lint나 git commit 등)
샌드박싱: 파일 시스템과 네트워크 접근을 제한하는 OS 수준 격리를 활성화하여, Claude가 정의된 경계 내에서 더 자유롭게 작업할 수 있게 합니다

또는 --dangerously-skip-permissions를 사용하여 lint 에러 수정이나 보일러플레이트 생성과 같은 제한된 워크플로에서 모든 권한 확인을 우회할 수 있습니다.

주의:

Claude가 임의의 명령을 실행하도록 허용하면 데이터 손실, 시스템 손상 또는 프롬프트 인젝션을 통한 데이터 유출이 발생할 수 있습니다. --dangerously-skip-permissions는 인터넷 접근이 없는 샌드박스에서만 사용하세요.

권한 설정하기 및 샌드박싱 활성화하기에서 자세히 읽어보세요.

CLI 도구 사용하기

팁:

외부 서비스와 상호작용할 때 Claude Code에게 gh, aws, gcloud, sentry-cli 같은 CLI 도구를 사용하도록 알려주세요.

MCP 서버 연결하기

팁:

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

훅 설정하기

팁:

예외 없이 매번 실행되어야 하는 작업에는 훅을 사용하세요.

스킬 생성하기

팁:

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

.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에게 서브에이전트를 사용하도록 명시적으로 지시하세요: "Use a subagent to review this code for security issues."

플러그인 설치하기

팁:

/plugin을 실행하여 마켓플레이스를 탐색하세요. 플러그인은 별도의 설정 없이 스킬, 도구 및 통합을 추가합니다.

스킬, 서브에이전트, 훅, MCP 중 선택하는 가이드는 Claude Code 확장하기를 참고하세요.

효과적으로 소통하기

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

코드베이스에 대해 질문하기

팁:

시니어 엔지니어에게 물어볼 것과 같은 질문을 Claude에게 하세요.

새로운 코드베이스에 온보딩할 때, Claude Code를 학습과 탐색에 활용하세요. 다른 엔지니어에게 물어볼 것과 같은 질문을 Claude에게 할 수 있습니다:

로깅은 어떻게 작동해?
새 API 엔드포인트는 어떻게 만들어?
foo.rs의 134번째 줄에서 async move { ... }는 무엇을 해?
CustomerOnboardingFlowImpl은 어떤 엣지 케이스를 처리해?
333번째 줄에서 이 코드가 왜 bar() 대신 foo()를 호출해?

Claude가 여러분을 인터뷰하도록 하기

팁:

큰 기능의 경우, 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가 잘못된 방향으로 가는 것을 알아차리는 즉시 수정하세요.

Esc: Esc 키로 Claude를 중간에 멈춥니다. 컨텍스트는 유지되므로 방향을 전환할 수 있습니다.
Esc + Esc 또는 /rewind: Esc를 두 번 누르거나 /rewind를 실행하여 되감기 메뉴를 열고 이전 대화 및 코드 상태를 복원하거나, 선택한 메시지부터 요약합니다.
"Undo that": Claude에게 변경 사항을 되돌리도록 합니다.
/clear: 관련 없는 작업 사이에 컨텍스트를 초기화합니다. 관련 없는 컨텍스트가 있는 긴 세션은 성능을 저하시킬 수 있습니다.

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

팁:

관련 없는 작업 사이에 /clear를 실행하여 컨텍스트를 초기화하세요.

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

작업 사이에 /clear를 자주 사용하여 컨텍스트 윈도우를 완전히 초기화하세요
자동 압축이 트리거되면, Claude는 코드 패턴, 파일 상태, 주요 결정 등 가장 중요한 것을 요약합니다
더 세밀한 제어를 위해 /compact <instructions>를 실행하세요, 예: /compact Focus on the API changes
대화의 일부만 압축하려면, Esc + Esc 또는 /rewind를 사용하여 메시지 체크포인트를 선택하고 Summarize from here를 선택하세요. 이전 컨텍스트는 유지하면서 해당 지점부터의 메시지를 압축합니다.
CLAUDE.md에 "When compacting, always preserve the full list of modified files and any test commands"와 같은 지시를 추가하여 압축 동작을 커스터마이즈하여 중요한 컨텍스트가 요약 과정에서 살아남도록 하세요

조사에 서브에이전트 사용하기

팁:

"use subagents to investigate X"로 조사를 위임하세요. 서브에이전트는 별도의 컨텍스트에서 탐색하여 메인 대화를 구현에 집중할 수 있게 합니다.

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가 수행하는 모든 작업은 체크포인트를 생성합니다. 이전 체크포인트의 대화, 코드 또는 둘 다 복원할 수 있습니다.

주의:

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

대화 이어가기

팁:

claude --continue를 실행하여 이전에 멈춘 곳에서 계속하거나, --resume으로 최근 세션 중에서 선택하세요.

Claude Code는 대화를 로컬에 저장합니다. 작업이 여러 세션에 걸칠 때, 컨텍스트를 다시 설명할 필요가 없습니다:

claude --continue    # Resume the most recent conversation
claude --resume      # Select from recent conversations

자동화 및 확장

하나의 Claude에 능숙해지면, 병렬 세션, 비대화형 모드, 팬아웃 패턴으로 출력을 배가하세요.

비대화형 모드 실행

팁:

CI, pre-commit 훅 또는 스크립트에서 claude -p "prompt"를 사용하세요. 스트리밍 JSON 출력을 위해 --output-format stream-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

여러 Claude 세션 실행

팁:

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

병렬 세션을 실행하는 세 가지 주요 방법이 있습니다:

Claude Code 데스크톱 앱: 여러 로컬 세션을 시각적으로 관리합니다. 각 세션은 자체 격리된 worktree를 가집니다.
웹에서의 Claude Code: Anthropic의 보안 클라우드 인프라에서 격리된 VM으로 실행합니다.
에이전트 팀: 공유 작업, 메시징, 팀 리더와 함께 여러 세션의 자동 조정.

예를 들어, Writer/Reviewer 패턴을 사용합니다:

세션 A (Writer)	세션 B (Reviewer)
`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 호출에 작업을 분배할 수 있습니다:

Step 1: 작업 목록 생성

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

Step 2: 목록을 순회하는 스크립트 작성

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

Step 3: 몇 개 파일로 테스트한 후 전체 규모로 실행

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

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

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

안전한 자율 모드

주의:

Claude가 임의의 명령을 실행하도록 허용하는 것은 위험하며, 데이터 손실, 시스템 손상 또는 데이터 유출(예: 프롬프트 인젝션 공격을 통해)이 발생할 수 있습니다. 이러한 위험을 최소화하려면, 인터넷 접근이 없는 컨테이너에서 --dangerously-skip-permissions를 사용하세요.

샌드박싱(/sandbox)을 활성화하면, 더 나은 보안과 함께 유사한 자율성을 얻을 수 있습니다. 샌드박스는 모든 확인을 우회하는 대신 사전에 경계를 정의합니다.

일반적인 실패 패턴 피하기

다음은 흔한 실수들입니다. 일찍 인식하면 시간을 절약할 수 있습니다:

종합 선물 세트 세션. 하나의 작업으로 시작했다가 관련 없는 것을 물어보고, 다시 첫 번째 작업으로 돌아갑니다. 컨텍스트가 관련 없는 정보로 가득 찹니다.

해결: 관련 없는 작업 사이에 /clear를 사용하세요.
반복적인 수정. Claude가 잘못하고, 수정하고, 여전히 잘못하고, 다시 수정합니다. 컨텍스트가 실패한 접근법으로 오염됩니다.

해결: 두 번 수정에 실패한 후에는, /clear하고 학습한 내용을 반영한 더 나은 초기 프롬프트를 작성하세요.
과도하게 명세된 CLAUDE.md. CLAUDE.md가 너무 길면, 중요한 규칙이 노이즈에 묻혀 Claude가 절반을 무시합니다.

해결: 과감하게 정리하세요. Claude가 지시 없이도 이미 올바르게 수행하고 있다면, 삭제하거나 훅으로 전환하세요.
신뢰 후 검증 격차. Claude가 그럴듯해 보이지만 엣지 케이스를 처리하지 않는 구현을 생성합니다.

해결: 항상 검증(테스트, 스크립트, 스크린샷)을 제공하세요. 검증할 수 없다면 배포하지 마세요.
끝없는 탐색. 범위를 지정하지 않고 Claude에게 무언가를 "조사"하도록 요청합니다. Claude가 수백 개의 파일을 읽어 컨텍스트를 채웁니다.

해결: 조사 범위를 좁게 설정하거나, 서브에이전트를 사용하여 탐색이 메인 컨텍스트를 소비하지 않도록 하세요.

직관을 키우세요

이 가이드의 패턴은 고정불변이 아닙니다. 일반적으로 잘 작동하는 출발점이지만, 모든 상황에 최적은 아닐 수 있습니다.

9. Claude Code 모범 사례

Claude Code 모범 사례

Claude에게 작업을 검증할 수단을 제공하세요

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

Step 1: 탐색

Step 2: 계획

Step 3: 구현

Step 4: 커밋

프롬프트에 구체적인 컨텍스트를 제공하세요

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

환경을 설정하세요

효과적인 CLAUDE.md 작성하기

권한 설정하기

CLI 도구 사용하기

MCP 서버 연결하기

훅 설정하기

스킬 생성하기

커스텀 서브에이전트 생성하기

플러그인 설치하기

효과적으로 소통하기

코드베이스에 대해 질문하기

Claude가 여러분을 인터뷰하도록 하기

세션 관리하기

빠르게 그리고 자주 방향을 수정하세요

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

조사에 서브에이전트 사용하기

체크포인트로 되감기

대화 이어가기

자동화 및 확장

비대화형 모드 실행

여러 Claude 세션 실행

파일 전체에 팬아웃

Step 1: 작업 목록 생성

Step 2: 목록을 순회하는 스크립트 작성

Step 3: 몇 개 파일로 테스트한 후 전체 규모로 실행

안전한 자율 모드

일반적인 실패 패턴 피하기

직관을 키우세요

관련 자료

9. Claude Code 모범 사례

Claude Code 모범 사례

Claude에게 작업을 검증할 수단을 제공하세요

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

Step 1: 탐색

Step 2: 계획

Step 3: 구현

Step 4: 커밋

프롬프트에 구체적인 컨텍스트를 제공하세요

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

환경을 설정하세요

효과적인 CLAUDE.md 작성하기

권한 설정하기

CLI 도구 사용하기

MCP 서버 연결하기

훅 설정하기

스킬 생성하기

커스텀 서브에이전트 생성하기

플러그인 설치하기

효과적으로 소통하기

코드베이스에 대해 질문하기

Claude가 여러분을 인터뷰하도록 하기

세션 관리하기

빠르게 그리고 자주 방향을 수정하세요

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

조사에 서브에이전트 사용하기

체크포인트로 되감기

대화 이어가기

자동화 및 확장

비대화형 모드 실행

여러 Claude 세션 실행

파일 전체에 팬아웃

Step 1: 작업 목록 생성

Step 2: 목록을 순회하는 스크립트 작성

Step 3: 몇 개 파일로 테스트한 후 전체 규모로 실행

안전한 자율 모드

일반적인 실패 패턴 피하기

직관을 키우세요

관련 자료