들어가며
Anthropic의 Claude Code는 빠르게 진화하고 있지만, 공식 문서가 방대해서 전체를 파악하기 어렵다. 이 글은 Claude Code 공식 문서 전체를 섹션별로 리뷰하고 핵심 내용을 정리한 것이다. Build, Deployment, Administration, Configuration, Reference 등 모든 영역을 다루며, 문서를 직접 읽지 않아도 실무에서 필요한 인사이트를 빠르게 얻을 수 있도록 구성했다.
1. Build — 개발 환경 구축
시작하기 (Getting Started)
Claude Code는 npm install -g @anthropic-ai/claude-code로 설치하고, 프로젝트 디렉토리에서 claude를 실행하면 시작된다. Anthropic 계정 인증 후 바로 사용 가능하며, Max, Team, Enterprise, API 플랜을 지원한다.
일반적인 워크플로우 (Common Workflows)
공식 문서에서 강조하는 핵심 워크플로우:
- 코드 이해: "이 프로젝트의 아키텍처를 설명해줘"로 코드베이스를 빠르게 파악
- 코드 수정: 버그 수정, 기능 추가, 리팩토링을 자연어로 요청
- Git 통합: 커밋 메시지 자동 생성, PR 생성, 코드 리뷰
- 테스트: 테스트 코드 생성, 실행, 실패 분석
터미널 밖에서의 Claude Code (Outside of the Terminal)
- VS Code 확장: 에디터 안에서 Claude Code 실행. 인라인 코드 수정, 터미널 통합
- JetBrains 플러그인: IntelliJ, WebStorm 등에서 Claude Code 사용
- Claude Code on the Web: 브라우저에서 직접 Claude Code 실행
- Desktop 앱: Mac/Windows 전용 데스크톱 애플리케이션
Agent 개발 (Building Agents)
Claude Code를 에이전트의 기반으로 사용하는 방법. Claude Agent SDK를 통해 프로그래밍 방식으로 Claude Code를 제어할 수 있다. Multi-agent Teams 구성, 에이전트 간 작업 분배 등이 가능하다.
GitHub Actions 통합
CI/CD 파이프라인에 Claude Code를 통합하는 방법. PR이 올라올 때 자동으로 코드 리뷰를 수행하거나, 이슈가 생성되면 자동으로 구현을 시작하는 워크플로우를 구성할 수 있다.
2. Deployment — 배포 전략
대규모 배포 (Deploy at Scale)
조직 차원에서 Claude Code를 배포하는 전략. 라이선스 관리, 사용량 모니터링, 보안 정책 적용 등을 다룬다. Team이나 Enterprise 플랜에서는 관리자가 조직 전체의 Claude Code 사용을 중앙에서 관리할 수 있다.
보안 구성
프로덕션 환경에서의 보안 설정. 파일 접근 권한, 네트워크 접근 제한, MCP 서버 화이트리스트, 허용되는 명령어 목록 등을 설정할 수 있다. 특히 --dangerously-skip-permissions 없이도 안전하게 자동화를 구현하는 방법이 중요하다.
3. Administration — 관리
사용량 관리 (Usage Dashboard)
토큰 사용량, 비용, 활성 사용자 수 등을 모니터링하는 대시보드. Team/Enterprise 플랜에서 제공되며, 사용자별/프로젝트별 사용량을 추적할 수 있다.
접근 제어 (Access Control)
역할 기반 접근 제어(RBAC)를 통해 누가 어떤 기능을 사용할 수 있는지 관리한다. 관리자, 개발자, 뷰어 등 역할별로 권한을 차등 부여할 수 있다.
4. Configuration — 설정
설정 파일 구조
Claude Code의 설정은 여러 레벨로 나뉜다:
- 전역 설정:
~/.claude/settings.json— 모든 프로젝트에 적용 - 프로젝트 설정:
.claude/settings.json— 해당 프로젝트에만 적용 - 환경 변수:
CLAUDE_CODE_*접두사로 설정
권한 설정 (Permissions)
어떤 도구와 명령어를 자동 승인할지, 수동 승인이 필요한지를 세밀하게 지정한다. 정규식 패턴으로 허용/차단 규칙을 정의할 수 있다.
Hooks
특정 이벤트(도구 호출 전/후, 파일 수정 전/후 등)에 자동으로 실행되는 쉘 명령이다. 린터 자동 실행, 로깅, 알림 등에 활용한다. 예를 들어 파일이 수정될 때마다 자동으로 ESLint를 실행하거나, 위험한 명령이 실행될 때 슬랙 알림을 보내는 것이 가능하다.
상태 줄 구성 (Status Line)
터미널 하단에 표시되는 상태 줄의 내용을 커스터마이징한다. 현재 모델, 토큰 사용량, 컨텍스트 상태 등의 정보를 원하는 형식으로 표시할 수 있다.
MCP 서버 설정
MCP 서버를 프로젝트 레벨 또는 전역 레벨로 설정하는 방법. claude mcp add 명령어 또는 설정 파일 직접 편집으로 추가할 수 있다.
5. Reference — 참고 자료
CLI 참고 자료 (CLI Reference)
모든 CLI 옵션과 플래그를 정리한 레퍼런스. claude --help로 확인할 수 있는 것 이상의 상세한 옵션 설명이 포함된다.
대화형 모드 (Interactive Mode)
claude 명령어로 진입하는 대화형 모드의 모든 기능. 슬래시 명령어, 키보드 단축키, 파일 첨부, 이미지 분석 등을 다룬다.
슬래시 명령어 (Slash Commands)
/help— 도움말/compact— 컨텍스트 압축/memory— 메모리 관리/model— 모델 변경/commit— 커밋 생성/review— 코드 리뷰/simplify,/batch,/debug— 내장 스킬
체크포인팅 (Checkpointing)
Claude Code가 파일을 수정하기 전에 자동으로 Git 체크포인트를 생성하는 기능. 문제가 생기면 git diff로 변경사항을 확인하고 git checkout으로 되돌릴 수 있다. 실험적인 변경을 안전하게 시도할 수 있는 안전망이다.
Hooks 참조 (Hooks Reference)
사용 가능한 모든 Hook 이벤트와 설정 방법:
PreToolUse— 도구 호출 전PostToolUse— 도구 호출 후Notification— 알림 발생 시
플러그인 참조 (Plugins Reference)
MCP 서버를 통해 Claude Code의 기능을 확장하는 방법. 커스텀 MCP 서버 개발 가이드와 베스트 프랙티스가 포함된다.
6. 공식 문서 읽기 팁
38편의 공식 문서 리뷰 시리즈를 통해 얻은 교훈:
- 처음 쓰는 사람은 Getting Started → Common Workflows 순서로 읽으면 된다. 나머지는 필요할 때 참조하는 레퍼런스로 활용한다.
- Configuration은 반드시 읽어야 한다. 기본 설정만으로도 충분하지만, 권한 설정과 Hooks를 활용하면 생산성이 크게 올라간다.
- Reference는 책갈피해두자. CLI 옵션이나 슬래시 명령어는 외울 필요 없이 필요할 때 찾아보면 된다.
- Deployment/Administration은 팀 리드나 관리자에게 중요하다. 개인 사용자는 스킵해도 된다.
마무리
Claude Code의 공식 문서는 방대하지만 잘 구조화되어 있다. 처음에는 Getting Started와 Common Workflows로 시작하고, 익숙해지면 Configuration으로 최적화하며, 필요에 따라 Reference를 참조하는 것이 효율적인 학습 경로다.
특히 Hooks와 Permission 설정을 잘 활용하면 "매번 승인 버튼 누르기"와 "전부 자동 승인" 사이의 정확한 중간 지점을 찾을 수 있다. 이것이 Claude Code를 프로덕션에서 안전하고 효율적으로 운영하는 핵심이다.