Claude Code Workflow란? — 쉽게 알려드리는 4단계 입문 가이드

비유부터 먼저 드릴게요. Claude Code 워크플로우는 유능한 페어 프로그래머가 옆자리에 앉아, 코드베이스를 같이 탐색하고, 작업 계획서를 먼저 쓰고, 실제 코드를 작성한 뒤, git에 커밋까지 해주는 4단계 협업 루틴이에요. 매번 명령을 일일이 내리지 않고, "원칙"만 정해두면 AI가 그 원칙대로 일해요.

이 글은 Anthropic 공식 문서 11편을 기반으로 한국어 초보자가 한 번에 이해할 수 있도록 정리한 입문 가이드예요. 코드 한 줄도 안 써본 분이라도 따라올 수 있게 비유 위주로 풀었어요.

Claude Code 워크플로우 4단계 다이어그램

1. 한 줄 정의 — "사고 흐름의 약속"

기술적으로 정의하면, Claude Code 워크플로우란 Anthropic 공식 Common Workflows 문서에서 권장하는 터미널 기반 agentic 코딩 도구 Claude Code를 효과적으로 사용하기 위한 반복 가능한 작업 패턴 집합이에요.

핵심은 4겹 구조예요.

1. Plan Mode로 작업 범위 합의
2. subagent / skill / slash command로 컨텍스트 분리
3. hooks로 결정론적 가드 추가
4. MCP로 외부 도구 연결

워크플로우는 단축키 모음이 아니라, AI에게 "어떻게 일할지" 가르치는 매뉴얼이에요. 그래서 도구 사용법보다 협업 방식 디자인이 본질이에요.

2. 핵심 4단계 워크플로우 (Explore → Plan → Code → Commit)

Anthropic은 모든 작업의 골격으로 4단계 흐름을 권장해요. 특히 3파일 이상 변경되거나 핵심 로직이 움직이는 작업에서 효과가 커요.

2.1 Explore — 코드베이스 탐색

먼저 AI에게 코드베이스를 같이 읽혀요. "auth 시스템이 어디에 있고, 어떤 파일에서 토큰을 갱신하는지 파악해줘" 같은 요청이에요. 이 단계는 무거운 탐색이라서 보통 subagent에 위임해요.

2.2 Plan — Plan Mode (Shift+Tab)

Shift+Tab으로 Plan Mode를 토글하면 Claude가 코드 수정 전에 계획서를 먼저 보여줘요. VS Code에서는 plan이 마크다운 문서로 자동으로 열리고, 인라인 코멘트로 피드백을 줄 수 있어요.

비유: 인테리어 공사 전에 도면을 합의하고 시작하는 거예요. 도면 없이 벽 다 뜯어내고 "어, 여기 화장실 있었어요?" 사고를 막아주는 안전장치예요.

2.3 Code — 실제 구현 (TDD 권장)

계획이 확정되면 Claude가 실제 코드를 작성해요. 이 단계에서 가장 추천되는 패턴이 TDD예요. 3장에서 자세히 다뤄요.

2.4 Commit — git까지 AI가

Code가 끝나면 Claude가 변경 사항을 staging하고 commit 메시지까지 작성해요. 코드 리뷰가 필요한 PR은 GitHub Actions와 연계해서 자동 리뷰까지 갈 수 있어요. (GitHub Actions 통합 가이드 참고)

3. 가장 강력한 패턴 — TDD

Anthropic이 공식 best practice 문서에서 **"가장 강력한 단일 패턴"**으로 명시한 게 TDD예요. (Claude Code Best Practices 참고)

순서가 핵심이에요.

# 1단계: 테스트 먼저 작성
$ vim tests/test_auth.py  # 아직 구현되지 않은 함수의 테스트 작성

# 2단계: 실패 확인
$ pytest tests/test_auth.py
# FAILED — 실패해야 정상

# 3단계: 실패 테스트를 commit
$ git add tests/test_auth.py && git commit -m "Add failing auth tests"

# 4단계: Claude에게 지시
> 테스트 수정하지 말고, 전부 통과할 때까지 구현해줘

red-to-green 사이클이에요. 모호한 요구사항보다 실패하는 테스트 한 줄이 훨씬 명확한 검증 신호를 줘요.

내부 가이드 더 보기: Claude Code 시작하기

4. Subagent, Slash Command, Skill — 헷갈리는 5가지 정리

이 다섯 단어가 비슷해 보여서 입문자분들이 가장 많이 헷갈리는 부분이에요. 비유로 풀게요.

2026-05월 v2.1.137+에서 공식 Plugin Marketplace가 정식 배포됐어요. 공식 디렉토리(claude-plugins-official)는 55+ 큐레이션 플러그인을, 커뮤니티 마켓플레이스는 72+ 플러그인을 제공해요.

Subagent의 핵심 가치는 별도 컨텍스트 윈도우예요. "auth 시스템의 토큰 갱신 로직 조사" 같은 탐색 작업을 subagent에 위임하면, 메인 세션의 200K 토큰을 보호하면서 결과 요약만 회수할 수 있어요. (Subagents 공식 문서)

5. Hooks와 MCP — 결정론적 가드 + 외부 도구 연결

Hooks — 공항 보안 검색대

Hooks는 Tool 실행 패턴에 매칭되어 자동 실행되는 결정론적 셸 명령이에요. (Hooks 공식 문서)

• PreToolUse: 위험 명령 차단 (예: rm -rf 실행 전 검증)
• PostToolUse: 파일 저장 후 자동 lint/prettier 실행

MCP 도구는 mcp__<server>__<tool> 패턴으로 명명되므로 hook에서 정확히 매칭할 수 있어요.

MCP — 통역사를 두고 외국 회사와 협업

MCP(Model Context Protocol)는 Supabase, Discord, GitHub 같은 외부 도구를 표준 프로토콜로 연결해요. 비유하면 통역사를 두고 외국 회사와 협업하는 거예요. AI가 외부 시스템과 대화할 때 공통 언어를 쓰게 만드는 역할이에요.

결정론적 가드(Hooks) + 외부 도구 연결(MCP). 이 두 가지가 워크플로우를 "실제로 굴러가는 시스템"으로 만들어줘요.

내부 가이드 더 보기: AI 에이전트 오케스트레이션

6. 컨텍스트 관리 — 70%, 83%, 100%의 의미

Claude Code의 컨텍스트 관리는 워크플로우의 절반이에요. 여기서 무너지면 응답 품질이 급격히 떨어져요.

6.1 200K 토큰의 구조

Claude Code는 200K 토큰 컨텍스트 윈도우를 기본 제공해요 (2026-05-24 KST 기준). 하지만 대화 시작 전에 시스템 프롬프트, MCP 스키마, 메모리 파일이 이미 30K~40K 토큰을 소비해요. (Context Windows 공식 문서)

6.2 Auto-compact 임계 — 83%

컨텍스트 사용량이 **약 83%(≈166K 토큰)**에 도달하면 auto-compact가 자동으로 트리거돼요. 나머지 ~34K 토큰은 응답 생성용 버퍼로 예약돼요. 환경변수 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=75로 임계값을 75%로 조정하는 게 권장 시작값이에요.

6.3 70% 룰

3가지 룰만 기억하세요.

1. /context 명령으로 토큰 사용량 실시간 확인
2. 70%(≈140K) 넘기 전에 /clear로 대화 초기화 — 147K 넘으면 응답 품질 저하 시작
3. 무거운 탐색 작업은 subagent에 위임해서 메인 세션 토큰 보호

비유: 책상 위에 서류를 무한정 쌓으면 일을 못 해요. 일정 두께가 되면 서랍에 정리하고, 정말 안 쓰는 건 파쇄해야 해요.

7. 한국어 초보자 FAQ

Q. "Claude Code"와 "VS Code 같은 IDE"가 뭐가 다른가요?

VS Code는 사용자가 직접 코드를 타이핑하는 편집기예요. Claude Code는 터미널에서 자연어로 요청하면 AI가 코드를 읽고·수정하고·git에 커밋까지 해주는 agentic CLI 도구예요. (Slash Commands 공식 문서)

VS Code는 "내가 운전하는 차", Claude Code는 "내가 목적지만 말하면 운전해주는 자율주행 차"에 가까워요. 둘이 충돌하는 게 아니라, Claude Code를 VS Code 안에서도 쓸 수 있어요 (IDE 통합 지원).

Q. 어디부터 자동화해야 하나요?

Anthropic 공식 권장 순서가 있어요.

1. CLAUDE.md 작성 (프로젝트 루트에 코딩 규칙·금지 패턴 명시) — ROI 가장 높아요
2. Custom Slash Commands (반복 작업을 /test, /lint 같은 단축어로)
3. Hooks (파일 저장 후 자동 prettier/lint)
4. GitHub Actions 통합 (자동 PR 리뷰, headless 모드) — 단, 비용 캡 필수 (리뷰 워크플로우 20K 토큰, fix 워크플로우 60K 토큰)

CLAUDE.md 하나만 잘 써도 같은 명령에서 결과 일관성이 눈에 띄게 올라가요.

8. 2026년 모델 라인업 (가격)

워크플로우를 짤 때 어느 모델에 어느 단계를 맡길지도 중요해요. 2026-05-24 KST 기준 공식 가격은 이래요. (Pricing 공식 문서, 접속: 2026-05-24 KST)

배치 처리는 50% 할인, 프롬프트 캐싱은 입력 비용 90% 절감이 가능해요. 단순 작업은 Haiku, 핵심 plan/리뷰는 Opus, 일반 구현은 Sonnet — 이런 식으로 stage별 모델 분리가 비용을 크게 줄여줘요.

9. 정리 — 한 줄 요약

Claude Code 워크플로우는 AI에게 "어떻게 일할지" 가르치는 매뉴얼이에요.

• Explore → Plan → Code → Commit 4단계 골격
• TDD가 가장 강력한 단일 패턴
• Subagent로 컨텍스트 분리, Hooks로 결정론적 가드, MCP로 외부 도구 연결
• 70% 룰로 컨텍스트 관리, 모델 분리로 비용 절감

이 글이 도움이 됐다면 댓글에 "AI 에이전트" 남겨주세요. 풀 버전 워크플로우 템플릿 + CLAUDE.md 샘플 링크를 보내드릴게요.

References (출처)

본 글은 다음 Anthropic 공식 source 11개를 기반으로 작성되었습니다 (2026-05-24 KST 기준 검증, 모든 source는 ⭐⭐⭐ Tier 1 공식 문서).

1. Common Workflows — Claude Code Docs (2026-04-15)
2. Subagents — Claude Code Docs (2026-04-15)
3. Pricing — Claude Platform (2026-05-10, 접속: 2026-05-24 KST)
4. Context Windows — Claude Platform (2026-04-23)
5. Claude Code Best Practices (2026-05-01)
6. Claude Code Overview (2026-04-15)
7. claude-plugins-official — GitHub (2026-05-15)
8. GitHub Actions Integration (2026-04-15)
9. Slash Commands (2026-04-15)
10. Claude Sonnet 4.5 출시 공식 블로그 (2026-02-17)
11. Hooks — Claude Code Docs (2026-04-15)

© 2026 정상록 / 퀀텀점프클럽(QJC). 본 글은 Anthropic 공식 source 기반으로 작성되었으며, 인용된 가격·기능·라인업은 2026-05-24 KST 기준입니다.