Claude Code 모범 사례 가이드

요약

Anthropic은 엔지니어에게 에이전트 코딩을 위해 Claude에 대한 직접적인 액세스를 제공하는 저수준, 무정견 명령줄 도구인 Claude Code에 대한 모범 사례 가이드를 게시했습니다. 이 가이드는 환경 구성, 도구 확장, 검증된 워크플로 채택 방법을 설명하여 생산성과 안전성을 높입니다.

1. 설정 맞춤화

1a. `CLAUDE.md` 파일 생성

CLAUDE.md는 Claude의 프롬프트 컨텍스트에 자동으로 로드됩니다. 이를 사용하여 일반적인 명령, 유틸리티 함수, 코드 스타일 지침, 테스트 지침, 저장소 에티켓, 환경 설정 및 프로젝트별 특이 사항을 문서화하세요. 파일을 저장소 루트, 모노레포의 상위 또는 하위 디렉터리, 또는 전역 기본값을 위해 ~/.claude/에 배치하세요. /init 명령으로 시작 파일을 생성할 수 있습니다.

1b. `CLAUDE.md` 콘텐츠 조정

CLAUDE.md를 자주 사용하는 프롬프트처럼 취급하세요: 문구를 반복해서 다듬고, 간결하게 유지하며, 중요한 지침을 강조하세요(예: "중요" 또는 "반드시" 사용). # 키를 사용하여 Claude가 문서를 자동으로 추가하게 하고, 더 높은 준수를 위해 Anthropic의 프롬프트 개선 도구를 통해 파일을 실행하는 것을 고려하세요.

1c. 허용 도구 목록 선별

Claude Code는 시스템을 수정하는 모든 작업에 대해 보수적으로 권한을 요청합니다. 다음을 통해 도구를 허용 목록에 추가할 수 있습니다:

세션 중 항상 허용 선택.
/permissions 명령 실행(예: Edit, Bash(git commit:*)).
.claude/settings.json 또는 ~/.claude.json 편집(전자를 소스 제어에 포함).
일회성 세션을 위해 --allowedTools CLI 플래그 사용.

1d. GitHub CLI(`gh`) 설치

gh가 설치되면 Claude가 이슈를 생성하고, PR을 열고, 댓글을 직접 읽을 수 있습니다. 설치되지 않으면 Claude는 GitHub API 또는 MCP 서버로 대체합니다.

2. Claude에 더 많은 도구 제공

2a. bash 유틸리티 활용

Claude는 셸 환경을 상속합니다. 사용자 정의 스크립트를 노출하려면 도구 이름과 사용법을 설명하고, Claude에게 --help를 실행하도록 요청하고, CLAUDE.md에 도구를 문서화하세요.

2b. MCP 서버 연결

Claude Code는 MCP 클라이언트와 서버 역할을 모두 수행합니다. 프로젝트 수준 구성, 전역 구성 또는 체크인된 .mcp.json에 도구를 등록하세요. 구성 문제를 해결하려면 --mcp-debug를 사용하세요.

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

재사용 가능한 프롬프트 템플릿을 .claude/commands/*.md에 저장하세요. / 메뉴에 표시되며 $ARGUMENTS 자리 표시자를 통해 인수를 받을 수 있습니다. 팀과 공유하려면 이러한 파일을 커밋하세요.

3. 검증된 워크플로

3a. 탐색 → 계획 → 코드 → 커밋

코드를 작성하지 않고 관련 파일 또는 URL을 읽습니다.
더 많은 계산 예산을 할당하기 위해 "생각" 계층 구조(think, think hard, think harder, ultrathink)를 사용하여 계획합니다.
추론을 확인하도록 Claude에게 요청하면서 솔루션을 구현합니다.
커밋하고 선택적으로 PR을 생성하거나 문서를 업데이트합니다.

3b. 테스트 주도 개발(TDD)

Claude에게 실패하는 테스트를 작성하도록 프롬프트합니다.
테스트를 실행하고 실패를 확인합니다.
테스트를 커밋합니다.
Claude에게 테스트를 통과하는 코드를 작성하도록 지시하고 모두 통과할 때까지 반복합니다.

3c. 스크린샷을 사용한 시각적 반복

붙여넣은 스크린샷, 끌어서 놓기 또는 파일 경로를 통해 디자인 목업을 제공하세요. Claude에게 UI 구현, 결과 스크린샷 캡처, 목업이 일치할 때까지 반복하도록 요청하세요.

3d. 안전한 "YOLO" 모드

빠르고 위험이 낮은 작업(예: 린트 수정)을 위해 권한 확인을 건너뛰려면 claude --dangerously-skip-permissions를 사용하세요. 데이터 손실 위험을 완화하려면 격리되고 인터넷이 차단된 컨테이너에서 실행하세요.

3e. 코드베이스 Q&A

Claude를 페어 프로그래머로 취급하세요: "로깅은 어떻게 작동하나요?" 또는 "foo.rs의 134행에서 async move { … }는 무엇을 하나요?"와 같은 질문을 하세요. Claude는 특별한 프롬프트 없이 저장소를 검색하고 답변합니다.

3f. Git 상호 작용

Claude는 다음을 수행할 수 있습니다:

변경 사항 또는 소유권에 대한 git 기록 검색.
diff 기반 커밋 메시지 초안 작성.
복잡한 git 작업(되돌리기, 리베이스, 패치 접목) 수행.

3g. GitHub 자동화

Claude는 풀 리퀘스트 생성을 위한 "pr"과 같은 약어를 이해하고, 리뷰 댓글을 수정하고, 이슈를 분류하고, 자동으로 레이블을 지정할 수 있습니다.

3h. Jupyter 노트북 지원

Claude는 .ipynb 파일을 읽고/쓸 수 있고, 출력 이미지를 해석하며, 지시를 받으면 노트북 미적 요소를 개선할 수 있습니다.

4. 워크플로 최적화

4a. 구체적으로 말하세요

명확하고 상세한 지침은 첫 시도에서 Claude의 성공률을 크게 향상시킵니다.

4b. 이미지 제공

스크린샷, 다이어그램 또는 디자인 목업을 붙여넣거나 끌어서 놓으세요; Claude는 이를 직접 처리합니다.

4c. 대상 파일 언급

탭 완성을 사용하여 정확한 파일 경로를 참조하고 Claude가 올바른 리소스에서 작업하도록 보장하세요.

4d. URL 제공

Claude가 가져올 URL을 붙여넣으세요; 반복적인 프롬프트를 피하려면 /permissions를 통해 도메인을 허용 목록에 추가하세요.

4e. 초기에 자주 방향 수정

Claude에게 코딩 전에 계획하도록 요청하세요.
Escape를 눌러 중단하고 컨텍스트를 유지하세요.
Escape를 두 번 눌러 이전 프롬프트를 편집하세요.
실행 취소를 사용하여 원치 않는 변경 사항을 되돌리세요.

4f. `/clear`로 컨텍스트 지우기

긴 세션 중에 주기적으로 컨텍스트 창을 재설정하여 Claude가 집중하도록 유지하세요.

4g. 체크리스트와 스크래치패드 사용

크고 다단계 작업의 경우 Markdown 체크리스트 또는 GitHub 이슈를 공유 스크래치패드로 유지하고 Claude가 완료된 항목을 체크하도록 하세요.

4h. 데이터를 효율적으로 전달

복사-붙여넣기, 파이핑(cat foo.txt | claude), bash 명령, MCP 도구 또는 파일 읽기를 결합하여 로그, CSV 또는 기타 데이터를 Claude에 공급하세요.

5. 자동화를 위한 헤드리스 모드

CI, 사전 커밋 훅 또는 기타 스크립트를 위해 -p "<프롬프트>" --output-format stream-json으로 Claude를 비대화식으로 실행하세요.

5a. 이슈 분류 자동화

공개 Claude Code 저장소에서 시연된 대로 GitHub Actions를 통해 Claude를 트리거하여 새 이슈에 레이블을 지정하세요.

5b. 주관적 린팅

정적 린터 이상의 미묘한 코드 리뷰 댓글을 제공하기 위해 GitHub Action에서 Claude를 사용하세요.

6. 다중 Claude 워크플로

6a. 병렬 검증

하나의 Claude 인스턴스를 실행하여 코드를 생성하고 두 번째를 실행하여 검토하거나 테스트한 다음 첫 번째에 피드백을 다시 제공하세요.

6b. 여러 체크아웃

별도의 git 체크아웃(또는 작업 트리)을 생성하고 각각에서 독립적인 Claude 세션을 실행하여 병렬 작업 실행을 허용하세요.

6c. 경량 병렬 처리를 위한 Git 작업 트리

작업 트리를 생성하고(git worktree add …) 각 디렉터리에서 Claude를 시작하여 기록을 공유하면서 작업을 격리하세요.

6d. 헤드리스 파이프라인

팬아웃: 작업 목록을 생성한 다음 각 항목에 대해 --allowedTools로 Claude를 호출하여 항목을 반복합니다.
파이프라이닝: 추가 처리를 위해 Claude의 JSON 출력을 다운스트림 명령으로 파이프하세요.

"Claude Code는 의도적으로 저수준이고 무정견이며, 특정 워크플로를 강요하지 않고 원시 모델 액세스에 가깝게 제공합니다." — Anthropic

결론: CLAUDE.md 구성, 도구 권한 선별, MCP 및 사용자 정의 슬래시 명령으로 Claude 확장, 계획 우선 코딩 또는 테스트 주도 개발과 같은 검증된 워크플로를 따르면 엔지니어는 Claude Code를 안전하고 유연하며 생산성 높은 에이전트 코딩 어시스턴트로 활용할 수 있습니다.