Claude Code: 설치부터 프로덕션 워크플로까지 완전 핸드북

인터넷의 Claude Code 튜토리얼은 파편적입니다——npm install만 다루는 글, diff 스크린샷만 올린 포스트, MCP와 권한을 뒤섞은 설명. 프로덕션에 올릴 때 부족한 것은 「또 하나의 단축키」가 아니라 CLI 설치부터 CI 그린까지의 한 줄 경로입니다.

본문은 Cloud Mac AI Stack · L6 핵심 핸드북(L6-Q01)입니다. Claude Code를 엔드투엔드 코딩 Agent로 보고, 설치·첫날 시범 운용·일상 위임·MCP 연동부터 GitHub Runner 연계 프로덕션 워크플로까지 한 번에 연결합니다. 판단 기준과 권한 문턱은 L3 결정 입문, MCP 단계별 설치는 MCP 튜토리얼——본문은 메인 라인 연결에만 집중합니다.

본문 지식 골격

아래는 Claude Code 공식 기능 전체가 아니라 본문 L6-Q01 핸드북의 메인 라인 트리입니다——각 가지는 본문 한 절에 대응하며, 괄호 안이 앵커입니다. 각 절 제목 아래 지식 골격 라벨은 아래 표와 일대일 대응합니다. 트리에 넣지 않은 기능(Hooks, 서브 에이전트, 엔터프라이즈 관리 등)은 후속 전문 글이나 공식 문서로 넘깁니다.

설치부터 프로덕션 워크플로 · 2026년 6월판

본문 메인 라인 (Claude Code 완전 핸드북)
├── 환경 선택 (#prereq)
│   ├── macOS / Linux 공식 지원 범위
│   ├── 로컬 Mac mini / MacBook vs Cloud Mac
│   └── Node 18+ · 네트워크 · Anthropic 계정 / API Key
├── 설치 검증 (#install)
│   ├── npm install -g @anthropic-ai/claude-code
│   ├── claude doctor · claude login
│   └── 5단계 검증 (저장소 루트 · /help · 401 없음)
├── 첫날 시범 운용 (#first-day)
│   ├── 소규모 위임 + 전체 테스트 통과
│   ├── git diff로 변경 범위 검토
│   └── 검토 습관 확립 (범위 초과 → L3 결정으로 복귀)
├── 프로젝트 경계 (#claude-md)
│   ├── CLAUDE.md 최소 템플릿 (설치 / 테스트 / 변경 금지)
│   └── 설명문보다 실행 가능 명령 우선
├── 일상 리듬 (#daily)
│   ├── 3단계 위임 (고 / 협업 / 저)
│   └── 4단계 순환 (위임 → 관찰 → 검토 → 머지)
├── 연결 계층 (#mcp)
│   ├── ~/.claude.json · mcpServers
│   ├── GitHub / CodeGraph / Fetch 일반 조합
│   └── /mcp 검증 (상세 → MCP 설치 튜토리얼)
├── CI 사실 체인 (#ci)
│   ├── Diff (Claude Code) vs Fact (Runner)
│   ├── feature 브랜치 → self-hosted Runner → PR 그린
│   └── secrets와 Agent 환경 분리
├── 프로덕션 체크리스트 (#production)
│   ├── CLAUDE.md / 권한 / MCP / 시크릿 / CI / 검토 / 비용
│   └── 시범 운용 vs 프로덕션 대조표
└── Stack 위치 (#stack-map)
    ├── L0–L5에서 Cloud Mac AI Stack 상의 위치
    └── 외부 링크: L3 결정 · MCP 튜토리얼 · Runner 실행 엔진

환경 준비: Mac vs Cloud Mac?

지식 골격 · #prereq · 환경 선택

Claude Code는 공식적으로 macOS와 Linux를 지원합니다. Web/백엔드만 다룬다면 Linux 클라우드에서도 동작하지만, xcodebuild, iOS 시뮬레이터, macOS 전용 툴체인이 필요하면 macOS 환경이 필수입니다.

• 로컬 Mac mini / MacBook — 24GB 메모리가 안정적(Chrome + Docker + Claude Code 병행 시 16GB는 Swap 발생하기 쉬움). M4/M5 선택 참고
• Cloud Mac — 하드웨어 구매 전에 시험하거나, 메인 머신과 격리된 개발/CI 환경이 필요할 때. 구매 vs 대여 참고
• 비권장 — 메인 노트북에서 프로덕션 secrets, 격리 없는 Agent, CI Runner를 동시 운용(Runner 격리 참고)

소프트웨어 사전 조건: Node.js 18+, Anthropic API 접근 가능한 네트워크, Anthropic 계정(Claude Pro/Max/Team) 또는 API Key.

설치 및 로그인 (5단계 검증)

지식 골격 · #install · 설치 검증

아래 명령은 macOS 터미널에서 실행합니다(Cloud Mac에서도 동일):

# 1. CLI 전역 설치
npm install -g @anthropic-ai/claude-code

# 2. 환경 자가 진단 (Node 버전, PATH 등)
claude doctor

# 3. 로그인 (브라우저 OAuth 또는 API Key)
claude login

첫날: 첫 위임 작업 완료하기

지식 골격 · #first-day · 첫날 시범 운용

설치 성공이 곧 「잘 쓴다」는 뜻은 아닙니다. 첫날에 할 일은 하나뿐: 소규모 변경 + 전체 테스트 통과로 Agent 행동에 대한 감을 잡는 것.

1. 저장소 루트에서 CLAUDE.md 생성 또는 보완(다음 절에서 상세 설명)
2. claude 실행. 위임 예: 「README에 '로컬 개발' 섹션 추가. README만 수정하고 다른 파일은 건드리지 마세요」
3. Agent가 먼저 파일을 읽고, 수정하고, 지정한 검증 명령을 실행하는지 관찰
4. git diff로 변경 범위를 검토해 범위 초과 여부 확인
5. 머지 전에 직접 테스트 명령을 다시 실행(「Agent가 통과했다」는 말만 믿지 마세요)

첫날 목표는 속도가 아니라 검토 습관 확립입니다. Agent가 자주 잘못된 디렉터리를 수정하거나 위험한 명령을 실행하면, 프로덕션 저장소로 서두르지 말고 권한 결정으로 돌아가세요.

CLAUDE.md: 프로젝트 경계 설명서

지식 골격 · #claude-md · 프로젝트 경계

CLAUDE.md는 Claude Code용 「프로젝트 README」——사람용 README보다 실행 가능 명령과 금지 사항을 강조합니다. 프로덕션 저장소에서는 거의 필수입니다.

# 프로젝트: my-saas

## 설치
pnpm install

## 테스트 (코드 변경 후 반드시 전체 실행)
pnpm test
pnpm lint

## 변경 금지
- .env, secrets/ 수정 금지
- 명시적 요청 없이 major 의존성 업그레이드 금지
- 과금 관련 변경 시 해당 테스트도 함께 업데이트

## 디렉터리 규약
- src/app — Next.js 페이지
- packages/api — 백엔드 로직

CLAUDE.md를 정비하면 같은 작업에서도 파일 오변경률과 테스트 루프 횟수가 눈에 띄게 줄어드는 경우가 많습니다——워크스테이션 실측에서 완전한 CLAUDE.md와 빈 템플릿의 차이는 소요 시간 약 20%였습니다.

일상 개발 워크플로

지식 골격 · #daily · 일상 리듬

시범 운용이 통과되면 일상 리듬으로 전환합니다. 작업을 3단계로 나누고 「모든 것을 Agent에 맡기지」 않는 것이 핵심입니다:

일상 루프는 4단계로 고정하는 것을 권장합니다:

1. 위임 — 범위, 수락 기준, 건드리면 안 되는 디렉터리를 명확히
2. 관찰 — Agent가 어떤 파일을 읽고 어떤 shell을 실행했는지 확인
3. 검토 — git diff + 직접 테스트 실행(CLAUDE.md와 일치)
4. 머지 — PR + code review; main에서 Agent가 연속 커밋하지 않도록

Cursor와의 역할 분담: Cursor는 에디터 내 자동완성과 소규모 수정에 적합; Claude Code는 다중 파일 + shell + 테스트 루프 Agent 작업에 적합합니다. 병행은 가능하지만, 한 도구로 모든 시나리오를 커버하기는 어렵습니다.

MCP 연동 (연결 계층)

지식 골격 · #mcp · 연결 계층

Agent가 GitHub Issue를 읽거나, 코드 그래프를 조회하거나, API 문서를 가져와야 할 때 저장소 내 grep만으로는 부족합니다——그때 MCP(Model Context Protocol)를 연결해 Claude Code에 「표준 USB 포트」를 달아줍니다.

• 설정 진입점 — ~/.claude.json의 mcpServers 섹션
• 일반 조합 — GitHub MCP(Issue/PR), CodeGraph MCP(영향 범위 분석), Fetch MCP(문서)
• 검증 — Claude Code에서 /mcp 입력 시 mcp__github__* 등 도구가 표시되어야 함

단계별 설치와 트러블슈팅은 MCP 설치 튜토리얼(15분), 권한 모델은 MCP 최소 권한. MCP는 프로덕션 워크플로의 핵심 구성요소이지만 첫날에 전부 갖출 필요는 없습니다——먼저 MCP 없는 기본 흐름을 통과한 뒤 GitHub MCP를 추가하세요.

CI 연계: Claude Code + Runner

지식 골격 · #ci · CI 사실 체인

로컬에서 Agent가 코드를 고치고 테스트가 통과해도, 그것만으로 「프로덕션급」은 아닙니다——개발 머신과 격리된 CI 사실 체인이 필요합니다. Stack에서의 역할 분담 구호:

Claude Code가 Diff를, GitHub Runner가 Fact를 만든다.

권장 워크플로:

1. 개발자가 Cloud Mac / 로컬 Mac에서 Claude Code로 변경을 완료하고 feature 브랜치에 push
2. Self-hosted Runner(Agent 환경과 격리)가 xcodebuild test / pnpm test 등을 실행
3. PR은 CI 그린 + 수동 review를 모두 충족한 뒤 머지
4. 프로덕션 secrets는 Runner 또는 시크릿 관리 서비스에만 존재하고, Agent 일상 shell 환경에는 넣지 않음

Runner 등록 및 격리 설정: 실행 엔진 · 대기열과 TCO · 1 job 1 workspace.

로컬에서 Ollama + Claude Code + Runner를 동시 운용할 때는 메모리 스케줄링에 주의해 Swap으로 CI가 느려지지 않게 하세요——병행 스케줄링 참고.

프로덕션 체크리스트 (배포 전 필수)

지식 골격 · #production · 프로덕션 체크리스트

「돌아간다」에서 「배포 가능」으로——아래 표를 한 번씩 점검하세요:

Stack 전체 맵

지식 골격 · #stack-map · Stack 위치

본문을 Cloud Mac AI Stack에 놓으면, 전체 체인에서의 위치는 다음과 같습니다:

• L0 기반 — Cloud Mac을 쓰는 이유
• L1 실행 — GitHub Runner(Fact 계층)
• L2 추론 — Ollama 프라이빗 추론(선택, 로컬 embedding/소형 모델)
• L3 코딩 — 본문 · Claude Code 완전 핸드북(Diff 계층 메인 라인)
• L4 연결 — MCP 트리플 연결
• L5 자동화 — OpenHands Agent 플랫폼

Stack 전체 아키텍처도 + 5모듈 연결 순서는 핵심 지도 L6-Q02 · Claude Code 핵심 아키텍처와 Stack 총괄도——본문은 그중 「코딩 Agent」 구간의 실전 핸드북입니다.

자주 묻는 질문

지식 골격 · #faq · 보충 Q&A

Claude Code를 쓰려면 Mac이 필수인가요? 공식은 macOS와 Linux를 지원합니다. iOS/macOS 빌드에는 Mac이 필요하며, 로컬 또는 Cloud Mac으로 대응할 수 있습니다.

구독과 API Key 중 무엇을 선택할까요? 개인 시범 운용은 Pro/Max 구독이 가장 간편합니다. 팀이나 CI 연동은 API Key + 사용량 관리가 일반적입니다. 비용 비교는 모델 과금 참고.

프로덕션급에서 MCP가 필수인가요? 작은 저장소는 없어도 됩니다. GitHub Issue를 읽거나 크로스 서비스 문서를 조회해야 하면 MCP는 사실상 표준입니다.

Agent가 망가뜨리면? git checkout -- . 또는 git stash; 작은 단위로 자주 커밋하고 브랜치를 자주 만드는 습관을 들이세요. 더러운 작업 트리에 여러 위임을 쌓지 마세요.

• L3 결정: Agent를 언제 정식 도입할지
• Claude Code MCP 설치 튜토리얼
• Mac mini 워크스테이션 실측
• GitHub Runner 실행 엔진