Claude Code 명령어로 코드 짜기 — 사용법 중심 예제
“이론”이 아니라 실제 코딩 세션에서 어떤 명령·단축키를 언제 누르는가를 따라가는 문서다. 한 기능을 추가하는 세션을 처음부터 끝까지, 입력 → 동작 → 왜 순서로 보여준다. 관련: docs/06(루프 전체), docs/07(SDD/SpecKit 절차),
/clear상세. 명령·단축키는 Claude Code Commands·Interactive mode 기준(버전에 따라 바뀔 수 있음).
코드 작성에 직접 쓰는 명령·단축키 (먼저 보기)
| 입력 | 종류 | 하는 일 |
|---|---|---|
@경로/파일 | 입력 접두 | 파일을 대화에 첨부(자동완성). “이 파일을 봐”라고 말하는 가장 빠른 방법 |
Shift+Tab | 단축키 | 권한 모드 순환: default → acceptEdits → plan … |
/plan [설명] | 명령 | plan mode 진입. 코드를 건드리지 않고 계획만 세움 |
!명령 | 입력 접두 | 셸 모드. ! npm test처럼 직접 실행하고 출력을 대화에 넣음 |
Esc | 단축키 | Claude를 중간에 멈춤(한 일은 보존). 방향을 다시 잡을 때 |
Esc Esc | 단축키 | (입력칸이 비어있을 때) 되감기(rewind) 메뉴 — 코드/대화를 이전 지점으로 |
/rewind | 명령 | 되감기. 별칭 /undo, /checkpoint |
/context | 명령 | 컨텍스트 사용량을 그리드로 시각화 |
/compact [지침] | 명령 | 대화를 요약 압축(맥락 유지) |
/clear | 명령 | 대화를 통째로 비움(새 작업) → 상세 |
/memory / #... | 명령/접두 | CLAUDE.md에 규칙·메모 저장 |
/review [PR] | 명령 | PR을 현재 세션에서 로컬 리뷰 |
/model, /effort | 명령 | 모델·추론 강도 전환 |
/agents | 명령 | subagent 관리(큰 탐색을 격리된 컨텍스트에 위임) |
프롬프트에서
/를 치면 사용 가능한 명령 전체가 뜬다. 명령은 메시지 맨 앞에서만 인식된다.
실전 세션: “할인 쿠폰 적용” 기능 추가
기존 장바구니 코드에 쿠폰 할인을 넣는 작은 작업을 가정한다. 한 줄 한 줄 무엇을 입력하는지 본다.
1. 세션 시작 — 관련 파일을 @로 붙인다
> @src/cart.py @tests/test_cart.py 장바구니에 쿠폰 코드를 적용하는 기능을 추가하고 싶어.- 동작:
@를 치면 파일 경로 자동완성이 뜬다. 고른 파일이 대화에 첨부돼 Claude가 바로 읽는다. - 왜: “cart 파일 찾아줘”라고 시키는 것보다 빠르고, 엉뚱한 파일을 읽느라 컨텍스트를 낭비하지 않는다.
2. 바로 짜지 말고 — /plan으로 계획부터
> /plan 쿠폰 코드를 받아 장바구니 합계에 정률/정액 할인을 적용. 만료·중복적용 규칙 포함.또는 키보드로 Shift+Tab 을 눌러 모드를 plan으로 바꾼 뒤 요청해도 된다.
- 동작: plan mode에서는 Claude가 코드를 수정하지 않고 접근법·바꿀 파일·엣지 케이스를 정리해 제시한다. 사람이 승인해야 구현으로 넘어간다.
- 왜: 여러 파일·낯선 코드·설계 결정이 걸릴 때, 몇 분의 계획이 “20분간 자신만만하게 엉뚱한 걸 구현”하는 사태를 막는다. → docs/06 게이트 2, docs/04 경계
계획이 마음에 안 들면 그 자리에서 고쳐 말한다: > 정액 할인은 빼고 정률만. 만료는 서버 시간 기준으로.
3. 구현 — 모드를 전환해 편집을 맡긴다
계획을 승인하면 Shift+Tab 으로 acceptEdits 모드로 바꿔 편집을 빠르게 진행하게 하거나, 기본 모드로 매 편집을 확인한다.
- 동작:
acceptEdits는 파일 편집을 매번 묻지 않고 적용한다(검증이 갖춰진 작업에서 속도↑). 위험한 작업이면 기본 모드로 두고 사람이 확인한다. - 왜: 검증성이 높을수록(테스트가 받쳐줄수록) 자율 편집을 허용하고, 위험할수록 게이트를 건다.
4. 테스트 실행 — !로 직접 돌린다
> ! pytest tests/test_cart.py -q- 동작:
!셸 모드는 Claude를 거치지 않고 명령을 바로 실행하고, 출력을 대화 컨텍스트에 넣는다. Claude가 그 결과를 보고 다음 수정을 한다. - 왜: “테스트 돌려줘 → 권한 승인 → 결과 해석”보다 빠르고, 실패 로그가 그대로 맥락에 남아 디버깅이 매끄럽다. TDD 루프(Red→Green)를 이 한 줄로 돌린다. → docs/02 TDD
5. 방향이 틀어지면 — Esc로 끊는다
Claude가 엉뚱한 파일을 고치기 시작하면:
Esc한 번 → 현재 응답/도구 호출을 즉시 중단한다(지금까지 한 일은 남는다). 그리고 다시 지시한다:> 그 파일 말고 cart.py의 apply_coupon만 고쳐.
이미 잘못 만든 편집까지 되돌리려면:
- 입력칸을 비우고
Esc Esc(또는/rewind) → 되감기 메뉴에서 코드/대화를 이전 지점으로 복원한다. - 왜: 잘못된 변경을 손으로
git checkout하지 않고 세션 안에서 되돌릴 수 있다.
6. 대화가 길어지면 — /context → /compact
> /context # 컨텍스트 어디에 쓰이는지 그리드로 확인
> /compact 쿠폰 기능의 결정사항과 남은 작업만 남겨줘- 동작:
/context는 사용량을 보여주고,/compact는 대화를 요약본으로 줄인다(맥락 유지). - 왜: 작업을 이어가면서 토큰만 줄이고 싶을 때. 작업이 끝났으면
/compact대신/clear. → 차이 상세
7. 작업 종료 — /clear로 비우고 다음으로
> /clear- 동작: 대화 기억을 통째로 비우고 새 세션을 시작한다. 코드·파일·
CLAUDE.md는 그대로, 이전 대화는 보존되어 나중에 이어볼 수 있다. - 왜: 다음 기능으로 넘어갈 때 앞 작업의 맥락이 섞여 답이 흐려지는 것을 막는다.
8. 배운 것 저장 — # 또는 /memory
> # 쿠폰 만료는 항상 서버 UTC 기준으로 비교한다- 동작:
#로 시작하면 그 내용을CLAUDE.md(메모리)에 저장한다./memory로 직접 편집·관리할 수도 있다. - 왜:
/clear후에도 살아남아 다음 세션에 자동 적용된다. 같은 맥락을 매번 다시 설명할 필요가 없다. → docs/05 CLAUDE.md
9. 리뷰 — /review
> /review 128 # PR #128을 현재 세션에서 로컬 리뷰- 동작: 지정한 PR(또는 현재 변경)을 Claude가 리뷰한다.
- 왜: 머지 전 게이트 3에서 사람의 diff 리뷰를 보조한다(대체가 아니라 보조).
한 장 치트시트
@파일 → 볼 파일을 콕 집어 첨부
/plan·Shift+Tab→ 짜기 전에 계획 (plan 모드)
Shift+Tab → acceptEdits로 편집 위임 / default로 매번 확인
!명령 → 테스트·빌드 직접 실행 (출력이 맥락에 들어감)
Esc → 잘못 가면 즉시 중단
Esc Esc /rewind→ 코드·대화를 이전 지점으로 되감기
/context /compact → 길어진 컨텍스트 점검·압축
/clear → 작업 끝, 깨끗이 새 출발
# … / /memory → 배운 규칙을 CLAUDE.md에 저장
/review → 머지 전 리뷰 보조핵심 습관 3가지: ① 짜기 전에
/plan, ② 테스트는!로 돌려 맥락에 남기기, ③ 작업이 바뀌면/clear. 나머지는 필요할 때 하나씩 붙이면 된다.