최근 저희는 Claude Code를 출시했습니다. 이는 연구 프로젝트로 개발된 커맨드라인 기반 도구로, Anthropic의 엔지니어들과 연구자들이 Claude를 자신의 코딩 워크플로우에 보다 자연스럽게 통합할 수 있도록 만들어졌습니다.
Claude Code는 의도적으로 낮은 수준(low-level)으로 설계되어 있으며, 특정한 워크플로우를 강요하지 않는 비의존적인(unopinionated) 방식으로 작동합니다. 이러한 설계 철학 덕분에 이 도구는 유연하고, 사용자 정의가 가능하며, 스크립트화하기 쉬우면서도 안전한 강력한 도구가 되었습니다. 하지만 이러한 유연성은 에이전트형 코딩 도구에 익숙하지 않은 엔지니어들에게는 다소 학습 곡선을 유발할 수 있습니다—최소한 자신만의 모범 사례를 구축할 때까지는 말이죠.
이 글에서는 Anthropic 내부 팀뿐 아니라 외부 엔지니어들이 Claude Code를 다양한 코드베이스, 언어, 환경에서 사용할 때 효과적이라고 입증된 일반적인 패턴들을 소개합니다. 이 목록의 어떤 것도 절대적이지 않으며, 모든 상황에 적용되지는 않습니다. 이 제안들을 출발점으로 삼아, 여러분에게 가장 잘 맞는 방식을 실험하고 찾아가길 바랍니다!
더 자세한 정보가 필요하신가요? claude.ai/code에 있는 공식 문서에서는 본문에서 언급된 모든 기능은 물론, 추가적인 예시, 구현 세부 사항, 고급 기법들까지 포괄적으로 다루고 있습니다.
1. 설정을 사용자 맞춤화하기
Claude Code는 문맥(context)을 자동으로 프롬프트에 끌어오는 에이전트형 코딩 어시스턴트입니다. 이 문맥 수집은 시간과 토큰을 소비하지만, 환경 설정을 조정하여 최적화할 수 있습니다.
CLAUDE.md는 Claude가 대화를 시작할 때 자동으로 문맥에 포함시키는 특수 파일입니다. 다음과 같은 내용을 정리해 두기에 이상적입니다:
자주 사용하는 Bash 명령어
핵심 파일 및 유틸리티 함수
코드 스타일 가이드라인
테스트 실행 방법
리포지토리 작업 규칙 (예: 브랜치 명명 규칙, merge vs. rebase 등)
개발 환경 세팅 방법 (예: pyenv 사용법, 호환되는 컴파일러 등)
프로젝트 특유의 예외적 동작이나 경고 사항
Claude가 기억하길 원하는 기타 정보
형식은 자유롭지만, 간결하고 사람이 읽기 쉬운 형식으로 작성하는 것이 좋습니다. 예시:
# Bash 명령어
- npm run build: 프로젝트 빌드
- npm run typecheck: 타입 검사 실행
# 코드 스타일
- ES 모듈(import/export) 문법 사용, CommonJS(require)는 사용하지 않음
- 가능하면 import 시 구조 분해 할당 사용 (예: import { foo } from 'bar')
# 작업 흐름
- 여러 코드 수정을 마쳤다면 반드시 타입 체크를 실행
- 전체 테스트보다는 단일 테스트 실행을 선호 (성능 향상)
CLAUDE.md 파일 위치 지정
다음 위치에 CLAUDE.md를 두면 Claude가 자동으로 참조합니다:
레포지토리 루트 또는 Claude를 실행하는 디렉토리
일반적으로 가장 많이 사용하는 위치
CLAUDE.md로 저장해 Git에 커밋하여 팀과 공유 (권장)
또는 CLAUDE.local.md로 만들고 .gitignore에 추가 (개인 설정용)
Claude 실행 디렉토리의 상위 폴더들
모노레포(monorepo) 구조에서 유용
예: root/foo에서 Claude를 실행하면 root/CLAUDE.md, root/foo/CLAUDE.md 모두 자동 포함됨
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에 반영한 뒤 커밋에 포함시켜 팀원들과 공유합니다.
예를 들어:
# test: Run `pytest -k` instead of full test suite for speed
# style: Always destructure props in React components
Anthropic에서는 CLAUDE.md 파일을 **프롬프트 개선 도구(prompt improver)**에 돌려보기도 하고, "IMPORTANT", "YOU MUST"와 같은 강조 문구를 넣어 모델의 응답 일관성과 순응도를 높이기 위한 튜닝을 자주 수행합니다.
c. Claude가 사용할 수 있는 도구 목록 관리하기
기본적으로 Claude Code는 시스템을 변경할 수 있는 모든 작업—예를 들어 파일 쓰기, 다양한 Bash 명령어 실행, MCP 도구 사용 등—에 대해 사전 허락을 요청합니다. 이러한 보수적인 접근 방식은 시스템 안전을 최우선으로 고려한 설계 철학입니다.
하지만 사용자는 신뢰할 수 있는 도구나, 되돌리기 쉬운 작업(예: 파일 편집, git 커밋 등)을 포함해 **허용 목록(allowlist)**을 사용자 정의할 수 있습니다.
Claude가 사용할 수 있는 도구를 관리하는 방법은 다음 네 가지입니다:
세션 중 프롬프트가 뜰 때 “항상 허용(Always allow)”을 선택
한 번 허용하면 이후 해당 작업은 자동으로 허용됩니다.
Claude Code 실행 후 /permissions 명령어 사용
도구를 허용하거나 제거할 수 있습니다.
예시:
Edit → 파일 편집 항상 허용
Bash(git commit:*) → git 커밋 허용
mcp__puppeteer__puppeteer_navigate → Puppeteer MCP 서버로 웹 페이지 이동 허용
.claude/settings.json 또는 ~/.claude.json 파일을 수동으로 수정
.claude/settings.json은 팀과 공유할 수 있도록 Git에 커밋하는 것을 권장합니다.
세션별로 --allowedTools CLI 플래그 사용
특정 세션에서만 임시로 도구 허용 가능
d. GitHub을 사용하는 경우, gh CLI를 설치하세요
Claude는 GitHub과 상호작용하기 위해 gh CLI를 사용할 수 있습니다. 이를 통해 다음과 같은 작업이 가능합니다:
이슈(issue) 생성
풀 리퀘스트(pull request) 열기
댓글(comment) 읽기
기타 다양한 작업
만약 gh CLI가 설치되어 있지 않더라도, Claude는 GitHub API 또는 MCP 서버(설치된 경우)를 통해서도 위 작업들을 수행할 수 있습니다.
2. Claude에 더 많은 도구를 제공하세요
Claude는 사용자의 쉘 환경(shell environment)에 접근할 수 있기 때문에, 마치 본인을 위해 작성하듯 편의용 스크립트나 함수들을 Claude용으로도 구축할 수 있습니다. 또한, Claude는 MCP나 REST API를 통해 더 복잡한 도구도 활용할 수 있습니다.
a. Bash 도구와 함께 Claude 사용하기
Claude Code는 사용자의 bash 환경을 그대로 상속받습니다. 따라서 Claude는 bash에서 실행 가능한 모든 도구에 접근할 수 있습니다. Claude는 unix 계열 기본 유틸리티나 gh 같은 일반적인 툴은 잘 알고 있지만, 사용자 정의 bash 도구는 따로 알려줘야 합니다.
이를 위해 다음 단계를 따라야 합니다:
도구 이름과 사용 예시를 Claude에게 알려주세요.
--help 실행 지시를 Claude에게 내려서 해당 도구의 문서 내용을 파악하도록 하세요.
자주 사용하는 도구는 CLAUDE.md에 문서화해 두세요.
b. MCP와 함께 Claude 사용하기
Claude Code는 MCP 서버이자 클라이언트 역할을 모두 수행할 수 있습니다. 클라이언트로 작동할 때 Claude는 여러 MCP 서버에 연결하여 3가지 방법으로 도구에 접근할 수 있습니다:
프로젝트 설정(Project config): 해당 프로젝트 디렉토리에서 Claude 실행 시 사용 가능
글로벌 설정(Global config): 모든 프로젝트에서 사용 가능
.mcp.json 파일에 명시: 소스코드에 체크인하여, 모든 팀원이 동일한 설정을 사용할 수 있도록 함
예: .mcp.json에 Puppeteer나 Sentry MCP 서버를 추가하면, 리포지토리를 사용하는 모든 엔지니어가 별도 설정 없이 Claude를 통해 바로 사용할 수 있음
MCP 설정 문제를 파악하고 싶을 때는, Claude를 --mcp-debug 플래그와 함께 실행하면 도움이 됩니다.
새로운 프로젝트에 처음 들어가면, “이 코드가 어떻게 작동하지?” “이 부분은 왜 이렇게 했지?” 이런 질문이 정말 많아지죠.
Claude Code는 마치 같이 일하는 선배 엔지니어처럼, 이런 질문에 대해 코드베이스를 스스로 탐색해서 답을 찾아주는 역할을 합니다.
🧠 Claude에게 할 수 있는 질문 예시
그냥 자연어로 물어보면 됩니다! 예를 들면:
“로깅은 어떻게 동작해?”
“API 엔드포인트를 새로 만들려면 어떻게 해야 해?”
“foo.rs 파일의 134번째 줄에 있는 async move { ... }는 무슨 뜻이야?”
“CustomerOnboardingFlowImpl 클래스는 어떤 예외 케이스를 처리해?”
“왜 333번째 줄에서 foo() 대신 bar()를 쓰고 있지?”
“baz.py의 334번째 줄을 Java로 바꾸면 어떤 코드가 될까?”
🚀 Anthropic 내부에서도 실제로 이렇게 사용 중!
Claude Code는 Anthropic 내부에서 새로운 엔지니어 온보딩 시 가장 핵심적인 도구로 자리 잡았습니다.
ramp-up(초기 적응 시간)을 확 줄이고
다른 팀원에게 물어보는 부담도 줄여줘요.
🎯 요약
항목
설명
목적
새로운 코드베이스를 빠르게 이해하고 질문에 답 찾기
방식
Claude에게 자연스럽게 질문 → 코드 탐색 후 답변
장점
빠른 온보딩, 다른 엔지니어 리소스 절약
별도 프롬프트
필요 없음! 그냥 질문하세요
🤖 Claude는 마치 “코드를 잘 아는 AI 동료”처럼, 파일을 열고, 분석하고, 설명해주는 역할을 해요. 처음 보는 프로젝트에서도 두려워 말고 편하게 질문해보세요!
f. Claude로 Git 작업하기
Claude는 Git 관련 작업을 상당히 잘 처리할 수 있습니다. Anthropic 엔지니어들 대부분은 Git 작업의 90% 이상을 Claude로 처리합니다.
🧩 Claude로 가능한 Git 작업 예시
Git 기록 탐색하기 Claude에게 이렇게 질문하세요:
“v1.2.3에는 어떤 변경사항이 포함되었지?”
“이 기능은 누가 담당했지?”
“이 API는 왜 이렇게 설계된 거야?” → Claude가 git log, git blame, git diff 등으로 직접 추적해 알려줍니다.
커밋 메시지 자동 작성 Claude는 변경사항과 이전 커밋을 기반으로, 문맥을 반영한 커밋 메시지를 알아서 작성해줍니다.
복잡한 Git 작업 처리 예:
파일 복구
리베이스 충돌 해결
패치 비교 및 병합 (graft)
🧠 g. Claude로 GitHub 작업하기
Claude는 GitHub과 관련된 다양한 작업을 자동으로 처리할 수 있어요. gh 명령어를 직접 쓰지 않아도 되고, 반복적인 GitHub 업무를 AI에게 맡길 수 있는 거죠!
✅ Claude가 도와줄 수 있는 GitHub 작업들
1. PR(Pull Request) 생성
Claude에게 그냥 이렇게 말해도 돼요: “pr 만들어줘”
그러면 Claude가:
변경된 코드를 확인하고
적절한 커밋 메시지를 만들고
PR을 자동으로 생성해 줍니다!
2. 리뷰 코멘트 자동 반영
PR에 코드 리뷰 코멘트가 달렸을 때,
Claude에게 이렇게 말하세요: “PR에 달린 리뷰 코멘트 반영해줘”
그러면 Claude가:
코멘트를 읽고 필요한 수정사항 반영
수정한 코드를 다시 PR 브랜치에 push 해줍니다
👉 더 구체적으로 지시해도 좋아요:
“변수명을 reviewer가 요청한 대로 바꿔줘”
3. 빌드 실패나 린트(lint) 오류 자동 수정
CI 빌드가 실패했거나 린트 경고가 뜬다면?
Claude에게 요청하세요: “CI 실패 원인을 찾아서 수정해줘” “린트 경고 해결해줘”
Claude가 오류 메시지를 분석해서 자동으로 수정해줍니다.
4. 열려 있는 GitHub 이슈 정리하기
Claude에게 이렇게 요청할 수 있어요: “열린 이슈들을 하나씩 확인해서 어떤 유형인지 분류해줘”
Claude는 모든 오픈 이슈를 돌면서:
중요도 태그 붙이기
중복 이슈 정리
긴급도 순 정렬 등을 자동으로 해줄 수 있습니다.
✨ 요약
작업
Claude가 하는 일
PR 생성
코드 diff 분석 → 메시지 생성 → PR 업로드
리뷰 반영
리뷰 코멘트 보고 코드 수정 → PR 브랜치에 push
빌드/린트 오류
실패 원인 분석 후 자동 수정
이슈 분류
오픈된 이슈 자동 분류 및 우선순위 지정
h. Claude로 Jupyter Notebook 작업하기
Anthropic의 연구자와 데이터 과학자들은 Claude Code를 사용해 Jupyter Notebook(.ipynb) 파일을 읽고 작성합니다.
🔍 가능한 작업
노트북의 출력 결과 해석, 이미지 포함된 시각화도 이해
데이터 탐색과 정리를 빠르게 수행
Claude Code와 .ipynb 파일을 VS Code에서 나란히 열고 작업하는 방식 추천
✨ 시각적으로 예쁘게 만들기
동료에게 노트북을 공유하기 전, Claude에게 요청하세요: “노트북을 더 보기 좋게 정리해줘” “시각화 결과가 더 미려하게 보이도록 수정해줘”
Claude는 “사람이 보기 좋게!” 라는 기준을 인식하면 더 깔끔하고 정돈된 결과물을 생성합니다.
✅ 요약 정리
항목
Claude 활용
Git 작업
커밋 메시지 작성, 변경 내역 탐색, 충돌 해결 등
GitHub 연동
PR 생성, 리뷰 반영, 이슈 관리, 빌드 오류 수정 등
Jupyter 노트북
코드 작성, 출력 해석, 시각화 정리, 디자인 개선
4. 워크플로우 최적화하기
Claude를 더 똑똑하게, 더 정확하게 사용하려면 다음 팁들을 기억하세요.
a. Claude에게 구체적으로 지시하세요
Claude Code는 처음부터 구체적인 지시를 줄수록 성공률이 훨씬 높아집니다. 처음에 모호하게 지시하면 나중에 다시 설명하거나 수정하게 되는 일이 많아져요.
🔁 예시: 나쁜 지시 vs. 좋은 지시
❌ 나쁜 예
✅ 좋은 예
foo.py에 테스트 추가해줘
foo.py에 로그인하지 않은 사용자의 엣지 케이스를 테스트하는 새로운 테스트 케이스를 추가해줘. mock은 사용하지 마.
ExecutionFactory API가 왜 이렇게 이상해?
ExecutionFactory의 git 히스토리를 확인하고, 이 API가 어떤 과정을 거쳐 현재 형태가 되었는지 요약해줘.
캘린더 위젯 추가해줘
홈페이지에 있는 기존 위젯 구현 방식을 참고해서, 코드와 인터페이스가 어떻게 분리되어 있는지 파악한 뒤, 그 패턴을 따라 캘린더 위젯을 새로 만들어줘. 월 선택, 연도 전환이 가능해야 해. HotDogWidget.php가 좋은 참고 예야. 기존 코드베이스에서 사용 중인 라이브러리 외에는 추가로 쓰지 말고, 처음부터 직접 구현해줘.
💡 왜 중요한가요?
Claude는 꽤 똑똑하지만 당신의 마음을 읽을 수는 없습니다. 구체적인 목표와 조건을 주면, 당신이 원하는 방향과 더 잘 맞는 결과를 만들어줍니다.
✅ 핵심 요약
처음부터 자세하고 명확하게 지시하세요.
필요한 조건, 제외해야 할 도구, 참고할 코드 등도 함께 전달하세요.
이렇게 하면 수정 없이 한 번에 원하는 결과에 도달할 가능성이 높아집니다.
b. Claude에게 이미지를 제공하세요
Claude는 이미지와 도표를 매우 잘 활용합니다. 다음과 같은 방법으로 이미지를 제공할 수 있어요:
🖼️ Claude에게 이미지 주는 방법
스크린샷 붙여넣기
macOS 사용 시: Cmd + Ctrl + Shift + 4 → 영역 지정 후 Ctrl + V로 Claude 입력창에 붙여넣기 ※ 일반적인 Cmd + V가 아닌 Ctrl + V입니다. 원격 접속 중엔 작동하지 않을 수 있어요.
이미지를 Claude 창으로 드래그 앤 드롭
이미지 파일 경로 입력
예: /images/mock.png 또는 ./screenshots/error.png
🎯 이미지가 특히 유용한 경우
**UI 개발 시 디자인 목업(mock)**을 참고할 때 → 예: “이 이미지처럼 버튼 배치해줘”
시각화 차트나 UI 분석·디버깅할 때 → 예: “이 에러 화면을 보고 코드 수정해줘”
💡 만약 이미지를 못 붙일 상황이라면?
이미지 없이도 괜찮지만, 그 대신 Claude에게 시각적 완성도가 중요하다고 명확히 말해주는 것이 좋아요.
예를 들어:
“결과물이 보기 좋고 깔끔해야 해” “사람이 보기에 미려한 UI로 만들어줘”
이렇게 말해주면 Claude가 그 점을 고려해서 작업합니다.
✅ 요약
방법
설명
붙여넣기
macOS: Cmd + Ctrl + Shift + 4 후 Ctrl + V
드래그 앤 드롭
이미지를 직접 Claude에 끌어다 놓기
경로 제공
이미지 파일 경로 입력
c. Claude에게 어떤 파일을 볼지 명확히 알려주세요
Claude에게 **”이 파일을 봐줘”, “이걸 수정해줘”**라고 할 때, 정확한 파일 이름을 말해주는 것이 매우 중요합니다.
🧩 팁: 파일 경로 자동완성(Tab-completion)
Claude Code는 입력 중에 Tab 키로 파일이나 폴더 경로를 자동완성할 수 있어요.
예를 들어:
claude> 수정하고 싶은 파일: `src/compo...` → [Tab] → `src/components/Header.tsx`
이렇게 하면 Claude가 정확한 파일을 인식하고 작업할 수 있습니다.
✅ 요약
항목
설명
Claude에게 파일 지시
수정하거나 참고할 파일 이름을 꼭 말해주기
경로 자동완성
Tab 키를 사용해 경로 빠르게 입력 가능
이유
Claude가 잘못된 파일을 보거나 놓치는 일 방지
Claude는 똑똑하지만, “어느 파일인지 모르면” 제대로 작업을 못해요. 꼭 파일명을 정확히 언급해주세요!
d. Claude에게 URL을 제공하세요
Claude는 웹 URL을 주면 그 페이지의 내용을 직접 읽고 분석할 수 있어요. 특히 문서, API 가이드, 외부 코드 레퍼런스 등을 참고할 때 유용합니다.
🔗 어떻게 사용하나요?
Claude에게 질문할 때, 참고할 웹사이트 URL을 함께 붙여넣기만 하면 됩니다.
예:
이 API의 인증 방식이 이해가 안 돼. 아래 문서를 참고해서 설명해줘:
https://docs.foo.com/api/authentication
Claude는 해당 페이지를 읽고, 질문에 답하거나 코드를 작성하는 데 활용합니다.
🔐 자주 쓰는 도메인은 허용 목록에 등록해두세요
처음에는 Claude가 “이 도메인을 읽어도 될까요?” 라고 물어볼 수 있어요. 매번 허락하지 않으려면 /permissions 명령어로 도메인을 미리 allowlist에 추가할 수 있습니다.
예:
/permissions addDomain docs.foo.com
→ 이제부터는 docs.foo.com 링크를 붙여도 Claude가 바로 접근할 수 있어요.
