Claude Code 정리

관련: AI 로드맵의 Claude Code 갈래 1단계 · 도구 선택은 AI 코딩 도구 지형도

📌 Claude Code란?

Claude Code는 터미널에서 직접 실행되는 AI 코딩 도구로, 자연어 명령으로 코드 작성·디버깅·Git 워크플로우를 수행한다. 별도 IDE나 채팅 창 없이 현재 작업 디렉토리에서 바로 동작한다.

• 터미널 통합 — 익숙한 개발 환경에서 바로 작업
• 실행 가능 — 파일 편집, 명령 실행, 커밋 생성 등 직접 액션 수행
• 프로젝트 인식 — 전체 코드베이스 구조 파악
• MCP 통합 — Google Drive, Slack 등 외부 데이터소스 연동
• Unix 철학 — 파이프로 조합·스크립트화 가능 (claude -p)

---

🚀 설치

npm으로 설치하려면 Node.js 18 이상이 필요하다 (네이티브 설치 프로그램을 쓰면 Node.js 불필요).

npm install -g @anthropic-ai/claude-code

cd your-project       # 프로젝트로 이동
claude                # 실행 — 처음이면 로그인 프롬프트

---

💡 주요 기능

1. 기능 구축

원하는 기능을 자연어로 설명하면 계획을 세우고 코드를 작성한다.

> 사용자 로그인 기능을 JWT 토큰 방식으로 추가해줘

2. 디버깅

버그 증상이나 에러 로그를 붙여넣으면 코드베이스를 분석해 수정한다.

> 로그인할 때 500 에러가 나. 에러 로그: [에러 내용]

3. 코드베이스 탐색

> 인증 로직이 어디에 구현돼 있어?
> 이 함수가 어떻게 동작하는지 설명해줘

4. 지루한 작업 자동화

Lint 수정, merge conflict 해결, release notes 작성, 문서 업데이트 등.

---

⌨️ 입력 모드와 단축키

입력 첫 글자로 모드 전환

입력	기능
!	Bash 모드 — 쉘 명령 직접 실행
/	슬래시 명령 모드
@	파일 경로 참조 (자동완성)

메모리에 기록은 /memory 명령으로 한다.

편집·제어 단축키

단축키	기능
Shift + Tab	권한 모드 순환 (아래 권한 모드 참고)
Shift + Enter	줄바꿈 (전송 안 함)
Tab	프롬프트 자동완성
Option/Alt + T	확장 사고(extended thinking) 토글
Ctrl + T	Todo 목록 표시
Ctrl + O	트랜스크립트(상세 출력) 토글
Ctrl + V	이미지 붙여넣기
ESC ESC	입력 지우기 / 되감기(rewind)

---

🎮 권한 모드

작업 승인 정책은 하나의 “모드”로 묶여 있고, Shift + Tab 으로 순환한다.

• default — 파일 변경·명령 실행 전마다 승인 요청 (가장 안전)
• acceptEdits — 파일 편집(Edit/Write)만 자동 수락, bash 등 나머지 도구는 정상 승인
• plan — 코드를 건드리지 않고 계획만 수립. 이때는 allow 규칙이 매칭돼도 편집·쓰기가 자동 승인되지 않는다 (복잡한 변경 전 전략 짜기)
• bypassPermissions — 도달하는 거의 모든 작업을 확인 없이 실행. CLI에서 흔히 “auto”라 부르는 게 이 모드다 (되돌리기 어려운 작업도 안 물어봄, 격리 환경에서만 권장)

시작 시 모드를 직접 지정하거나, /permissions로 허용·거부 규칙을 관리할 수 있다.

claude --permission-mode plan          # 특정 모드로 시작
claude --dangerously-skip-permissions  # 모든 권한 우회 (주의!)
> /permissions                         # 허용/거부 규칙 관리

---

🛠️ 주요 명령어

claude                       # 대화형 실행
claude -p "버그를 찾아 수정해줘"  # 헤드리스(print) 모드 — 실행 후 종료
claude --continue            # 또는 -c. 최근 대화 이어가기
claude --resume              # 또는 -r. 과거 세션 목록에서 골라 재개
claude --model <name>        # 시작 모델 지정 (예: claude-opus-4-8)
claude update                # 최신 버전으로 자체 업데이트
claude --safe-mode           # 모든 커스터마이즈(훅·플러그인 등) 끄고 시작 — 문제 격리용

슬래시 명령 전체 목록(기본/설정/Git/계정/통합 + 커스텀 커맨드)은 Claude Code 슬래시 명령어 사전에 따로 정리했다.

---

🆕 알아두면 좋은 기능

체크포인트 & 되감기 (/rewind)

Claude Code는 편집할 때마다 코드 상태를 자동으로 스냅샷(체크포인트)한다. /rewind 또는 ESC 두 번으로 코드와 대화를 특정 시점으로 되돌릴 수 있다 — 에이전트가 엉뚱한 방향으로 파일을 고쳤을 때 수동 git checkout 없이 즉시 복구된다.

플러그인 (/plugin)

슬래시 명령·서브에이전트·MCP 서버·훅을 한 묶음으로 설치하는 확장 방식. /plugin 으로 마켓플레이스에서 설치·관리한다. 팀 공용 워크플로우를 패키지로 배포할 때 유용하다.

컨텍스트 관리 (/context, /compact)

• /context — 현재 컨텍스트 윈도우를 무엇이 채우고 있는지 시각화
• /compact — 대화가 길어지면 요약해 공간 확보
• /usage — 사용량·한도 확인

모델·추론 조절 (/model, /effort)

세션 도중 /model 로 모델을, /effort 로 추론 강도를 바꾼다. Opus 계열에서는 /fast 로 빠른 출력 모드를 켤 수 있다(모델을 낮추는 게 아니라 같은 Opus로 더 빠르게 응답).

---

🔌 MCP (Model Context Protocol)

MCP로 Claude Code를 외부 데이터소스·도구와 연결한다. 프로토콜 자체의 개념은 MCP 개념 정리, 여러 서버를 붙이는 실전은 MCP 서버 더 붙이기에서 이어진다.

claude mcp add <name> -- <command...>   # 서버 추가 (stdio)
claude mcp list                         # 등록된 서버 목록
claude mcp get <name>                   # 서버 설정 확인
claude --debug                          # MCP 포함 디버그 로그

프로젝트 루트에 .mcp.json 을 두면 팀 전체가 공유한다.

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-puppeteer"]
    }
  }
}

---

📋 베스트 프랙티스

CLAUDE.md 로 프로젝트 컨텍스트 제공

프로젝트 루트의 CLAUDE.md 는 매 세션 자동으로 읽힌다. 기술 스택·코딩 규칙·디렉토리 구조를 적어 두면 매번 설명할 필요가 없다. 계층·import·.claude/rules·Auto Memory까지 깊게는 Claude Code 메모리 시스템 정리에서 다룬다.

# 프로젝트 개요
Next.js 기반 전자상거래 플랫폼.

## 코딩 규칙
- 함수형 컴포넌트, TypeScript strict
- 테스트 커버리지 80% 이상

## 구조
- `/app` 앱 라우터 · `/components` 컴포넌트 · `/lib` 유틸

복잡한 작업은 단계로 나눠 진행

연구 → 계획 → 구현 → 문서화. plan 모드로 계획을 먼저 받고 검토한 뒤 구현시키면 큰 변경의 사고를 줄인다.

Sub-Agents 로 작업 분담

/agents 로 코드 리뷰어·테스터 등 전문화된 서브 에이전트를 만든다. 각자 자체 지침과 권한을 가진다.

파이프라인으로 조합

tail -f app.log | claude -p "에러나 이상 징후가 보이면 요약해줘"

---

🔧 설정과 통합

설정 파일 위치

• 전역: ~/.claude/settings.json
• 프로젝트: .claude/settings.json (공유) · .claude/settings.local.json (개인 override)

컨텍스트 윈도우

Claude Code는 최신 Claude 모델(Opus·Sonnet 계열)을 사용한다. [1m] 컨텍스트를 지원하는 모델·플랜에서는 최대 1M 토큰까지 쓸 수 있다. 다만 효율을 위해 필요한 파일만 포함하고, 큰 CLAUDE.md 는 작은 문서로 쪼개는 게 좋다.

IDE 통합

VS Code·JetBrains(IntelliJ, PyCharm 등) 확장이 있어 터미널 없이도 사용할 수 있다.

비용

Claude API 토큰을 표준 API 가격으로 사용한다 (Claude 구독 또는 API 키 기반 과금).

---

🆘 트러블슈팅

• 응답 없음 — curl https://api.anthropic.com 로 연결 확인 후 재시작
• MCP 서버 문제 — claude mcp list / claude mcp get <name> 로 설정 확인, claude --debug 로 로그 확인

---

📚 추가 리소스

• Claude Code 공식 문서
• Claude Code GitHub
• Claude Code 베스트 프랙티스