CLAUDE.md
프로젝트별 규약을 한곳에 관리하면 리뷰 비용이 대폭 감소합니다 - 서브 에이전트 병렬 실행(Task)을 활용한 지시 설계로 처리 속도가 크게 향상됩니다 - 커스텀 슬래시 명령어와 권한 설정을 조합하면 안전하면서도 빠르게 작업할 수 있습니다.
Claude Code는 리포지토리 루트에 있는 CLAUDE.md 파일을 자동으로 읽어 컨텍스트로 사용합니다. 단순히 규칙을 나열하는 것이 아니라, 프로젝트 고유의 제약 사항, 기술 스택, 명령어 목록 등을 작성함으로써 매번 지시할 내용을 대폭 줄일 수 있습니다.
# 프로젝트 규약
## 기술 스택
- Runtime: Node.js 22 (ESM only)
...
CLAUDE.md를 작성한 후 Claude Code에게 "이 문서를 개선해 달라"고 요청하면, 실제 구현 내용을 읽어 부족한 정보를 보완해 줍니다.
Claude Code는 방대한 지시를 받을 경우 사고가 분산되기 쉽습니다. 효과적인 방법은 '1 지시 = 1 커밋에 해당하는 변경' 수준으로 작업 단위를 맞추는 것입니다.
나쁜 예 (너무 큰 범위의 지시):
인증 기능 전체를 구현해 주세요. JWT와 리프레시 토큰, 로그아웃 API, 미들웨어를 모두 포함해서요.
좋은 예 (분할된 지시):
Step 1: JWT 검증 유틸리티를 src/lib/auth/jwt.ts에 구현해 주세요.
입력: string, 출력: { userId: string } | null
Step 2: /api/auth/refresh 엔드포인트를 구현해 주세요.
...
단계적으로 확인하며 진행하면 중간에 방향을 수정해야 하는 비용을 최소화할 수 있습니다.
CI 환경이나 자동화 스크립트로 Claude Code를 실행할 때, --dangerously-skip-permissions 플래그를 사용하면 모든 작업이 허용되어 위험합니다. 대신 설정 파일에서 허용/금지 목록을 명시하는 방법이 권장됩니다.
~/.claude/settings.json 또는 .claude/settings.json (프로젝트 로컬):
{
"permissions": {
"allow": [
...
이를 통해 "테스트는 자유롭게 실행할 수 있지만, 외부 통신이나 파괴적인 명령어는 거부한다"라는 안전한 샌드박스를 구축할 수 있습니다.
.claude/commands/ 디렉토리에 마크다운 파일을 두면, /로 호출할 수 있는 커스텀 명령어가 됩니다.
.claude/commands/review-pr.md:
## PR 리뷰 실행
다음 관점에서 `$ARGUMENTS`의 차이점을 리뷰해 주세요.
1. **타입 안정성**: `any` 타입 사용 및 타입 어서션 (`as`) 남용 여부
...
Claude Code 상에서 /review-pr HEAD~1라고 입력하는 것만으로 프로젝트 고유의 관점에서 리뷰가 실행됩니다.
Claude Code의 Task 도구는 독립적인 조사 작업을 병렬로 실행할 수 있습니다. 이 특성을 활용하려면, 서로 의존성이 없는 작업들을 동시에 요청하는 지시 설계가 중요합니다.
다음 내용을 병렬로 조사하고, 각각의 조사 결과를 정리해 주세요:
A) src/components/ 디렉토리에서 "use client"를 사용하고 있는 파일 목록과
이것이 정말 필요한지에 대한 판단 여부
...
A, B, C는 각각 독립적이기 때문에 Claude Code가 내부적으로 서브 에이전트에게 분배하여 병렬 실행합니다. 순차적으로 실행하는 것보다 체감상 2~3배 빠릅니다.
Claude Code는 한 세션에서 하나의 디렉토리만 조작할 수 있습니다. 여러 기능을 동시에 개발할 때는 git worktree를 사용하여 작업 트리를 여러 개 생성하고, 터미널을 분리하여 각각의 Claude Code 세션을 실행하는 것이 실용적입니다.
# 메인 브랜치 작업 트리와 별도로 feature 브랜치용을 생성
git worktree add ../my-project-feat-auth feature/auth
git worktree add ../my-project-feat-payment feature/payment
...
각 세션은 독립된 파일 시스템을 보기 때문에 파일 충돌이 발생하지 않습니다. 병합(Merge)은 사람이 마지막에 확인하여 정리합니다.
Claude Code에서는 # 뒤에 파일 경로나 URL을 작성함으로써, 해당 파일의 내용을 즉시 참조할 수 있습니다. 이는 긴 '〇〇 파일을 읽어줘'라는 지시보다 컨텍스트 효율이 높습니다.
# src/lib/api/client.ts 구현을 참고하여,
# src/lib/api/webhook.ts 를 구현해 주세요.
에러 핸들링은 기존 클라이언트에 맞추세요.
더 나아가, 이미 확인한 큰 파일은 대화(Conversation)를 거쳐 재참조할 경우 토큰이 증가합니다. 중요한 정보만 CLAUDE.md나 별도의 reference 파일에 추출하여 요약해 두면, 장기 세션에서의 비용 효율성이 개선됩니다.
| 테크닉 | 주요 효과 |
|---|
CLAUDE.md 정리 | 매번의 지시를 단축 및 일관성 향상 |
| 태스크(Task) 단위 적정화 | 방향 수정 비용 최소화 |
| 세밀한 권한 설정 (Fine-grained permission) | 자동화 환경에서의 안전성 확보 |
| 커스텀 슬래시 명령어 (Custom slash command) | 팀 워크플로우 표준화 |
| 병렬 태스크 지시 | 조사 단계의 2~3배 속도 향상 |
git worktree 연동 | 여러 기능의 동시 개발 |
# 표기법을 통한 컨텍스트 압축 | 장기 세션의 토큰 효율화 |
Claude Code는 'AI에게 코드를 작성하게 하는 도구'라기보다는 'AI와 함께 소프트웨어를 설계하는 협업 환경'으로 이해하면 사용 방식이 크게 달라집니다. 위에 언급된 7가지는 오늘부터 시도할 수 있는 것들이니, 꼭 자신의 프로젝트에 맞는 형태로 조정해 보세요.
✍️ 본 기사 작성자: 合同会社ジモラボ
지모라보는 하치오지에 거점을 두고 AI를 활용한 SaaS를 다수 개발하고 있습니다. 본 기사의 기술 검증 역시 그러한 개발 과정의 부산물입니다.
관심을 가져주신다면, 각 SNS 팔로우도 부탁드립니다!
![Claude Code를 가장 빠르게 활용하는 7가지 실전 테크닉 [2026년판] 대표 이미지](/api/thumb?u=https%3A%2F%2Fqiita-user-contents.imgix.net%2Fhttps%253A%252F%252Fqiita-user-contents.imgix.net%252Fhttps%25253A%25252F%25252Fcdn.qiita.com%25252Fassets%25252Fpublic%25252Farticle-ogp-background-afbab5eb44e0b055cce1258705637a91.png%253Fixlib%253Drb-4.1.1%2526w%253D1200%2526blend64%253DaHR0cHM6Ly9xaWl0YS11c2VyLXByb2ZpbGUtaW1hZ2VzLmltZ2l4Lm5ldC9odHRwcyUzQSUyRiUyRmxoMy5nb29nbGV1c2VyY29udGVudC5jb20lMkZhJTJGQUNnOG9jS2ZuWlN6eUZwRTRLWEppdXNpakx5dm5aczlKMVgxdXlJX0ZCZGFxaXdDbC1yMXVjUSUzRHM5Ni1jP2l4bGliPXJiLTQuMS4xJmFyPTElM0ExJmZpdD1jcm9wJm1hc2s9ZWxsaXBzZSZiZz1GRkZGRkYmZm09cG5nMzImcz0wNmU4ZDAzNjI5N2Q0NTRmOGMzMDk1MTQ3ZDQ4OTg1OQ%2526blend-x%253D120%2526blend-y%253D467%2526blend-w%253D82%2526blend-h%253D82%2526blend-mode%253Dnormal%2526s%253D6b9dd9d4b2cb70a5b4abb956c8bd7df5%3Fixlib%3Drb-4.1.1%26w%3D1200%26fm%3Djpg%26mark64%3DaHR0cHM6Ly9xaWl0YS11c2VyLWNvbnRlbnRzLmltZ2l4Lm5ldC9-dGV4dD9peGxpYj1yYi00LjEuMSZ3PTk2MCZoPTMyNCZ0eHQ9Q2xhdWRlJTIwQ29kZSUyMCVFMyU4MiU5MiVFNiU5QyU4MCVFOSU4MCU5RiVFMyU4MSVBNyVFNCVCRCVCRiVFMyU4MSU4NCVFMyU4MSU5MyVFMyU4MSVBQSVFMyU4MSU5OSUyMDclMjAlRTMlODElQTQlRTMlODElQUUlRTUlQUUlOUYlRTglQjclQjUlRTMlODMlODYlRTMlODIlQUYlRTMlODMlOEIlRTMlODMlODMlRTMlODIlQUYlRTMlODAlOTAyMDI2JUU1JUI5JUI0JUU3JTg5JTg4JUUzJTgwJTkxJnR4dC1hbGlnbj1sZWZ0JTJDdG9wJnR4dC1jb2xvcj0lMjMxRTIxMjEmdHh0LWZvbnQ9SGlyYWdpbm8lMjBTYW5zJTIwVzYmdHh0LXNpemU9NTYmdHh0LXBhZD0wJnM9ZTAzODRmOGQ1Y2QxMzc2MGQ0OGMyNDEyMWE1NjA0ZWE%26mark-x%3D120%26mark-y%3D112%26blend64%3DaHR0cHM6Ly9xaWl0YS11c2VyLWNvbnRlbnRzLmltZ2l4Lm5ldC9-dGV4dD9peGxpYj1yYi00LjEuMSZ3PTgzOCZoPTU4JnR4dD0lNDBsb2NhbGxhYiZ0eHQtY29sb3I9JTIzMUUyMTIxJnR4dC1mb250PUhpcmFnaW5vJTIwU2FucyUyMFc2JnR4dC1zaXplPTM2JnR4dC1wYWQ9MCZzPWM1NGIxN2U0ZjAxZTM1M2Q5ZDAwZDk5OWQ3NTZmMzQ1%26blend-x%3D242%26blend-y%3D480%26blend-w%3D838%26blend-h%3D46%26blend-fit%3Dcrop%26blend-crop%3Dleft%252Cbottom%26blend-mode%3Dnormal%26s%3D6b20080725fa122e25b5754eaf3a583a&w=640&s=9qixKFyoFa-3_G6Gl1DUrnw0)