Claude Code Best Practices Guide

Overview

Claude Code는 AI가 단순히 코드를 검토하는 것을 넘어, 파일을 읽고 명령을 실행하며 자율적으로 솔루션을 구현할 수 있도록 하는 에이전트형 코딩 환경입니다. 효과를 극대화하려면 사용자는 컨텍스트 윈도우(모든 메시지, 파일 읽기 및 명령 출력이 저장되는 공간)를 관리해야 합니다. 윈도우가 가득 차면 성능이 저하되기 때문입니다.

Implementing Autonomous Verification

사용자가 유일한 검증 루프가 되는 것을 방지하기 위해, Claude Code에는 작업이 완료되었음을 결정할 수 있는 결정론적 신호(deterministic signals)가 제공되어야 합니다.

Verification Strategies

Verification Criteria: 모호한 요청 대신 구체적인 테스트 케이스(예: "validateEmail 함수를 작성하세요; user@example.com은 true, invalid는 false여야 합니다")를 제공하고 Claude에게 이를 실행하도록 지시하십시오.
Visual Verification: UI 변경의 경우, 디자인 스크린샷을 제공하고 Claude에게 결과 스크린샷을 찍어 차이점을 나열하도록 지시하십시오.
Root Cause Analysis: 빌드 오류를 수정할 때, 특정 오류를 제공하고 오류를 억제하지 않고도 빌드가 성공해야 함을 요구하십시오.

Gating Mechanisms

필요한 자율성 수준에 따라 다음과 같이 검증을 구현할 수 있습니다:

Single Prompts: 한 메시지 내에서 확인과 반복을 요청합니다.
Goal Conditions (/goal): 별도의 평가자를 사용하여 매 턴마다 조건을 재확인합니다.
Stop Hooks: 특정 체크를 통과할 때까지 턴이 종료되는 것을 차단하는 스크립트입니다.
Verification Subagents: 새로운 모델을 사용하여 기본 에이전트의 결과를 반박하도록 합니다.

Workflow: Explore, Plan, and Code

코딩에 바로 뛰어드는 것은 잘못된 문제를 해결하는 결과로 이어질 수 있습니다. Anthropic은 탐색과 실행을 분리하기 위해 plan mode를 사용하는 4단계 워크플로우를 권장합니다:

Explore: 코드베이스와 문제를 이해합니다.
Plan: 구현 전략을 정의합니다.
Code: 계획을 실행합니다.
Verify: 솔루션이 기준을 충족하는지 확인합니다.

Prompting and Context Optimization

Providing Specific Context

프롬프트의 정밀도는 모호함을 줄이고 오류를 방지합니다. 효과적인 전략은 다음과 같습니다:

Scoping Tasks: 정확한 파일, 시나리오 및 테스트 선호도(예: "mocks를 피하세요")를 지정합니다.
Directing Sources: 아키텍처 질문에 답하기 위해 Claude에게 특정 git 히스토리나 파일을 가리킵니다.
Referencing Patterns: 일관성을 보장하기 위해 Claude에게 기존 코드베이스 예시(예: "HotDogWidget.php")를 참조하도록 지시합니다.
Describing Symptoms: 오류, 발생 가능성이 높은 위치 및 "수정됨"에 대한 정의를 제공합니다.

Rich Content Integration

@ References: @를 사용하여 파일을 직접 참조하면 Claude가 응답하기 전에 해당 파일을 읽습니다.
Direct Inputs: 이미지를 붙여넣거나, 문서에 대한 URL을 제공하거나, cat error.log | claude를 사용하여 데이터를 파이프(pipe)로 전달합니다.
Autonomous Fetching: Claude에게 Bash 명령어나 MCP 도구를 사용하여 필요한 컨텍스트를 가져오도록 지시합니다.

Environment Configuration

The CLAUDE.md File

CLAUDE.md는 모든 세션 시작 시 읽히는 지속적인 컨텍스트 파일입니다. 컨텍스트 윈도우가 비대해지는 것을 방지하기 위해 간결하게 유지해야 합니다.

포함할 내용: 명확하지 않은 Bash 명령, 커스텀 코드 스타일 규칙, 선호하는 테스트 러너, 저장소 에티켓 및 프로젝트별 아키텍처 결정 사항.
제외할 내용: 표준 언어 관례, 상세한 API 문서(대신 링크 제공), 자주 변경되는 정보.

Permissions and Automation

Auto Mode: 분류 모델을 사용하여 위험한 작업(예: 권한 상승)만 차단함으로써 수동 승인의 필요성을 줄입니다.
Permission Allowlists: npm run lint와 같은 안전한 도구를 명시적으로 허용합니다.
Sandboxing: 파일 시스템 및 네트워크 액세스를 제한하기 위한 OS 수준의 격리.

Extensions and Tooling

CLI Tools: GitHub CLI(gh)와 같은 도구를 설치하면 Claude가 API보다 더 효율적으로 이슈와 PR을 관리할 수 있습니다.
MCP Servers: Claude를 이슈 트래커, 데이터베이스 및 Figma 디자인에 연결합니다.
Hooks: 특정 시점에 실행되는 결정론적 스크립트(예: 모든 편집 후 eslint 실행).
Skills: /skill-name을 통해 호출할 수 있는 .claude/skills/에 저장된 프로젝트별 지식.
Subagents: 메인 세션이 혼란스러워지는 것을 방지하기 위해 심층 조사나 대조 검토에 사용되는 독립적인 컨텍스트.
Plugins: 타입 언어를 위한 코드 인텔리전스 플러그인을 포함하여 기술, 훅, MCP 서버가 결합된 단위.

Session Management

Context Maintenance

컨텍스트 윈도우가 주요 제약 사항이므로 공격적인 관리가 필요합니다:

/clear: "kitchen sink sessions"를 방지하기 위해 관련 없는 작업 사이의 컨텍스트를 초기화합니다.
/compact: 대화 기록의 요약을 수동으로 트리거합니다.
/btw: 대화 기록에 저장되지 않아야 할 부수적인 질문에 사용합니다.
Course Correction: Claude가 동일한 문제로 두 번 실패하면, 세션을 /clear하고 더 구체적인 프롬프트로 시작하십시오.

State Control

Rewind and Checkpoints: Esc + Esc 또는 /rewind를 사용하여 이전 코드 상태나 대화 기록을 복구합니다.
Resuming: claude --continue 또는 claude --resume를 사용하여 이전 세션을 이어갑니다.

Scaling and Automation

Non-Interactive Mode

claude -p "prompt"를 사용하면 CI 파이프라인 및 pre-commit 훅에 통합할 수 있으며, 출력은 plain text, JSON 또는 streaming JSON으로 사용할 수 있습니다.

Parallel Execution

Worktrees: 별도의 CLI 세션을 위한 격리된 git 체크아웃.
Agent Teams: 팀 리더와 함께 여러 세션을 자동화된 방식으로 조정.
Writer/Reviewer Pattern: 편향을 제거하기 위해 구현과 검토에 별도의 세션을 사용.

Fan-out Patterns

대규모 마이그레이션의 경우, 사용자는 파일을 식별하고, 작업 목록을 생성하고, 병렬 비대화형 호출을 실행하여 작업을 분산할 수 있습니다.

Common Failure Patterns to Avoid

The Kitchen Sink Session: 한 세션에 관련 없는 작업을 섞는 것; /clear를 사용하여 해결.
Over-correcting: 동일한 오류를 반복해서 수정하는 것; 더 나은 프롬프트로 세션을 재시작하여 해결.
Over-specified CLAUDE.md: 너무 많은 규칙으로 인해 Claude가 지침을 무시하는 경우; 가지치기를 통해 해결.
Trust-then-Verify Gap: 그럴듯하지만 테스트되지 않은 코드를 배포하는 것; 결정론적 검증을 요구하여 해결.
Infinite Exploration: 컨텍스트를 채우는 범위가 지정되지 않은 조사; subagents를 사용하여 해결.