Claude Code란 무엇인가?
공식 문서에는 다음과 같이 작성되어 있다.
Documentation Index
Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
Claude Code 개요
Claude Code는 코드베이스를 읽고, 파일을 편집하고, 명령을 실행하고, 개발 도구와 통합하는 에이전트 코딩 도구입니다. 터미널, IDE, 데스크톱 앱 및 브라우저에서 사용할 수 있습니다.
Claude Code는 기능을 구축하고, 버그를 수정하고, 개발 작업을 자동화하는 데 도움이 되는 AI 기반 코딩 어시스턴트입니다. 전체 코드베이스를 이해하고 여러 파일과 도구에 걸쳐 작업할 수 있습니다.
Claude Code 설치 후 생성되는 것들
시점별 생성 항목
1️⃣ npm install -g @anthropic-ai/claude-code 실행 시
~/.npm-global/
├── lib/node_modules/@anthropic-ai/claude-code/
│ ├── cli.js # 핵심 실행 파일 (13MB)
│ ├── package.json # 패키지 메타정보
│ ├── sdk-tools.d.ts # TypeScript 타입 정의
│ ├── vendor/ # 번들된 외부 라이브러리
│ └── node_modules/ # 추가 의존성
└── bin/
└── claude # 실행 명령어 파일2️⃣ claude 첫 실행 시
~/.claude/
├── settings.json # 전체 설정 파일
└── ... # 기본 폴더 구조 생성3️⃣ 로그인(인증) 후
~/.claude/
└── settings.json # 인증 정보(API Key 등) 저장4️⃣ 대화 시작 후
~/.claude/
├── history.jsonl # 전체 대화 히스토리
├── sessions/ # 세션별 대화 저장
├── session-env/ # 세션 환경변수
├── file-history/ # 파일 수정 이력
├── shell-snapshots/ # 쉘 상태 스냅샷
├── cache/ # API 응답 캐시
├── paste-cache/ # 붙여넣기 임시 저장
├── backups/ # 파일 백업본
├── stats-cache.json # 사용량 통계
└── plugins/ # 플러그인핵심 포인트
npm install만으로는~/.claude/폴더가 생성되지 않음claude명령어를 실제로 실행해야~/.claude/폴더 생성- 모든 데이터는 로컬 PC에만 저장 (Anthropic 서버에 영구 저장 X)
Claude Code핵심 개념
🔑 핵심 개념
CLAUDE.md
매 세션마다 자동으로 로드되는 영구 컨텍스트 파일이다.
프로젝트 컨벤션, 빌드 명령어, "절대 하지 말 것" 규칙 등 Claude가 항상 알아야 할 내용을 담는다.
핵심 포인트
200줄 이하로 유지 권장. 길어지면 Skills로 분리
작업 디렉토리부터 위로 올라가며 계층적으로 모두 로드됨 (additive)
CLAUDE.local.md — 개인용 메모, gitignore에 추가
위치: ~/.claude/CLAUDE.md (전역) 또는 프로젝트 루트 CLAUDE.md (프로젝트)
Commands (.claude/commands/)
- 사용자가
/명령어로 직접 트리거하는 것들 - 명시적인 액션 위주
- "내가 원할 때 실행"하는 느낌
예시
.claude/commands/
commit.md → /commit
deploy.md → /deploy
pr.md → /prSkills (.claude/skills/)
- Claude가 대화 흐름을 보고 알아서 로드하는 것들
- 지식/컨벤션 위주 — API 스타일 가이드, 코딩 패턴, 도메인 지식
- "Claude가 알아서 참고"하는 느낌
예시
.claude/skills/
api-conventions/ → API 설계 패턴 자동 참고
error-handling/ → 에러 처리 방식 자동 참고
test-patterns/ → 테스트 작성 패턴 자동 참고공식 문서 기준
Commands와 Skills는 동일한 메커니즘입니다.
둘 다 /명령어로 직접 호출 가능하고, 둘 다 Claude가 자동 감지해서 사용 가능합니다.
자동/수동 제어는 파일 위치가 아니라 프론트매터로 합니다.
# 수동 호출만 허용 (사용자만 트리거)
disable-model-invocation: true
# Claude만 자동으로 사용 (메뉴에서 숨김)
user-invocable: false실제 차이: 파일 구조
| Commands | Skills | |
|---|---|---|
| 파일 구조 | 단일 .md 파일 | 디렉토리 + SKILL.md |
| 추가 파일 지원 | ❌ | ✅ 스크립트, 예시, 레퍼런스 |
/명령어 직접 호출 | ✅ | ✅ |
| Claude 자동 감지 | ✅ | ✅ |
| 권장 여부 | 레거시 (계속 동작) | 현재 권장 방식 |
Skills 디렉토리 구조 예시
.claude/skills/deploy/
SKILL.md # 메인 지시사항 (필수)
checklist.md # 배포 체크리스트
scripts/
rollback.sh # 롤백 스크립트Commands의 단일 파일로는 위처럼 추가 파일을 묶을 수 없기 때문에
복잡한 워크플로우엔 Skills를 쓰는 것이 권장됩니다.
Agents (Subagents)
서브에이전트는 메인 대화와 분리된 독립 컨텍스트에서 실행되어 결과 요약만 반환한다.
많은 파일을 읽어야 하는 작업, 병렬 처리, 전문화된 워커에 적합합니다.
메인 컨텍스트를 오염시키지 않는 것이 핵심 장점이다. (예: 보안 리뷰 에이전트, 코드 분석 에이전트 등을 별도로 실행.)
name: security-reviewer
description: 보안 취약점 검토
allowed-tools: Read, Grep, Glob
---
보안 관점에서 코드를 리뷰하세요...위치: ~/.claude/agents/.md (전역) 또는 .claude/agents/.md (프로젝트)
Hooks
훅은 라이프사이클 이벤트(툴 실행 전/후, 세션 시작/종료, 프롬프트 제출 등)에 자동으로 실행되는 결정론적 스크립트이다.
LLM 없이 동작하는 자동화로 Git 훅처럼 Claude가 파일을 수정할 때마다 자동으로 ESLint를 실행하거나, rm -rf 실행 전에 차단하거나, 작업 완료 시 슬랙 알림을 보낼 수 있다.
settings.json에 설정:
{
"hooks": {
"PostToolUse": [{
"matcher": "Write",
"hooks": [{"type": "command", "command": "npm run lint"}]
}]
}
}주요 이벤트: PreToolUse, PostToolUse, SessionStart, SessionEnd
위치: ~/.claude/settings.json (전역) 또는 .claude/settings.json (프로젝트)
MCP (Model Context Protocol)
MCP는 Claude를 외부 서비스와 연결하는 프로토콜이다.
GitHub, 데이터베이스, Slack, 브라우저 등에 연결할 수 있습니다.
MCP 서버는 별도 프로세스로 실행되며 Claude에게 새로운 도구를 제공합니다.
{
"mcpServers": {
"github": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@anthropic/mcp-github"],
"env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
}
}
}우선순위: local > project > user
위치: .mcp.json — 프로젝트 루트 (팀 공유, git 커밋)
~/.claude.json — 개인 전역 MCP 서버
