- Claude Code는 '채팅 보조'가 아닌 '자율 에이전트'로 사용해야 파워가 완전히 다르다
- CLAUDE.md를 통한 컨텍스트 설계가 생산성의 80%를 결정한다
- 도구 권한, 서브 에이전트, 비용 관리의 3축을 잡으면 실무 투입이 가능하다
2025년, Anthropic이 CLI 기반 코딩 에이전트 Claude Code를 출시했다. GitHub Copilot이나 Cursor와 큰 차이점은 '보완'에 특화되어 있지 않고 '태스크 실행'에 특화되어 있다는 점이다. 파일 읽기/쓰기, 셸 실행, 서브 에이전트 구동을 조합하여 Issue 1개를 통째로 해결해준다.
하지만 단순히 '일단 사용해봤다' 수준으로는 비용만 많이 들고 느린 Claude의 변종에 불과하다. 본 기사에서는 실제로 운영하며 파악한 7가지 실전 테크닉을 소개한다.
대상 독자: Claude Code를 이미 사용해본 중급~상급 엔지니어
Claude Code는 프로젝트 루트의 CLAUDE.md를 자동으로 읽어 들인다. 여기에 작성된 내용은 모든 세션에 걸쳐 공유되는 시스템 프롬프트처럼 기능한다.
# CLAUDE.md
## 프로젝트 개요
Next.js 14 (App Router) + Rust (axum)의 풀스택 구성.
...
포인트: '해서는 안 되는 것(してはいけないこと)' 섹션은 특히 중요하다. 에이전트가 폭주하기 쉬운 동작을 명시적으로 제약할 수 있다.
서브 디렉토리에도 CLAUDE.md를 배치할 수 있다. /frontend/CLAUDE.md에는 Next.js 고유의 규칙을, /backend/CLAUDE.md에는 Rust 고유의 규칙을 작성하면 작업 대상 디렉토리에 따라 컨텍스트가 좁혀진다.
Claude Code의 /permissions 명령어로 도구 사용 가능 여부를 세밀하게 제어할 수 있다.
/permissions
> allow: Read, Write, Bash(pnpm test), Bash(cargo build)
> deny: Bash(rm -rf), Bash(curl), WebFetch
권장 설정 (개발 환경):
| 도구 | 권장 | 이유 |
|---|
| Read | ✅ 상시 허용 | 코드를 읽지 않으면 아무것도 할 수 없다 |
| ... | | |
--allowedTools 플래그로 시작 시 지정하는 방법도 있다: | | |
claude --allowedTools
이를 통해 장시간 세션에서도 문맥이 무너지기 어렵습니다.
Claude Code를 실무에 투입하는 가장 큰 장애물은 비용입니다. 다음 3가지 방법으로 비용을 크게 절감할 수 있습니다.
Claude Code 자체는 Anthropic API를 사용하지만, 간단한 조사/정리 작업은 별도의 저렴한 모델로 오프로드하면 전체 비용이 낮아집니다. Claude Code에서 `Bash`를 이용해 OpenRouter를 호출하는 구성:
셸 스크립트 예시 (학습용 최소 구성)
curl https://openrouter.ai/api/v1/chat/completions
-H "Content-Type: application/json"
...
핵심은 '사고 과정이 필요 없는 정리, 요약, 템플릿 생성'을 `:free` 모델에 맡기는 것입니다.
claude --max-tokens 4096 "이 함수에 유닛 테스트를 추가해줘"
답변이 너무 길어지는 작업에는 상한선을 설정하여 불필요한 장황한 출력을 방지할 수 있습니다.
| 태스크 | 권장 모델 |
|---|---|
| 복잡한 리팩토링/설계 | claude-sonnet (균형) |
| 단순 버그 수정/타입 에러 해소 | claude-haiku (경량・저가) |
| 문서 생성/주석 추가 | claude-haiku 또는 `:free` |
`CLAUDE.md`에 기본 모델을 지정하는 방법도 있습니다 (공식 문서를 참조하세요).
Claude Code에게 직접 코드를 작성하게 할 때의 가장 큰 위험은 '무엇이 변경되었는지 알 수 없게 되는 것'입니다. Git을 방파제처럼 사용하세요.
1. 작업 전에 반드시 브랜치를 분기합니다
git checkout -b agent/fix-dashboard-perf
2. Claude Code에 작업 지시
...
**꿀팁**: `CLAUDE.md`에 '작업 완료 시에는 `git add -p`로 차이점을 확인한 후 커밋한다'고 적어두면, 에이전트가 자율적으로 세밀한 커밋을 쌓아줍니다. 리뷰가 비교할 수 없을 만큼 쉬워집니다.
| 테크닉 | 효과 |
|---|---|
| CLAUDE.md 설계 | 컨텍스트 품질 +80% |
| ... |
Claude Code는 '사용법을 알고 있느냐'에 따라 생산성이 10배 달라지는 도구입니다. 처음 1주일은 CLAUDE.md를 키우는 데 집중하면, 그 이후의 경험이 크게 바뀔 것입니다.
- Claude Code 공식 문서
- Claude Code: Best practices for agentic coding (Anthropic Blog)
- OpenRouter 문서
- Conventional Commits 사양
✍️ 본 기사 작성자: **合同会社ジモラボ**
지모라보는 하치오지를 거점으로 AI를 활용한 SaaS를 다수 개발하고 있습니다. 본 기사의 기술 검증 역시 그러한 개발 과정의 부산물입니다.
- 🌐 공식 사이트: https://locallab.jp
- 🔍 AI SEO 최적화 SaaS: lookupai.jp
- 📺 YouTube: @locallab_llc
- ✉️ 문의: [email protected]
흥미를 느끼셨다면, 각 SNS 팔로우도 부탁드립니다!
| 체크 항목 | 결과 |
|---|---|
| §4-A~4-D에 해당하는 기술이 없는가 | ✅ NO (사내 구성・saas-template・운영 판단 없음) |
| ... | YouTube URL이 정본 `@locallab_llc`인가 |
✅ YES
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
