요약: 이 블로그 게시물은 2026년 1월 26일부터 더 이상 유지되지 않으며, 최신 Claude Code 모범 사례는 공식 문서에서 확인할 수 있습니다. Claude Code는 Anthropic 엔지니어와 연구원들이 코딩 워크플로우에 Claude를 더 자연스럽게 통합할 수 있도록 개발된 명령줄 도구로, 낮은 수준의 접근성과 높은 유연성을 제공합니다. 이 글에서는 Anthropic 내부 팀과 외부 엔지니어들이 다양한 코드베이스와 언어, 환경에서 Claude Code를 효과적으로 활용하는 데 입증된 일반적인 패턴들을 다룹니다. 환경 설정 최적화, 도구 확장, 일반적인 워크플로우, 다중 Claude 세션 활용 등 다양한 팁과 전략을 제공합니다.
===BODY_KO## Claude Code 모범 사례가 문서로 이동했습니다

2026년 1월 26일

이 블로그 게시물은 더 이상 유지되지 않습니다. Claude Code가 발전함에 따라 항상 최신 상태로 유지되는 공식 문서(https://code.claude.com/docs/en/best-practices)에서 가장 최신 Claude Code 모범 사례를 확인하시기 바랍니다.

—

우리는 최근 Claude Code를 출시했습니다. 이는 에이전트 코딩을 위한 명령줄 도구입니다. 연구 프로젝트로 개발된 Claude Code는 Anthropic 엔지니어와 연구원들이 코딩 워크플로우에 Claude를 더 자연스럽게 통합할 수 있는 방법을 제공합니다.

Claude Code는 의도적으로 낮은 수준으로 설계되어 특정 워크플로우를 강요하지 않고 원시 모델 액세스에 가까운 접근성을 제공합니다. 이 디자인 철학은 유연하고, 사용자 정의 가능하며, 스크립트 가능하고, 안전한 강력한 도구를 만듭니다.

강력하지만 이러한 유연성은 에이전트 코딩 도구에 익숙하지 않은 엔지니어들에게는 학습 곡선을 제시합니다. 적어도 그들이 자신만의 모범 사례를 개발할 때까지는 그렇습니다.

이 게시물은 Anthropic의 내부 팀과 다양한 코드베이스, 언어, 환경에서 Claude Code를 사용하는 외부 엔지니어 모두에게 효과적인 것으로 입증된 일반적인 패턴을 설명합니다.

이 목록의 어떤 항목도 확정된 것이 아니며 보편적으로 적용 가능하지 않습니다. 이러한 제안을 시작점으로 고려해 주십시오. 우리는 실험하고 가장 잘 작동하는 것을 찾아보라고 권장합니다!

—

## 더 자세한 정보를 찾고 계신가요?

claude.ai/code의 포괄적인 문서는 이 게시물에서 언급된 모든 기능을 다루며 추가 예제, 구현 세부사항, 고급 기술을 제공합니다.

—

## 1. 설정 사용자 정의

Claude Code는 자동으로 프롬프트에 컨텍스트를 가져오는 에이전트 코딩 어시스턴트입니다. 이 컨텍스트 수집은 시간과 토큰을 소비하지만, 환경 튜닝을 통해 최적화할 수 있습니다.

### a. CLAUDE.md 파일 생성

CLAUDE.md는 대화를 시작할 때 Claude가 자동으로 컨텍스트로 가져오는 특수 파일입니다. 따라서 다음을 문서화하기에 이상적인 장소입니다:

– 일반적인 bash 명령어
– 핵심 파일과 유틸리티 함수
– 코드 스타일 지침
– 테스트 지시사항
– 저장소 에티켓(예: 브랜치 이름 지정, merge vs rebase 등)
– 개발자 환경 설정(예: pyenv 사용, 작동하는 컴파일러)
– 프로젝트에 특이한 예기치 않은 동작이나 경고
– Claude가 기억하길 원하는 기타 정보

CLAUDE.md 파일에 필요한 형식은 없습니다. 간결하고 사람이 읽기 쉽게 유지하는 것이 좋습니다. 예를 들어:

“`markdown
# Bash 명령어
– npm run build: 프로젝트 빌드
– npm run typecheck: 타입 체커 실행

# 코드 스타일
– CommonJS(require)가 아닌 ES 모듈(import/export) 구문 사용
– 가능한 경우 import 해제(예: import { foo } from 'bar')

# 워크플로우
– 일련의 코드 변경이 완료되면 타입 체크 확인
– 성능을 위해 전체 테스트 스위트가 아닌 단일 테스트 실행 선호
“`

CLAUDE.md 파일을 여러 위치에 배치할 수 있습니다:

– 저장소의 루트 또는 claude를 실행하는 위치(가장 일반적인 사용법). CLAUDE.md라고 이름을 지정하고 git에 커밋하여 세션 간에 공유하고 팀과 공유(권장), 또는 CLAUDE.local.md라고 이름을 지정하고 .gitignore 추가
– claude를 실행하는 디렉토리의 상위 디렉토리. 이는 모노레포에서 가장 유용하며, 루트/foo에서 claude를 실행할 수 있고 루트/CLAUDE.md와 루트/foo/CLAUDE.md 모두에 CLAUDE.md 파일을 둘 수 있습니다. 둘 다 자동으로 컨텍스트로 가져옵니다
– claude를 실행하는 디렉토리의 하위 디렉토리. 위와 반대이며 이 경우 Claude는 하위 디렉토리의 파일로 작업할 때 필요에 따라 CLAUDE.md 파일을 가져옵니다
– 홈 폴더(~/.claude/CLAUDE.md), 모든 claude 세션에 적용

/init 명령어를 실행하면 Claude가 자동으로 CLAUDE.md를 생성합니다.

### b. CLAUDE.md 파일 튜닝

CLAUDE.md 파일은 Claude의 프롬프트의 일부가 되므로, 자주 사용하는 프롬프트처럼 다듬어야 합니다. 흔한 실수는 효과성을 반복하지 않고 광범위한 콘텐츠를 추가하는 것입니다. 실험하고 모델에서 가장 좋은 지시사항 따르기를 생성하는 것이 무엇인지 결정하는 데 시간을 투자하십시오.

CLAUDE.md에 콘텐츠를 수동으로 추가하거나 # 키를 눌러 Claude에 지시사항을 제공할 수 있으며, Claude는 이를 관련 CLAUDE.md에 자동으로 통합합니다.

많은 엔지니어가 코딩할 때 #를 자주 사용하여 명령어, 파일, 스타일 지침을 문서화한 다음, 팀원들도 혜택을 받을 수 있도록 CLAUDE.md 변경사항을 커밋에 포함합니다.

Anthropic에서는 때때로 CLAUDE.md 파일을 프롬프트 개선자를 통해 실행하고, 준수를 개선하기 위해 지시사항을 튜닝합니다(예: “중요” 또는 “반드시”를 추가하여 강조).

### c. Claude의 허용된 도구 목록 큐레이팅

기본적으로 Claude Code는 시스템을 수정할 수 있는 모든 작업에 대해 권한을 요청합니다: 파일 쓰기, 많은 bash 명령어, MCP 도구 등. 우리는 안전을 최우선으로 하기 위해 Claude Code를 고의적으로 보수적인 접근 방식으로 설계했습니다.

허용 목록을 사용자 정의하여 안전하다고 알고 있는 추가 도구를 허용하거나, 실행 취소하기 쉬운 잠재적으로 안전하지 않은 도구를 허용할 수 있습니다(예: 파일 편집, git commit).

허용된 도구를 관리하는 네 가지 방법이 있습니다:

1. 세션 중에 프롬프트가 표시될 때 “항상 허용” 선택
2. Claude Code를 시작한 후 /permissions 명령어를 사용하여 허용 목록에 도구 추가 또는 제거. 예를 들어, 항상 파일 편집을 허용하려면 Edit 추가, git 커밋을 허용하려면 Bash(git commit:*) 추가, Puppeteer MCP 서버로 탐색을 허용하려면 mcp__puppeteer__puppeteer_navigate 추가
3. .claude/settings.json 또는 ~/.claude.json 수동 편집(팀과 공유하려면 전자를 소스 제어에 커밋하는 것이 좋습니다)
4. 세션별 권한에 대해 –allowedTools CLI 플래그 사용

### d. GitHub 사용 시 gh CLI 설치

Claude는 gh CLI를 사용하여 GitHub와 상호작용하는 방법을 알고 있습니다: 이슈 생성, PR 열기, 댓글 읽기 등. gh가 설치되어 있지 않더라도 Claude는 GitHub API 또는 MCP 서버(설치된 경우)를 사용할 수 있습니다.

—

## 2. Claude에 더 많은 도구 제공

Claude는 쉘 환경에 액세스할 수 있으며, 여기서 자신을 위해 하는 것처럼 편의성 스크립트와 함수 세트를 구축할 수 있습니다. MCP와 REST API를 통해 더 복잡한 도구도 활용할 수 있습니다.

### a. Claude와 bash 도구 사용

Claude Code는 bash 환경을 상속받아 모든 도구에 액세스할 수 있습니다. Claude는 unix 도구 및 gh와 같은 일반적인 유틸리티를 알고 있지만, 지시사항 없이는 사용자 정의 bash 도구를 알지 못합니다:

– 사용 예제와 함께 도구 이름을 Claude에 알려주십시오
– Claude에 –help를 실행하여 도구 문서를 확인하도록 지시하십시오
– 자주 사용하는 도구를 CLAUDE.md에 문서화하십시오

### b. Claude와 MCP 사용

Claude Code는 MCP 서버와 클라이언트 모두로 작동합니다. 클라이언트로서 다양한 MCP 서버에 연결하여 세 가지 방법으로 해당 도구에 액세스할 수 있습니다:

– 프로젝트 구성(해당 디렉토리에서 Claude Code를 실행할 때 사용 가능)
– 전역 구성(모든 프로젝트에서 사용 가능)
– 체크인된 .mcp.json 파일(코드베이스에서 작업하는 모든 사람이 사용 가능)

예를 들어, .mcp.json에 Puppeteer 및 Sentry 서버를 추가할 수 있으므로 저장소에서 작업하는 모든 엔지니어가 이를 즉시 사용할 수 있습니다.

MCP로 작업할 때 –mcp-debug 플래그로 Claude를 실행하는 것도 구성 문제를 식별하는 데 도움이 될 수 있습니다.

### c. 사용자 정의 슬래시 명령어 사용

반복적인 워크플로우—디버깅 루프, 로그 분석 등—에 대해 .claude/commands 폴더 내의 Markdown 파일에 프롬프트 템플릿을 저장합니다. 이는 /를 입력할 때 슬래시 명령어 메뉴를 통해 사용할 수 있습니다.

이러한 명령어를 git에 커밋하여 팀의 나머지 사람들이 사용할 수 있도록 할 수 있습니다.

사용자 정의 슬래시 명령어에는 명령어 호출에서 매개변수를 전달하는 특수 키워드 $ARGUMENTS를 포함할 수 있습니다.

예를 들어, GitHub 이슈를 자동으로 가져와서 수정하는 데 사용할 수 있는 슬래시 명령어는 다음과 같습니다:

“`
다음 GitHub 이슈를 분석하고 수정해 주세요: $ARGUMENTS

다음 단계를 따르세요:
1. `gh issue view`를 사용하여 이슈 세부사항 가져오기
2. 이슈에 설명된 문제 이해하기
3. 관련 파일을 위해 코드베이스 검색하기
4. 이슈를 수정하기 위해 필요한 변경사항 구현하기
5. 수정을 확인하기 위해 테스트 작성 및 실행하기
6. 코드가 linting 및 타입 체크를 통과하는지 확인하기
7. 설명적인 커밋 메시지 작성하기
8. 푸시하고 PR 생성하기

모든 GitHub 관련 작업에 GitHub CLI(`gh`)를 사용하는 것을 기억하세요.
“`

위 내용을 .claude/commands/fix-github-issue.md에 넣으면 Claude Code에서 /project:fix-github-issue 명령어로 사용할 수 있습니다.

그런 다음 /project:fix-github-issue 1234를 사용하여 Claude가 이슈 #1234를 수정하게 할 수 있습니다.

마찬가지로, 모든 세션에서 사용할 수 있는 개인 명령어를 ~/.claude/commands 폴더에 추가할 수 있습니다.

—

## 3. 일반적인 워크플로우 시도

Claude Code는 특정 워크플로우를 강요하지 않으므로 원하는 대로 사용할 수 있는 유연성을 제공합니다. 이러한 유연성이 제공하는 공간 내에서 사용자 커뮤니티 전반에 걸쳐 Claude Code를 효과적으로 사용하는 몇 가지 성공적인 패턴이 나타났습니다:

### a. 탐색, 계획, 코드, 커밋

이 다재다능한 워크플로우는 많은 문제에 적합합니다:

1. Claude에 관련 파일, 이미지 또는 URL을 읽도록 요청합니다. 일반적인 포인터(“로깅을 처리하는 파일을 읽으세요”) 또는 구체적인 파일 이름(“logging.py를 읽으세요”)을 제공하지만, 아직 코드를 작성하지 않도록 명시적으로 지시하십시오. 이는 특히 복잡한 문제의 경우 서브에이전트를 강력하게 사용해야 하는 워크플로우의 부분입니다. Claude가 특정 세부사항을 확인하거나 탐색할 수 있는 특정 질문에 대해 조사하도록 지시하면, 특히 대화나 작업 초기에 컨텍스트 가용성을 보존하며 효율성 손실이 거의 없는 경향이 있습니다.
2. Claude에 특정 문제를 해결하는 방법에 대한 계획을 세우도록 요청합니다. 확장된 생각 모드를 트리거하기 위해 “think”라는 단어를 사용하는 것이 좋습니다. 이는 Claude가 대안을 더 철저하게 평가할 수 있는 추가 계산 시간을 제공합니다. 이러한 특정 구문은 시스템에서 생각 예산의 점진적으로 높은 수준에 직접 매핑됩니다: “think” < "think hard" < "think harder" < "ultrathink." 각 수준은 Claude가 사용하기 위해 점진적으로 더 많은 생각 예산을 할당합니다. 3. 이 단계의 결과가 합리적으로 보이면 Claude가 계획으로 문서나 GitHub 이슈를 만들어 구현(단계 3)이 원하는 것이 아닌 경우 이 지점으로 되돌아갈 수 있습니다. 4. Claude에 코드로 해결책을 구현하도록 요청합니다. 이는 또한 해결책의 일부를 구현할 때 해결책의 합리성을 명시적으로 확인하도록 요청하기에 좋은 곳입니다. 5. Claude에 결과를 커밋하고 PR을 생성하도록 요청합니다. 관련된 경우, 이것은 방금 수행한 작업에 대한 설명으로 README나 변경 로그를 업데이트하도록 요청하기에도 좋은 시기입니다. 단계 #1-#2가 중요합니다. 이 없으면 Claude는 해결책을 코딩하는 것으로 곧바로 넘어가는 경향이 있습니다. 때로는 원하는 것이지만, Claude에 먼저 연구하고 계획을 세우도록 요청하면 깊은 생각이 필요한 문제의 성능이 크게 향상됩니다. ### b. 테스트 작성, 커밋; 코드, 반복, 커밋 이는 단위, 통합 또는 엔드 투 엔드 테스트로 쉽게 검증 가능한 변경에 대한 Anthropic이 선호하는 워크플로우입니다. 테스트 주도 개발(TDD)은 에이전트 코딩에서 더욱 강력해집니다: 1. 예상되는 입력/출력 쌍을 기반으로 Claude에 테스트를 작성하도록 요청합니다. 코드베이스에 아직 존재하지 않는 기능에 대해서도 모의 구현을 만들지 않도록 테스트 주도 개발을 하고 있다는 것을 명시하는 것이 좋습니다. 2. Claude에 테스트를 실행하고 실패하는지 확인하도록 지시합니다. 이 단계에서 구현 코드를 작성하지 않도록 명시적으로 지시하는 것이 종종 도움이 됩니다. 3. 테스트에 만족하면 Claude에 테스트를 커밋하도록 요청합니다. 4. 테스트를 통과하는 코드를 작성하도록 Claude에 지시하며, 테스트를 수정하지 않도록 지시합니다. 5. 모든 테스트가 통과할 때까지 계속하도록 지시합니다. 코드 작성, 테스트 실행, 코드 조정, 테스트 재 실행을 위해 보통 몇 번의 반복이 필요합니다. 이 단계에서 독립적인 서브에이전트로 구현이 테스트에 과적합하지 않는지 확인하도록 요청하는 것이 도움이 될 수 있습니다. 6. 변경 사항에 만족하면 Claude에 코드를 커밋하도록 요청합니다. Claude는 반복할 수 있는 명확한 목표가 있을 때 가장 잘 수행합니다—비주얼 모크, 테스트 케이스 또는 다른 종류의 출력입니다. 테스트와 같은 예상 출력을 제공함으로써 Claude는 변경을 수행하고, 결과를 평가하고, 성공할 때까지 점진적으로 개선할 수 있습니다. ### c. 코드 작성, 스크린샷 결과, 반복 테스트 워크플로우와 유사하게 Claude에 비주얼 목표를 제공할 수 있습니다: 1. Claude에 브라우저 스크린샷을 찍는 방법을 제공합니다(예: Puppeteer MCP 서버, iOS 시뮬레이터 MCP 서버 사용 또는 수동으로 스크린샷을 Claude에 복사/붙여넣기). 2. 복사/붙여넣기 또는 이미지 드래그 앤 드롭을 통해 비주얼 모크를 제공하거나 Claude에 이미지 파일 경로를 제공합니다. 3. Claude에 코드로 디자인을 구현하도록 요청하고, 결과의 스크린샷을 찍고, 결과가 모크와 일치할 때까지 반복하도록 요청합니다. 4. 만족하면 Claude에 커밋하도록 요청합니다. 사람들과 마찬가지로 Claude의 출력도 반복을 통해 크게 향상되는 경향이 있습니다. 첫 번째 버전이 좋을 수 있지만, 2-3번의 반복 후에는 훨씬 더 좋아 보일 것입니다. 최상의 결과를 얻으려면 Claude가 출력을 볼 수 있는 도구를 제공하세요. ### d. 안전한 YOLO 모드 Claude를 감독하는 대신 claude --dangerously-skip-permissions를 사용하여 모든 권한 확인을 건너뛰고 Claude가 완료될 때까지 방해받지 않고 작업하도록 할 수 있습니다. 이는 lint 오류 수정 또는 상용구 코드 생성과 같은 워크플로우에 잘 작동합니다. Claude에 임의의 명령어를 실행하도록 하는 것은 위험하며 데이터 손실, 시스템 손상 또는 데이터 탈취(예: 프롬프트 인젝션 공격을 통해)와 같은 결과가 발생할 수 있습니다. 이러한 위험을 최소화하려면 인터넷 액세스 없는 컨테이너에서 --dangerously-skip-permissions를 사용하세요. Docker Dev Containers를 사용하는 이 참조 구현을 따를 수 있습니다. ### e. 코드베이스 Q&A 새 코드베이스에 온보딩할 때 학습 및 탐색을 위해 Claude Code를 사용하세요. 페어 프로그래밍할 때 프로젝트의 다른 엔지니어에게 물어볼 것과 동일한 종류의 질문을 Claude에 할 수 있습니다. Claude는 에이전트적으로 코드베이스를 검색하여 다음과 같은 일반적인 질문에 답할 수 있습니다: - 로깅은 어떻게 작동하나요? - 새 API 엔드포인트를 만드는 방법은 무엇인가요? - foo.rs의 134번 라인에서 async move { ... }는 무엇을 하나요? - CustomerOnboardingFlowImpl는 어떤 엣지 케이스를 처리하나요? - 333번 라인에서 bar()가 아닌 foo()를 호출하는 이유는 무엇인가요? - baz.py의 334번 라인과 동등한 것은 Java에서 무엇인가요? Anthropic에서는 이런 식으로 Claude Code를 사용하는 것이 핵심 온보딩 워크플로우가 되었으며, 램업 시간을 크게 개선하고 다른 엔지니어의 부담을 줄였습니다. 특별한 프롬프트가 필요하지 않습니다! 질문만 하면 Claude가 코드를 탐색하여 답을 찾습니다. ### f. git과 상호작용하기 위해 Claude 사용 Claude는 많은 git 작업을 효과적으로 처리할 수 있습니다. 많은 Anthropic 엔지니어가 git 상호작용의 90% 이상에 Claude를 사용합니다: - "v1.2.3에 어떤 변경사항이 포함되었나요?", "이 특정 기능의 소유자는 누구인가요?", 또는 "이 API가 이런 식으로 설계된 이유는 무엇인가요?"와 같은 질문에 답하기 위해 git 기록 검색. 이러한 질문에 답하기 위해 git 기록을 살펴보도록 Claude에 명시적으로 프롬프트하는 것이 도움이 됩니다 - 커밋 메시지 작성. Claude는 관련 모든 컨텍스트를 고려하여 메시지를 작성하기 위해 변경 사항과 최근 기록을 자동으로 살펴봅니다 - 파일 되돌리기, 리베이스 충돌 해결, 패치 비교 및 그래프와 같은 복잡한 git 작업 처리 ### g. GitHub와 작업하기 위해 Claude 사용 Claude Code는 많은 GitHub 상호작용을 관리할 수 있습니다: - PR 생성: Claude는 "pr" 축약어를 이해하며 diff와 주변 컨텍스트를 기반으로 적절한 커밋 메시지를 생성합니다 - 간단한 코드 리뷰 댓글에 대한 원샷 해결 구현: PR의 댓글을 수정하도록 지시하면(선택적으로 더 구체적인 지시사항 제공) 완료되면 PR 브랜치로 다시 푸시합니다 - 실패한 빌드 또는 린터 경고 수정 - Claude에 열린 GitHub 이슈를 루프하도록 요청하여 열린 이슈 분류 및 분류 이는 일상적인 작업을 자동화하면서 gh 명령줄 구문을 기억할 필요를 없앱니다. ### h. Jupyter 노트북과 작업하기 위해 Claude 사용 Anthropic의 연구원과 데이터 과학자는 Claude Code를 사용하여 Jupyter 노트북을 읽고 씁니다. Claude는 이미지를 포함한 출력을 해석할 수 있으며, 데이터를 탐색하고 상호작용하는 빠른 방법을 제공합니다. 필요한 프롬프트나 워크플로우는 없지만, 우리가 권장하는 워크플로우는 VS Code에서 Claude Code와 .ipynb 파일을 나란히 열어두는 것입니다. 또한 동료에게 보여주기 전에 Claude에 Jupyter 노트북을 정리하거나 미적 개선을 만들도록 요청할 수 있습니다. 노트북이나 데이터 시각화를 "미적으로 즐겁게" 만들도록 구체적으로 지시하면 인간 시청 경험을 최적화하고 있다는 것을 상기시키는 데 도움이 되는 경향이 있습니다. --- ## 4. 워크플로우 최적화 다음 제안은 모든 워크플로우에 적용됩니다: ### a. 지시사항을 구체적으로 작성 Claude Code의 성공률은 더 구체적인 지시사항으로 크게 향상되며, 특히 첫 번째 시도에서 그렇습니다. 명확한 방향을 앞서 제공하면 나중에 방향 수정의 필요성이 줄어듭니다. 예를 들어: | 나쁨 | 좋음 | |------|------| | foo.py에 테스트 추가 | foo.py에 대한 새 테스트 케이스를 작성하세요. 사용자가 로그아웃된 엣지 케이스를 포함합니다. | | 모의 방지 | ExecutionFactory의 api가 왜 그렇게 이상한가요? ExecutionFactory의 git 기록을 살펴보고 api가 어떻게 되었는지 요약하세요 | | 캘린더 위젯 추가 | 홈 페이지의 기존 위젯이 구현되는 방식을 살펴보고 특히 코드와 인터페이스가 어떻게 분리되는지 이해하세요. HotDogWidget.php는 시작하기에 좋은 예입니다. 그런 다음 패턴을 따라 사용자가 월을 선택하고 연도를 선택하기 위해 앞뒤로 페이징할 수 있는 새 캘린더 위젯을 구현하세요. 코드베이스의 나머지 부분에서 이미 사용된 것 외에는 라이브러리 없이 처음부터 빌드하세요. | Claude는 의도를 추론할 수 있지만 마음을 읽을 수는 없습니다. 구체성은 기대치와 더 나은 정렬로 이어집니다. ### b. Claude에 이미지 제공 Claude는 여러 방법을 통해 이미지와 다이어그램에 뛰어납니다: - 스크린샷 붙여넣기(팁: macOS에서 cmd+ctrl+shift+4를 눌러 클립보드에 스크린샷을 찍고 ctrl+v를 눌러 붙여넣습니다. Mac에서 일반적으로 사용하는 cmd+v가 아니며 원격으로 작동하지 않습니다) - 이미지를 프롬프트 입력으로 직접 드래그 앤 드롭 - 이미지의 파일 경로 제공 이는 UI 개발을 위한 참조 지점으로 디자인 모크, 분석 및 디버깅을 위한 비주얼 차트로 작업할 때 특히 유용합니다. 컨텍스트에 비주얼을 추가하지 않는 경우에도 결과가 얼마나 시각적으로 매력적인지 Claude에게 명확하게 하는 것이 여전히 도움이 될 수 있습니다. ### c. Claude가 살펴보거나 작업할 파일을 언급 탭 완성을 사용하여 저장소의 어느 곳에서든 파일이나 폴더를 빠르게 참조하여 Claude가 올바른 리소스를 찾거나 업데이트하도록 도와주세요. ### d. Claude에 URL 제공 Claude가 가져와서 읽을 수 있도록 프롬프트와 함께 특정 URL을 붙여넣으세요. 동일한 도메인(예: docs.foo.com)에 대한 권한 프롬프트를 피하려면 /permissions를 사용하여 도메인을 허용 목록에 추가하세요. ### e. 자주 그리고 조기에 수정 자동 수락 모드(shift+tab으로 토글)는 Claude가 자율적으로 작업할 수 있게 하지만, 적극적인 협력자가 되어 Claude의 접근 방식을 안내하면 더 나은 결과를 얻을 수 있습니다. 작업 시작에 Claude에게 철저하게 설명하여 최상의 결과를 얻을 수 있지만, 언제든지 Claude를 수정할 수도 있습니다. 이 네 가지 도구가 수정에 도움이 됩니다: - 코딩하기 전에 Claude에 계획을 세우도록 요청합니다. 계획이 좋아 보일 때까지 코딩하지 않도록 명시적으로 지시하십시오. - 아무 단계에서(생각, 도구 호출, 파일 편집) Escape를 눌러 Claude를 중단하여 컨텍스트를 보존하고 방향을 재지정하거나 지시사항을 확장할 수 있습니다. - Escape를 두 번 누르면 기록으로 돌아가서 이전 프롬프트를 편집하고 다른 방향을 탐색할 수 있습니다. 원하는 결과를 얻을 때까지 프롬프트를 편집하고 반복할 수 있습니다. - Claude에 변경 사항을 실행 취소하도록 요청합니다. 종종 옵션 #2와 함께 사용하여 다른 접근 방식을 취합니다. Claude Code는 때때로 첫 번째 시도에서 완벽하게 문제를 해결하지만, 이러한 수정 도구를 사용하면 일반적으로 더 나은 해결책을 더 빨리 얻을 수 있습니다. ### f. 컨텍스트를 집중 상태로 유지하기 위해 /clear 사용 긴 세션 동안 Claude의 컨텍스트 윈도우는 관련 없는 대화, 파일 내용, 명령어로 채워질 수 있습니다. 이는 성능을 저하시키고 때로는 Claude를 방해할 수 있습니다. 작업 간에 /clear 명령어를 자주 사용하여 컨텍스트 윈도우를 재설정하세요. ### g. 복잡한 워크플로우에 체크리스트 및 스크래치패드 사용 여러 단계가 있거나 철저한 해결책이 필요한 큰 작업—예: 코드 마이그레이션, 수많은 lint 오류 수정, 복잡한 빌드 스크립트 실행—의 경우 Claude가 Markdown 파일(또는 GitHub 이슈조차도!)을 체크리스트와 작업 스크래치패드로 사용하도록 하여 성능을 향상시킬 수 있습니다. 예를 들어, 많은 수의 lint 문제를 수정하려면 다음을 수행할 수 있습니다: 1. Claude에 lint 명령어를 실행하고 결과 오류(파일 이름 및 줄 번호 포함)를 Markdown 체크리스트에 작성하도록 지시합니다 2. Claude에 각 문제를 하나씩 해결하고 다음으로 넘어가기 전에 수정하고 확인하도록 지시합니다 ### h. Claude에 데이터 전달 Claude에 데이터를 제공하는 여러 가지 방법이 있습니다: - 프롬프트에 직접 복사 및 붙여넣기(가장 일반적인 접근 방식) - Claude Code로 파이프(예: cat foo.txt | claude), 로그, CSV 및 대용량 데이터에 특히 유용 - Claude에 bash 명령어, MCP 도구 또는 사용자 정의 슬래시 명령어를 통해 데이터를 가져오도록 지시 - Claude에 파일을 읽거나 URL을 가져오도록 지시(이미지도 작동) 대부분의 세션은 이러한 접근 방식의 조합을 포함합니다. 예를 들어, 로그 파일을 파이프한 다음 Claude에 도구를 사용하여 로그를 디버깅하는 추가 컨텍스트를 가져오도록 지시할 수 있습니다. --- ## 5. 인프라를 자동화하기 위해 헤드리스 모드 사용 Claude Code는 CI, 사전 커밋 후크, 빌드 스크립트, 자동화와 같은 비대화형 컨텍스트를 위한 헤드리스 모드를 포함합니다. 프롬프트와 함께 -p 플래그를 사용하여 헤드리스 모드를 활성화하고 스트리밍 JSON 출력을 위해 --output-format stream-json을 사용합니다. 헤드리스 모드는 세션 간에 지속되지 않습니다. 매 세션마다 트리거해야 합니다. ### a. 이슈 분류에 Claude 사용 헤드리스 모드는 GitHub 이벤트에 의해 트리거되는 자동화를 제공할 수 있습니다. 예를 들어, 공개 Claude Code 저장소는 Claude를 사용하여 들어오는 새 이슈를 검사하고 적절한 레이블을 할당합니다. ### b. 린터로 Claude 사용 Claude Code는 전통적인 linting 도구가 감지하는 것을 넘어선 주관적인 코드 리뷰를 제공할 수 있습니다. 오타, 오래된 주석, 오해를 일으키는 함수 또는 변수 이름 등을 식별할 수 있습니다. --- ## 6. 다중 Claude 워크플로우로 수준 높이기 독립형 사용을 넘어, 가장 강력한 응용 프로그램 중 일부는 여러 Claude 인스턴스를 병렬로 실행하는 것을 포함합니다: ### a. 한 Claude가 코드를 작성하게 하고 다른 Claude로 확인 단순하지만 효과적인 접근 방식은 한 Claude가 코드를 작성하는 동안 다른 Claude가 검토하거나 테스트하는 것입니다. 여러 엔지니어와 작업하는 것과 유사하게 때로는 별도의 컨텍스트를 갖는 것이 유익합니다: 1. Claude를 사용하여 코드 작성 2. /clear를 사용하거나 다른 터미널에서 두 번째 Claude 시작 3. 두 번째 Claude가 첫 번째 Claude의 작업을 검토하도록 함 4. 또 다른 Claude를 시작하거나 다시 /clear를 사용하여 코드와 검토 피드백을 모두 읽음 5. 이 Claude가 피드백을 기반으로 코드를 편집하도록 함 테스트로 비슷한 작업을 수행할 수 있습니다. 한 Claude에 테스트를 작성하게 한 다음 다른 Claude가 테스트를 통과하는 코드를 작성하게 할 수 있습니다. 별도의 작업 스크래치패드를 제공하고 어디에 쓰고 어디에서 읽어야 하는지 지시하여 Claude 인스턴스가 서로 통신하도록 할 수도 있습니다. 이러한 분리는 단일 Claude가 모든 것을 처리하는 것보다 종종 더 나은 결과를 산출합니다. ### b. 저장소의 여러 체크아웃 사용 Claude가 각 단계를 완료할 때까지 기다리는 대신, 많은 Anthropic 엔지니어가 하는 것은: 1. 별도의 폴더에 3-4개의 git 체크아웃 생성 2. 각 폴더를 별도의 터미널 탭에서 열기 3. 각 폴더에서 다른 작업으로 Claude 시작 4. 진행 상황을 확인하고 권한 요청을 승인/거부하기 위해 순환 ### c. git worktrees 사용 이 접근 방식은 여러 독립 작업에 빛을 발하며 여러 체크아웃보다 가벼운 대안을 제공합니다. Git worktrees를 사용하면 동일한 저장소에서 여러 브랜치를 별도의 디렉토리로 체크아웃할 수 있습니다. 각 worktree는 고립된 파일이 있는 자체 작업 디렉토리를 가지며 동일한 Git 기록 및 reflog를 공유합니다. git worktrees를 사용하면 프로젝트의 다른 부분에서 동시에 여러 Claude 세션을 실행할 수 있으며, 각각 자체 독립 작업에 집중할 수 있습니다. 예를 들어, 한 Claude는 인증 시스템을 리팩터링하는 동안 다른 Claude는 완전히 관련 없는 데이터 시각화 구성 요소를 구축할 수 있습니다. 작업이 겹치지 않으므로 각 Claude는 다른 Claude의 변경을 기다리거나 병합 충돌을 처리하지 않고 최고 속도로 작업할 수 있습니다: 1. worktrees 생성: `git worktree add ../project-feature-a feature-a` 2. 각 worktree에서 Claude 시작: `cd ../project-feature-a && claude` 3. 필요에 따라 추가 worktrees 생성(새 터미널 탭에서 단계 1-2 반복) 몇 가지 팁: - 일관된 명명 규칙 사용 - worktree당 하나의 터미널 탭 유지 - Mac에서 iTerm2를 사용하는 경우 Claude에 주의가 필요할 때 알림 설정 - 다른 worktrees용 별도의 IDE 창 사용 - 완료되면 정리: `git worktree remove ../project-feature-a` ### d. 사용자 정식 하니스와 함께 헤드리스 모드 사용 claude -p(헤드리스 모드)는 Claude Code를 더 큰 워크... (생략됨)

Claude Code 모범 사례 \ Anthropic

이 블로그 게시물은 2026년 1월 26일부터 더 이상 유지되지 않으며, 최신 Claude Code 모범 사례는 공식 문서에서 확인할 수 있습니다. Claude Code는 Anthropic 엔지니어와 연구원들이 코딩 워크플로우에 Claude를 더 자연스럽게 통합할 수 있도록 개발된 명령줄 도구로, 낮은 수준의 접근성과 높은 유연성을 제공합니다. 이 글에서는 Anthropic 내부 팀과 외부 엔지니어들이 다양한 코드베이스와 언어, 환경에서 Claude Code를 효과적으로 활용하는 데 입증된 일반적인 패턴들을 다룹니다. 환경 설정 최적화, 도구 확장, 일반적인 워크플로우, 다중 Claude 세션 활용 등 다양한 팁과 전략을 제공합니다.

===BODY_KO## Claude Code 모범 사례가 문서로 이동했습니다

2026년 1월 26일

이 블로그 게시물은 더 이상 유지되지 않습니다. Claude Code가 발전함에 따라 항상 최신 상태로 유지되는 공식 문서(https://code.claude.com/docs/en/best-practices)에서 가장 최신 Claude Code 모범 사례를 확인하시기 바랍니다.

---

우리는 최근 Claude Code를 출시했습니다. 이는 에이전트 코딩을 위한 명령줄 도구입니다. 연구 프로젝트로 개발된 Claude Code는 Anthropic 엔지니어와 연구원들이 코딩 워크플로우에 Claude를 더 자연스럽게 통합할 수 있는 방법을 제공합니다.

Claude Code는 의도적으로 낮은 수준으로 설계되어 특정 워크플로우를 강요하지 않고 원시 모델 액세스에 가까운 접근성을 제공합니다. 이 디자인 철학은 유연하고, 사용자 정의 가능하며, 스크립트 가능하고, 안전한 강력한 도구를 만듭니다.

강력하지만 이러한 유연성은 에이전트 코딩 도구에 익숙하지 않은 엔지니어들에게는 학습 곡선을 제시합니다. 적어도 그들이 자신만의 모범 사례를 개발할 때까지는 그렇습니다.

이 게시물은 Anthropic의 내부 팀과 다양한 코드베이스, 언어, 환경에서 Claude Code를 사용하는 외부 엔지니어 모두에게 효과적인 것으로 입증된 일반적인 패턴을 설명합니다.

이 목록의 어떤 항목도 확정된 것이 아니며 보편적으로 적용 가능하지 않습니다. 이러한 제안을 시작점으로 고려해 주십시오. 우리는 실험하고 가장 잘 작동하는 것을 찾아보라고 권장합니다!

---

더 자세한 정보를 찾고 계신가요?

claude.ai/code의 포괄적인 문서는 이 게시물에서 언급된 모든 기능을 다루며 추가 예제, 구현 세부사항, 고급 기술을 제공합니다.

---

1. 설정 사용자 정의

Claude Code는 자동으로 프롬프트에 컨텍스트를 가져오는 에이전트 코딩 어시스턴트입니다. 이 컨텍스트 수집은 시간과 토큰을 소비하지만, 환경 튜닝을 통해 최적화할 수 있습니다.

a. CLAUDE.md 파일 생성

CLAUDE.md는 대화를 시작할 때 Claude가 자동으로 컨텍스트로 가져오는 특수 파일입니다. 따라서 다음을 문서화하기에 이상적인 장소입니다:

• 일반적인 bash 명령어
• 핵심 파일과 유틸리티 함수
• 코드 스타일 지침
• 테스트 지시사항
• 저장소 에티켓(예: 브랜치 이름 지정, merge vs rebase 등)
• 개발자 환경 설정(예: pyenv 사용, 작동하는 컴파일러)
• 프로젝트에 특이한 예기치 않은 동작이나 경고
• Claude가 기억하길 원하는 기타 정보

CLAUDE.md 파일에 필요한 형식은 없습니다. 간결하고 사람이 읽기 쉽게 유지하는 것이 좋습니다. 예를 들어:

“markdown

Bash 명령어

• npm run build: 프로젝트 빌드
• npm run typecheck: 타입 체커 실행

코드 스타일

• CommonJS(require)가 아닌 ES 모듈(import/export) 구문 사용
• 가능한 경우 import 해제(예: import { foo } from 'bar')

워크플로우

• 일련의 코드 변경이 완료되면 타입 체크 확인
• 성능을 위해 전체 테스트 스위트가 아닌 단일 테스트 실행 선호

`

CLAUDE.md 파일을 여러 위치에 배치할 수 있습니다:

• 저장소의 루트 또는 claude를 실행하는 위치(가장 일반적인 사용법). CLAUDE.md라고 이름을 지정하고 git에 커밋하여 세션 간에 공유하고 팀과 공유(권장), 또는 CLAUDE.local.md라고 이름을 지정하고 .gitignore 추가
• claude를 실행하는 디렉토리의 상위 디렉토리. 이는 모노레포에서 가장 유용하며, 루트/foo에서 claude를 실행할 수 있고 루트/CLAUDE.md와 루트/foo/CLAUDE.md 모두에 CLAUDE.md 파일을 둘 수 있습니다. 둘 다 자동으로 컨텍스트로 가져옵니다
• claude를 실행하는 디렉토리의 하위 디렉토리. 위와 반대이며 이 경우 Claude는 하위 디렉토리의 파일로 작업할 때 필요에 따라 CLAUDE.md 파일을 가져옵니다
• 홈 폴더(~/.claude/CLAUDE.md), 모든 claude 세션에 적용

/init 명령어를 실행하면 Claude가 자동으로 CLAUDE.md를 생성합니다.

b. CLAUDE.md 파일 튜닝

CLAUDE.md 파일은 Claude의 프롬프트의 일부가 되므로, 자주 사용하는 프롬프트처럼 다듬어야 합니다. 흔한 실수는 효과성을 반복하지 않고 광범위한 콘텐츠를 추가하는 것입니다. 실험하고 모델에서 가장 좋은 지시사항 따르기를 생성하는 것이 무엇인지 결정하는 데 시간을 투자하십시오.

CLAUDE.md에 콘텐츠를 수동으로 추가하거나 # 키를 눌러 Claude에 지시사항을 제공할 수 있으며, Claude는 이를 관련 CLAUDE.md에 자동으로 통합합니다.

많은 엔지니어가 코딩할 때 #를 자주 사용하여 명령어, 파일, 스타일 지침을 문서화한 다음, 팀원들도 혜택을 받을 수 있도록 CLAUDE.md 변경사항을 커밋에 포함합니다.

Anthropic에서는 때때로 CLAUDE.md 파일을 프롬프트 개선자를 통해 실행하고, 준수를 개선하기 위해 지시사항을 튜닝합니다(예: "중요" 또는 "반드시"를 추가하여 강조).

c. Claude의 허용된 도구 목록 큐레이팅

기본적으로 Claude Code는 시스템을 수정할 수 있는 모든 작업에 대해 권한을 요청합니다: 파일 쓰기, 많은 bash 명령어, MCP 도구 등. 우리는 안전을 최우선으로 하기 위해 Claude Code를 고의적으로 보수적인 접근 방식으로 설계했습니다.

허용 목록을 사용자 정의하여 안전하다고 알고 있는 추가 도구를 허용하거나, 실행 취소하기 쉬운 잠재적으로 안전하지 않은 도구를 허용할 수 있습니다(예: 파일 편집, git commit).

허용된 도구를 관리하는 네 가지 방법이 있습니다:

1. 세션 중에 프롬프트가 표시될 때 "항상 허용" 선택

2. Claude Code를 시작한 후 /permissions 명령어를 사용하여 허용 목록에 도구 추가 또는 제거. 예를 들어, 항상 파일 편집을 허용하려면 Edit 추가, git 커밋을 허용하려면 Bash(git commit:*) 추가, Puppeteer MCP 서버로 탐색을 허용하려면 mcp__puppeteer__puppeteer_navigate 추가

3. .claude/settings.json 또는 ~/.claude.json 수동 편집(팀과 공유하려면 전자를 소스 제어에 커밋하는 것이 좋습니다)

4. 세션별 권한에 대해 --allowedTools CLI 플래그 사용

d. GitHub 사용 시 gh CLI 설치

Claude는 gh CLI를 사용하여 GitHub와 상호작용하는 방법을 알고 있습니다: 이슈 생성, PR 열기, 댓글 읽기 등. gh가 설치되어 있지 않더라도 Claude는 GitHub API 또는 MCP 서버(설치된 경우)를 사용할 수 있습니다.

---

2. Claude에 더 많은 도구 제공

Claude는 쉘 환경에 액세스할 수 있으며, 여기서 자신을 위해 하는 것처럼 편의성 스크립트와 함수 세트를 구축할 수 있습니다. MCP와 REST API를 통해 더 복잡한 도구도 활용할 수 있습니다.

a. Claude와 bash 도구 사용

Claude Code는 bash 환경을 상속받아 모든 도구에 액세스할 수 있습니다. Claude는 unix 도구 및 gh와 같은 일반적인 유틸리티를 알고 있지만, 지시사항 없이는 사용자 정의 bash 도구를 알지 못합니다:

• 사용 예제와 함께 도구 이름을 Claude에 알려주십시오
• Claude에 --help를 실행하여 도구 문서를 확인하도록 지시하십시오
• 자주 사용하는 도구를 CLAUDE.md에 문서화하십시오

b. Claude와 MCP 사용

Claude Code는 MCP 서버와 클라이언트 모두로 작동합니다. 클라이언트로서 다양한 MCP 서버에 연결하여 세 가지 방법으로 해당 도구에 액세스할 수 있습니다:

• 프로젝트 구성(해당 디렉토리에서 Claude Code를 실행할 때 사용 가능)
• 전역 구성(모든 프로젝트에서 사용 가능)
• 체크인된 .mcp.json 파일(코드베이스에서 작업하는 모든 사람이 사용 가능)

예를 들어, .mcp.json에 Puppeteer 및 Sentry 서버를 추가할 수 있으므로 저장소에서 작업하는 모든 엔지니어가 이를 즉시 사용할 수 있습니다.

MCP로 작업할 때 --mcp-debug 플래그로 Claude를 실행하는 것도 구성 문제를 식별하는 데 도움이 될 수 있습니다.

c. 사용자 정의 슬래시 명령어 사용

반복적인 워크플로우—디버깅 루프, 로그 분석 등—에 대해 .claude/commands 폴더 내의 Markdown 파일에 프롬프트 템플릿을 저장합니다. 이는 /를 입력할 때 슬래시 명령어 메뉴를 통해 사용할 수 있습니다.

이러한 명령어를 git에 커밋하여 팀의 나머지 사람들이 사용할 수 있도록 할 수 있습니다.

사용자 정의 슬래시 명령어에는 명령어 호출에서 매개변수를 전달하는 특수 키워드 $ARGUMENTS를 포함할 수 있습니다.

예를 들어, GitHub 이슈를 자동으로 가져와서 수정하는 데 사용할 수 있는 슬래시 명령어는 다음과 같습니다:

`

다음 GitHub 이슈를 분석하고 수정해 주세요: $ARGUMENTS

다음 단계를 따르세요:

1. gh issue view를 사용하여 이슈 세부사항 가져오기

2. 이슈에 설명된 문제 이해하기

3. 관련 파일을 위해 코드베이스 검색하기

4. 이슈를 수정하기 위해 필요한 변경사항 구현하기

5. 수정을 확인하기 위해 테스트 작성 및 실행하기

6. 코드가 linting 및 타입 체크를 통과하는지 확인하기

7. 설명적인 커밋 메시지 작성하기

8. 푸시하고 PR 생성하기

모든 GitHub 관련 작업에 GitHub CLI(gh)를 사용하는 것을 기억하세요.

`

위 내용을 .claude/commands/fix-github-issue.md에 넣으면 Claude Code에서 /project:fix-github-issue 명령어로 사용할 수 있습니다.

그런 다음 /project:fix-github-issue 1234를 사용하여 Claude가 이슈 #1234를 수정하게 할 수 있습니다.

마찬가지로, 모든 세션에서 사용할 수 있는 개인 명령어를 ~/.claude/commands 폴더에 추가할 수 있습니다.

---

3. 일반적인 워크플로우 시도

Claude Code는 특정 워크플로우를 강요하지 않으므로 원하는 대로 사용할 수 있는 유연성을 제공합니다. 이러한 유연성이 제공하는 공간 내에서 사용자 커뮤니티 전반에 걸쳐 Claude Code를 효과적으로 사용하는 몇 가지 성공적인 패턴이 나타났습니다:

a. 탐색, 계획, 코드, 커밋

이 다재다능한 워크플로우는 많은 문제에 적합합니다:

1. Claude에 관련 파일, 이미지 또는 URL을 읽도록 요청합니다. 일반적인 포인터("로깅을 처리하는 파일을 읽으세요") 또는 구체적인 파일 이름("logging.py를 읽으세요")을 제공하지만, 아직 코드를 작성하지 않도록 명시적으로 지시하십시오. 이는 특히 복잡한 문제의 경우 서브에이전트를 강력하게 사용해야 하는 워크플로우의 부분입니다. Claude가 특정 세부사항을 확인하거나 탐색할 수 있는 특정 질문에 대해 조사하도록 지시하면, 특히 대화나 작업 초기에 컨텍스트 가용성을 보존하며 효율성 손실이 거의 없는 경향이 있습니다.

2. Claude에 특정 문제를 해결하는 방법에 대한 계획을 세우도록 요청합니다. 확장된 생각 모드를 트리거하기 위해 "think"라는 단어를 사용하는 것이 좋습니다. 이는 Claude가 대안을 더 철저하게 평가할 수 있는 추가 계산 시간을 제공합니다. 이러한 특정 구문은 시스템에서 생각 예산의 점진적으로 높은 수준에 직접 매핑됩니다: "think" < "think hard" < "think harder" < "ultrathink." 각 수준은 Claude가 사용하기 위해 점진적으로 더 많은 생각 예산을 할당합니다.

3. 이 단계의 결과가 합리적으로 보이면 Claude가 계획으로 문서나 GitHub 이슈를 만들어 구현(단계 3)이 원하는 것이 아닌 경우 이 지점으로 되돌아갈 수 있습니다.

4. Claude에 코드로 해결책을 구현하도록 요청합니다. 이는 또한 해결책의 일부를 구현할 때 해결책의 합리성을 명시적으로 확인하도록 요청하기에 좋은 곳입니다.

5. Claude에 결과를 커밋하고 PR을 생성하도록 요청합니다. 관련된 경우, 이것은 방금 수행한 작업에 대한 설명으로 README나 변경 로그를 업데이트하도록 요청하기에도 좋은 시기입니다.

단계 #1-#2가 중요합니다. 이 없으면 Claude는 해결책을 코딩하는 것으로 곧바로 넘어가는 경향이 있습니다. 때로는 원하는 것이지만, Claude에 먼저 연구하고 계획을 세우도록 요청하면 깊은 생각이 필요한 문제의 성능이 크게 향상됩니다.

b. 테스트 작성, 커밋; 코드, 반복, 커밋

이는 단위, 통합 또는 엔드 투 엔드 테스트로 쉽게 검증 가능한 변경에 대한 Anthropic이 선호하는 워크플로우입니다.

테스트 주도 개발(TDD)은 에이전트 코딩에서 더욱 강력해집니다:

1. 예상되는 입력/출력 쌍을 기반으로 Claude에 테스트를 작성하도록 요청합니다. 코드베이스에 아직 존재하지 않는 기능에 대해서도 모의 구현을 만들지 않도록 테스트 주도 개발을 하고 있다는 것을 명시하는 것이 좋습니다.

2. Claude에 테스트를 실행하고 실패하는지 확인하도록 지시합니다. 이 단계에서 구현 코드를 작성하지 않도록 명시적으로 지시하는 것이 종종 도움이 됩니다.

3. 테스트에 만족하면 Claude에 테스트를 커밋하도록 요청합니다.

4. 테스트를 통과하는 코드를 작성하도록 Claude에 지시하며, 테스트를 수정하지 않도록 지시합니다.

5. 모든 테스트가 통과할 때까지 계속하도록 지시합니다. 코드 작성, 테스트 실행, 코드 조정, 테스트 재 실행을 위해 보통 몇 번의 반복이 필요합니다. 이 단계에서 독립적인 서브에이전트로 구현이 테스트에 과적합하지 않는지 확인하도록 요청하는 것이 도움이 될 수 있습니다.

6. 변경 사항에 만족하면 Claude에 코드를 커밋하도록 요청합니다.

Claude는 반복할 수 있는 명확한 목표가 있을 때 가장 잘 수행합니다—비주얼 모크, 테스트 케이스 또는 다른 종류의 출력입니다. 테스트와 같은 예상 출력을 제공함으로써 Claude는 변경을 수행하고, 결과를 평가하고, 성공할 때까지 점진적으로 개선할 수 있습니다.

c. 코드 작성, 스크린샷 결과, 반복

테스트 워크플로우와 유사하게 Claude에 비주얼 목표를 제공할 수 있습니다:

1. Claude에 브라우저 스크린샷을 찍는 방법을 제공합니다(예: Puppeteer MCP 서버, iOS 시뮬레이터 MCP 서버 사용 또는 수동으로 스크린샷을 Claude에 복사/붙여넣기).

2. 복사/붙여넣기 또는 이미지 드래그 앤 드롭을 통해 비주얼 모크를 제공하거나 Claude에 이미지 파일 경로를 제공합니다.

3. Claude에 코드로 디자인을 구현하도록 요청하고, 결과의 스크린샷을 찍고, 결과가 모크와 일치할 때까지 반복하도록 요청합니다.

4. 만족하면 Claude에 커밋하도록 요청합니다.

사람들과 마찬가지로 Claude의 출력도 반복을 통해 크게 향상되는 경향이 있습니다. 첫 번째 버전이 좋을 수 있지만, 2-3번의 반복 후에는 훨씬 더 좋아 보일 것입니다. 최상의 결과를 얻으려면 Claude가 출력을 볼 수 있는 도구를 제공하세요.

d. 안전한 YOLO 모드

Claude를 감독하는 대신 claude --dangerously-skip-permissions를 사용하여 모든 권한 확인을 건너뛰고 Claude가 완료될 때까지 방해받지 않고 작업하도록 할 수 있습니다. 이는 lint 오류 수정 또는 상용구 코드 생성과 같은 워크플로우에 잘 작동합니다.

Claude에 임의의 명령어를 실행하도록 하는 것은 위험하며 데이터 손실, 시스템 손상 또는 데이터 탈취(예: 프롬프트 인젝션 공격을 통해)와 같은 결과가 발생할 수 있습니다. 이러한 위험을 최소화하려면 인터넷 액세스 없는 컨테이너에서 --dangerously-skip-permissions를 사용하세요. Docker Dev Containers를 사용하는 이 참조 구현을 따를 수 있습니다.

e. 코드베이스 Q&A

새 코드베이스에 온보딩할 때 학습 및 탐색을 위해 Claude Code를 사용하세요. 페어 프로그래밍할 때 프로젝트의 다른 엔지니어에게 물어볼 것과 동일한 종류의 질문을 Claude에 할 수 있습니다. Claude는 에이전트적으로 코드베이스를 검색하여 다음과 같은 일반적인 질문에 답할 수 있습니다:

• 로깅은 어떻게 작동하나요?
• 새 API 엔드포인트를 만드는 방법은 무엇인가요?
• foo.rs의 134번 라인에서 async move { ... }는 무엇을 하나요?
• CustomerOnboardingFlowImpl는 어떤 엣지 케이스를 처리하나요?
• 333번 라인에서 bar()가 아닌 foo()를 호출하는 이유는 무엇인가요?
• baz.py의 334번 라인과 동등한 것은 Java에서 무엇인가요?

Anthropic에서는 이런 식으로 Claude Code를 사용하는 것이 핵심 온보딩 워크플로우가 되었으며, 램업 시간을 크게 개선하고 다른 엔지니어의 부담을 줄였습니다. 특별한 프롬프트가 필요하지 않습니다! 질문만 하면 Claude가 코드를 탐색하여 답을 찾습니다.

f. git과 상호작용하기 위해 Claude 사용

Claude는 많은 git 작업을 효과적으로 처리할 수 있습니다. 많은 Anthropic 엔지니어가 git 상호작용의 90% 이상에 Claude를 사용합니다:

• "v1.2.3에 어떤 변경사항이 포함되었나요?", "이 특정 기능의 소유자는 누구인가요?", 또는 "이 API가 이런 식으로 설계된 이유는 무엇인가요?"와 같은 질문에 답하기 위해 git 기록 검색. 이러한 질문에 답하기 위해 git 기록을 살펴보도록 Claude에 명시적으로 프롬프트하는 것이 도움이 됩니다
• 커밋 메시지 작성. Claude는 관련 모든 컨텍스트를 고려하여 메시지를 작성하기 위해 변경 사항과 최근 기록을 자동으로 살펴봅니다
• 파일 되돌리기, 리베이스 충돌 해결, 패치 비교 및 그래프와 같은 복잡한 git 작업 처리

g. GitHub와 작업하기 위해 Claude 사용

Claude Code는 많은 GitHub 상호작용을 관리할 수 있습니다:

• PR 생성: Claude는 "pr" 축약어를 이해하며 diff와 주변 컨텍스트를 기반으로 적절한 커밋 메시지를 생성합니다
• 간단한 코드 리뷰 댓글에 대한 원샷 해결 구현: PR의 댓글을 수정하도록 지시하면(선택적으로 더 구체적인 지시사항 제공) 완료되면 PR 브랜치로 다시 푸시합니다
• 실패한 빌드 또는 린터 경고 수정
• Claude에 열린 GitHub 이슈를 루프하도록 요청하여 열린 이슈 분류 및 분류

이는 일상적인 작업을 자동화하면서 gh 명령줄 구문을 기억할 필요를 없앱니다.

h. Jupyter 노트북과 작업하기 위해 Claude 사용

Anthropic의 연구원과 데이터 과학자는 Claude Code를 사용하여 Jupyter 노트북을 읽고 씁니다. Claude는 이미지를 포함한 출력을 해석할 수 있으며, 데이터를 탐색하고 상호작용하는 빠른 방법을 제공합니다. 필요한 프롬프트나 워크플로우는 없지만, 우리가 권장하는 워크플로우는 VS Code에서 Claude Code와 .ipynb 파일을 나란히 열어두는 것입니다.

또한 동료에게 보여주기 전에 Claude에 Jupyter 노트북을 정리하거나 미적 개선을 만들도록 요청할 수 있습니다. 노트북이나 데이터 시각화를 "미적으로 즐겁게" 만들도록 구체적으로 지시하면 인간 시청 경험을 최적화하고 있다는 것을 상기시키는 데 도움이 되는 경향이 있습니다.

---

4. 워크플로우 최적화

다음 제안은 모든 워크플로우에 적용됩니다:

a. 지시사항을 구체적으로 작성

Claude Code의 성공률은 더 구체적인 지시사항으로 크게 향상되며, 특히 첫 번째 시도에서 그렇습니다. 명확한 방향을 앞서 제공하면 나중에 방향 수정의 필요성이 줄어듭니다.

예를 들어:

| 나쁨 | 좋음 |

|------|------|

| foo.py에 테스트 추가 | foo.py에 대한 새 테스트 케이스를 작성하세요. 사용자가 로그아웃된 엣지 케이스를 포함합니다. |

| 모의 방지 | ExecutionFactory의 api가 왜 그렇게 이상한가요? ExecutionFactory의 git 기록을 살펴보고 api가 어떻게 되었는지 요약하세요 |

| 캘린더 위젯 추가 | 홈 페이지의 기존 위젯이 구현되는 방식을 살펴보고 특히 코드와 인터페이스가 어떻게 분리되는지 이해하세요. HotDogWidget.php는 시작하기에 좋은 예입니다. 그런 다음 패턴을 따라 사용자가 월을 선택하고 연도를 선택하기 위해 앞뒤로 페이징할 수 있는 새 캘린더 위젯을 구현하세요. 코드베이스의 나머지 부분에서 이미 사용된 것 외에는 라이브러리 없이 처음부터 빌드하세요. |

Claude는 의도를 추론할 수 있지만 마음을 읽을 수는 없습니다. 구체성은 기대치와 더 나은 정렬로 이어집니다.

b. Claude에 이미지 제공

Claude는 여러 방법을 통해 이미지와 다이어그램에 뛰어납니다:

• 스크린샷 붙여넣기(팁: macOS에서 cmd+ctrl+shift+4를 눌러 클립보드에 스크린샷을 찍고 ctrl+v를 눌러 붙여넣습니다. Mac에서 일반적으로 사용하는 cmd+v가 아니며 원격으로 작동하지 않습니다)
• 이미지를 프롬프트 입력으로 직접 드래그 앤 드롭
• 이미지의 파일 경로 제공

이는 UI 개발을 위한 참조 지점으로 디자인 모크, 분석 및 디버깅을 위한 비주얼 차트로 작업할 때 특히 유용합니다.

컨텍스트에 비주얼을 추가하지 않는 경우에도 결과가 얼마나 시각적으로 매력적인지 Claude에게 명확하게 하는 것이 여전히 도움이 될 수 있습니다.

c. Claude가 살펴보거나 작업할 파일을 언급

탭 완성을 사용하여 저장소의 어느 곳에서든 파일이나 폴더를 빠르게 참조하여 Claude가 올바른 리소스를 찾거나 업데이트하도록 도와주세요.

d. Claude에 URL 제공

Claude가 가져와서 읽을 수 있도록 프롬프트와 함께 특정 URL을 붙여넣으세요. 동일한 도메인(예: docs.foo.com)에 대한 권한 프롬프트를 피하려면 /permissions를 사용하여 도메인을 허용 목록에 추가하세요.

e. 자주 그리고 조기에 수정

자동 수락 모드(shift+tab으로 토글)는 Claude가 자율적으로 작업할 수 있게 하지만, 적극적인 협력자가 되어 Claude의 접근 방식을 안내하면 더 나은 결과를 얻을 수 있습니다.

작업 시작에 Claude에게 철저하게 설명하여 최상의 결과를 얻을 수 있지만, 언제든지 Claude를 수정할 수도 있습니다. 이 네 가지 도구가 수정에 도움이 됩니다:

• 코딩하기 전에 Claude에 계획을 세우도록 요청합니다. 계획이 좋아 보일 때까지 코딩하지 않도록 명시적으로 지시하십시오.
• 아무 단계에서(생각, 도구 호출, 파일 편집) Escape를 눌러 Claude를 중단하여 컨텍스트를 보존하고 방향을 재지정하거나 지시사항을 확장할 수 있습니다.
• Escape를 두 번 누르면 기록으로 돌아가서 이전 프롬프트를 편집하고 다른 방향을 탐색할 수 있습니다. 원하는 결과를 얻을 때까지 프롬프트를 편집하고 반복할 수 있습니다.
• Claude에 변경 사항을 실행 취소하도록 요청합니다. 종종 옵션 #2와 함께 사용하여 다른 접근 방식을 취합니다.

Claude Code는 때때로 첫 번째 시도에서 완벽하게 문제를 해결하지만, 이러한 수정 도구를 사용하면 일반적으로 더 나은 해결책을 더 빨리 얻을 수 있습니다.

f. 컨텍스트를 집중 상태로 유지하기 위해 /clear 사용

긴 세션 동안 Claude의 컨텍스트 윈도우는 관련 없는 대화, 파일 내용, 명령어로 채워질 수 있습니다. 이는 성능을 저하시키고 때로는 Claude를 방해할 수 있습니다. 작업 간에 /clear 명령어를 자주 사용하여 컨텍스트 윈도우를 재설정하세요.

g. 복잡한 워크플로우에 체크리스트 및 스크래치패드 사용

여러 단계가 있거나 철저한 해결책이 필요한 큰 작업—예: 코드 마이그레이션, 수많은 lint 오류 수정, 복잡한 빌드 스크립트 실행—의 경우 Claude가 Markdown 파일(또는 GitHub 이슈조차도!)을 체크리스트와 작업 스크래치패드로 사용하도록 하여 성능을 향상시킬 수 있습니다.

예를 들어, 많은 수의 lint 문제를 수정하려면 다음을 수행할 수 있습니다:

1. Claude에 lint 명령어를 실행하고 결과 오류(파일 이름 및 줄 번호 포함)를 Markdown 체크리스트에 작성하도록 지시합니다

2. Claude에 각 문제를 하나씩 해결하고 다음으로 넘어가기 전에 수정하고 확인하도록 지시합니다

h. Claude에 데이터 전달

Claude에 데이터를 제공하는 여러 가지 방법이 있습니다:

• 프롬프트에 직접 복사 및 붙여넣기(가장 일반적인 접근 방식)
• Claude Code로 파이프(예: cat foo.txt | claude), 로그, CSV 및 대용량 데이터에 특히 유용
• Claude에 bash 명령어, MCP 도구 또는 사용자 정의 슬래시 명령어를 통해 데이터를 가져오도록 지시
• Claude에 파일을 읽거나 URL을 가져오도록 지시(이미지도 작동)

대부분의 세션은 이러한 접근 방식의 조합을 포함합니다. 예를 들어, 로그 파일을 파이프한 다음 Claude에 도구를 사용하여 로그를 디버깅하는 추가 컨텍스트를 가져오도록 지시할 수 있습니다.

---

5. 인프라를 자동화하기 위해 헤드리스 모드 사용

Claude Code는 CI, 사전 커밋 후크, 빌드 스크립트, 자동화와 같은 비대화형 컨텍스트를 위한 헤드리스 모드를 포함합니다. 프롬프트와 함께 -p 플래그를 사용하여 헤드리스 모드를 활성화하고 스트리밍 JSON 출력을 위해 --output-format stream-json을 사용합니다.

헤드리스 모드는 세션 간에 지속되지 않습니다. 매 세션마다 트리거해야 합니다.

a. 이슈 분류에 Claude 사용

헤드리스 모드는 GitHub 이벤트에 의해 트리거되는 자동화를 제공할 수 있습니다. 예를 들어, 공개 Claude Code 저장소는 Claude를 사용하여 들어오는 새 이슈를 검사하고 적절한 레이블을 할당합니다.

b. 린터로 Claude 사용

Claude Code는 전통적인 linting 도구가 감지하는 것을 넘어선 주관적인 코드 리뷰를 제공할 수 있습니다. 오타, 오래된 주석, 오해를 일으키는 함수 또는 변수 이름 등을 식별할 수 있습니다.

---

6. 다중 Claude 워크플로우로 수준 높이기

독립형 사용을 넘어, 가장 강력한 응용 프로그램 중 일부는 여러 Claude 인스턴스를 병렬로 실행하는 것을 포함합니다:

a. 한 Claude가 코드를 작성하게 하고 다른 Claude로 확인

단순하지만 효과적인 접근 방식은 한 Claude가 코드를 작성하는 동안 다른 Claude가 검토하거나 테스트하는 것입니다. 여러 엔지니어와 작업하는 것과 유사하게 때로는 별도의 컨텍스트를 갖는 것이 유익합니다:

1. Claude를 사용하여 코드 작성

2. /clear를 사용하거나 다른 터미널에서 두 번째 Claude 시작

3. 두 번째 Claude가 첫 번째 Claude의 작업을 검토하도록 함

4. 또 다른 Claude를 시작하거나 다시 /clear를 사용하여 코드와 검토 피드백을 모두 읽음

5. 이 Claude가 피드백을 기반으로 코드를 편집하도록 함

테스트로 비슷한 작업을 수행할 수 있습니다. 한 Claude에 테스트를 작성하게 한 다음 다른 Claude가 테스트를 통과하는 코드를 작성하게 할 수 있습니다.

별도의 작업 스크래치패드를 제공하고 어디에 쓰고 어디에서 읽어야 하는지 지시하여 Claude 인스턴스가 서로 통신하도록 할 수도 있습니다. 이러한 분리는 단일 Claude가 모든 것을 처리하는 것보다 종종 더 나은 결과를 산출합니다.

b. 저장소의 여러 체크아웃 사용

Claude가 각 단계를 완료할 때까지 기다리는 대신, 많은 Anthropic 엔지니어가 하는 것은:

1. 별도의 폴더에 3-4개의 git 체크아웃 생성

2. 각 폴더를 별도의 터미널 탭에서 열기

3. 각 폴더에서 다른 작업으로 Claude 시작

4. 진행 상황을 확인하고 권한 요청을 승인/거부하기 위해 순환

c. git worktrees 사용

이 접근 방식은 여러 독립 작업에 빛을 발하며 여러 체크아웃보다 가벼운 대안을 제공합니다. Git worktrees를 사용하면 동일한 저장소에서 여러 브랜치를 별도의 디렉토리로 체크아웃할 수 있습니다. 각 worktree는 고립된 파일이 있는 자체 작업 디렉토리를 가지며 동일한 Git 기록 및 reflog를 공유합니다.

git worktrees를 사용하면 프로젝트의 다른 부분에서 동시에 여러 Claude 세션을 실행할 수 있으며, 각각 자체 독립 작업에 집중할 수 있습니다. 예를 들어, 한 Claude는 인증 시스템을 리팩터링하는 동안 다른 Claude는 완전히 관련 없는 데이터 시각화 구성 요소를 구축할 수 있습니다. 작업이 겹치지 않으므로 각 Claude는 다른 Claude의 변경을 기다리거나 병합 충돌을 처리하지 않고 최고 속도로 작업할 수 있습니다:

1. worktrees 생성: git worktree add ../project-feature-a feature-a

2. 각 worktree에서 Claude 시작: cd ../project-feature-a && claude

3. 필요에 따라 추가 worktrees 생성(새 터미널 탭에서 단계 1-2 반복)

몇 가지 팁:

• 일관된 명명 규칙 사용
• worktree당 하나의 터미널 탭 유지
• Mac에서 iTerm2를 사용하는 경우 Claude에 주의가 필요할 때 알림 설정
• 다른 worktrees용 별도의 IDE 창 사용
• 완료되면 정리: git worktree remove ../project-feature-a`

d. 사용자 정식 하니스와 함께 헤드리스 모드 사용

claude -p(헤드리스 모드)는 Claude Code를 더 큰 워크… (생략됨)

• CLAUDE.md 파일을 프로젝트의 다양한 위치에 배치하여 프로젝트별 컨텍스트를 자동으로 제공하면 Claude의 이해도와 효율성을 크게 향상시킬 수 있습니다
• MCP 서버와 사용자 정의 슬래시 명령어를 활용하면 Claude의 기능을 확장하고 반복적인 워크플로우를 자동화할 수 있습니다
• 탐색-계획-구현-커밋 또는 테스트-코드-반복 워크플로우를 사용하면 복잡한 작업을 체계적으로 처리하고 코드 품질을 높일 수 있습니다
• 구체적인 지시사항, 이미지/URL 제공, 자주 수정(/clear 사용)은 Claude와의 협업 효율을 크게 높이는 핵심 전략입니다
• 다중 Claude 세션, git worktrees, 헤드리스 모드를 활용하면 병렬 작업과 자동화를 통해 개발 속도를 크게 높일 수 있습니다

Claude Code|클로드 코드|Anthropic이 개발한 명령줄 기반 에이전트 코딩 도구로, 개발자의 코딩 워크플로우에 Claude AI를 통합

MCP (Model Context Protocol)|모델 컨텍스트 프로토콜|Claude Code와 외부 도구/서비스 간의 통신을 위한 표준 프로토콜

Slash Command|슬래시 명령어|/로 시작하는 사용자 정의 명령어로, 반복적인 워크플로우를 자동화하고 재사용 가능한 프롬프트 템플릿 제공

Headless Mode|헤드리스 모드|CLI, CI/CD, 스크립트 등 비대화형 환경에서 Claude Code를 프로그래밍 방식으로 실행하는 모드

YOLO Mode|YOLO 모드|–dangerously-skip-permissions 플래그로 모든 권한 확인을 건너뛰고 Claude가 방해받지 않고 작업하는 모드(안전에 주의 필요)

Git Worktree|깃 워크트리|동일한 저장소에서 여러 브랜치를 별도의 디렉토리로 체크아웃하여 동시에 작업할 수 있는 Git 기능

TDD (Test-Driven Development)|테스트 주도 개발|먼저 테스트를 작성하고, 실패하는 테스트를 통과하는 코드를 구현하는 개발 방법론

GitHub CLI (gh)|깃허브 CLI|명령줄에서 GitHub와 상호작용할 수 있는 공식 도구

핵심 포인트

• CLAUDE.md 파일을 프로젝트의 다양한 위치에 배치하여 프로젝트별 컨텍스트를 자동으로 제공하면 Claude의 이해도와 효율성을 크게 향상시킬 수 있습니다
• MCP 서버와 사용자 정의 슬래시 명령어를 활용하면 Claude의 기능을 확장하고 반복적인 워크플로우를 자동화할 수 있습니다
• 탐색-계획-구현-커밋 또는 테스트-코드-반복 워크플로우를 사용하면 복잡한 작업을 체계적으로 처리하고 코드 품질을 높일 수 있습니다
• 구체적인 지시사항, 이미지/URL 제공, 자주 수정(/clear 사용)은 Claude와의 협업 효율을 크게 높이는 핵심 전략입니다
• 다중 Claude 세션, git worktrees, 헤드리스 모드를 활용하면 병렬 작업과 자동화를 통해 개발 속도를 크게 높일 수 있습니다

---

출처: Claude Code Best Practices \ Anthropic