Anthropic의 엔지니어, 연구자 그리고 외부 개발자들이 Claude Code를 효과적으로 사용하는 방법과 워크플로우, 도구 통합, 환경 최적화, Headless 모드 자동화 등 탄탄한 실무 경험에 기반한 모범 사례를 제공합니다.
최근에 Claude Code를 출시했습니다. 이 커맨드라인 도구는 에이전트 기반 코딩을 위한 것으로, Anthropic 내부 엔지니어와 연구진들에게 Claude를 코딩 워크플로우에 더 자연스럽게 통합할 방법을 제공합니다.
Claude Code는 의도적으로 저수준이고 비의견적(opinionated하지 않은) 설계로, 특정 워크플로우를 강제하지 않으면서 거의 원형 모델 접근성을 제공합니다. 이 ‘파워 도구’의 설계 철학은 유연함, 맞춤화, 스크립트화 및 안전성을 중시합니다. 단점은 초보자에게는 다소 학습 곡선이 있을 수 있다는 것 – 하지만 자신의 베스트 프랙티스를 개발하면 금세 적응하게 됩니다.
이 문서는 Anthropic 내부팀뿐만 아니라 다양한 코드베이스, 언어, 환경에서 Claude Code를 사용하는 외부 엔지니어들에게도 효과가 입증된 일반적인 패턴을 소개합니다. 100% 보편적·불변인 원칙은 없습니다. 이 글의 제안들을 ‘출발점’으로 삼아 각자 실험해보고 자신에게 가장 잘 맞는 방법을 찾아보시기 바랍니다.
더 자세한 내용이 필요하신가요? claude.ai/code 공식 문서 에는 이 글에 언급된 모든 기능, 예시, 구현 세부 및 심화 기법이 수록되어 있습니다.
Claude Code는 컨텍스트를 자동으로 프롬프트로 끌어오는 에이전트형 코딩 어시스턴트입니다. 이 컨텍스트 수집은 시간과 토큰을 소모하지만, 환경 튜닝을 통해 최적화할 수 있습니다.
CLAUDE.md 파일 활용하기CLAUDE.md는 대화 시작 시 Claude가 자동 컨텍스트로 불러오는 특수 파일입니다. 여기에 다음과 같은 정보를 기록하세요:
포맷은 무관하지만 짧고 사람이 읽기 쉽게 유지하는 것을 추천합니다. 예:
# Bash 명령어
- npm run build: 프로젝트 빌드
- npm run typecheck: 타입체크 실행
# 코드 스타일
- ES module(import/export) 문법 사용, CommonJS(require) 사용 X
- import 시 구조분해 할당(ex. import { foo } from 'bar')
# 워크플로우
- 코드 수정 후 타입체크 필수
- 전체 테스트 스위트 대신 단일 테스트 우선 실행
최적 위치는 다음과 같습니다:
CLAUDE.md로 이름 지어 git에 커밋해 공유하세요(권장). 개별 환경용은 CLAUDE.local.md로 저장하고 .gitignore에 추가하세요.root/CLAUDE.md, root/foo/CLAUDE.md) 모두 자동 인식됩니다.~/.claude/CLAUDE.md) – 모든 세션에 적용됩니다./init 명령 실행 시 Claude가 자동으로 CLAUDE.md를 생성해줍니다.
CLAUDE.md 반복 개선하기CLAUDE.md도 프롬프트처럼 자주 다듬어야 합니다. 흔한 실수는 장황하게 내용만 추가하고 실제 효과성을 테스트하지 않는 것입니다. 다양한 실험을 통해 어떤 설명이 Claude의 성능을 높이는지 직접 검증해보세요.
직접 수정하거나 #키를 눌러 즉석 지시를 남기면 Claude가 내용을 관련 CLAUDE.md에 자동 반영합니다. 명령, 파일, 스타일 가이드를 코딩 중 위키처럼 기록하고, 변경사항도 git 커밋에 포함해 팀원과 같이 활용하는 패턴이 많습니다.
Anthropic에서는 prompt improver로 CLAUDE.md를 다듬거나, "IMPORTANT" "YOU MUST"처럼 강조를 추가하여 모델의 지시 따름성을 높이기도 합니다.
Claude Code는 시스템을 변경할 수 있는 작업(파일 쓰기, 다양한 bash 명령, MCP 도구 등)에 기본적으로 승인 요청을 합니다. 안전을 최우선하다보니 매우 보수적으로 설계된 셈이죠. 하지만 직접 추가적인 도구를 ‘허용리스트’에 명시해 보다 자유롭게 사용할 수 있습니다. 파일 편집, git commit 등 쉽게 되돌릴 수 있는 작업은 과감히 허용해보세요.
도구 허용 방법은 네 가지:
/permissions 명령어 사용
Edit, git 커밋을 허용하려면 Bash(git commit:*), puppeteer MCP 서버 네비게이션을 허용하려면 mcp__puppeteer__puppeteer_navigate 추가.claude/settings.json 또는 ~/.claude.json (전자는 소스컨트롤에 공유 권장)--allowedTools 사용Claude는 gh CLI로 GitHub 이슈/PR 생성, 댓글 확인 등 다양한 상호작용이 가능합니다. gh 미설치 시엔 GitHub API 혹은 MCP 서버(설치 시)로도 작업이 일부 가능합니다.
Claude는 셸 환경의 모든 도구(스크립트, 함수 등)를 당신처럼 자유롭게 활용할 수 있습니다. MCP와 REST API를 통한 복잡한 도구 연결도 가능합니다.
Claude Code는 bash 환경을 그대로 상속합니다. Claude가 유닉스 표준 툴이나 gh는 원래 아는 반면, 직접 만든 커스텀 툴은 직접 알려줘야 사용이 가능합니다:
--help로 사용법 조회를 명시적으로 지시CLAUDE.md에 기록Claude Code는 MCP 서버이자 클라이언트입니다. 클라이언트로서는 여러 MCP 서버에 접속해 아래 세 가지 방식으로 그 도구들을 사용할 수 있습니다:
.mcp.json에 커밋(같은 코드베이스 모든 사용자에게 적용). 예: .mcp.json에 Puppeteer, Sentry 서버를 등록 시, 전체 팀원이 기본적으로 사용 가능MCP 디버깅을 위해 --mcp-debug 옵션 활용도 권장합니다.
반복적 워크플로우(디버깅 루프, 로그 분석 등)는 마크다운 파일 형태로 .claude/commands 폴더 내 템플릿을 만들어 슬래시 커맨드로 추가하세요. 이들은 /를 입력하면 메뉴에 등장하며, 팀원 참여를 위해 git에 커밋할 수 있습니다.
특수 키워드 $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로 이슈 #1234 자동 해결 요청하는 식입니다. 개인 전용 커맨드는 ~/.claude/commands 폴더에 넣어 모든 세션에서 활용할 수 있습니다.
Claude Code는 특정 워크플로우 강제 없이, 사용자의 자유로운 활용을 장려합니다. 이런 설계 덕분에 실제 커뮤니티 내에서 아래와 같은 ‘효과적 사용 패턴’이 자연스럽게 자리 잡고 있습니다:
가장 범용적인 워크플로우:
1~2단계(탐색+계획)가 매우 중요합니다. 선행 없이 곧장 구현부터 시키면 결과물이 겉핥기일 수 있습니다. 사전 리서치 및 기획 프로세스를 추가하면 복잡한 문제일수록 훨씬 더 깊이 있는 결과가 나옵니다.
테스트로 결과를 쉽게 검증할 수 있는 변경(유닛·통합·E2E 테스팅 등)에서 Anthropic이 선호하는 워크플로우입니다. TDD(Test Driven Development)는 에이전트형 코딩과 궁합이 매우 좋습니다:
Claude는 명확한 타겟(테스트, 비주얼 목업 등)이 있을 때 가장 잘 동작합니다. 기대 결과(테스트)를 제공하면 반복 개선 프로세스를 일정하게 유지할 수 있습니다.
테스팅과 비슷하게, 비주얼 타겟도 줄 수 있습니다:
Claude 역시 반복 학습에 따라 결과물이 향상됩니다. 최소 2~3회 반복 후 결과 화질이 훨씬 개선되는 경향이 있습니다. Claude가 "자기 눈"으로 결과를 볼 수 있게 도구를 연결하세요.
수동 승인 없이 Claude에 자유롭게 작업시키려면 claude --dangerously-skip-permissions로 모든 권한 체크를 우회할 수 있습니다. 린트 오류 수정, 보일러플레이트 자동생성 등 반복 작업에 효과적입니다.
임의 명령어 실행은 위험(데이터 유실, 시스템 훼손, 데이터 무단반출)하므로 인터넷 연결 없는 컨테이너 등 격리 환경에서만 사용하세요. 이런 레퍼런스 도커 환경을 참고하세요.
타 코드베이스 온보딩 시, Claude Code로 빠르게 탐구, 학습하세요. 페어프로그래밍처럼, 새 엔지니어에게 물을 법한 질문 모두 Claude에게 물어보면 됩니다. Claude가 코드베이스 전체를 에이전트형으로 탐색, 다음과 같은 질문에도 답변 가능합니다:
async move { ... }는 무슨 역할인가요?foo() 호출 대신 왜 bar()를 씁니까?Anthropic 내부에서는 온보딩 시 Claude Code 활용이 표준이 되었을 정도입니다. 별도 프롬프트 없이 대화하듯 묻기만 하면 됩니다.
Claude는 다양한 git 작업을 효과적으로 처리합니다. 실제로 Anthropic 엔지니어의 90% 이상이 대다수 git 상호작용을 Claude로 처리합니다:
Claude Code는 다양한 GitHub 상호작용도 지원합니다:
복잡한 gh CLI 문법 기억 없이 루틴 자동화에 활용할 수 있습니다.
Anthropic의 연구자·데이터 과학자팀은 Claude Code로 Jupyter 노트북 읽기/쓰기, 시각화 결과 해석을 빠르게 처리합니다. 별도 프롬프트나 정해진 프로세스는 없지만, 추천 패턴은 VS Code에서 Claude Code와 .ipynb 파일을 나란히 띄워 함께 작업하는 것.
동료에게 제출 전 Claude에 노트북을 "가독성 있게 다듬어 달라" 요청하면 시각/미적 품질까지 개선할 수 있습니다. 명시적으로 "미적 최적화" 등의 요청을 하면 좋은 효과가 있습니다.
아래 제안들은 모든 워크플로우에 통용됩니다:
Claude Code의 성공률은 처음 지시를 얼마나 구체적으로 주느냐에 따라 크게 달라집니다. 명확히 지시할수록 후속 수정을 줄일 수 있습니다.
| Poor | Good |
|---|---|
| add tests for foo.py | write a new test case for foo.py, covering the edge case where the user is logged out. avoid mocks |
| why does ExecutionFactory have such a weird api? | look through ExecutionFactory's git history and summarize how its api came to be |
| add a calendar widget | look at how existing widgets are implemented on the home page to understand the patterns and specifically how code and interfaces are separated out. HotDogWidget.php is a good example to start with. then, follow the pattern to implement a new calendar widget that lets the user select a month and paginate forwards/backwards to pick a year. Build from scratch without libraries other than the ones already used in the rest of the codebase. |
Claude는 의도 추론은 가능하지만, 독심술사가 아닙니다. 명확할수록 원하는 결과에 가까워집니다.
Claude는 이미지, 도표를 여러 방식으로 잘 다룹니다:
UI 개발용 디자인 목업, 분석·디버깅용 차트 등에 활용하세요. 시각적 맥락이 없다면, 결과물의 ‘비주얼 퀄리티’ 중요성을 명시적으로 전달하는 것도 도움이 됩니다.
탭 완성 기능으로 레포 내 임의 파일/폴더를 빠르게 참조하고 Claude에게 정확히 어떤 파일을 봐야 하는지 지정하세요.
프롬프트에 특정 URL을 붙여 넣으면 Claude가 직접 해당 내용을 읽을 수 있습니다. 같은 도메인 반복 요청은 /permissions로 도메인을 허용리스트에 추가해 권한 프롬프트를 줄이세요.
Auto-accept모드(shift+tab 전환)로도 자동으로 작업이 가능하지만, Claude와 적극적으로 협업하여 틀어진 방향을 바로잡을 때 더 빠르고 좋은 결과를 얻을 수 있습니다. 초기 설명을 충분하게 전달하고, 언제든 방향 전환이나 중간 수정을 할 수 있습니다.
조율 도구 4가지:
Claude가 한 번에 완벽히 해결할 때도 있지만, 적극적 조율이 보통 더 빨리 더 나은 결과를 이끌어냅니다.
/clear로 컨텍스트 정리긴 세션에서는 대화/파일/명령내용으로 컨텍스트가 불필요하게 오염될 수 있습니다. /clear로 꼭 컨텍스트 윈도우를 자주 리셋하세요.
마이그레이션, 대량 린트, 복잡한 빌드/스크립트 등 다단계·대규모 작업은 마크다운 체크리스트나 깃허브 이슈를 Claude의 체크리스트/작업패드로 삼게 하세요.
예: 린트 오류 대량 수정 시
Claude에 데이터를 입력하는 방법:
cat foo.txt | claude) — 로그, CSV 등 대용량 데이터에 특히 유용실제 세션에서는 여러 방법을 혼합해서 사용하게 됩니다. 예: 로그파일 파이프로 넘긴 뒤 추가 분석 데이터는 MCP 도구로 불러오게 지시 등.
Claude Code는 헤드리스 모드도 지원합니다. 이 모드는 CI, pre-commit hook, 빌드 스크립트, 기타 자동화 환경에 적합합니다. -p 플래그로 프롬프트 지정, --output-format stream-json은 스트림형 JSON 출력을 지원합니다.
세션 간 상태 유지 없이 매번 별도 트리거가 필요합니다.
헤드리스 모드는 GitHub 이벤트(이슈 생성 등) 트리거 자동화에 쓸 수 있습니다. 예: Claude Code 공식 레포는 새 이슈가 등록되면 Claude가 검사 후 라벨을 자동 부여합니다.
Claude Code는 주관적 코드 리뷰까지 가능해, 기존 린트툴이 잡아내지 못하는 오타/낡은 주석/함수명/변수명 오류까지 탐지할 수 있습니다.
독립 사용을 넘어서, 여러 Claude 인스턴스를 병렬로 활용하면 생산성을 극대화할 수 있습니다.
한쪽 Claude는 코드를 작성, 다른쪽은 리뷰·테스트를 담당 – 마치 여러 개발자가 동시에 일하는 효과가 납니다. 별도 컨텍스트 덕분에 작업 분리가 용이합니다:
/clear 또는 새 터미널에서 두 번째 Claude 시작/clear) 코드+피드백 종합 확인테스트도 유사하게 한 쪽이 테스트, 다른 쪽이 코드 구현·합격/불합격 판정 역할로 분업시킬 수 있습니다. Claude간 scratchpad 공유 지시도 가능합니다.
이런 분리 전략이 "모든 걸 혼자 시키는 것"보다 훨씬 결과가 좋을 때가 많습니다.
많은 Anthropic 개발자는 효율성을 위해 다음과 같이 활용합니다:
다수 독립 작업엔 여러 체크아웃보다 worktree가 편리합니다. git worktree로 동일 레포 내 여러 브랜치를 각기 별도 디렉토리로 분리, 각기 작업할 수 있습니다. 작업간 결합이 적고, 작업영역간 충돌도 피할 수 있습니다.
git worktree add ../project-feature-a feature-acd ../project-feature-a && claude팁:
git worktree remove ../project-feature-aclaude -p(헤드리스 모드)은 Claude Code를 시스템 자동화/파이프라인에도 쉽게 통합할 수 있습니다. 대표 패턴:
Fan-out: 대형 마이그레이션/분석(수백 로그·수천 CSV 등)에 유리
파이프라이닝: 기존 파이프라인에 Claude 삽입
claude -p "<프롬프트>" --json | your_command(다음 스텝 연동)둘 다 --verbose 플래그로 디버깅 추천, 프로덕션에서는 꼭 끄세요.
여러분은 Claude Code를 어떻게 활용하시나요? @AnthropicAI를 태그해 여러분의 베스트 프랙티스도 공유해주세요!
Boris Cherny 집필. 이 글은 Claude Code 사용자 커뮤니티(내부 및 외부)의 창의적 사용법과 경험에서 영감을 받았습니다. Daisy Hollman, Ashwin Bhat, Cat Wu, Sid Bidasaria, Cal Rueb, Nodir Turakulov, Barry Zhang, Drew Hodun 그리고 수많은 Anthropic 엔지니어분들의 실무적인 인사이트와 경험에 감사드립니다.