Claude Code 실전 워크플로우 총정리

hahhhm·2026년 3월 4일

Claude Code를 실전에서 극한까지 활용하는 개발자들의 노하우를 한곳에 모음

핵심 인물 소개
환경 구성 & 병렬 실행
CLAUDE.md — 팀 단위 지식 축적 시스템
Plan 모드 → 실행 워크플로우
슬래시 커맨드 & 반복 작업 자동화
서브에이전트 활용법
Hooks — 자동화의 핵심
MCP 서버 구성 & 컨텍스트 윈도우 관리
플러그인 생태계
검증 피드백 루프 — 가장 중요한 원칙
컨텍스트 관리 & 토큰 최적화
TDD + Claude Code
권한 & 보안 관리
에디터 연동
실전 적용 체크리스트
팔로우할 사람들 & 리소스

1. 핵심 인물 소개

이 블로그에서 인용하는 주요 인물들이다.

이름	한줄 소개	대표 리소스
Boris Cherny	Claude Code 창시자, Anthropic	X 스레드
Affaan Mustafa	everything-claude-code (51K+ ⭐), Anthropic 해커톤 우승	GitHub
YK Sugi (ykdojo)	CS Dojo (190만+ 구독), 전 구글 개발자	GitHub
Boris Tane	Research→Plan→Annotate→Implement 방법론 창시	블로그

2. 환경 구성 & 병렬 실행

Boris Cherny의 병렬 실행 전략

Boris Cherny는 코딩을 선형적으로 하지 않는다. 마치 "함대 사령관"처럼 여러 AI 에이전트를 동시에 지휘한다.

로컬 터미널: 5개 병렬

터미널에서 Claude 5개를 동시에 실행
탭에 1~5 번호를 붙이고, iTerm2 시스템 알림으로 입력이 필요한 시점을 파악
각 세션은 독립된 git checkout을 사용해 충돌 방지

웹: 5~10개 추가 병렬

claude.ai/code에서 5~10개의 Claude를 추가로 운영
&로 로컬 세션을 웹으로 핸드오프
--teleport로 웹 ↔ 로컬 양방향 전환
iOS 앱에서 매일 아침 세션을 시작하고 나중에 확인

💡 한 유저가 이 셋업을 따라 하고 "코딩이라기보다 스타크래프트 같다"고 표현했다.

모델 선택:

Boris는 모든 작업에 Opus 4.5 with thinking을 사용한다. Sonnet보다 크고 느리지만, 조정(steering)이 적게 필요하고 도구 활용 능력이 뛰어나서 결과적으로 더 빠른 최종 결과를 도출한다고 한다.

"작은 모델의 빠른 속도에 투자하는 대신, 큰 모델의 정확도에 투자하면 '수정 비용(correction tax)'이 사라진다." — Boris Cherny 워크플로우 분석, VentureBeat

Git Worktrees를 이용한 병렬 작업

# 독립된 워크트리 생성
git worktree add ../feature-auth feature/auth
git worktree add ../feature-ui feature/ui

# 각 워크트리에서 별도의 Claude 인스턴스 실행
cd ../feature-auth && claude
cd ../feature-ui && claude

각 워크트리는 독립된 checkout이라 파일 충돌 없이 동시에 작업할 수 있다.

출처: Boris Cherny X 스레드 / Affaan Mustafa Shorthand Guide

3. CLAUDE.md — 팀 단위 지식 축적 시스템

Boris Cherny의 CLAUDE.md 운영법

Anthropic Claude Code 팀은 저장소에 단일 CLAUDE.md 파일을 유지한다.

핵심 운영 원칙:

git에 체크인하며, 팀 전체가 주 단위로 여러 번 기여
Claude가 잘못된 행동을 할 때마다 CLAUDE.md에 추가 → 같은 실수 반복 방지
코드 리뷰 시 동료 PR에 @.claude를 태그해 CLAUDE.md에 학습 내용 추가
현재 Boris 팀의 CLAUDE.md는 약 2.5k 토큰

"모든 실수가 규칙이 된다. 팀이 함께 일할수록 에이전트가 더 똑똑해진다." — Aakash Gupta, VentureBeat 인터뷰 중

CLAUDE.md에 포함할 내용

# CLAUDE.md

## 프로젝트 개요
- 기술 스택: Next.js, NestJS, GraphQL, React Native/Expo
- 아키텍처: FSD (Feature-Sliced Design)

## 코딩 규칙
- console.log 절대 커밋 금지
- 이모지 코드베이스에 사용 금지
- 파일 하나당 200줄 이내 유지
- 컴포넌트는 항상 named export

## 알려진 함정
- [날짜] GraphQL resolver에서 N+1 쿼리 발생 → DataLoader 반드시 사용
- [날짜] Expo Router에서 동적 라우트 타입 에러 → as const 단언 필요

## PR 규칙
- Conventional Commits 형식 사용
- 변경 파일 10개 이상이면 분할

shanraisshan의 CLAUDE.md 관리 팁

CLAUDE.md는 150줄 이내로 유지 (넘으면 컨텍스트 낭비)
범용적인 내용은 CLAUDE.md에, 기능별 세부사항은 서브에이전트에 분리
/memory, /rules, constitution.md는 보장되지 않으므로 과신 금지

출처: Boris Cherny X 스레드 / shanraisshan claude-code-best-practice

4. Plan 모드 → 실행 워크플로우

Boris Cherny의 Plan → Auto-Accept 패턴

대부분의 세션을 Plan 모드(Shift+Tab 두 번)로 시작
PR 작성이 목표일 경우 Plan 모드에서 Claude와 계획이 만족스러워질 때까지 반복 협의
계획 확정 후 auto-accept edits 모드로 전환
Claude가 보통 한 번에(1-shot) 완성

"좋은 계획이 정말 중요하다(A good plan is really important!)." — Boris Cherny

Boris Tane의 Research → Plan → Annotate → Implement

Boris Tane은 9개월간 Claude Code를 주력 도구로 사용하며 정립한, 가장 체계적인 워크플로우를 공개했다. 핵심 원칙은 "코드 작성 전에 리뷰하고 승인한 계획서가 있어야 한다"는 것이다.

Step 1: Research (리서치)

이 프로젝트의 인증 시스템을 deeply, in great detail 조사해줘.
모든 intricacies를 파악하고 research.md에 정리해.

"deeply, in great details, intricacies, go through everything — 이런 단어 없이는 Claude가 대충 훑고 넘어간다." — Boris Tane

research.md를 리뷰해서 Claude가 시스템을 제대로 이해했는지 확인한다. 리서치가 틀리면 계획이 틀리고, 구현도 틀린다.

Step 2: Plan (계획)

Claude가 plan.md를 작성하면, 에디터에서 열어 인라인 노트를 직접 추가한다.

[NOTE: 이 접근은 기존 캐싱 레이어와 충돌할 수 있음. Redis 패턴 확인 필요]
[NOTE: 여기서는 DataLoader 대신 직접 배치 쿼리 사용할 것]

Claude에게 다시 보내면 노트를 반영해 plan.md를 업데이트한다. 이 과정을 만족할 때까지 반복한다.

Step 3: Implement (구현)

계획이 확정되면 구현을 요청한다. 이 시점에서는 Claude가 중간에 멈추지 않고 한 번에 실행할 수 있다.

Step 4: Reference Implementation (참조 구현 활용)

이 프로젝트의 sortable ID 생성 코드를 봐.
비슷한 접근을 우리 프로젝트에 적용하는 plan.md를 작성해줘.

"Claude는 처음부터 설계하는 것보다, 구체적인 참조 구현이 있을 때 극적으로 더 잘 작동한다." — Boris Tane

출처: Boris Tane, How I Use Claude Code

5. 슬래시 커맨드 & 반복 작업 자동화

Boris Cherny의 Inner Loop 자동화

하루에 수십 번 반복하는 워크플로우를 슬래시 커맨드로 자동화한다.

# 커맨드 디렉토리 구조
.claude/commands/
  commit-push-pr.md    # 커밋 → 푸시 → PR 생성 (매일 수십 번 사용)
  refactor-clean.md    # 데드 코드 + 불필요 .md 파일 정리
  tdd.md               # 테스트 주도 개발 워크플로우
  e2e.md               # E2E 테스트 실행
  test-coverage.md     # 테스트 커버리지 체크

커맨드 파일 안에서 인라인 bash로 git status 등 정보를 미리 계산해서, 모델과의 불필요한 왕복을 방지한다.

YK Sugi의 dx 플러그인

YK Sugi는 실전에서 자주 쓰는 워크플로우를 dx 플러그인으로 번들화했다.

# 설치
claude plugin marketplace add ykdojo/claude-code-tips
claude plugin install dx@ykdojo

커맨드	기능
`/dx:gha <url>`	GitHub Actions 실패 분석 (flakiness 체크, 원인 커밋 특정)
`/dx:handoff`	세션 인수인계 문서 자동 생성 (다음 에이전트가 바로 이어받을 수 있도록)
`/dx:clone`	대화 복제 → 다른 접근 시도용 브랜치
`/dx:half-clone`	대화 후반부만 복제 → 토큰 절약하면서 최근 작업 유지
`/dx:reddit-fetch`	Gemini CLI로 Reddit 콘텐츠 가져오기 (WebFetch 차단 우회)
`/dx:review-claudemd`	최근 대화를 분석해서 CLAUDE.md 개선점 제안

출처: Boris Cherny X 스레드 / YK Sugi claude-code-tips

6. 서브에이전트 활용법

Boris Cherny의 서브에이전트 구조

~/.claude/agents/
  code-simplifier.md      # Claude 작업 완료 후 코드 단순화
  verify-app.md            # E2E 테스트를 위한 상세 지침
  planner.md               # 기능 구현 계획 수립
  architect.md             # 시스템 설계 결정
  tdd-guide.md             # 테스트 먼저 작성
  code-reviewer.md         # 품질/보안 리뷰
  security-reviewer.md     # 취약점 분석
  build-error-resolver.md  # 빌드 에러 해결
  e2e-runner.md            # Playwright 테스트
  refactor-cleaner.md      # 데드 코드 제거
  doc-updater.md           # 문서 동기화

서브에이전트는 스킬과 함께 사용하면 효과적이다. 특정 스킬만 실행할 수 있는 서브에이전트를 만들어 위임하면, 메인 에이전트의 컨텍스트를 아낀다.

Affaan Mustafa의 서브에이전트 팁

서브에이전트마다 허용된 도구, MCP, 권한을 별도로 설정
범용 "백엔드 엔지니어" 에이전트보다 기능별 전문 에이전트가 훨씬 효과적
포그라운드/백그라운드 모드를 상황에 따라 사용

모델 선택 가이드 (Affaan Mustafa)

상황	모델
일반 코딩 작업 (90%)	Sonnet
첫 시도 실패, 5개+ 파일 수정, 아키텍처 결정, 보안 관련	Opus
반복적 작업, 명확한 지시, 멀티에이전트의 "worker"	Haiku

출처: Boris Cherny X 스레드 / Affaan Mustafa Longform Guide

7. Hooks — 자동화의 핵심

Hook 타입 총정리 (Affaan Mustafa)

Hook	트리거 시점	활용 예시
`PreToolUse`	도구 실행 전	검증, 리마인더, 위험 명령 차단
`PostToolUse`	도구 실행 후	포매팅, 피드백 루프, 타입 체크
`UserPromptSubmit`	메시지 전송 시	프롬프트 전처리
`Stop`	Claude 응답 완료 시	최종 감사, console.log 체크
`PreCompact`	컨텍스트 압축 전	중요 정보 보존
`Notification`	권한 요청 시	알림 커스터마이즈

Boris Cherny의 PostToolUse 포매팅 훅

Claude는 기본적으로 잘 포매팅된 코드를 생성하지만, 훅이 나머지 10%를 처리해서 CI에서 포매팅 오류를 방지한다.

Affaan Mustafa의 실전 Hook 설정

{
  "PreToolUse": [
    {
      "matcher": "npm|pnpm|yarn|cargo|pytest",
      "hooks": [{ "type": "command", "command": "tmux 세션 확인 리마인더" }]
    },
    {
      "matcher": "Write && .md file",
      "hooks": [{ "type": "command", "command": "README/CLAUDE 외 .md 파일 생성 차단" }]
    },
    {
      "matcher": "git push",
      "hooks": [{ "type": "command", "command": "에디터에서 리뷰 열기" }]
    }
  ],
  "PostToolUse": [
    {
      "matcher": "Edit && .ts/.tsx/.js/.jsx",
      "hooks": [{ "type": "command", "command": "prettier --write" }]
    },
    {
      "matcher": "Edit && .ts/.tsx",
      "hooks": [{ "type": "command", "command": "tsc --noEmit" }]
    },
    {
      "matcher": "Edit",
      "hooks": [{ "type": "command", "command": "console.log 경고" }]
    }
  ],
  "Stop": [
    {
      "matcher": "*",
      "hooks": [{ "type": "command", "command": "수정된 파일에서 console.log 감사" }]
    }
  ]
}

💡 hookify 플러그인을 사용하면 JSON을 직접 작성하지 않고 대화형으로 훅을 생성할 수 있다.

출처: Boris Cherny X 스레드 / Affaan Mustafa Shorthand Guide

8. MCP 서버 구성 & 컨텍스트 윈도우 관리

컨텍스트 윈도우 관리의 핵심 (Affaan Mustafa)

"200k 컨텍스트 윈도우가 너무 많은 도구가 활성화되면 실질적으로 70k까지 줄어든다."

황금 규칙:

설정에 20~30개 MCP를 등록하되, 활성화는 10개 미만 / 도구 80개 미만 유지
프로젝트별로 불필요한 MCP를 비활성화

Affaan Mustafa의 MCP 설정 예시

{
  "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] },
  "supabase": { "command": "npx", "args": ["-y", "@supabase/mcp-server-supabase@latest"] },
  "memory": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-memory"] },
  "sequential-thinking": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"] },
  "vercel": { "type": "http", "url": "https://mcp.vercel.com" },
  "firecrawl": { "command": "npx", "args": ["-y", "firecrawl-mcp"] }
}

프로젝트별 비활성화:

{
  "disabledMcpServers": [
    "playwright",
    "cloudflare-workers-builds",
    "cloudflare-observability",
    "clickhouse"
  ]
}

"14개 MCP를 설정해두지만, 프로젝트당 5~6개만 활성화한다. 이게 컨텍스트 윈도우를 건강하게 유지하는 핵심이다." — Affaan Mustafa

Boris Cherny의 도구 통합 활용

Claude Code가 직접 외부 도구를 사용하게 한다:

Slack: MCP 서버로 검색 및 게시 (.mcp.json에 체크인하여 팀 공유)
BigQuery: bq CLI로 분석 질문에 답변
Sentry: 에러 로그 가져오기

출처: Affaan Mustafa Shorthand Guide / Boris Cherny X 스레드

9. 플러그인 생태계

mgrep: grep의 상위호환

mgrep "function handleSubmit"           # 로컬 검색
mgrep --web "Next.js 15 app router"     # 웹 검색

LSP 플러그인의 가치

에디터 밖에서 Claude Code를 자주 실행한다면, LSP 플러그인이 특히 유용하다. IDE 없이도 실시간 타입 체크, go-to-definition, 자동 완성을 제공한다. 단, MCP와 마찬가지로 컨텍스트 윈도우를 소모하니 주의.

출처: Affaan Mustafa Shorthand Guide

10. 검증 피드백 루프 — 가장 중요한 원칙

Boris Cherny의 #1 팁

"Claude Code에서 훌륭한 결과를 얻기 위한 가장 중요한 요소는 Claude에게 작업을 검증할 방법을 제공하는 것이다. 이 피드백 루프가 있으면 최종 결과물 품질이 2~3배 향상된다."

Anthropic 내부 검증 방식:

Claude Chrome 확장 프로그램으로 claude.ai/code에 랜딩하는 모든 변경 사항을 테스트
브라우저를 열고 UI를 테스트하며, 코드가 작동하고 UX가 좋을 때까지 반복

도메인별 검증 방식:

도메인	검증 방법
백엔드	bash 명령 실행, 테스트 스위트
프론트엔드	브라우저 자동화 (Playwright, Chrome 확장)
모바일	폰 시뮬레이터에서 앱 테스트
API	curl/httpie로 엔드포인트 호출

장시간 작업의 검증 (Boris Cherny)

매우 긴 작업의 경우 세 가지 중 선택:

완료 시 백그라운드 에이전트로 작업 검증하도록 프롬프트
에이전트 Stop 훅으로 더 결정론적으로 검증
ralph-wiggum 플러그인 (Geoffrey Huntley 고안) — 샌드박스에서 자율적으로 반복 실행

출처: Boris Cherny X 스레드

11. 컨텍스트 관리 & 토큰 최적화

YK Sugi의 컨텍스트 관리 철학

"AI 컨텍스트는 우유와 같다 — 신선하고 농축된 상태가 가장 좋다."

커스텀 상태 표시줄:

YK Sugi는 Claude Code 하단에 커스텀 상태 표시줄을 설정해서 실시간으로 현황을 모니터링한다:

Opus 4.5 | 📁project-name | 🔀main (2 uncommitted, synced 12m ago) | ██░░░░░░░░ 18% of 200k tokens
💬 마지막 메시지 미리보기...

모델, 디렉토리, git 브랜치, 커밋 안 된 파일 수, origin 동기화 상태, 토큰 사용률을 한눈에 볼 수 있다.

Affaan Mustafa의 토큰 관리 전략

auto compact 비활성화, 논리적 분기점에서 수동으로 /compact 실행
탐색 컨텍스트가 쌓이면 Plan 모드에서 계획 확정 후 컨텍스트 클리어
CLI 플래그로 세션별로 다른 컨텍스트를 주입 (항상 모든 걸 로드하지 않음)

shanraisshan의 실전 규칙

50%에서 수동 /compact — "agent dumb zone" (성능 저하 구간) 방지
CLAUDE.md는 150줄 이내 유지
기능별 세부사항은 서브에이전트로 분리 (progressive disclosure)

출처: YK Sugi claude-code-tips / Affaan Mustafa Longform Guide / shanraisshan claude-code-best-practice

12. TDD + Claude Code

YK Sugi의 TDD 접근법

"AI가 자기 코드를 테스트할 수 없다고 하는 사람들이 있지만, 실제로 가능하다. 인간의 뇌가 작동하는 방식과 비슷하게, 테스트를 작성할 때는 같은 문제를 다른 방식으로 생각하게 된다."

Claude Code TDD 워크플로우:

실패하는 테스트를 먼저 작성
테스트를 커밋 (구현 전에!)
Claude Code에게 구현 요청
테스트 통과 확인
테스트를 직접 리뷰해서 return true 같은 무의미한 테스트가 아닌지 확인

"실패하는 테스트를 먼저 작성하고 커밋하면, 코드가 해야 할 일에 대한 명확한 계약이 생긴다. Claude Code에게 구체적인 목표가 생기고, 테스트를 실행해서 구현이 맞는지 검증할 수 있다."

실전 TDD 스킬 예시

# .claude/commands/tdd.md

1. 사용자가 설명한 기능에 대해 실패하는 테스트를 먼저 작성해줘
2. 테스트가 실패하는지 확인해줘 (npm test 실행)
3. 테스트를 통과시키는 최소한의 구현을 작성해줘
4. 모든 테스트가 통과하는지 확인해줘
5. 리팩토링이 필요하면 진행하되, 테스트가 계속 통과하는지 확인

출처: YK Sugi claude-code-tips

13. 권한 & 보안 관리

Boris Cherny의 권한 관리 방식

--dangerously-skip-permissions 사용하지 않음
/permissions로 안전한 bash 명령을 사전 허용
.claude/settings.json에 체크인하여 팀과 공유

// .claude/settings.json 예시
{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git *)",
      "Bash(npx prettier *)",
      "Edit(/src/**)",
      "Edit(/tests/**)"
    ]
  }
}

Affaan Mustafa의 AgentShield

1282개 테스트, 102개 규칙으로 Claude Code 설정의 보안 취약점을 스캔한다.

# 빠른 스캔 (설치 불필요)
npx ecc-agentshield scan

# 안전한 이슈 자동 수정
npx ecc-agentshield scan --fix

# 3개의 Opus 에이전트로 심층 분석
npx ecc-agentshield scan --opus --stream

shanraisshan의 보안 팁

/permissions에서 와일드카드 문법 사용: Bash(npm run *), Edit(/docs/**)
/sandbox로 파일/네트워크 격리하여 권한 프롬프트 줄이기
--dangerously-skip-permissions는 샌드박스 환경에서만 사용

출처: Boris Cherny X 스레드 / Affaan Mustafa AgentShield / shanraisshan claude-code-best-practice

14. 에디터 연동

Affaan Mustafa의 선택: Zed

Rust 기반으로 가볍고 빠름, 대규모 코드베이스에서도 렉 없음
Agent Panel로 Claude가 편집하는 파일 변경을 실시간 추적
CMD+Shift+R로 커스텀 슬래시 커맨드에 빠르게 접근
Ctrl+G로 Claude가 현재 작업 중인 파일을 Zed에서 즉시 열기
Vim 모드 지원

에디터 연동 베스트 프랙티스

설정	이유
Auto-save 활성화	Claude의 파일 읽기가 항상 최신 상태
File watcher 확인	변경된 파일 자동 리로드
Git 통합 사용	Claude의 변경 사항을 커밋 전에 리뷰
화면 분할	터미널(Claude) + 에디터 동시 보기

tmux로 장시간 명령 관리

tmux new -s dev
# Claude가 여기서 서버를 띄우고, 로그를 모니터링
# detach: Ctrl+B → D
tmux attach -t dev
# 다시 들어와서 로그 확인