해당 글은 Claude Code Docs의 Core concepts의 마지막 부분에 대한 글이다.
이 글은 Claude Code를 최대한 잘 활용하기 위한 팁과 패턴을 다룬다.
환경 설정부터 병렬 세션 확장까지 포함한다.
Claude Code는 일반 대화 모델과 달리 파읽을 읽고 명령을 실행하고 내가 개입하지 않아도 자율적으로 문제를 해결할 수 있다.
이로 인해 작업 방식이 바뀌게 된다. 코드를 쓰고 리뷰를 Claude한테 맡기는 대신, 내가 뭘 원하는지를 설명하고, 클로드는 방법을 찾고 계획을 세워 구현한다.
그러나 이런 자율적인 방법은 러닝 커브가 있다. Claude는 특정 환경에서만 잘 작동하고, 우리는 이 환경을 이해해야 한다.
이 가이드는 앤트로픽 내부에서 효과를 본 방법들을 소개한다.
Best practice는 Claude의 context window가 빠르게 차는 것과 용랑이 증가함에 따라 성능이 줄어드는 것의 제약을 기초로 한다.
Claude의 context window는 전체 대화, 모든 파일, 모든 명령어 결과를 가지고 있는다. 그래서 디버깅 세션이나 코드 탐색만 하더라도 많은 토큰을 소모한다.
1. Give Claude a way to verify its work
클로드가 스스로 결과를 확인할 수 있는 방법을 제공하는 것이 가장 높은 레버리지를 가진 행동이다.
- 테스트, 스크린샷, 기대 출력
클로드가 스스로 검증이 가능할 때 성능은 극적으로 향상된다. 단, 뚜렷한 검증 기준이 없다면 겉으로는 그럴듯하게 보이지만 실제로 동작하지 않는 것을 만든다.
| 전략 | Before (나쁜 예) | After (좋은 예) |
|---|---|---|
| 검증 기준 제공하기 | 이메일 주소를 검증하는 함수를 구현해줘 | validateEmail 함수를 작성해줘. 테스트 예시: user@example.com은 true, invalid는 false, user@.com은 false. 구현 후 테스트를 실행해. |
| UI 변경을 시각적으로 검증하기 | 대시보드를 더 보기 좋게 만들어줘 | [스크린샷 붙여넣기] 이 디자인을 구현해줘. 결과 스크린샷을 찍어서 원본과 비교하고, 차이점을 나열한 뒤 수정해. |
| 증상이 아닌 근본 원인 해결하기 | 빌드가 실패해 | 빌드가 이 에러로 실패해: [에러 로그 붙여넣기]. 이 문제를 수정하고 빌드가 성공하는지 검증해. 에러를 숨기지 말고 근본 원인을 해결해. |
UI 실패는 Claude in Chrome extension 활용
Claude Code를 사용할 때, 검증 로직을 견고하게 만드는 데 투자할 것!
2. Explore first, then plan, then code
탐색 + 계획 단계와 구현 단계를 분리할 것!
클로드가 바로 코딩에 들어가게 되면 문제를 잘못 이해한 채로 코드를 작성하게 된다.
권장하는 네 단계
- 탐색 (플랜 모드)
/src/auth를 읽고
세션과 로그인 처리를 어떻게 하고 있는지 이해해줘.
또한 시크릿을 위한 환경 변수를 어떻게 관리하는지도 살펴봐.- 계획 (플랜 모드)
Google OAuth를 추가하고 싶어.
어떤 파일들을 수정해야 할까?
세션 플로우는 어떻게 되는지 설명하고,
구현 계획을 만들어줘.이때 플랜을 수정하고 싶다면 Ctrl + G를 눌러서 수정할 수 있다.
- 구현
네가 만든 계획에 따라 OAuth 플로우를 구현해줘.
콜백 핸들러에 대한 테스트를 작성하고,
전체 테스트 스위트를 실행한 뒤
실패하는 테스트가 있으면 수정해.- 커밋
설명적인 커밋 메시지로 커밋하고 PR을 열어줘.플랜 모드를 언제 써야 할까?
플랜 모드는 오버헤드가 발생하므로 한 줄을 고치거나 고칠 부분이 명확할 경우는 바로 Claude에게 구현을 시키는 것이 좋다.
플랜 모드는 잘 모르겠을 때, 여러 파일을 수정할 때 등에 쓰는 것이 좋다.
3. Provide specific context in your prompts
지시가 명확할수록 수정이 적다
클로드는 의도를 추론할 순 있지만 생각을 읽을 순 없다. 구체적인 파일이나 예시를 알려줘라.
| 전략 | Before (나쁜 예) | After (좋은 예) |
|---|---|---|
| 작업 범위를 명확히 하라. 어떤 파일인지, 어떤 시나리오인지, 테스트 선호 사항을 지정하라. | foo.py에 테스트 추가해줘 | foo.py에 대해 사용자가 로그아웃된 상태에서 발생하는 엣지 케이스를 다루는 테스트를 작성해줘. mock은 사용하지 마. |
| 출처를 명시하라. 질문에 답이 될 수 있는 소스를 Claude에게 직접 가리켜라. | ExecutionFactory의 API는 왜 이렇게 이상해? | ExecutionFactory의 git 히스토리를 살펴보고, 이 API가 어떻게 만들어지게 되었는지 요약해줘. |
| 기존 패턴을 참조하라. 코드베이스에 이미 존재하는 구현 패턴을 알려줘라. | 캘린더 위젯 추가해줘 | 홈 페이지에 있는 기존 위젯 구현 방식을 살펴봐서 패턴을 이해해줘. HotDogWidget.php가 좋은 예야. 그 패턴을 따라 월 선택과 연도 앞/뒤 페이지 이동이 가능한 새로운 캘린더 위젯을 구현해줘. 코드베이스에서 이미 사용 중인 라이브러리 외에는 새 라이브러리를 사용하지 말고, 처음부터 구현해. |
| 증상을 설명하라. 증상, 의심되는 위치, 그리고 “해결됨”의 기준을 제공하라. | 로그인 버그 고쳐줘 | 사용자들이 세션 타임아웃 이후 로그인이 실패한다고 보고하고 있어. src/auth/의 인증 플로우를 확인해줘. 특히 토큰 리프레시 부분을 집중적으로 봐. 이 문제를 재현하는 실패하는 테스트를 먼저 작성한 뒤, 그 테스트가 통과하도록 수정해줘. |
모호한 프롬프트는 생각을 넓힐 때 필요하다. 그런 프롬프트는 오히려 생각지 못한 것들을 생각해보게 해준다.
Provide rich content
@로 파일을 참조, 스크린샷 이미지 붙여넣기, 데이터 직접 전달하기
URL 제공하기
- api 레퍼런스나 documentation의 링크를 제공하라. 자주 사용하는 도메인은 /permissions를 사용해 추가할 수 있다.
클로드에게 스스로 수집하도록 지시하기
4. Configure your environment
CLAUDE.md 효과적으로 쓰는 법
- Bash commands, code style, workflow rules를 모두 포함시켜라.
- /init 커맨드는 현재 codebase를 조사해 초기 버전을 만든다.
- 특별한 format은 필요 없지만 짧게 유지하고, 사람이 읽기 쉽게 만들어라.
- 그리고 최대한 간결하게 유지해라. 각 문장마다 '이 문장을 지우면 Claude가 실수를 하게 될까?'에 대해 질문하고 필요 없으면 삭제해라. 불필요한게 많으면 Claude는 정말 중요한 지침을 무시한다.
- 모든 세션에 로드되는 것이기에 넓게 적용되는 것만 넣어라.가끔 관련 있는 도메인 지식이나 workflow들은 skills에 넣어라.
CLAUDE.md 예시
# 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모든 세션에 로드되는 것이기에 넓게 적용되는 것만 넣어라.
-> 가끔 관련 있는 도메인 지식이나 workflow들은 skills에 넣기.
| ✅ 포함해야 할 것 | ❌ 제외해야 할 것 |
|---|---|
| Claude가 추측하기 어려운 Bash 명령 | 코드를 읽으면 Claude가 스스로 알아낼 수 있는 내용 |
| 기본값과 다른 코드 스타일 규칙 | Claude가 이미 알고 있는 표준 언어 관례 |
| 테스트 지침과 선호하는 테스트 러너 | 상세한 API 문서 (대신 문서 링크 제공) |
| 저장소 사용 규칙 (브랜치 이름, PR 규칙 등) | 자주 변경되는 정보 |
| 프로젝트에 특화된 아키텍처 결정 | 긴 설명이나 튜토리얼 |
| 개발 환경의 특이사항 (필수 환경 변수 등) | 코드베이스를 파일 단위로 설명한 목록 |
| 자주 발생하는 함정이나 직관적이지 않은 동작 | “클린 코드 작성”처럼 자명한 관행 |
만약 Claude가 룰에 적혀 있음에도 불구하고, 계속 원하지 않는 행동을 하는 경우면 CLAUDE.md가 너무 길어서 룰을 잊어버릴 가능성이 있다.
또한, 만약 Claude가 적혀져 있는 룰에 대해서 질문한다면, 해당 지시가 모호할 가능성이 있다.
CLAUDE.md를 코드를 관리하듯 - 잘못되었을 때 리뷰하고, 정기적으로 정리하라. 그리고 변경 후 Claude의 실제 행동이 정말로 바뀌는지 관찰하며 테스트해라
중요한 것들에 대해서는 IMPORTANT, YOU MUST 등의 문구를 통해 강조할 수 있다.
또한, 필요할 때 파일을 참고하게 하고 싶을 때, 파일 전체를 넣지 않고 위치로 넣을 수 있다.
ex)
프로젝트 전체 개요는 @README.md를 참고하고, 사용 가능한 npm 명령어는 @package.json을 참고하라.
# Additional Instructions
- Git workflow: @docs/git-instructions.md
- Personal overrides: @~/.claude/my-project-instructions.md허가 조절하기 (반복되는 권한 요청)
Claude Code를 쓰다보면 가끔 권한 요청이 귀찮게 느껴질 경우가 많다. 그럴 때 읽으면 도움이 되는 내용이다.
기본적으로 Claude Code는 특정 작업에 대해 권한 요청을 한다. (파일 쓰기, Bash 명령 실행 등)
이는 안전하지만 반복되면 번거로워 열번 째 승인부터는 내용 검토 없이 클릭하게 된다.
이런 중단을 줄이는 방법은 두 가지다.
- Permission allowlists
- 이미 안전하다고 있는 도구들을 미리 허용하는 것
- Sandboxing
- OS 수준의 격리를 활성화해 파일 시스템 접근, 네트워크 접근 등을 제한한다. 정해진 범위에서 Claude는 자유롭게 작업할 수 있다.
이런 방법 말고 --dangerously-skip-permissions 이 옵션을 쓰면 모든 요청을 허가할 수 있다.
단 --dangerously-skip-permissions는 프롬프트 인젝션으로 인한 데이터 유출 등이 가능하므로 인터넷이 차단된 샌드박스 환경에서만 사용되는 것이 권장된다.
Create skills
.claude/skills/ 위치에 SKILL.md를 만들어서 Claude에게 도메인 지식이나 재사용가능한 workflows 주기
지식으로 쓰는 경우 예시
---
name: api-conventions
description: REST API design conventions for our services
---
# API Conventions
- Use kebab-case for URL paths
- Use camelCase for JSON properties
- Always include pagination for list endpoints
- Version APIs in the URL path (/v1/, /v2/)workflow로 쓰는 경우 예시
---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---
Analyze and fix the GitHub issue: $ARGUMENTS.
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이 경우 /fix-issue 1234로 할 수 있고, 1234는 $ 변수에 들어간다.
이 경우 disable-model-invocation: true로 해야 하는데, 해당 pr 작업은 모델이 스스로 호출하면 문제가 생길 수 있기 때문.
서브 에이전트 만들기
.claude/agetnes/ 디렉터리에 전문 역할의 서브 에이전트를 정의할 수 있다.
만드는 예시
---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
model: opus
---
You are a senior security engineer. Review code for:
- Injection vulnerabilities (SQL, XSS, command injection)
- Authentication and authorization flaws
- Secrets or credentials in code
- Insecure data handling
Provide specific line references and suggested fixes.사용할 땐 명시적으로 서브 에이전트를 호출해라
“Use a subagent to review this code for security issues.”
플러그인 설치하기
/plugin 명령으로 마켓플레이스를 볼 수 있다. 플러그인은 스킬들과 툴들 등을 제공한다.
플러그인은 커뮤니티나 Anthropic이 제공하는 스킬, 툴, 서브 에이전트, 훅들의 설치가능한 묶음이다.
5. Communicate effectively
Claude Code와 의사소통 잘하는 법이다.
Claude에게 시니어 엔지니어에게 묻듯이 질문하라. 특별한 프롬프트는 필요 없다. 그냥 바로 물어봐라.
규모가 큰 기능을 만들 때는, 처음부터 구현하지 말고 Claude가 먼저 나를 인터뷰하게 해서 요구사항을 명확하게 하라. 이때 AskUserQuestion 도구를 사용하면 된다.
I want to build [brief description]. Interview me in detail using the AskUserQuestion tool.
Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs. Don't ask obvious questions, dig into the hard parts I might not have considered.
Keep interviewing until we've covered everything, then write a complete spec to SPEC.md.6. Manage your session
7. Automate and scale
8. Avoid common failure patterns
자주 일어나는 실패 패턴
싱크대 세션 (The kitchen sink session)
하나의 세션에서 중간에 전혀 다른 걸 물어보고 다시 처음 작업으로 오는 경우 컨텍스트에 관련 없는 정보가 잔뜩 쌓인다.
-> 관련 없는 작업을 했다면 /clear로 컨텍스트를 비우자
끝없는 수정 반복 (Correcting over and over)
Claude가 잘못한다 -> 고친다 -> 잘못한다 -> 고친다
이 루프가 반복되는 경우 컨텍스트는 실패한 접근들로 오염된다.
-> 두 번 이상 실패하는 경우 /clear로 없애고 더 나은 프롬프트를 쓰자.
과도하게 길어진 CLAUDE.md (The over-specified CLAUDE.md)
CLAUDE.md가 너무 길면 절반은 무시하게 된다.
-> 가차 없이 정리할 것
믿음과 검증의 간극 (The trust-then-verify gap)
Claude가 그럴듯한 결과를 내놓지만, edge 케이스를 처리하지 못하는 경우
-> 항상 검증 수단을 제공할 것. 검증할 수 없다면 배포하지 않기!
끝없는 탐색 (The infinite exploration)
Claude에게 조사해줘라고 하고 범위를 말하지 않는 경우, 수백 개의 파일을 읽으며 컨텍스트를 가득 채운다.
-> 조사의 범위 지정하고 서브 에이전트 사용하라.
