Claude Code란?
Claude Code는 Anthropic이 만든 에이전틱 코딩 도구다. 일반적인 코드 자동완성이나 챗봇과 근본적으로 다르다. 코드베이스 전체를 읽고, 파일을 직접 편집하고, 터미널 명령어를 실행하며, 문제를 자율적으로 해결한다. 터미널 CLI, VS Code, JetBrains IDE, 데스크톱 앱, 웹 버전까지 다양한 환경에서 동작한다.
왜 이 도구를 제대로 배워야 하는가? Claude Code의 핵심 자원은 컨텍스트 윈도우인데, 이것이 빠르게 차오르면 성능이 급격히 떨어진다. Anthropic 공식 문서에 따르면 "대부분의 베스트 프랙티스는 하나의 제약에 기반한다: Claude의 컨텍스트 윈도우가 빠르게 차고, 차면 성능이 저하된다"고 명시하고 있다. 따라서 CLAUDE.md 설정, 슬래시 명령어, hooks, 메모리 시스템을 제대로 이해하고 활용해야 생산성을 극대화할 수 있다.
이 글의 대상과 난이도
- 대상 독자: Claude Code를 설치했거나 설치 예정인 개발자. 터미널 기본 조작이 가능한 수준이면 충분하다.
- 난이도: 입문 ~ 중급
- 예상 소요시간: 읽기 15분 / 따라하기 30분
- 다루는 범위: CLAUDE.md 작성법, .claude/rules/ 구조, Auto Memory, hooks, settings.json, 권한 관리, 슬래시 명령어, Plan Mode, 세션 관리
전체 구조
Claude Code의 작업 흐름은 6단계로 구성된다. 세션이 시작되면 CLAUDE.md, .claude/rules/, Auto Memory가 자동으로 컨텍스트에 주입된다. 이후 사용자가 프롬프트를 입력하면 Plan Mode 또는 Normal Mode로 처리되고, hooks가 도구 실행 전후에 자동으로 트리거된다. 최종적으로 파일 편집, 명령어 실행, 컨텍스트 관리가 이루어진다.
이 가이드에서는 각 단계를 순서대로 설정하는 방법을 다룬다. 모든 설정은 프로젝트 루트의 CLAUDE.md와 .claude/ 디렉토리에서 관리된다.
도구 선택
Claude Code에는 7가지 설정 도구가 있다. 이 가이드에서는 입문자가 반드시 알아야 할 CLAUDE.md, .claude/rules/, settings.json, hooks, Auto Memory 5가지를 집중적으로 다룬다. Skills와 Subagents는 중급/고급 기능이므로 별도 가이드에서 다룬다.
선택 기준: "Claude가 규칙을 따르면 좋겠다" 수준이면 CLAUDE.md로 충분하다. "반드시 매번 실행돼야 한다"면 hooks를 사용한다. Anthropic 공식 문서는 이 차이를 "advisory vs deterministic"으로 구분한다. CLAUDE.md는 권고사항이고, hooks는 강제사항이다.
실전 사용법
Step
1: CLAUDE.md 작성 (현재 1/5단계 | ~5분)
CLAUDE.md는 Claude Code가 세션을 시작할 때 자동으로 읽는 컨텍스트 파일이다. 프로젝트 규칙, 코딩 스타일, 빌드 명령어를 여기에 적어두면 매 세션마다 반복 설명할 필요가 없다.
가장 빠른 시작법: 프로젝트 디렉토리에서 /init 명령어를 실행한다. Claude가 코드베이스를 분석해서 빌드 시스템, 테스트 프레임워크, 코드 패턴을 감지하고 초기 CLAUDE.md를 자동 생성한다.
# Code style
- Use ES modules (import/export) syntax, not CommonJS (require)
- Destructure imports when possible
# Workflow
- Be sure to typecheck when you are done making a series of code changes
- Prefer running single tests, not the whole test suite, for performance
200줄 법칙: Anthropic 공식 문서는 CLAUDE.md를 200줄 이하로 유지할 것을 권장한다. 파일이 길어질수록 컨텍스트를 더 많이 소비하고, Claude의 규칙 준수율이 떨어진다. Reddit 사용자 u/DevMoses의 사례가 대표적이다. CLAUDE.md 규칙을 45줄에서 190줄로 늘렸더니 오히려 준수율이 감소했다고 보고했다. (출처: r/ClaudeCode)
CLAUDE.md 파일 위치별 역할:
~/.claude/CLAUDE.md: 모든 프로젝트에 공통 적용되는 개인 설정./CLAUDE.md또는./.claude/CLAUDE.md: 팀과 공유하는 프로젝트 규칙 (Git으로 관리)./CLAUDE.local.md: 개인 프로젝트 설정 (.gitignore에 추가)- 하위 디렉토리 CLAUDE.md: 해당 디렉토리의 파일을 작업할 때만 자동 로드
작성 원칙 체크리스트:
- 각 줄을 지웠을 때 Claude가 실수할 것인가? 아니면 이미 알고 있는 내용인가?
- Claude가 코드를 읽으면 스스로 파악할 수 있는 내용은 쓰지 않는다
- "깨끗한 코드를 작성하라" 같은 자명한 지시는 넣지 않는다
- 빌드/테스트 명령어, 코드 스타일 예외, 아키텍처 결정사항 위주로 넣는다
체크포인트:
/memory명령어를 실행했을 때 CLAUDE.md가 로드된 파일 목록에 표시되면 성공이다.
Step
2: .claude/rules/ 구성 (현재 2/5단계 | ~5분)
프로젝트가 커지면 CLAUDE.md 하나로는 한계가 있다. .claude/rules/ 디렉토리에 주제별 마크다운 파일을 분리하면 된다.
your-project/
.claude/
CLAUDE.md
rules/
code-style.md
testing.md
security.md
rules/ 파일의 핵심 기능은 paths 프론트매터를 통한 조건부 로딩이다. 특정 파일 유형을 작업할 때만 해당 규칙이 컨텍스트에 주입된다.
---
paths:
- "src/api/**/*.ts"
---
# API Development Rules
- All API endpoints must include input validation
- Use the standard error response format
이 방식의 장점은 컨텍스트 절약이다. 프론트엔드 작업 중에 백엔드 API 규칙이 컨텍스트를 차지하지 않는다. 대형 모노레포에서는 claudeMdExcludes 설정으로 다른 팀의 CLAUDE.md를 제외할 수도 있다.
체크포인트:
.claude/rules/디렉토리에 파일을 추가한 뒤/memory명령어로 해당 파일이 표시되는지 확인한다.
만약 rules 파일이 인식되지 않으면: 파일 확장자가
.md인지 확인한다..claude/rules/하위에 있는.md파일만 자동 탐지된다.
Step
3: Auto Memory 활용 (현재 3/5단계 | ~2분)
Auto Memory는 Claude가 세션 중에 학습한 내용을 자동으로 기록하는 시스템이다. 빌드 명령어, 디버깅 패턴, 코드 스타일 선호도 등을 ~/.claude/projects/<project>/memory/MEMORY.md에 저장한다.
사용자가 별도로 설정할 필요 없이 기본 활성화되어 있다. Claude Code v2.1.59 이상에서 지원된다. /memory 명령어로 현재 저장된 메모리를 확인하고 편집할 수 있다.
동작 원칙:
- MEMORY.md의 처음 200줄 또는 25KB(둘 중 먼저 도달하는 쪽)만 세션 시작 시 로드된다
- 상세 내용은 별도 토픽 파일(debugging.md, patterns.md 등)로 분리되고, 필요할 때만 읽는다
- "이 빌드는 pnpm을 사용한다"처럼 Claude가 반복적으로 물어보던 정보가 자동으로 축적된다
사용자 보정: "pnpm을 사용해라, npm 말고"라고 말하면 Claude가 Auto Memory에 저장한다. CLAUDE.md에 명시적으로 넣고 싶으면 "이걸 CLAUDE.md에 추가해줘"라고 말하면 된다.
체크포인트: 몇 번의 세션 후
/memory를 실행해서 Auto Memory 폴더에 파일이 생겼는지 확인한다.
Step
4: Hooks 설정 (현재 4/5단계 | ~10분)
Hooks는 Claude Code의 라이프사이클 특정 시점에서 자동 실행되는 셸 명령어다. CLAUDE.md의 "권고"와 달리 hooks는 "강제"다. 매번 예외 없이 실행된다.
hooks는 .claude/settings.json(프로젝트 레벨) 또는 ~/.claude/settings.json(사용자 레벨)에 설정한다.
실전 예시 1: 파일 편집 후 자동 포맷팅
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
}
]
}
]
}
}
Claude가 파일을 편집할 때마다 Prettier가 자동으로 실행된다. 수동으로 포맷팅할 필요가 사라진다.
실전 예시 2: 보호 파일 수정 차단 (PreToolUse)
#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")
for pattern in "${PROTECTED_PATTERNS[@]}"; do
if [[ "$FILE_PATH" == *"$pattern"* ]]; then
echo "Blocked: $FILE_PATH matches protected pattern" >&2
exit 2
fi
done
exit 0
PreToolUse hook에서 exit code 2를 반환하면 해당 도구 실행이 차단된다. exit 0은 허용이다. Claude는 차단 사유를 피드백으로 받아서 다른 방법을 시도한다.
실전 예시 3: 작업 완료 알림 (Notification)
{
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
}
]
}
]
}
}
Claude가 입력을 기다릴 때 데스크톱 알림이 뜬다. 다른 작업을 하면서 Claude를 백그라운드로 돌릴 때 유용하다.
체크포인트:
/hooks명령어로 설정된 hooks 목록이 표시되면 성공이다.
만약 hook이 실행되지 않으면: (1)
/hooks에서 올바른 이벤트 아래 등록됐는지 확인 (2) matcher의 대소문자가 정확한지 확인 (Edit|Write는 되지만 edit|write는 안 된다) (3) 스크립트 파일의 실행 권한 확인 (chmod +x)
Step
5: 권한과 슬래시 명령어 (현재 5/5단계 | ~5분)
권한 모드 4가지:
- prompt (기본): 매번 승인 요청. 안전하지만 번거롭다
- allowlist: settings.json에서 특정 도구만 자동 허용.
/permissions명령어로 관리 - auto mode: 분류기 모델이 위험도를 판단해서 자동 허용/차단. 2026년 추가된 기능으로, 범위 확대나 알 수 없는 인프라 접근만 차단한다
- dangerously-skip-permissions: CI/CD용. 모든 권한 검사 생략
대부분의 일상 작업에서는 auto mode가 적절하다. /permissions에서 자주 쓰는 도구(예: Edit, Bash(git commit:*))를 allowlist에 추가하면 승인 클릭 횟수를 크게 줄일 수 있다.
핵심 슬래시 명령어:
| 명령어 | 기능 | 사용 시점 |
|---|---|---|
/clear | 컨텍스트 완전 초기화 | 다른 작업으로 전환할 때 |
/compact | 대화 요약 압축 | 같은 작업 중 컨텍스트가 길어졌을 때 |
/memory | 로드된 파일 확인, Auto Memory 관리 | CLAUDE.md가 제대로 인식됐는지 확인 |
/hooks | 설정된 hooks 목록 조회 | hook 동작 확인 |
/permissions | 도구 허용/차단 관리 | allowlist 설정 |
/init | CLAUDE.md 자동 생성 | 프로젝트 초기 설정 |
/rewind | 이전 체크포인트로 복원 | 실수 되돌리기 |
/btw | 사이드 질문 (컨텍스트에 남지 않음) | 빠른 확인이 필요할 때 |
Plan Mode (Shift+Tab): 코드를 실행하지 않고 계획만 세우는 모드다. 5개 이상의 파일을 수정해야 하거나 DB 스키마 변경이 포함된 작업 전에 사용한다. 계획 확인 후 Ctrl+G로 텍스트 에디터에서 직접 편집할 수도 있다.
세션 관리 팁:
claude --continue: 마지막 세션 이어서 작업claude --resume: 최근 세션 목록에서 선택/rename: 세션에 이름 부여 (예: "oauth-migration")- 2번 이상 같은 실수를 수정했다면
/clear후 더 구체적인 프롬프트로 새 세션 시작. 누적된 실패 맥락이 성능을 저하시킨다
트러블슈팅
CLAUDE.md 규칙을 무시할 때
/memory로 파일이 실제로 로드됐는지 확인한다. 목록에 없으면 파일 위치가 잘못된 것이다- 파일이 200줄을 초과하면 규칙이 "묻힌다".
.claude/rules/로 분리하거나@path/to/import문법으로 외부 파일을 참조한다 - 두 CLAUDE.md 파일 간에 규칙이 충돌하면 Claude가 임의로 하나를 선택한다. 주기적으로 충돌 여부를 점검한다
- 강조가 필요한 규칙에는 "IMPORTANT" 또는 "YOU MUST"를 붙이면 준수율이 올라간다
/compact 후 규칙이 사라질 때
CLAUDE.md는 compaction 후에도 디스크에서 다시 읽어서 재주입된다. 사라진 것처럼 보이는 규칙은 대화 중에만 언급했고 CLAUDE.md에 기록하지 않은 것이다. 지속적으로 유지해야 하는 규칙은 반드시 CLAUDE.md에 넣는다.
Hook이 실행되지 않을 때
/hooks메뉴에서 올바른 이벤트에 등록됐는지 확인- matcher의 대소문자 확인 (case-sensitive)
- 스크립트를 수동으로 테스트:
echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh && echo $? - 스크립트 실행 권한 확인:
chmod +x - JSON 파싱 에러: 셸 프로파일(~/.zshrc)에 echo 문이 있으면 hook 출력에 섞인다.
if [[ $- == *i* ]]조건으로 감싸야 한다
Stop hook이 무한 루프에 빠질 때
Stop hook 스크립트에서 stop_hook_active 필드를 확인하지 않으면 무한 반복된다.
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
exit 0
fi
더 알아보기
- 심화 학습 경로: Claude Code 공식 문서의 "Common workflows" 페이지에서 디버깅, 테스트, PR 생성 등 실전 레시피를 확인할 수 있다. Skills와 Subagents를 활용한 고급 워크플로우는 "Extend Claude Code" 문서에서 다룬다.
- 관련 도구/서비스: Claude Code는 Anthropic의 Claude Sonnet 4, Claude Opus 4 모델을 기반으로 동작한다. GitHub CLI(gh), MCP 서버(Notion, Figma 등), Prettier 같은 코드 포맷터와 연동하면 생산성이 더 올라간다.
- 커뮤니티 참고 자료: r/ClaudeCode 서브레딧은 주간 활성 기여자 4,200명 이상으로 AI 코딩 에이전트 중 가장 활발한 커뮤니티다. 실사용 팁과 트러블슈팅 사례를 얻기에 좋다. (출처: 2026년 초 기준, DEV Community 집계)
