클로드 코드 기능 총정리 — 5화 시리즈 로드맵

한 줄 요약: Claude Code의 모든 기능을 5가지 테마로 분류했다. 기초 → 자동화 → 협업 → 환경 → 고급 순서로 읽으면 전체 그림이 잡힌다.

Claude Code는 기능이 넓다. CLI 명령어, CLAUDE.md, MCP 서버, 에이전트 팀, GitHub Actions 연동, 권한 관리, 토큰 최적화, 트러블슈팅까지 — 모든 걸 한 글로 담으면 오히려 읽기 어렵다. 이 포스트는 Claude Code의 전체 기능을 5화 테마로 나누고, 어디서부터 읽어야 하는지 안내하는 로드맵이다. 시리즈를 처음 접하는 사람이든, 특정 기능을 찾는 중급자든 이 페이지에서 출발점을 잡으면 된다.

※ 2026년 3월 기준, Claude Code 공식 문서 및 사이트 내 가이드 시리즈 기반으로 작성됐습니다.

Claude Code의 기능은 크게 세 가지 이유로 단편 가이드로 담기 어렵다.

첫째, 기능 범위가 넓다. 설치와 인증이라는 입구부터 시작해 에이전트 팀 구성, GitHub Actions 자동화, 토큰 최적화, 런타임 에러 대응까지 — 사용 목적이 전혀 다른 독자가 같은 도구를 쓴다. 입문자에게 필요한 정보와 자동화 파이프라인을 구축하는 개발자에게 필요한 정보는 겹치지 않는다.

둘째, 기능 간 의존 관계가 있다. MCP 서버를 이해하려면 에이전트 개념이 먼저 잡혀야 한다. 권한 관리를 제대로 쓰려면 headless 모드 개념이 있어야 한다. 순서 없이 읽으면 맥락이 끊긴다.

셋째, 깊이가 다르다. 기초 셋업은 빠르게 훑어도 되지만 트러블슈팅과 토큰 최적화는 케이스별로 촘촘하게 다뤄야 실무에서 쓸 수 있다. 같은 포스트에 넣으면 둘 다 얕아진다.

이 시리즈는 아래 5개 테마로 나뉜다.

Claude Code를 처음 쓴다면 1화에서 시작한다. 설치와 인증을 마치고, CLI에서 무엇을 할 수 있는지 파악하고, CLAUDE.md로 프로젝트 컨텍스트를 잡는 것이 목표다.

다루는 내용

• 설치와 인증 — npm을 통한 설치, Anthropic 계정 연동, 첫 실행 확인
• CLAUDE.md — 프로젝트 루트에 놓는 컨텍스트 파일. Claude Code가 세션 시작 시 가장 먼저 읽는다. 작업 범위, 금지 사항, 자주 쓰는 명령어를 여기에 적어두면 매번 긴 프롬프트를 반복하지 않아도 된다.
• CLI 명령어와 슬래시 커맨드 — /plan, /compact, /context, /resume 등 대화형 세션에서 쓰는 핵심 슬래시 커맨드. claude --help로 보이는 플래그들의 실제 쓰임새.
• 설치~인증 트러블슈팅 — npm 권한 오류, 인증 실패, Node.js 버전 불일치 등 초기 셋업에서 자주 막히는 케이스.

관련 가이드

• Claude Code 가이드 #1 — 개요와 설치
• Claude Code 가이드 #2 — CLAUDE.md 완벽 가이드
• Claude Code 가이드 #3 — CLI 명령어 총정리
• Claude Code 가이드 #19 — 설치~인증 트러블슈팅

2화는 Claude Code를 사람 없이 돌리고 싶을 때 읽는다. 권한 인터럽트 없이 실행하는 방법, 스케줄러와 연동하는 방법, 허용할 도구 범위를 settings.json으로 고정하는 방법이 핵심이다.

다루는 내용

• --dangerously-skip-permissions — 권한 질문을 건너뛰는 플래그. 사용 조건과 리스크, 안전하게 쓰는 범위.
• allowedTools / settings.json — 프로젝트 또는 사용자 레벨에서 허용할 도구를 미리 지정해 실행 중 인터럽트를 최소화.
• headless 모드 (-p) — 대화 없이 프롬프트 하나로 결과를 반환하는 비대화형 실행. 스크립트에서 stdout을 받아 다음 단계로 넘길 수 있다.
• cron 자동화 — macOS launchd, Linux cron, GitHub Actions 스케줄러와 연동해 매시간 무인 실행.
• 리밋 감지와 재개 전략 — rate limit(429), 컨텍스트 초과, 구독 한도 소진 시 스크립트가 어떻게 반응하고 재시도하는지.

관련 가이드

• 클로드 코드 완전 자동화 #1 — 권한 질문 없이 실행하기
• 클로드 코드 완전 자동화 #2 — cron으로 매시간 무인 실행하기
• 클로드 코드 완전 자동화 #3 — 리밋 걸리면? 중단과 재개 전략

3화는 Claude Code 하나가 아니라 여러 에이전트를 조율하거나, 외부 서비스와 연결하고 싶을 때 읽는다. 에이전트 아키텍처, 팀 구성, Skills와 Hooks, MCP 서버 연결이 이 파트에 모여 있다.

다루는 내용

• 에이전트 & 서브에이전트 — Claude Code가 복잡한 작업을 처리할 때 내부적으로 어떻게 서브에이전트를 만들고 조율하는지. 작업 분해 전략.
• Agent Teams — 여러 Claude Code 인스턴스를 팀으로 묶어 역할을 분담하는 구성. orchestrator-worker 패턴, 권한 위임, 팀 내 컨텍스트 공유.
• Skills — 반복 작업을 슬래시 커맨드로 패키징하는 방법. 팀 전체가 같은 워크플로우를 재사용할 수 있다.
• Hooks — 특정 이벤트(파일 저장, 커밋, 빌드 완료 등)에 Claude Code 동작을 자동으로 트리거하는 방법.
• MCP 서버 연결 — Model Context Protocol로 외부 데이터 소스, API, 도구를 Claude Code에 연결. 설정 방법과 실전 활용 패턴.

관련 가이드

• Claude Code 가이드 #4 — MCP 서버 연결하기
• Claude Code 가이드 #5 — 에이전트 & 서브에이전트
• Claude Code 가이드 #13 — Agent Teams 실전 가이드

4화는 Claude Code를 어느 환경에서 쓰느냐에 따라 달라지는 내용이다. 터미널, VS Code, 데스크톱 앱의 차이부터 GitHub Actions CI/CD 연동, 웹 브라우저에서 실행, 코드 리뷰 자동화까지 커버한다.

다루는 내용

• 터미널 / VS Code / 데스크톱 앱 — 세 실행 환경의 차이. 어떤 상황에서 어떤 환경을 선택하는 게 맞는지 판단 기준.
• GitHub Actions 연동 — PR 생성, 커밋, 배포 이벤트에 Claude Code를 연결해 자동 리뷰·자동 수정 파이프라인 구성.
• 웹 & 리모트 실행 — 로컬 머신 없이 클라우드 환경에서 Claude Code를 실행하는 방법. SSH 터널, 원격 개발 서버 활용.
• 코드 리뷰 자동화 — Claude Code가 PR을 받아 자동으로 리뷰 코멘트를 달거나 수정 제안을 제출하는 파이프라인.

관련 가이드

• Claude Code 가이드 #6 — GitHub Actions 연동
• Claude Code 가이드 #7 — 터미널 vs VS Code vs 데스크톱

5화는 Claude Code를 실제로 운영하면서 부딪히는 문제들을 다룬다. 토큰과 비용 최적화, 보안과 권한 관리, 그리고 실제로 막히는 에러 케이스별 해결 경로가 이 파트에 있다.

다루는 내용

• 컨텍스트 & 토큰 최적화 — 200K 컨텍스트 창을 효율적으로 쓰는 방법. .claudeignore, /compact, CLAUDE.md 활용, 모델 선택으로 비용 줄이기.
• 보안 & 권한 관리 — allowedTools 범위 설정, API 키 보관, 민감 파일 제외, CI/CD 환경에서의 시크릿 처리.
• 트러블슈팅 종합 — 실행 중 발생하는 다양한 에러의 원인과 해결 경로. "케이스 → 원인 → 해결" 3단 구조로 정리.
• 설치~인증 트러블슈팅 — 설치 단계에서 막히는 케이스 집중 정리 (1화와 연계).

관련 가이드

• Claude Code 가이드 #9 — 트러블슈팅 & 팁 종합
• Claude Code 가이드 #19 — 설치~인증 트러블슈팅

목적에 따라 추천 읽기 순서가 다르다.

처음 설치하는 초보자

1화 순서대로 읽는다. 설치 → CLAUDE.md 작성 → CLI 기본 명령어 숙지. 막히면 19편 설치~인증 트러블슈팅을 참고한다.

1. 가이드 #1 — 개요와 설치
2. 가이드 #2 — CLAUDE.md 완벽 가이드
3. 가이드 #3 — CLI 명령어 총정리

자동화 파이프라인을 구축하려는 개발자

1화에서 headless 모드 개념만 잡고 바로 2화로 이동한다. cron, GitHub Actions, rate limit 대응 순서로 읽는다.

1. 가이드 #1 — 개요와 설치 (headless 섹션 중심)
2. 자동화 #1 — 권한 질문 없이 실행하기
3. 자동화 #2 — cron 스케줄링
4. 자동화 #3 — 리밋 대응

MCP 서버나 에이전트 팀을 쓰려는 중급자

1화로 기초를 다진 뒤 3화부터 읽는다. MCP 서버 → 에이전트 → Agent Teams 순서가 자연스럽다.

1. 가이드 #4 — MCP 서버 연결하기
2. 가이드 #5 — 에이전트 & 서브에이전트
3. 가이드 #13 — Agent Teams 실전 가이드

비용이 많이 나오거나 에러가 잦은 경우

5화부터 바로 읽는다. 트러블슈팅 → 토큰 최적화 → 보안 순서.

1. 가이드 #9 — 트러블슈팅 & 팁 종합
2. 자동화 #3 — 리밋 대응 전략

아래 표는 이 사이트에 있는 Claude Code 관련 가이드 전체 목록이다. 링크가 있는 항목은 현재 공개된 포스트다.

※ 링크 없는 항목은 순차적으로 공개 예정입니다. 공식 문서: code.claude.com/docs