Deep Work Workflow: Brainstorm → Research → Plan → Implement → Test

v5.6.0 Session Fork

v5.6.0 신규 기능:

/deep-fork [session-id] [--from-phase=PHASE]

현재 세션을 fork하여 다른 접근법을 탐색합니다. 원래 세션은 보존됩니다.

• Git 환경: worktree 기반 전체 복제. implement/test까지 진행 가능.
  • Dirty 상태 검증: clean/commit/stash 중 선택
  • Session ID 기반 branch suffix (race condition 방지)
  • Worktree 컨텍스트 자동 전환 (FORK_PROJECT_ROOT)
• Non-git 환경: 산출물만 복제. plan phase까지만 진행 가능.
  • Phase guard가 implement/test 진입 차단
• Fork 관계 추적:
  • fork_info: fork된 세션의 상태 파일에 부모 관계 기록
  • fork_children: 부모 세션의 상태 파일에 자식 목록 기록
  • fork-snapshot.yaml: fork 시점 상태 스냅샷 (비교 기준점)
• 비교 & 시각화:
  • /deep-status --tree: fork 관계 트리 시각화
  • /deep-status --compare: fork 관계 자동 감지 비교
• Edge cases: 최대 3세대 fork (경고), idle 세션 fork 금지, stale 부모 검증

v5.5.2 Robust Detection & Signal Processing

v5.5.2 신규 기능:

• 확장된 bash 파일 쓰기 감지: perl, node -e, python -c, ruby -e, swift, awk, git destructive ops 등 20+ 패턴 추가
• 보안: file-write-first 감지 순서: FILE_WRITE 패턴을 SAFE 패턴보다 먼저 검사하여 우회 방지
• 확장된 언어 지원: Dart, Elixir, Lua, Vue 테스트 패턴 + fixtures/mocks 디렉토리 인식
• TDD exempt 확장: .toml, .ini, .cfg, .lock, .editorconfig, 이미지 파일 면제
• splitCommands 개선: backtick, $() subshell 깊이 추적으로 중첩 표현식 내부 잘못된 분할 방지
• TDD state 검증: 알 수 없는 상태값 차단 + 안내 메시지
• 에러 로깅: /dev/null → .claude/deep-work-guard-errors.log 파일 기록
• Node.js 25 호환: file-tracker.sh argv 인덱싱 수정 (receipt 생성 무음 실패 해결)
• Assumption Engine 수정: CLI 버그, threshold 전달, dedup 순서 (keep-latest), 입력 가드

v6.0.2 Phase Review Gate & Folder Rename

v6.0.2 신규 기능:

• Phase Review Gate: 모든 Phase(0~3) 종료 시 통합 리뷰 게이트 자동 실행. 셀프 리뷰 + 외부 리뷰(deep-review/codex/gemini/Opus) 후 사용자 확인
• Phase별 Fallback 체인: Phase 0~2(문서)는 Structural+Adversarial, Phase 3(코드)는 deep-review 우선
• 사용자 확인 UX: 요약 → 선택지(자동 수정/현재 진행/상세 보기)
• Degraded Mode: 외부 리뷰어 실패 시 자동 fallback
• 세션 폴더 이름 변경: deep-work/ → .deep-work/ (숨김 폴더). 마이그레이션 자동 처리
• State 스키마 확장: phase_review 필드 추가 (기존 review_results 하위 호환)

v5.5 Review Flow Enhancement

v5.5 신규 기능:

• Research Cross-Model Review: research 단계에도 codex/gemini 크로스 리뷰 적용
• Claude 자체 재검토: plan 작성 직후 자동 품질 점검 (placeholder, 일관성, 누락)
• 종합 판단 프로토콜: cross-review 후 Claude 판단 + 사용자 일괄 확인 (개별 conflict 질문 대체)
• Structural Review 강화: auto-fix 기준 score < 5 → score < 7, 스냅샷 기반 rollback
• Degraded Mode: cross-model 리뷰어 실패 시 명시적 상태 표시 + graceful fallback
• State 스키마 마이그레이션: 신규 필드 자동 초기화, resume 시 문서-판단 시각 검증

v5.3 Precision + Evidence

/deep-work "task" 하나로 전체 워크플로우가 자동 진행됩니다. Plan 승인이 유일한 필수 인터랙션입니다.

v5.3 신규 기능:

• Document Intelligence: 피드백 적용 시 중복/불필요 내용 자동 정리 (Apply → Deduplicate → Prune)
• Session Relevance Detection: 현재 세션 범위 밖 피드백 감지 → 새 세션 분리 제안
• Plan Fidelity Score: 구현 vs 플랜 충실도 0-100 점수 산출
• Session Quality Score: 세션 종료 시 품질 점수 자동 계산 — 5-component system: Test Pass Rate (25%), Rework Cycles (20%), Plan Fidelity (25%), Sensor Clean Rate (15%), Mutation Score (15%). Sensor/Mutation components excluded proportionally when not_applicable.
• Cross-Session Quality Trend: /deep-status --history에서 세션 간 품질 추이 시각화
• Assumption Engine Quality Integration: 품질 점수 기반 규칙 자가 최적화 (cohort 분석, 3세션 minimum gate)
• Quality Badge: /deep-status --badge로 shields.io 뱃지 생성

Primary commands (7): /deep-work, /deep-research, /deep-plan, /deep-implement, /deep-test, /deep-status, /deep-debug

Deprecated commands (13): 자동 흐름에 흡수됨. 수동 호출 가능하지만 불필요.

• brainstorm, review, receipt, slice, insight, finish, cleanup, history, assumptions, resume, report, drift-check, solid-review

Core mechanisms:

• Phase Guard (hook-enforced code blocking)
• TDD Enforcement (state machine: PENDING → RED → GREEN → REFACTOR)
• Slice-based Execution with Receipt Collection
• Profile/Preset System (zero-question restart)
• Auto-transition between phases

Why This Workflow Exists

When AI coding tools work on complex tasks without structure, common failure modes emerge:

1. Architecture Ignorance: AI generates code that doesn't follow existing patterns
2. Duplicate Implementation: AI creates new utilities when equivalent ones already exist
3. Premature Coding: AI starts writing code before understanding the full picture
4. Scope Creep: AI adds "improvements" not requested, introducing bugs
5. Inconsistency: AI uses different conventions than the rest of the codebase

The Deep Work workflow prevents these by strictly separating brainstorming, analysis, planning, coding, and testing into five distinct phases with enforced gates between them.

The Five Phases

Phase 0: Brainstorm (/deep-brainstorm) — Optional

Goal: Explore "why before how" — define the problem, compare approaches, establish success criteria.

What happens:

• Structured design conversation with the user
• 2-3 approach comparison with pros/cons
• Spec-reviewer subagent validates the brainstorm document
• Documentation in $WORK_DIR/brainstorm.md
• Phase Review Gate: Phase 완료 시 셀프 리뷰 + 외부 리뷰 자동 실행, 사용자 확인 후 전환

What's blocked: All code file modifications (enforced by hook) Skip: Use --skip-brainstorm to start directly at Research.

Phase 1: Research (/deep-research)

Goal: Build a complete mental model of the relevant codebase before making any decisions.

What happens:

• Exhaustive analysis of architecture, patterns, and conventions
• Identification of all relevant files, dependencies, and risk areas
• Documentation of everything in $WORK_DIR/research.md
• Output begins with Executive Summary and Key Findings (pyramid principle)
• Phase Review Gate: Phase 완료 시 셀프 리뷰 + 외부 리뷰 자동 실행, 사용자 확인 후 전환

What's blocked: All code file modifications (enforced by hook)

Key principle: "You cannot plan what you don't understand, and you cannot understand what you haven't read."

Features:

• Zero-base mode: For new projects, researches technology stacks, architecture patterns, and scaffolding instead of existing code
• Partial re-run: /deep-research --scope=api,data re-analyzes specific areas only
• Research caching: Reuses previous session's research as baseline, updating only changed areas
• Team mode: 3 specialist agents (arch-analyst, pattern-analyst, risk-analyst) analyze in parallel with progress notifications
• Structural Review 강화: score < 7 auto-fix, 스냅샷 기반 rollback
• Cross-Model Review: codex/gemini가 research.md를 독립 평가 (plan과 동일 패턴)
• 종합 판단: Claude가 모든 리뷰 결과를 분석, 사용자 일괄 확인 후 수정

For detailed guidance, see Research Guide or Zero-Base Guide.

Phase 2: Plan (/deep-plan)

Goal: Create a detailed, reviewable, approvable implementation plan.

What happens:

• Transform research findings into a concrete action plan
• Plan Summary at the top with approach, scope, risk level, and key decisions
• Define exact files to modify, code snippets, execution order
• Code completeness tiered by slice size: S=pseudocode OK, M=signatures+types actual code, L=boundary code complete (interfaces, APIs, tests)
• No placeholders: Plan must pass the Completeness Policy — no TBD, TODO, or vague directives
• Research traceability: Architecture decisions reference tagged research findings [RF-NNN], [RA-NNN]
• Create a checklist-style task list in $WORK_DIR/plan.md
• Phase Review Gate: Phase 완료 시 셀프 리뷰 + 외부 리뷰 자동 실행, 사용자 확인 후 전환

What's blocked: All code file modifications (enforced by hook)

Key principle: "The plan is the contract between human and AI. No implementation without approval."

Features:

• Interactive review: Chat-based feedback loop — say "3번 항목 변경해줘" and plan.md updates automatically
• Plan templates: Auto-suggests templates for common task types (API endpoint, UI component, DB migration, etc.)
• Version history: Previous plans backed up as plan.v1.md, plan.v2.md with change logs
• Mode re-evaluation: Suggests Team↔Solo switching based on plan complexity
• Auto-implementation: When approved ("승인"), implementation starts automatically
• Claude 자체 재검토: plan 작성 직후 placeholder/일관성/누락 자동 점검 및 수정
• Structural Review 강화: score < 7 auto-fix, 스냅샷 기반 rollback
• 종합 판단: cross-review 후 Claude 판단 + 사용자 일괄 확인 (개별 conflict 질문 대체)
• Team research 교차 검증 (v5.5.1): team_mode: team일 때 부분 리서치 파일(research-architecture/patterns/dependencies.md)을 보조 참조로 로드하여 합성 누락 세부 사항 교차 확인

Note: Plan phase does not use Team mode — planning requires a single coherent document produced by one agent.

For detailed guidance, see Planning Guide.

Phase 3: Implement (/deep-implement)

Goal: Mechanically execute the approved plan, task by task.

What happens:

• Follow the plan checklist exactly
• Implement one task at a time, marking each complete
• Document any issues encountered — never improvise
• Automatically transition to Test phase upon completion
• Computational sensors: After each slice reaches GREEN, computational sensors (linter, type checker) run automatically. Failures trigger a self-correction loop (SENSOR_FIX state) where the AI attempts to fix sensor errors before moving to the next slice. Results are stored in receipt sensor_results fields.
• Slice Review: After sensors pass, independent 2-stage review per slice — spec compliance (required) and code quality (advisory). Issues caught immediately, not deferred to Phase 4.
• Pre-flight Check: Before each slice's TDD cycle, verify prerequisites (files exist, commands work). Problems surface immediately via AskUserQuestion.
• Status Reporting: Each slice records slice_confidence (done/done_with_concerns) and specific concerns in the receipt.
• Red Flags: Rationalization prevention tables in implement and test phases. Complements hook-based hard gates with soft behavioral guidance.
• Phase Review Gate: Phase 완료 시 셀프 리뷰 + 외부 리뷰 자동 실행, 사용자 확인 후 전환

What's allowed: All tools — code modification is now permitted

Key principle: "The best implementation is a boring implementation. No creativity, no surprises, just faithful execution."

Features:

• Checkpoint support: If interrupted, resumes from the last incomplete task
• Team mode: Tasks clustered by file ownership, distributed to parallel agents with cross-review and progress notifications
• Auto-test: After all tasks complete, transitions to Test phase automatically
• TDD state 업데이트 필수화 (v5.5.1): B-1/B-2 완료 후 state file 업데이트를 필수로 명시, 미수행 시 phase guard 차단 경고
• Slice Review: Per-slice 2-stage independent review (spec compliance → code quality) after sensors pass. Solo mode only; delegation mode uses self-review recorded as slice_review.mode: "self"

For detailed guidance, see Implementation Guide.

Phase 4: Test (/deep-test)

Goal: Verify the implementation through comprehensive automated testing.

What happens:

• Auto-detects verification commands (test, lint, typecheck) from project config
• Runs all checks sequentially, records results
• Sensor Clean gate: Reads sensor_results from receipts (no re-execution) to verify all slices passed computational sensors
• Mutation testing: Verifies AI-generated test quality by running mutation analysis (stryker/mutmut). Survived mutants trigger automatic test improvement via return to the implement phase — /deep-mutation-test handles this transition internally
• Cross-slice consistency + backfill review: Phase 4 now verifies inter-slice compatibility instead of per-slice compliance (done in Phase 3). Slices that skipped Phase 3 review get backfill (보완) review here.
• Pass: Session completes, report generated
• Fail: Returns to implement phase for fixes (up to 3 retries)

What's blocked: All code file modifications (enforced by hook)

Key principle: "Trust but verify. The test phase catches what implementation missed."

Features:

• Auto-detection: Scans package.json, pyproject.toml, Makefile, Cargo.toml, go.mod
• Implement-test loop: Automatic retry cycle with detailed failure reports
• Cumulative results: All attempts recorded in $WORK_DIR/test-results.md
• Git integration: Suggests commit after all tests pass

For detailed guidance, see Testing Guide.

Quality Gates & Utilities

Plan Alignment Check (/drift-check) — deprecated, auto-runs in /deep-test

Compares plan.md items with actual git diff. Reports implemented, missing, out-of-scope, and design drift. Standalone mode available: /drift-check [plan-file].

SOLID Design Review (/solid-review) — deprecated, auto-runs in /deep-test

Evaluates code against the 5 SOLID design principles with a per-principle scorecard. Standalone mode available: /solid-review [target]. See SOLID Guide.

Code Insight Analysis (/deep-insight) — deprecated, auto-runs in /deep-test

Measures file metrics, complexity indicators, and dependency graphs. Never blocks workflow. Standalone mode available: /deep-insight [target]. See Insight Guide.

Session Report (/deep-report) — deprecated, use /deep-status --report

Generates a comprehensive session report (research, plan, implementation, test outcomes, phase durations). Auto-generated after all tests pass. Manual: /deep-report or /deep-status --report.

Phase Enforcement

Hooks enforce phase boundaries and track activity:

• PreToolUse (phase-guard.sh): During Research, Plan, and Test phases — Write/Edit tools are blocked for all files except $WORK_DIR/ documents and the state file. During Implement — all tools available. No session — no restrictions.
• PostToolUse (file-tracker.sh): During Implement phase — automatically logs modified file paths to $WORK_DIR/file-changes.log with timestamps. Used by /deep-report and /deep-insight.
• Stop (session-end.sh): On CLI session end — if a deep-work session is active, outputs a reminder message and sends notification via configured channels.

This is not a suggestion — it's a hard gate. The AI literally cannot modify code files until the plan is approved, and cannot modify code during testing.

Quick Start

/deep-work "Add user authentication with JWT tokens"
# → Brainstorm (자동) → Research (자동) → Plan (승인 대기)
# → 승인하면 → Implement (자동) → Test (자동) → Finish (선택)

# 수동 오버라이드가 필요할 때:
/deep-research                  # 리서치 다시 실행
/deep-plan                      # 플랜 수정
/deep-implement                 # 구현 재실행
/deep-test                      # 테스트 재실행
/deep-status                    # 상태 확인 (--receipts, --history, --report, --assumptions)
/deep-debug                     # 디버깅 모드

Session Options

During /deep-work initialization:

• Solo / Team mode selection
• Existing / Zero-Base project type
• Research / Plan starting phase (skip research if you know the codebase)
• Git branch creation (optional)

Session History

Each session creates a unique task folder under .deep-work/:

.deep-work/
├── 20260307-143022-jwt-기반-인증/
│   ├── research.md
│   ├── plan.md
│   ├── test-results.md
│   └── report.md
├── 20260306-091500-api-리팩토링/
│   ├── research.md
│   ├── plan.md
│   ├── plan.v1.md        ← plan version history
│   ├── test-results.md
│   └── report.md

Previous sessions are preserved when starting new ones. Use /deep-status to view history or /deep-status --compare to compare sessions.

Profile System

First run saves setup answers to .claude/deep-work-profile.yaml as default preset. Subsequent runs skip all questions. Multi-preset support: dev, quick, review etc.

Flags: --profile=quick, --team, --zero-base, --skip-research, --no-branch, --setup

Session Resume — deprecated, auto-detected in /deep-work

/deep-work 실행 시 기존 활성 세션이 감지되면 자동으로 resume 옵션을 제시합니다. /deep-resume는 여전히 수동으로 호출 가능합니다.

State Management

Session state is stored in .claude/deep-work.{SESSION_ID}.md (e.g., .claude/deep-work.s-a3f7b2c1.md) with YAML frontmatter tracking. Legacy single-session path .claude/deep-work.local.md is auto-migrated on first use.

• Current phase (research / plan / implement / test / idle)
• Task description
• Work directory
• Research/plan completion status
• Team mode and project type
• Git branch
• Test retry count and pass status
• Phase timestamps (started_at, completed_at for each phase)

Use /deep-status at any time to see the current state, progress, phase durations, and next recommended action.

When to Use Deep Work

Use it when:

• The task touches multiple files or modules
• You're working in an unfamiliar codebase
• The change has architectural implications
• Previous AI attempts have gone wrong
• You want to review the approach before any code is written
• You're starting a brand new project from scratch (zero-base mode)

Consider Team mode when:

• The codebase is large and research would benefit from parallel analysis
• The implementation plan has many independent tasks across different files
• Complex refactoring that touches many modules simultaneously
• You want built-in cross-review of implementation quality

Skip it when:

• Simple one-file bug fixes
• Trivial text or config changes
• You already know exactly what to do

Lightweight mode (skip to /deep-plan directly):

• Touches 2-4 files in a well-understood area
• Follows established patterns with minor extensions
• Start with /deep-work then select "Plan부터" to skip research

Complementary Usage with Built-in Plan Mode

Use built-in plan mode for quick task decomposition, Deep Work for complex subtasks needing thorough research and strict phase gates. They combine well: plan mode for initial design, Deep Work for implementation.

Internationalization

All commands auto-detect the user's language and output in that language. Korean is the reference format; Claude translates naturally while preserving structure.