Claude Code: 에이전트 코딩을 위한 모범 사례

20 hours ago 1

Claude Code는 CLI 기반의 에이전틱 코딩 도구로, 다양한 개발 환경과 언어에 유연하게 적용 가능함
CLAUDE.md 설정, 도구 허용 목록 관리, 사용자 정의 명령어 생성을 통해 Claude 사용성을 극대화할 수 있음
워크플로우별 전략(탐색-계획-구현-커밋, 테스트 기반 개발, 시각적 반복 등)을 적용하면 효과적임
헤드리스 모드와 멀티 Claude 구성으로 자동화와 병렬작업도 가능함
Claude를 Git, GitHub, Jupyter 등 다양한 개발 도구와 통합하여 고급 활용이 가능함

Claude Code 개요

Claude Code는 에이전틱 코딩(command line 기반 자동화 코딩) 을 위한 도구임
Anthropic의 내부 개발자와 연구자들이 Claude를 보다 자연스럽게 코딩에 통합할 수 있도록 설계됨
로우레벨 인터페이스와 비의존적 설계 덕분에 특정 개발 방식에 얽매이지 않으며,
- 개발자는 자신에게 맞는 방식으로 Claude를 구성하고 활용 가능함
결과적으로 매우 강력하면서도 유연하고 안전한 코딩 파워 도구로 자리매김함
단점으로는 초기 사용자에게는 높은 학습 곡선이 존재하며,
- 이로 인해 자체적인 베스트 프랙티스를 만들어가는 과정이 필요함
이 글은 Claude Code를 실제로 사용해본 내부 팀과 외부 엔지니어들의 경험을 바탕으로,
- 여러 언어, 코드베이스, 환경에서 효과적인 일반적인 패턴을 소개함
제시된 내용은 정답이 아닌 출발점으로, 각자에게 맞는 방식으로 실험하고 개선하는 것을 권장함

# 1. 설정 커스터마이징

Claude Code는 자동으로 문맥을 수집하여 프롬프트를 구성하는 에이전틱 코딩 도우미임
이 문맥 수집은 시간과 토큰을 소모하지만, 환경을 조정하여 최적화할 수 있음

a. CLAUDE.md 파일 생성

CLAUDE.md는 Claude가 대화를 시작할 때 자동으로 문맥에 포함시키는 특수 파일임
이 파일은 다음 항목을 문서화하는 데 이상적임:

자주 사용하는 bash 명령어
핵심 파일 및 유틸리티 함수
코드 스타일 가이드라인
테스트 실행 방법
저장소 작업 방식 (예: 브랜치 네이밍, merge vs. rebase)
개발 환경 설정법 (예: pyenv 사용 여부, 호환되는 컴파일러)
해당 프로젝트의 예외 동작이나 경고 사항
Claude가 기억해야 할 기타 정보

CLAUDE.md 파일은 형식에 제한이 없으며, 간결하고 사람이 읽기 쉬운 형태로 작성할 것을 권장함
예시:

# Bash commands - npm run build: Build the project - npm run typecheck: Run the typechecker # 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 파일 위치

Claude는 다음 위치에서 CLAUDE.md를 탐색하여 문맥에 포함함:

레포 루트 또는 claude를 실행한 디렉토리
- CLAUDE.md로 저장하여 git에 체크인하면 세션 간 및 팀 간 공유 가능 (권장)
- 개인 설정용으로는 CLAUDE.local.md로 저장 후 .gitignore 처리 가능
실행 디렉토리의 상위 디렉토리
- 모노레포 구조에서 유용 (예: root/CLAUDE.md와 root/foo/CLAUDE.md 둘 다 사용 가능)
실행 디렉토리의 하위 디렉토리
- 해당 디렉토리 내 파일을 작업할 때 자동으로 문맥에 포함
홈 디렉토리(~/.claude/CLAUDE.md)
- 모든 세션에 글로벌 적용

/init 명령어 실행 시 Claude가 CLAUDE.md 파일을 자동 생성해줌

b. CLAUDE.md 파일 튜닝

CLAUDE.md는 Claude 프롬프트의 일부로 사용되므로, 프롬프트처럼 반복적으로 다듬고 최적화해야 함
흔한 실수는 내용을 너무 많이 넣고 효과를 검증하지 않는 것임

어떤 내용이 모델의 응답 성능을 높이는지 실험을 통해 파악하는 것이 중요함
수동으로 내용을 추가할 수도 있고, # 키를 눌러 Claude에게 지시하여 자동으로 CLAUDE.md에 반영하도록 할 수도 있음
많은 엔지니어가 실시간으로 명령어, 스타일 가이드 등을 문서화하며, CLAUDE.md의 변경 사항을 커밋에 포함하여 팀과 공유함

Anthropic에서는 프롬프트 개선기(prompt improver) 를 통해 CLAUDE.md를 정제하고
“IMPORTANT”, “YOU MUST”와 같은 강조 문구를 추가하여 응답 정확도를 높임

c. Claude의 허용 도구 리스트 관리

Claude Code는 시스템을 변경할 수 있는 작업(파일 쓰기, bash 명령어 실행, MCP 도구 사용 등)에 대해 기본적으로 사용자 승인 요청을 함
이는 보안을 위한 보수적 설계이며, 사용자가 안전하다고 판단되는 도구는 허용 목록(allowlist) 을 통해 사전 승인 가능함

허용 도구 설정 방법

세션 중 프롬프트가 떴을 때 "Always allow" 선택
/allowed-tools 명령어로 도구 추가/삭제
예시:
- Edit → 파일 편집 허용
- Bash(git commit:*) → git 커밋 허용
- mcp__puppeteer__puppeteer_navigate → Puppeteer MCP 서버 내비게이션 허용
.claude/settings.json 또는 ~/.claude.json을 수동으로 편집
- 팀과 공유하려면 전자를 사용해 Git에 체크인 추천
세션별 CLI 플래그인 --allowedTools 사용

d. GitHub 사용 시 gh CLI 설치

Claude는 gh CLI를 사용할 수 있어, 이슈 생성, PR 작성, 코멘트 읽기 등 GitHub 작업을 자동화함
gh를 설치하지 않아도 GitHub API 또는 MCP 서버를 통해 대체 가능함

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

Claude는 사용자의 쉘 환경에 접근 가능하므로, 사용자가 직접 만든 스크립트와 함수들을 그대로 사용할 수 있음
또한 MCP나 REST API를 통해 보다 복잡한 외부 도구들과도 연동 가능

a. Bash 도구와 함께 사용

Claude Code는 사용자의 bash 환경을 상속받아 이미 설치된 유틸리티 도구들에 접근 가능함

일반적인 유닉스 도구나 gh CLI는 Claude가 이미 알고 있음
하지만 사용자가 만든 커스텀 bash 도구는 별도로 알려줘야 함

Claude가 커스텀 도구를 인식하려면 다음 작업을 수행:

도구 이름과 사용 예시를 Claude에게 명시
--help 옵션으로 도구 사용법을 보도록 지시
자주 사용하는 도구들을 CLAUDE.md에 문서화

b. MCP와 함께 사용

Claude Code는 MCP 서버이자 클라이언트 역할을 동시에 수행함
클라이언트로서 여러 MCP 서버에 연결해 다양한 도구를 활용할 수 있음

세 가지 방식으로 MCP 서버 도구를 Claude에 연결 가능:

프로젝트 설정 내 정의 (해당 디렉토리에서만 사용 가능)
글로벌 설정을 통해 모든 프로젝트에서 사용 가능
.mcp.json 파일에 체크인하여 협업 중인 모든 개발자가 도구를 즉시 사용 가능
- 예: .mcp.json에 Puppeteer, Sentry 서버 등록 시 팀 전체 사용 가능

MCP 사용 중 설정 문제를 디버깅하려면 --mcp-debug 플래그로 Claude를 실행하는 것이 유용함

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

반복되는 워크플로우(디버깅, 로그 분석 등)를 위해
.claude/commands 폴더에 프롬프트 템플릿을 Markdown 파일로 저장 가능

Claude에서 / 입력 시 자동 완성 메뉴에 해당 명령어가 표시됨
git에 커밋하여 팀원들과 공유 가능

매개변수 전달: $ARGUMENTS

슬래시 명령어에 $ARGUMENTS를 포함하면 명령어 실행 시 전달된 파라미터를 자동 삽입 가능

예시: GitHub 이슈 자동 분석 및 수정

Please analyze and fix the GitHub issue: $ARGUMENTS. Follow these steps: 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 Remember to use the GitHub CLI (`gh`) for all GitHub-related tasks.

위 내용을 .claude/commands/fix-github-issue.md에 저장하면, /project:fix-github-issue 명령어로 사용할 수 있음
예: /project:fix-github-issue 1234 → Claude가 #1234 이슈 자동 수정 시도

개인 설정 명령어는 ~/.claude/commands 폴더에 저장하면 모든 세션에서 사용 가능함

# 3. 일반적인 워크플로우 활용하기

Claude Code는 특정 워크플로우를 강제하지 않으며, 사용자에게 완전한 유연성을 제공함
이러한 유연성을 기반으로, 사용자 커뮤니티에서 성공적으로 자리 잡은 다양한 사용 패턴이 있음

a. 탐색 → 계획 → 구현 → 커밋

Claude에게 관련 파일, 이미지, URL을 읽어보도록 요청
- 예: “로그 처리하는 파일 읽어줘”, “logging.py 읽어줘”
- 단, 코딩은 하지 말라고 명확히 지시
- 이 단계에서 서브에이전트(subagents) 활용이 매우 효과적임 (복잡한 문제일수록 더욱 유리)
Claude에게 문제 해결을 위한 계획 수립 요청
- “think”, “think hard”, “ultrathink” 등의 키워드 사용 시 더 많은 연산 예산을 할당받음
- 계획이 타당하면 계획 내용을 문서로 정리하거나 GitHub 이슈로 생성해 되돌아갈 기준점 확보
이후 Claude에게 계획한 방식으로 코드 구현 요청
- 구현 중에도 스스로 결과의 타당성을 검증하도록 명시적으로 요청 가능
마지막으로 결과 커밋 및 PR 생성 지시
- 필요 시 README나 CHANGELOG 업데이트 요청도 함께 수행

📌 이 흐름에서 1~2단계를 생략하면 Claude가 곧바로 코딩에 들어가므로, 특히 복잡한 문제일수록 계획 단계가 중요함

b. 테스트 작성 → 커밋 → 코드 작성 → 반복 → 커밋 (테스트 주도 개발)

Anthropic 내부에서 자주 사용하는 방식으로, 단위/통합/e2e 테스트가 있는 작업에 적합함

Claude에게 입력/출력 기준으로 테스트 작성 요청
- 테스트 주도 개발임을 명확히 전달 → 기능 구현 없이 테스트만 작성하도록 유도
테스트가 실패하는지 확인 요청
- 구현은 하지 말고 테스트만 실행하도록 지시
테스트에 만족하면 커밋
Claude에게 테스트를 통과하는 코드 작성 요청
- 테스트는 수정하지 말라고 명시
- 보통 여러 차례 반복 실행을 거쳐 테스트를 통과하게 됨
- 서브에이전트를 사용해 과적합 여부를 검증하는 것도 효과적
모든 테스트가 통과되면 코드 커밋 지시

✅ Claude는 **명확한 타겟(예: 테스트 케이스, 이미지 등)**이 있을 때 가장 잘 작동함

c. 코드 작성 → 결과 스크린샷 제공 → 반복 개선

브라우저 스크린샷을 자동으로 제공할 수 있는 환경 구축 (예: Puppeteer MCP, iOS 시뮬레이터 등)
시각적 목업(mock) 제공 (이미지 붙여넣기, 경로 전달 등)
Claude에게 디자인 구현 요청 → 결과 스크린샷 → 다시 비교 및 개선 지시
만족할 경우 커밋

💡 Claude도 사람처럼 2~3번 반복 시 결과가 훨씬 좋아짐 → 시각 피드백 루프가 중요

d. Safe YOLO 모드

--dangerously-skip-permissions 옵션으로 모든 승인 요청 생략
Claude가 사용자 승인 없이 완전 자동으로 작업을 수행함

⚠️ 데이터 손실, 시스템 손상, 프롬프트 인젝션 위험 존재 → 인터넷 차단된 컨테이너에서만 실행 권장
→ 예시 구현은 Docker Dev Container 기반 사용을 추천

e. 코드베이스 Q&A

새로운 프로젝트에 적응할 때 동료 엔지니어에게 물어보듯 Claude에게 질문 가능
Claude는 코드베이스를 탐색해 스스로 답을 찾음

예시 질문:

로깅은 어떻게 작동해?
새 API 엔드포인트는 어떻게 만들지?
foo.rs의 134번 줄 async move는 무슨 역할이야?
CustomerOnboardingFlowImpl은 어떤 엣지 케이스를 다루지?
왜 foo() 대신 bar()를 호출해?
baz.py 334번 줄과 비슷한 자바 코드는 뭐야?

📌 별도 프롬프트 없이 자연어 질문만으로 탐색 가능
→ Anthropic에서는 이 방식을 주요 온보딩 도구로 활용 중

f. Git 연동

Claude는 다음과 같은 Git 작업 자동화를 잘 수행함:

Git 히스토리 검색:
- 예: "v1.2.3에서 어떤 변경사항이 포함됐어?", "이 기능 누가 만들었어?", "이 API는 왜 이런 구조야?"
커밋 메시지 작성:
- 변경사항과 주변 컨텍스트를 기반으로 자동 구성
고급 Git 작업:
- 파일 되돌리기, 리베이스 충돌 해결, 패치 비교 및 병합 등

g. GitHub 연동

Claude Code는 GitHub 관련 작업을 대폭 자동화할 수 있음:

Pull Request 생성:
- pr 라는 키워드를 인식하며, 변경 사항 기반으로 자동 커밋 메시지 생성
코드 리뷰 코멘트 수정:
- "PR에 달린 코멘트 고쳐줘"만으로 수정 후 푸시 가능
빌드 실패, 린트 에러 수정
이슈 분류 및 정리:
- Claude에게 “열려있는 이슈들 돌면서 정리해줘”라고 요청

💡 gh 명령어 기억할 필요 없이 자동화된 GitHub 작업 가능

h. Jupyter Notebook 작업

Claude는 .ipynb 파일을 읽고 쓰며, 이미지 포함 출력 해석까지 가능함
VS Code에서 Claude Code와 노트북 파일을 나란히 열어 활용하는 방식 추천

추가 기능:

다른 사람에게 공유 전 노트북 정리 및 시각적 개선 요청 가능
- “보기 좋게 정리해줘”, “시각화 예쁘게 바꿔줘” 등 인간 중심 뷰 최적화 요청이 잘 작동함

# 4. 워크플로우 최적화

아래 제안들은 모든 워크플로우에 공통적으로 적용 가능한 최적화 방법임

a. 지시어는 구체적으로 작성

Claude Code는 첫 시도일수록 지시가 구체적일수록 성공률이 높아짐
처음부터 명확하게 요청하면 중간 수정의 필요성이 줄어듦

예시 비교

❌ add tests for foo.py → 너무 포괄적
✅ foo.py에 대해, 로그아웃된 사용자 케이스를 다루는 새로운 테스트 케이스 작성. mock은 사용하지 말 것
❌ why does ExecutionFactory have such a weird api? → 모호함
✅ ExecutionFactory의 git 히스토리를 추적해서, API가 현재 구조로 만들어진 이유를 요약해줘
❌ add a calendar widget → 구현 방향 불분명
✅ 홈페이지에 있는 기존 위젯 구현 방식을 분석해 (예: HotDogWidget.php) 코드와 인터페이스 분리 패턴을 파악한 뒤, 사용자가 월 선택 및 연도 페이지 전환이 가능한 새 달력 위젯을 동일한 방식으로 구현해줘. 외부 라이브러리는 기존 프로젝트에서 이미 사용하는 것만 허용

Claude는 의도를 유추할 수는 있지만, 생각을 읽을 수는 없음 → 명확함이 핵심

b. 이미지 제공

Claude는 이미지나 다이어그램 처리에 뛰어남
다음 방법으로 이미지 제공 가능:

macOS에서 cmd+ctrl+shift+4 → 클립보드로 스크린샷 → ctrl+v 붙여넣기 (원격 환경에서는 불가)
이미지 파일 드래그 앤 드롭
이미지 파일 경로 전달

디자인 목업 구현, 시각적 차트 분석 등 UI/데이터 시각화에 매우 유용
비주얼이 없는 경우에도, 결과의 시각적 품질이 중요한지 명확히 전달하는 것이 도움됨

c. 작업할 파일 지정

Claude에게 어떤 파일을 참고하거나 수정할지를 명확히 알려주면 작업 정확도 향상

Tab 키 자동완성으로 파일/폴더 경로 빠르게 입력 가능

d. Claude에게 URL 제공

Claude에게 URL을 주면 문서나 웹페이지를 직접 읽어올 수 있음

예: API 문서 링크, 디자인 시스템 페이지 등
같은 도메인 반복 접근을 위해선 /allowed-tools 명령어로 도메인을 화이트리스트에 추가하면 승인 생략 가능

e. 빠르고 자주 방향 수정 (코스 리디렉션)

Shift + Tab을 눌러 자동 승인 모드(auto-accept mode) 로 작업을 자동화할 수 있으나,
보통은 Claude와 적극 협업하며 방향을 조정하는 것이 더 나은 결과를 유도함

유용한 조정 도구 4가지:

계획 먼저 요청: 구현 전에 반드시 계획을 세우도록 하고, 확인 후 진행
Escape 키로 즉시 중단: 언제든지 생각, 파일 편집 등 도중에 중단 가능
Escape 두 번 눌러 이전 프롬프트 편집: 이전 명령어를 수정하고 새로운 방향으로 전환 가능
변경사항 되돌리기 요청: Claude에게 수정한 내용을 롤백해 다른 접근 방식 시도 가능

Claude가 한 번에 완벽하게 해결할 때도 있지만, 위 도구들을 활용하면 더 빠르고 정확한 결과 도출 가능

f. /clear 명령어로 맥락 초기화

긴 세션이 지속되면 Claude의 문맥 창(context window) 이 필요 없는 정보로 채워져 성능 저하 가능성 있음
→ 작업 단위마다 /clear로 문맥을 초기화하는 습관 추천

g. 체크리스트 및 스크래치패드 활용

복잡한 작업(예: 코드 마이그레이션, 린트 오류 대량 수정 등)의 경우,
Markdown 파일이나 GitHub 이슈를 체크리스트로 사용하면 효율 향상

예: 린트 오류 해결

Claude에게 lint 명령어 실행 요청 → 에러 내용을 Markdown 형식 체크리스트로 정리
각 항목을 하나씩 처리하며 확인 후 체크 → 다음 항목으로 진행

이 방식을 통해 진행 상황 추적과 품질 관리 동시 수행 가능

h. Claude에게 데이터 전달하기

Claude에 데이터를 전달하는 여러 방법 존재:

복사/붙여넣기 (가장 일반적인 방법)
파이프 입력 (예: cat foo.txt | claude)
- 로그, CSV, 대용량 텍스트에 적합
bash 명령어나 MCP 도구, 슬래시 명령어를 통해 직접 가져오게 지시
파일 또는 URL 읽기 요청 (이미지 포함)

실제 작업에서는 여러 방식의 혼합 사용이 일반적
예: 로그를 파이프로 전달하고, Claude에게 MCP 도구를 사용해 추가 맥락을 가져오도록 요청

# 5. 헤드리스 모드로 인프라 자동화하기

Claude Code는 비인터랙티브 환경(CI, pre-commit 훅, 빌드 스크립트, 자동화 등)을 위한 헤드리스 모드를 지원함

-p 플래그를 통해 프롬프트와 함께 헤드리스 모드 실행
--output-format stream-json 옵션으로 스트리밍 JSON 출력 사용 가능

⚠️ 헤드리스 모드는 세션 간 지속되지 않으며, 매번 직접 실행해야 함

a. Claude로 이슈 자동 분류

헤드리스 모드는 GitHub 이벤트 기반 자동화 트리거에 적합함
예: 새로운 이슈가 생성될 때 자동 분석 및 라벨 분류

실제로 Claude Code의 공개 저장소에서도 이 기능을 사용해 새 이슈에 자동으로 라벨을 붙이는 기능 구현

b. Claude를 린터로 사용

Claude는 전통적인 린트 도구로는 감지하기 어려운 주관적 코드 리뷰를 자동화할 수 있음
예:

오탈자
오래된 주석
오해의 소지가 있는 함수/변수명
비직관적인 코드 흐름 등

이를 통해 정적 분석 도구 이상의 코드 품질 개선이 가능함

# 6. 멀티 Claude 워크플로우로 레벨업하기

단일 Claude 사용을 넘어서, 여러 Claude 인스턴스를 병렬로 실행하는 방식은 매우 강력한 활용법임
여러 엔지니어가 협업하듯, Claude를 분업시키는 전략은 효율성과 품질을 모두 향상시킬 수 있음

a. 한 Claude가 코드 작성, 다른 Claude가 검토

가장 간단하면서도 효과적인 패턴:

Claude 1: 코드 작성
/clear 또는 다른 터미널에서 Claude 2 실행 → 작성된 코드 리뷰
Claude 3 실행 또는 다시 /clear → 코드와 리뷰를 모두 읽고 수정 반영

또는,

Claude 1: 테스트 작성
Claude 2: 테스트를 통과하는 코드 작성

❗ Claude 인스턴스끼리 서로 별도의 scratchpad를 공유하거나
“이 Claude는 A 파일에만 기록, 저 Claude는 B만 읽기” 식으로 역할 분리 설정도 가능

📌 단일 Claude보다 작업 분리가 더 나은 결과를 제공하는 경우가 많음

b. 저장소를 여러 개 체크아웃하기

Claude가 작업을 완료하길 기다리는 대신, 여러 Git 체크아웃 디렉토리를 생성하여 병렬 작업 가능

3~4개의 git checkout을 별도 폴더에 생성
각 폴더를 다른 터미널 탭에서 열기
각 Claude 인스턴스에 서로 다른 작업 할당
탭을 전환하며 진행 상황 확인 및 승인/거절 수행

c. Git worktree 활용

git worktree는 여러 브랜치를 하나의 레포에서 서로 다른 디렉토리에 체크아웃하는 Git 기능임
→ 복수의 독립 작업을 병렬로 처리하기에 이상적

예:

하나의 Claude가 인증 시스템을 리팩토링
다른 Claude는 별개로 데이터 시각화 컴포넌트 생성
서로 간섭 없음 → 병렬성 극대화

사용법

워크트리 생성:
git worktree add ../project-feature-a feature-a
Claude 실행:
cd ../project-feature-a && claude
필요한 만큼 반복

팁

워크트리 이름은 일관성 있게
터미널 탭 하나당 워크트리 하나 유지
iTerm2 (Mac) 사용자라면 알림 설정 추천
IDE도 각 워크트리에 맞게 분리
작업 완료 후 정리:
git worktree remove ../project-feature-a

d. 헤드리스 모드 + 커스텀 자동화 구조체

헤드리스 모드(claude -p)는 Claude Code를 프로그래밍 방식으로 워크플로우에 통합 가능하게 함
여기에 Claude 자체 도구와 시스템 프롬프트를 결합해 다음 두 패턴 활용 가능

1. Fanning out: 대규모 마이그레이션/분석 작업 분산 처리

예시:

Claude에게 작업 목록 생성 스크립트 작성 요청
→ 예: React에서 Vue로 마이그레이션할 2,000개 파일 리스트 생성
각 작업마다 claude -p로 실행
→ 예:
claude -p "migrate foo.py from React to Vue. When done, return OK or FAIL." --allowedTools Edit Bash(git commit:*)
프롬프트를 여러 번 개선하며 성능 최적화