Claude Code 공식 문서 1시간 요약

1. Claude Code 가 뭐야?

Claude Code 공식 Overview 기준으로 한 문장:

"An agentic coding system" — 터미널에서 돌며, 파일을 읽고·명령을 실행하고·코드를 수정하는 AI 에이전트.

채팅봇이 아니라 에이전트 라는 구분이 중요합니다. 사용자가 질문하면 답만 주는 게 아니라, 스스로 파일을 뒤져보고, 테스트 돌리고, 실패하면 고치고, 다시 돌려보는 피드백 루프를 갖고 있어요.

핵심 실행 사이클

전통적 AI 채팅과의 결정적 차이: 사용자가 코드를 쓰고 리뷰를 요청하는 게 아니라, 사용자가 원하는 결과를 설명하면 Claude 가 탐색·계획·구현까지 전부 처리합니다.

2. 설치와 첫 실행

Quickstart 공식 문서 에 풀 버전이 있습니다. 핵심만.

설치 (권장: 네이티브)

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

Homebrew, WinGet, VS Code 확장, JetBrains 플러그인 등 다른 방법은 Quickstart 공식 문서 참고.

인증

셋 중 하나:

• Claude Pro / Max / Team / Enterprise 구독
• Anthropic Console API 키 (선불 크레딧)
• Amazon Bedrock / Google Vertex AI / Microsoft Foundry (기업용)

첫 실행

cd your-project
claude          # 첫 실행 시 로그인 화면

프로젝트 루트로 가서 claude 한 번 치면 끝. 그 뒤론 그냥 자연어로 뭐든 시켜보면 됩니다.

3. 1 시간 안에 알아야 할 핵심 기능들

공식 문서에 등장하는 기능 중 실전 생산성에 가장 직접적으로 영향 미치는 7 가지.

3-1. Plan Mode — "읽기만 하고 수정 안 하는 모드"

• Shift+Tab 으로 순환하거나 --permission-mode plan 으로 진입.
• 이 모드에서 Claude 는 파일을 읽고 분석하지만 변경을 일절 하지 않습니다.
• 복잡한 작업은 항상 Plan → 일반 모드 두 단계로 분리하는 게 공식 권장 패턴.
• Ctrl+G 로 Claude 가 만든 계획을 에디터에서 직접 편집 후 다시 넘길 수 있음.

3-2. Sub-agents — 메인 컨텍스트를 보호하는 조사 위임

• .claude/agents/ 아래 마크다운 파일로 정의. tools, model, 시스템 프롬프트를 개별 지정.
• 서브에이전트는 빈 컨텍스트로 시작해서 요약만 메인에 돌려줍니다.
• 파일 100 개 조사 같은 작업은 서브에이전트에 위임하면 메인 컨텍스트가 거의 안 줄어들어요.
• 공식 문서: Sub-agents

3-3. Hooks — 결정론적 자동화 트리거

• PreToolUse, PostToolUse, SessionStart, Stop 같은 이벤트에 쉘 명령을 자동 실행.
• CLAUDE.md 지시가 "조언" 이라면 훅은 강제 예요. Claude 가 무시할 수 없음.
• 설정 위치: .claude/settings.json.
• 공식 문서: Hooks Reference, Hooks Guide

3-4. Skills — 필요할 때만 로드되는 워크플로

• .claude/skills/ 아래 마크다운 파일. /skill-name 으로 직접 호출하거나 Claude 가 관련성 판단 시 자동 적용.
• CLAUDE.md 와 달리 필요할 때만 컨텍스트에 로드 되어 토큰을 아낍니다.
• 공식 문서: Skills

3-5. MCP (Model Context Protocol) — 외부 시스템 연결

• 오픈 표준으로 Notion, Figma, Jira, Slack, 데이터베이스 등과 연동.
• claude mcp add 로 서버 추가.
• 공식 문서: MCP

3-6. CLAUDE.md 메모리 — 프로젝트 영속 지침

• 매 세션 시작 시 자동 로드되는 마크다운.
• 계층(높은 우선순위 순): CLAUDE.local.md → ./CLAUDE.md → ~/.claude/CLAUDE.md → 조직 관리 경로
• Auto memory (v2.1.59+) 는 세션 중 Claude 가 스스로 학습한 내용을 ~/.claude/projects/<project>/memory/MEMORY.md 에 자동 저장.
• 자세한 건 Compact 활용법과 CLAUDE.md 메모리 전략 참고.

3-7. Agent SDK — 스크립트·CI 에서 Claude Code 호출

• Python, TypeScript 패키지 + CLI -p 플래그로 제공.
• CI/CD 파이프라인, 배치 작업, 서버 자동화에 통합 가능.
• 공식 문서: Agent SDK Overview, Headless / Programmatic Use

4. 공식 문서 지도

처음 보면 어디서 시작해야 할지 모르겠는 공식 문서를 "이것부터 읽어라" 순서로 8개만 뽑았습니다.

나머지 전체 URL 목록은 docs/llms.txt 에서 기계가독 포맷으로 볼 수 있어요. CLI Reference, env-vars, IDE 통합 등은 필요할 때 여기서 점프하면 됩니다.

5. 공식 문서 사이에 숨은 팁들

더 많은 환경변수가 궁금하면 공식 env-vars 페이지 를 직접 참고하세요.

6. 실전 CLI 예시

공식 문서에 흩어져 있는 패턴 중 가장 재사용 가치 있는 것들.

예시 A. 파이프로 로그 분석

tail -200 app.log | claude -p "Slack me if you see any anomalies"

예시 B. CI 에서 변경 파일 보안 리뷰

git diff main --name-only | claude -p "review these changed files for security issues"

예시 C. 세션 재개로 멀티턴 자동화

# 첫 요청 (세션 ID 추출)
session_id=$(claude -p "Review this codebase for performance issues" \
  --output-format json | jq -r '.session_id')

# 같은 세션에서 후속 요청
claude -p "Now focus on the database queries" --resume "$session_id"
claude -p "Generate a summary of all issues found" --resume "$session_id"

예시 D. Plan Mode → 구현 2 단계 분리

# 1단계: 읽기만 (변경 없음)
claude --permission-mode plan
# 프롬프트: "read /src/auth and understand the session flow"

# 2단계: 구현 (일반 모드)
claude -p "implement the OAuth flow from your plan. write tests and run them." \
  --allowedTools "Bash,Read,Edit"

예시 E. JSON 출력으로 파이프라인 통합

claude -p "List all API endpoints" --output-format json | jq '.result'

7. 버전·호환성 메모

• 공식 문서 도메인이 docs.anthropic.com/en/docs/claude-code/* 에서 code.claude.com/docs/en/* 로 이전됐어요. 301 리다이렉트는 되지만 새 링크를 쓰는 게 안전.
• Auto memory 는 v2.1.59 이상에서만 동작. claude --version 으로 확인.
• --effort max 는 Opus 4.6 전용.
• Homebrew / WinGet 설치본은 자동 업데이트가 없습니다. 주기적으로 수동 업그레이드 필요.
• Windows 설치 시 Git for Windows 선행 설치 필요.

8. 다음에 읽을 글

공식 문서를 한 시간 훑고 나면, 이 글들이 구체적인 실전 깊이로 들어갈 수 있게 해줍니다.

• Claude Code 네이티브 슬래시 커맨드 카탈로그 — 이 글에서 언급한 커맨드들의 풀 카탈로그
• Compact 활용법과 CLAUDE.md 메모리 전략 — 3-6 절에서 요약한 메모리를 실전 수준으로 확장

참고 자료 (Primary sources)

공식 문서 (Anthropic)

• Overview — Claude Code 가 무엇인지
• Quickstart — 설치·첫 실행·기본 커맨드
• Best Practices — Anthropic 내부 팀 검증 패턴
• CLI Reference — 전체 플래그·명령
• Environment Variables — 숨은 env var 의 출처
• Memory — CLAUDE.md 계층·auto memory
• Sub-agents
• Hooks Reference
• Headless / Programmatic Use — claude -p CLI 패턴
• Docs index (llms.txt)