문서 인덱스
전체 문서 인덱스는 아래 주소에서 확인하세요: https://code.claude.com/docs/llms.txt
추가 탐색 전에 이 파일로 이용 가능한 모든 페이지를 확인하세요.
Claude Code는 에이전트 기반 코딩 환경입니다. 질문에 답하고 기다리는 챗봇과 달리, 파일을 읽고, 명령을 실행하고, 변경 사항을 적용하며, 사용자가 지켜보거나 방향을 바꾸거나 완전히 자리를 비운 사이에도 스스로 문제를 해결합니다.
이는 작업 방식 자체를 바꿉니다. 코드를 직접 작성한 뒤 Claude에게 검토를 요청하는 대신, 원하는 것을 설명하면 Claude가 어떻게 만들지 스스로 파악합니다. 탐색하고, 계획하고, 구현까지 직접 처리합니다.
다만 이 자율성을 제대로 활용하려면 어느 정도 학습이 필요합니다. Claude는 이해해야 할 몇 가지 제약 안에서 작동합니다.
이 가이드는 Anthropic 내부 팀과 다양한 코드베이스, 언어, 환경에서 Claude Code를 사용하는 엔지니어들 사이에서 효과가 입증된 패턴을 다룹니다. 에이전트 루프의 내부 작동 방식은 Claude Code 작동 원리를 참고하세요.
대부분의 모범 사례는 하나의 제약에서 비롯됩니다. Claude의 컨텍스트 윈도우는 빠르게 채워지고, 채워질수록 성능이 저하됩니다.
Claude의 컨텍스트 윈도우에는 대화 전체가 담깁니다. 주고받은 모든 메시지, Claude가 읽은 모든 파일, 모든 명령 출력이 포함됩니다. 그런데 이 공간은 금세 찬다는 문제가 있습니다. 디버깅 세션 하나나 코드베이스 탐색 하나만으로도 수만 개의 토큰이 소비될 수 있습니다.
LLM은 컨텍스트가 채워질수록 성능이 떨어지기 때문에 이 문제는 중요합니다. 컨텍스트 윈도우가 거의 찼을 때 Claude는 앞서 받은 지시를 '잊어버리거나' 실수를 더 많이 할 수 있습니다. 컨텍스트 윈도우는 가장 중요하게 관리해야 할 자원입니다. 세션이 실제로 어떻게 채워지는지 확인하려면 인터랙티브 워크스루를 통해 시작 시 무엇이 로드되고 파일 읽기마다 얼마나 소비되는지 살펴보세요. 커스텀 상태 표시줄로 컨텍스트 사용량을 지속적으로 추적하고, 토큰 사용량 줄이기에서 전략을 확인하세요.
Claude가 스스로 결과를 검증할 수 있게 하세요
테스트, 스크린샷, 예상 출력을 포함해 Claude가 스스로 확인할 수 있게 하세요. 이것이 가장 효과적인 단 하나의 방법입니다.
먼저 탐색하고, 계획을 세운 다음, 코드를 작성하세요
잘못된 문제를 푸는 상황을 방지하려면 조사와 계획 단계를 구현과 분리하세요.
탐색
플랜 모드로 진입합니다. Claude가 파일을 읽고 질문에 답하되 변경은 하지 않습니다.read /src/auth and understand how we handle sessions and login.
also look at how we manage environment variables for secrets.
계획
Claude에게 상세한 구현 계획서 작성을 요청합니다.I want to add Google OAuth. What files need to change?
What's the session flow? Create a plan.
Ctrl+G를 눌러 Claude가 진행하기 전에 텍스트 편집기에서 계획서를 직접 수정하세요. 구현
플랜 모드를 종료하고 Claude가 계획에 따라 코딩하도록 합니다.implement the OAuth flow from your plan. write tests for the
callback handler, run the test suite and fix any failures.
커밋
Claude에게 설명이 담긴 메시지로 커밋하고 PR을 생성하도록 요청합니다.commit with a descriptive message and open a PR
플랜 모드는 유용하지만 부가적인 작업이 생깁니다.오타 수정, 로그 줄 추가, 변수명 변경처럼 범위가 명확하고 수정 규모가 작은 작업은 Claude에게 바로 처리하도록 요청하세요.접근 방식이 불확실하거나, 여러 파일을 수정해야 하거나, 수정할 코드에 익숙하지 않을 때 계획 단계가 가장 유용합니다. diff를 한 문장으로 설명할 수 있다면 계획은 건너뛰세요.
프롬프트에 구체적인 컨텍스트를 제공하세요
Claude는 의도를 추론할 수 있지만 마음을 읽지는 못합니다. 특정 파일을 지정하고, 제약 조건을 언급하고, 참고할 패턴을 가리켜 주세요.
탐색 중이고 방향을 수정할 여유가 있을 때는 모호한 프롬프트도 유용합니다. "what would you improve in this file?" 같은 프롬프트는 미처 생각하지 못했던 것들을 드러내 줄 수 있습니다.
풍부한 콘텐츠를 제공하세요
@를 사용해 파일을 참조하거나, 스크린샷/이미지를 붙여넣거나, 데이터를 직접 파이프하세요.
@로 파일 참조: 코드가 어디에 있는지 설명하는 대신 사용하세요. Claude가 응답 전에 파일을 직접 읽습니다.- 이미지 직접 붙여넣기: 이미지를 복사/붙여넣거나 드래그 앤 드롭으로 프롬프트에 넣으세요.
- URL 제공: 문서 및 API 레퍼런스용으로 사용하세요.
/permissions로 자주 사용하는 도메인을 허용 목록에 추가하세요.
- 데이터 파이프 전달:
cat error.log | claude을 실행해 파일 내용을 직접 전달하세요.
- Claude가 필요한 것을 직접 가져오도록 하세요: Bash 명령, MCP 도구, 또는 파일 읽기를 통해 Claude가 직접 컨텍스트를 가져오도록 지시하세요.
몇 가지 설정 단계만으로 모든 세션에서 Claude Code의 효율을 크게 높일 수 있습니다. 확장 기능 전체 개요와 각 기능의 활용 시점은 Claude Code 확장하기를 참고하세요.
효과적인 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
@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/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가 정해진 경계 안에서 더 자유롭게 작업할 수 있습니다
권한 모드, 권한 규칙, 샌드박싱에 대해 더 알아보세요.
외부 서비스와 상호작용할 때 gh, aws, gcloud, sentry-cli 같은 CLI 도구를 사용하도록 Claude Code에 지시하세요.
gh CLI를 설치하세요. Claude는 이를 활용해 이슈 생성, PR 열기, 댓글 읽기 등을 수행할 수 있습니다. gh 없이도 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, 데이터베이스 같은 외부 도구를 연결하세요.
훅 설정하기
예외 없이 매번 실행되어야 하는 작업에는 훅을 사용하세요.
.claude/settings.json를 직접 편집해 훅을 수동으로 설정하거나, /hooks를 실행해 설정된 내용을 확인하세요.
스킬 만들기
.claude/skills/에 SKILL.md 파일을 만들어 Claude에게 도메인 지식과 재사용 가능한 워크플로를 제공하세요.
/skill-name로 직접 호출할 수 있습니다.
.claude/skills/에 SKILL.md가 있는 디렉토리를 추가해 스킬을 만드세요:
.claude/skills/api-conventions/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/)
.claude/skills/fix-issue/SKILL.md
---
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가 격리된 작업을 위임할 수 있게 하세요.
.claude/agents/security-reviewer.md
---
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.
플러그인 설치하기
/plugin을 실행해 마켓플레이스를 탐색하세요. 플러그인은 별도 설정 없이 스킬, 도구, 통합 기능을 추가합니다.
효과적으로 소통하기
Claude Code와 소통하는 방식은 결과의 질에 크게 영향을 미칩니다.
코드베이스 질문하기
시니어 엔지니어에게 할 법한 질문을 Claude에게 해보세요.
- 로깅은 어떻게 동작해?
- 새 API 엔드포인트는 어떻게 만들어?
foo.rs의 134번 줄에서 async move { ... }은 무슨 역할을 해?CustomerOnboardingFlowImpl은 어떤 엣지 케이스를 처리해?- 333번 줄에서 이 코드는 왜
bar() 대신 foo()을 호출해?
이런 방식으로 Claude Code를 활용하면 온보딩이 효과적으로 이루어지고, 적응 시간이 단축되며 다른 엔지니어의 부담도 줄어듭니다. 특별한 프롬프트 기술은 필요 없습니다. 바로 질문하세요.
Claude가 인터뷰하게 하세요
규모가 큰 기능을 작업할 때는 먼저 Claude가 인터뷰하게 하세요. 최소한의 프롬프트로 시작해 AskUserQuestion 도구를 사용해 인터뷰를 진행해달라고 요청하세요.
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: 관련 없는 작업 사이에 컨텍스트를 초기화하세요. 관련 없는 컨텍스트가 쌓인 긴 세션은 성능을 저하시킬 수 있습니다.
같은 세션에서 같은 문제로 Claude를 두 번 이상 수정했다면, 컨텍스트가 실패한 시도들로 가득 찬 것입니다. /clear을 실행하고 배운 점을 반영한 더 구체적인 프롬프트로 새로 시작하세요. 더 나은 프롬프트로 시작하는 새 세션이 수정이 쌓인 긴 세션보다 거의 항상 더 좋은 결과를 냅니다.
컨텍스트를 적극적으로 관리하세요
관련 없는 작업 사이에 /clear을 실행해 컨텍스트를 초기화하세요.
- 작업 사이에
/clear을 자주 사용해 컨텍스트 윈도우를 완전히 초기화하세요
- 자동 압축이 트리거되면 Claude는 코드 패턴, 파일 상태, 주요 결정 사항 등 가장 중요한 내용을 요약합니다
- 더 세밀하게 제어하려면
/compact Focus on the API changes처럼 /compact <instructions>을 실행하세요
- 대화의 일부만 압축하려면
Esc + Esc 또는 /rewind를 사용해 메시지 체크포인트를 선택하고 여기서부터 요약 또는 여기까지 요약을 선택하세요. 전자는 해당 시점 이후 메시지를 압축하고 이전 컨텍스트는 그대로 유지하며, 후자는 이전 메시지를 압축하고 최근 메시지는 전체를 유지합니다. 복원 vs. 요약을 참고하세요.
- CLAUDE.md에
"When compacting, always preserve the full list of modified files and any test commands" 같은 지시를 추가해 압축 동작을 커스터마이즈하고 요약 후에도 중요한 컨텍스트가 유지되도록 하세요
- 컨텍스트에 남길 필요 없는 빠른 질문에는
/btw을 사용하세요. 닫을 수 있는 오버레이에 답이 표시되며 대화 기록에는 남지 않아, 컨텍스트를 늘리지 않고 세부 사항을 확인할 수 있습니다.
조사에 서브에이전트를 활용하세요
"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.
use a subagent to review this code for edge cases
체크포인트로 되돌리기
보내는 모든 프롬프트가 체크포인트를 생성합니다. 대화, 코드, 또는 둘 다를 이전 체크포인트로 복원할 수 있습니다.
Escape를 두 번 탭하거나 /rewind을 실행해 리와인드 메뉴를 여세요. 대화만 복원, 코드만 복원, 둘 다 복원, 또는 선택한 메시지부터 요약을 선택할 수 있습니다. 자세한 내용은 체크포인팅을 참고하세요.
모든 행동을 신중하게 계획하는 대신, Claude에게 위험한 것을 시도해 보라고 할 수 있습니다. 잘 되지 않으면 되돌리고 다른 방법을 시도하세요. 체크포인트는 세션 간에도 유지되므로 터미널을 닫아도 나중에 되돌릴 수 있습니다.
체크포인트는 외부 프로세스가 아닌 Claude가 수행한 변경 사항만 추적합니다. git의 대체재가 아닙니다.
대화 재개하기
/rename로 세션에 이름을 붙이고 브랜치처럼 다루세요. 각 작업 흐름이 자체적인 영속 컨텍스트를 갖습니다.
claude --continue을 실행해 가장 최근 세션을 이어받거나, claude --resume로 목록에서 선택하세요. oauth-migration처럼 세션에 설명적인 이름을 붙이면 나중에 찾기 쉽습니다. 재개, 브랜치, 명명 관련 전체 기능은 세션 관리를 참고하세요.
자동화하고 확장하기
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 세션을 병렬로 실행해 개발 속도를 높이고, 격리된 실험을 진행하거나, 복잡한 워크플로를 시작하세요.
- 워크트리: 격리된 git 체크아웃에서 별도의 CLI 세션을 실행해 편집 충돌을 방지하세요
- 데스크탑 앱: 각각 자체 워크트리가 있는 여러 로컬 세션을 시각적으로 관리하세요
- 웹에서의 Claude Code: 격리된 VM에서 Anthropic이 관리하는 클라우드 인프라에서 세션을 실행하세요
- 에이전트 팀: 공유 작업, 메시징, 팀 리더를 통한 여러 세션의 자동화된 조율
작업 병렬화 외에도 여러 세션은 품질 중심 워크플로를 가능하게 합니다. Claude가 방금 작성한 코드에 편향되지 않으므로 새 컨텍스트가 코드 리뷰를 개선합니다.
예를 들어, 작성자/검토자 패턴을 활용하세요:
테스트도 비슷하게 할 수 있습니다. Claude 하나가 테스트를 작성하면, 다른 Claude가 테스트를 통과하는 코드를 작성합니다.
파일 전체에 팬아웃하기
각 작업에 claude -p을 호출하며 반복하세요. 배치 작업의 권한 범위는 --allowedTools를 사용하세요.
작업 목록 생성
마이그레이션이 필요한 모든 파일을 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 -p "<your prompt>" --output-format json | your_command
--verbose을 사용하고 프로덕션에서는 끄세요.
자동 모드로 자율 실행하기
백그라운드 안전 검사와 함께 중단 없이 실행하려면 자동 모드를 사용하세요. 분류기 모델이 명령 실행 전에 검토하여 범위 확대, 알 수 없는 인프라, 적대적 콘텐츠 기반 작업을 차단하면서 일상적인 작업은 프롬프트 없이 진행합니다.
claude --permission-mode auto -p "fix all lint errors"
-p 플래그를 사용한 비대화형 실행의 경우, 분류기가 작업을 반복적으로 차단하면 자동 모드가 중단됩니다. 사용자로 폴백할 수 없기 때문입니다. 자동 모드 폴백 시점에서 임계값을 확인하세요.
흔한 실패 패턴 피하기
다음은 자주 나타나는 실수들입니다. 일찍 인식하면 시간을 절약할 수 있습니다:
- 주방 싱크대 세션. 하나의 작업으로 시작해서 관련 없는 것을 Claude에게 묻고, 다시 첫 번째 작업으로 돌아갑니다. 컨텍스트가 관련 없는 정보로 가득 찹니다.
해결책: 관련 없는 작업 사이에 /clear을 실행하세요.
- 반복적인 수정. Claude가 잘못하면 수정하고, 여전히 잘못되면 또 수정합니다. 컨텍스트가 실패한 시도들로 오염됩니다.
해결책: 두 번 수정에 실패하면 /clear을 실행하고 배운 점을 반영한 더 나은 초기 프롬프트를 작성하세요.
- 과도하게 명시된 CLAUDE.md. CLAUDE.md가 너무 길면 중요한 규칙이 소음 속에 묻혀 Claude가 절반을 무시합니다.
해결책: 가차 없이 정리하세요. 지시 없이도 Claude가 이미 올바르게 하는 것이라면 삭제하거나 훅으로 변환하세요.
- 신뢰 후 검증의 격차. Claude가 그럴듯해 보이지만 엣지 케이스를 처리하지 못하는 구현을 만들어냅니다.
해결책: 항상 검증 수단(테스트, 스크립트, 스크린샷)을 제공하세요. 검증할 수 없다면 배포하지 마세요.
- 끝없는 탐색. 범위를 정하지 않고 Claude에게 무언가를 '조사'하라고 요청합니다. Claude가 수백 개의 파일을 읽어 컨텍스트를 채웁니다.
해결책: 조사 범위를 좁게 설정하거나 서브에이전트를 사용해 탐색이 메인 컨텍스트를 소비하지 않도록 하세요.
직관을 개발하세요
이 가이드의 패턴은 고정된 것이 아닙니다. 일반적으로 잘 작동하는 출발점이지만, 모든 상황에서 최적은 아닐 수 있습니다.
복잡한 문제에 깊이 빠져 있고 기록이 가치 있을 때는 컨텍스트를 쌓아두는 것이 맞습니다. 작업이 탐색적이라면 계획을 건너뛰고 Claude가 알아내도록 두어야 할 때도 있습니다. 제약을 가하기 전에 Claude가 문제를 어떻게 해석하는지 보고 싶을 때는 모호한 프롬프트가 정답일 수 있습니다.
무엇이 효과적인지 주목하세요. Claude가 훌륭한 결과물을 만들어낼 때, 어떻게 했는지 확인하세요. 프롬프트 구조, 제공한 컨텍스트, 사용한 모드를 살펴보세요. Claude가 어려움을 겪을 때는 이유를 생각해보세요. 컨텍스트가 너무 노이즈가 많았나요? 프롬프트가 너무 모호했나요? 한 번에 처리하기엔 작업이 너무 컸나요?
시간이 지나면 어떤 가이드도 담을 수 없는 직관이 생깁니다. 언제 구체적이어야 하고 언제 열린 방식이어야 하는지, 언제 계획하고 언제 탐색해야 하는지, 언제 컨텍스트를 비우고 언제 쌓아야 하는지를 알게 됩니다.
