클로드 코드 사용법을 다룬 글은 많지만, 대부분 「설치하고 첫 응답을 받는 데까지」에서 끝납니다. 정작 막히는 건 그다음입니다 — 같은 설명을 매번 반복하게 되고, 확인창이 너무 자주 뜨고, 작업이 한창일 때 5시간 사용량 창이 닫힙니다. 이 글은 입문 글이 끝나는 지점에서 시작해 그 세 가지를 차례로 정리합니다.
전제를 하나 맞추고 가겠습니다. 클로드 코드는 채팅창에 코드를 붙여 넣는 도구가 아니라 터미널에서 저장소 안에 상주하는 에이전트입니다. 파일을 읽고 고치고, 테스트를 돌리고, 커밋까지 합니다. 그래서 처음 할 일은 사용법을 외우는 것이 아니라 프로젝트의 규칙을 넘겨주는 것입니다.
첫 세 단계 — 실행, /init, 구체적인 요청
설치 직후에 할 가치가 있는 건 이 셋뿐입니다. 특히 두 번째 /init을 건너뛰면 이후 모든 세션에서 같은 설명을 반복하게 됩니다.
# 1. 프로젝트 디렉터리에서 실행한다 (이게 전제 조건입니다)
cd ~/work/my-app
claude
# 2. 첫 명령은 /init — 저장소를 읽고 CLAUDE.md를 만들어 줍니다
> /init
# 3. 이후엔 한국어로 그냥 부탁하면 됩니다. 파일 경로를 붙일수록 정확해집니다
> src/api/user.ts의 검증 로직을 zod로 바꾸고 테스트도 같이 고쳐줘/init은 저장소를 읽고 CLAUDE.md를 만들어 줍니다. 생성된 내용은 초안이므로 그대로 두지 말고 반드시 손으로 정리하세요. 다음 절이 그 내용에 대한 이야기입니다.
CLAUDE.md — 매번 설명하던 것을 한 번만 쓴다
CLAUDE.md는 프로젝트 루트에 두는 마크다운 파일이고 세션마다 자동으로 읽힙니다. 여기 적을 것은 「코드를 읽어도 알 수 없는 것」뿐입니다.
# CLAUDE.md — 프로젝트 루트에 두고 git에 커밋합니다
## 명령어
- 테스트: npm test (파일 하나만: npm test -- path/to/file)
- 타입 검사: npx tsc --noEmit
- 린트: npm run lint
## 규칙
- 날짜는 date-fns만 사용. moment 금지.
- API 핸들러는 app/api/**/route.ts에만 둔다.
- 커밋 메시지는 한국어, prefix는 feat / fix / docs.
## 건드리면 안 되는 곳
- db/migrations/ — 생성물. 직접 수정 금지.반대로 적지 말아야 할 것도 분명합니다. 디렉터리 구조나 함수 설명은 코드를 읽으면 나오므로 불필요합니다. CLAUDE.md는 매 요청에 함께 실리기 때문에 길어질수록 토큰을 씁니다 — 짧게, 규칙만. git에 커밋하면 팀 전체에 같은 규칙이 적용됩니다.
권한 — 확인창은 줄이되, 다 끄지는 않기
파일을 고치거나 명령을 실행할 때마다 확인창이 뜹니다. 안전장치이므로 전부 끄는 대신 읽기·검증 계열만 허용하는 선에서 맞추는 것이 실무적입니다. 세션 중에 「항상 허용」을 고르면 기억되고, .claude/settings.json에 적으면 프로젝트 단위로 고정됩니다.
모든 확인을 건너뛰는 플래그도 있지만 삭제와 원격 push까지 무확인이 됩니다. 망가져도 버릴 수 있는 컨테이너나 일회용 작업 트리 안에서만 쓰세요. 판단 기준은 --dangerously-skip-permissions를 언제 쓰는가에 정리돼 있습니다.
커스텀 명령 — 같은 부탁을 매번 타이핑하지 않기
리뷰, 릴리스 전 점검, 커밋 메시지 정리처럼 매번 거의 같은 방식으로 부탁하는 작업은 명령으로 만들어 둘 수 있습니다. .claude/commands/에 마크다운을 두기만 하면 됩니다.
# .claude/commands/review.md — 파일만 두면 /review로 쓸 수 있습니다
지정된 파일을 리뷰하고 다음 세 가지만 지적하세요.
1. 실제로 실패하는 조건이 있는 버그 (재현 방법 포함)
2. 기존 유틸리티로 대체 가능한 중복
3. 테스트가 없는 분기
스타일 취향은 지적하지 마세요.이러면 /review src/api/user.ts로 같은 관점의 리뷰가 돌아옵니다. git에 커밋하면 팀이 공유하게 되고, 리뷰 기준 자체를 저장소에 둘 수 있습니다. 실전에서 쓰이는 명령의 형태는 Claude Code workflows에 영어로 더 자세히 적어 두었습니다.
사용량 창이 닫혔을 때 이어가는 법
구독 사용량은 5시간 롤링 윈도우로 관리되고, 하필 작업이 붙는 오후에 닫힙니다. 상위 요금제로 올려도 그 순간 열리지는 않습니다. 실질적인 선택지는 셋입니다.
| 선택지 | 맞는 상황 |
|---|---|
| 창이 열릴 때까지 기다린다 | 마감이 없다. 몇 시간 미룰 수 있다 |
| 상위 요금제로 변경 | 매일 걸린다. 지속적으로 한도가 부족하다 |
| 그 작업만 API 키로 전환 | 오늘 끝내야 한다. 한 달에 몇 번만 걸린다 |
세 번째는 구독을 해지하지 않고 됩니다. 아래 두 줄이 설정된 동안에만 종량제로 청구되고, 변수를 지우면 구독으로 돌아갑니다.
# 사용량 창이 닫혀도 작업을 이어가는 두 줄.
# 이 변수가 설정된 동안에만 종량제로 청구되고, 지우면 구독으로 돌아갑니다.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...
# 보조 작업을 가장 싼 모델로 넘기는 한 줄 (매 세션 효과가 있습니다)
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5요율은 카탈로그에서 그대로 읽어옵니다: Claude Sonnet 4.6은 1M 토큰당 $1.20 / $6.00, Claude Haiku 4.5은 $0.40 / $2.00입니다. 선불 잔액에서 차감되므로 작업하지 않은 달에는 청구가 없습니다. 구독과 종량제 중 어느 쪽이 싼지, 손익분기점 계산은 클로드 코드 요금에 있고, 한국 카드로 결제가 막힐 때의 해결은 Claude API 가격·결제에, 사용량 창의 구조 자체는 클로드 프로 제한에 정리돼 있습니다.
결과가 좋아지는 요청, 나빠지는 요청
마지막으로 사용법의 차이가 가장 크게 드러나는 부분입니다. 파일 경로를 붙이면 탐색에 쓰는 토큰이 줄어 결과가 빠르고 정확해집니다 — 「검증 로직 고쳐줘」보다 「src/api/user.ts의 검증 로직을 zod로 바꿔줘」.
그리고 큰 작업을 한 번에 던지지 마세요. 변경 → 테스트 → 다음 변경으로 끊으면 실패했을 때 되돌아갈 지점이 분명해집니다. 오류가 났을 때의 구분법은 클로드 코드 오류 정리에 있습니다.
자주 묻는 질문
클로드 코드 사용법에서 가장 먼저 해야 할 일은?
프로젝트 디렉터리에서 claude를 실행한 뒤 /init을 한 번 돌리는 것입니다. /init은 저장소를 읽어 CLAUDE.md를 만들어 줍니다. 이 파일에는 테스트 실행 방법, 프로젝트 규칙, 건드리면 안 되는 경로를 적어 두며 이후 모든 세션에서 자동으로 읽힙니다. 이걸 건너뛰면 같은 설명을 매번 다시 쓰게 됩니다.
CLAUDE.md에는 무엇을 써야 하나요?
「매번 설명하게 되는 것」만 씁니다. 테스트와 타입 검사 명령, 프로젝트 고유의 규칙(이 라이브러리를 쓴다, 이 계층에는 로직을 두지 않는다), 수정하면 안 되는 생성물 경로 세 가지면 충분합니다. 반대로 코드를 읽으면 알 수 있는 디렉터리 구조나 함수 설명은 쓰지 마세요. CLAUDE.md는 매 요청에 함께 실려 나가므로 길어질수록 비용만 늘고 정확도는 오르지 않습니다.
5시간 사용량 제한에 걸리면 어떻게 하나요?
선택지는 세 가지입니다. 창이 다시 열릴 때까지 기다리거나, 상위 요금제로 올리거나, 그 작업만 API 키로 넘기거나. 세 번째는 ANTHROPIC_BASE_URL과 ANTHROPIC_AUTH_TOKEN 두 줄이면 되고 구독을 해지할 필요가 없습니다. 변수가 있는 동안에만 종량제로 청구되고 지우면 원래대로 돌아옵니다. 상위 요금제로 올려도 그 순간 창이 열리지는 않으므로, 마감이 있는 날에는 세 번째가 가장 빠릅니다.
매번 실행해도 되냐고 묻는 확인창을 줄일 수 있나요?
줄일 수 있습니다. 세션 중에 「항상 허용」을 고르면 기억되고, .claude/settings.json에 적으면 프로젝트 단위로 고정됩니다. npm test나 git status처럼 읽기·검증 계열만 허용해 두면 확인 횟수가 크게 줄어듭니다. 모든 확인을 건너뛰는 플래그도 있지만 삭제와 push까지 무확인이 되므로, 버려도 되는 컨테이너 안에서만 쓰세요.
커스텀 명령은 어떻게 만드나요?
.claude/commands/ 아래에 마크다운 파일을 두기만 하면 됩니다. review.md를 두면 /review로 호출됩니다. 내용은 자연어 프롬프트로 충분합니다. git에 커밋하면 팀 전체가 같은 명령을 쓰게 되므로, 리뷰 기준이나 릴리스 점검처럼 매번 같은 방식으로 부탁하는 작업을 저장소에 담아 둘 수 있습니다.
결과를 좋게 만드는 가장 확실한 요령은?
파일 경로를 구체적으로 붙이는 것입니다. 「검증 로직 고쳐줘」보다 「src/api/user.ts의 검증 로직을 zod로 바꿔줘」가 탐색에 쓰는 토큰이 적어 더 빠르고 정확합니다. 또 하나는 큰 작업을 한 번에 던지지 않는 것 — 변경 → 테스트 → 다음 변경으로 끊으면 실패했을 때 되돌아갈 지점이 분명해집니다.