Common Workflows

Common Workflow Packs

Seven battle-tested workflow packs that mirror the official Claude Code common-workflows guide. Each pack is a complete playbook, not generic advice.

Pack 1: Understand a Codebase

When: First time in an unfamiliar repo, onboarding a new project, or before making large changes.

Start Prompt

You are a senior engineer exploring this codebase for the first time.

Phase 1 — Structure mapping:
1. Read CLAUDE.md, README.md, and package.json/pyproject.toml
2. Map the top-level directory structure (2 levels deep)
3. Identify: entry points, main business logic, data layer, API layer, test layer
4. Identify: tech stack, framework version, package manager

Phase 2 — Architecture extraction:
5. Find the 3 most important source files (highest import count or central routing)
6. Read each one and extract: purpose, key abstractions, dependencies
7. Map data flow: where does data enter, transform, and exit?
8. Identify patterns: are there service layers, repositories, DTOs, event buses?

Phase 3 — Output:
9. Write a 1-page architecture summary to .claude/context-snapshot.md with:
   - Tech stack table
   - 3-sentence architecture description
   - Key file map (path → purpose, one line each)
   - Entry points and their routes/triggers
   - Known complexity hotspots (files > 300 lines or deeply nested logic)

Verification Steps

• Tech stack correctly identified (check package.json/Cargo.toml/pyproject.toml)
• All entry points found (check for main.ts, index.ts, manage.py, main.go)
• Architecture snapshot written to .claude/context-snapshot.md
• No assumptions made that weren't verified in code

Subagent Opportunities

• Delegate framework-specific analysis: spawn a subagent for src/auth/ while you explore src/api/
• Use a Haiku subagent to list imports and build the dependency graph (fast, cheap)
• Use an Opus subagent only for the final architecture synthesis

Common Failure Modes

• Over-reading: reading every file instead of tracing from entry points inward
• Missing the glue: forgetting to read middleware, config loaders, and DI containers
• Stale docs: trusting README over what's actually in the code

Completion Checklist

• .claude/context-snapshot.md written
• Can explain the system in 3 sentences without looking at the code
• Know where to find: routing, data models, auth, config, tests

Pack 2: Fix a Bug from an Error Trace

When: You have a stack trace, error message, or failing test and need to find and fix the root cause.

Start Prompt

You are debugging the following error:

{PASTE ERROR TRACE HERE}

Evidence-based debugging protocol:

Phase 1 — Parse:
1. Extract: error type, message, file, line number, call stack
2. Identify the proximate cause (where it failed) vs. likely root cause (why)

Phase 2 — Locate:
3. Read the file at the error line + 20 lines of context
4. Trace the call stack: read each frame's function to understand data flow
5. Find where the problematic value was created or last mutated

Phase 3 — Hypothesize:
6. Form 2-3 specific hypotheses about root cause
7. For each hypothesis: identify a code path that would produce this error
8. Pick the most likely hypothesis based on evidence

Phase 4 — Fix:
9. Write the minimal fix for the chosen hypothesis
10. Explain why the fix works
11. Identify if there are other call sites with the same bug

Phase 5 — Verify:
12. Run the failing test: {test_cmd}
13. Run the full test suite to check for regressions: {test_cmd}
14. If tests pass: commit with message "fix({scope}): {one-line description}"

Verification Steps

• Error is reproducible before fix (confirm test fails)
• Root cause identified (not just symptom masked)
• Fix is minimal (no unrelated changes in the same commit)
• Tests pass after fix
• Other call sites checked for same bug

Subagent Opportunities

• Use a subagent to search for similar patterns across the codebase: Grep "same_pattern" --all
• Delegate test writing to a test-writer subagent after the fix is confirmed

Common Failure Modes

• Symptom masking: adding null checks without finding why null appears
• Over-engineering: refactoring instead of fixing
• Regression: fixing one thing, breaking another — always run full suite
• Wrong hypothesis: jumping to a fix without verifying the hypothesis first

Completion Checklist

• Failing test was confirmed before fix
• Root cause statement written in commit message
• All tests pass
• No unrelated changes in the commit

Pack 3: Refactor Safely

When: You need to restructure code without changing behavior. Extract a function, rename a module, split a large file, introduce an abstraction.

Start Prompt

You are a refactoring engineer. Goal: {DESCRIBE REFACTOR GOAL}.

Safety protocol:

Phase 1 — Baseline:
1. Identify the exact scope of change (files, functions, types affected)
2. Run the test suite and confirm it passes: {test_cmd}
3. Count the test coverage for the affected code: check coverage report
4. If coverage < 80% for the target code: write missing tests first

Phase 2 — Characterize:
5. List every call site for the code being changed: Grep for function/class name
6. List every import of the modules being changed
7. Identify any reflection, dynamic dispatch, or string-based lookups that might miss a grep

Phase 3 — Refactor (small steps):
8. Make one structural change at a time
9. After each change: compile/typecheck and run affected tests
10. Never have the codebase in a broken state between steps
11. Commit each step separately with message "refactor({scope}): {step description}"

Phase 4 — Verify:
12. Run the full test suite
13. Check that all call sites compile correctly
14. Run linter/formatter on changed files
15. Read the final version: does it actually read better than before?

Verification Steps

• Full test suite passes before refactor starts
• Full test suite passes after refactor ends
• No behavior changes (same inputs → same outputs)
• All call sites updated (no missed references)
• Commits are granular (one logical step per commit)

Subagent Opportunities

• Delegate test writing for uncovered code before refactoring starts
• Use a subagent to find all import sites across a large monorepo

Common Failure Modes

• Big bang refactor: changing too many files at once → hard to debug if tests break
• Missing call sites: grepping for the wrong pattern, missing dynamic usages
• No baseline: not confirming tests pass before starting
• Scope creep: refactoring adjacent code that "looked messy"

Completion Checklist

• Tests passed before and after
• Commits are atomic and descriptive
• No new TODO comments added (fix or defer explicitly)
• Code is demonstrably more readable

Pack 4: TDD Implementation

When: Building a new feature or fixing a bug with a test-first approach.

Start Prompt

You are implementing {FEATURE DESCRIPTION} using TDD.

Red-Green-Refactor protocol:

Phase 1 — RED (write failing test):
1. Write the smallest possible test that captures the desired behavior
2. Run it: {test_cmd} — confirm it FAILS
3. If it passes without implementation, the test is wrong — fix the test

Phase 2 — GREEN (minimal implementation):
4. Write the simplest code that makes the test pass
5. No gold-plating: no error handling, no edge cases, no abstractions yet
6. Run tests: confirm it PASSES
7. Commit: "test({scope}): add test for {behavior}" + "feat({scope}): minimal implementation"

Phase 3 — REFACTOR:
8. Now improve the implementation: add error handling, extract functions, add types
9. After each change: run tests
10. When satisfied: commit "refactor({scope}): clean up {thing}"

Phase 4 — Edge cases:
11. List 3-5 edge cases: empty input, null, max values, concurrent access, etc.
12. Write a test for each
13. Make each pass with minimal changes
14. Commit per case

Phase 5 — Integration:
15. Write an integration test that exercises the full flow
16. Run the complete suite: {test_cmd}

Verification Steps

• First test confirmed to fail before implementation
• Each test written before the code that makes it pass
• All edge cases listed and tested
• Integration test covers end-to-end flow
• All tests pass before PR

Subagent Opportunities

• Use a test-writer subagent to generate edge case tests after the happy path is done
• Delegate integration test writing to a separate agent

Common Failure Modes

• Test after code: writing tests after implementation — defeats the purpose, biases toward what works
• Trivial tests: testing implementation details instead of behavior
• Skipping refactor: stopping at green, never cleaning up
• Too large a first test: write the smallest useful test, not the full feature in one shot

Completion Checklist

• Each feature commit has a corresponding test commit
• No test accesses private/internal state
• Coverage >= 80% for new code
• Tests document expected behavior clearly

Pack 5: Repo Review Before Merge

When: Reviewing a PR or branch before merging to main. Catch issues a human reviewer might miss.

Start Prompt

You are a senior code reviewer. Review branch {BRANCH_NAME} before merge.

Phase 1 — Diff analysis:
1. git diff main...{branch} --stat — get the scope of change
2. git diff main...{branch} — read the full diff
3. Classify each changed file: new feature / bug fix / refactor / config / test

Phase 2 — Systematic review:
For each changed source file:
a. Does the change do what the PR description says?
b. Are there any obvious bugs (null deref, off-by-one, race condition)?
c. Is there missing error handling at I/O or network boundaries?
d. Are there hardcoded values that should be config?
e. Are there any security concerns (injection, auth bypass, secret exposure)?
f. Is the change covered by tests?

Phase 3 — Cross-cutting checks:
5. Are there any new dependencies? Check their license and security posture.
6. Does the diff include any changes to .env files or secrets? BLOCK if yes.
7. Does the migration (if any) have a rollback plan?
8. Does the API change break existing consumers?

Phase 4 — Report:
9. Output structured report with sections:
   BLOCK: must fix before merge
   REQUEST: should fix before merge
   SUGGEST: optional improvements
   PRAISE: good patterns worth keeping

Verification Steps

• Full diff was read (not just summary)
• All BLOCK items documented with specific line references
• Security check completed (secrets, injection, auth)
• Test coverage assessed for changed code
• Migration/rollback plan verified if applicable

Subagent Opportunities

• Use /cc-council for adversarial multi-perspective review (security + performance + architecture)
• Delegate security scan to a security-reviewer subagent

Common Failure Modes

• Shallow review: skimming the diff without reading full context
• Ignoring tests: not checking if tests cover the change
• Missing cross-cutting: not checking auth, logging, config for new features
• Blocking on style: using BLOCK for minor style preferences instead of REQUEST/SUGGEST

Completion Checklist

• Structured report produced (BLOCK / REQUEST / SUGGEST / PRAISE)
• All BLOCK items have file:line references
• Security checklist completed
• No opinions stated without evidence from the code

Pack 6: Generate CLAUDE.md for an Existing Repo

When: A project has no CLAUDE.md and you need to bootstrap one from the existing codebase.

Start Prompt

You are a Claude Code architect. Generate a CLAUDE.md for this repository.

Phase 1 — Detect:
1. Read: package.json / pyproject.toml / Cargo.toml / go.mod (whichever exists)
2. Check for: .eslintrc, .prettierrc, .editorconfig, tsconfig.json, pyproject.toml [tool.black]
3. Find test runner: jest.config*, vitest.config*, pytest.ini, conftest.py
4. Find CI: .github/workflows/, .gitlab-ci.yml, Jenkinsfile
5. Read README.md (first 50 lines)

Phase 2 — Extract:
6. Install command (from package.json scripts.install or README)
7. Build command (from scripts.build or Makefile)
8. Test command (from scripts.test or CI config)
9. Lint command (from scripts.lint or linter config)
10. Key directories (src/, lib/, app/, tests/, docs/)

Phase 3 — Write CLAUDE.md:
Output a CLAUDE.md under 150 lines that is a routing file, not a knowledge dump:
- Build & Test section (all commands)
- Tech stack table (5-10 rows max)
- Key paths (3-6 entries)
- Architecture (1 paragraph, repo-specific — not generic)
- Decision trees (3-5 entries pointing to specific directories)
- Conventions (extracted from linter configs, not invented)
- Don't Touch (lock files, generated dirs, build output)

Write to: CLAUDE.md

Verification Steps

• All commands verified to actually work (run install, build, test)
• Architecture paragraph is specific to this repo (not generic)
• Decision trees point to real directories that exist
• Conventions extracted from actual config files, not assumed
• File is under 150 lines

Subagent Opportunities

• Use /cc-setup --audit after generating CLAUDE.md to get a setup score
• Delegate rules file generation to a second pass

Common Failure Modes

• Generic CLAUDE.md: using template boilerplate without customizing to the actual codebase
• Wrong commands: not verifying commands actually run
• Too long: adding documentation instead of routing

Completion Checklist

• CLAUDE.md written, under 150 lines
• All build/test commands verified
• Architecture paragraph is specific and accurate

Pack 7: Create a Migration Plan Before Making Edits

When: About to make large structural changes (database schema, API refactor, framework upgrade, module reorganization). Plan before touching code.

Start Prompt

You are a migration architect. Before any code changes, produce a complete migration plan for: {DESCRIBE MIGRATION}.

Phase 1 — Inventory:
1. Map everything affected: files, tables, API endpoints, consumers, configs
2. List all dependencies (what depends on what you're changing)
3. Identify the blast radius: small (1-3 files) / medium (4-20 files) / large (20+)

Phase 2 — Risk assessment:
4. Identify data-loss risks (especially for database migrations)
5. Identify breaking changes (API changes that affect consumers)
6. Identify rollback complexity: can this be undone in < 30 minutes?

Phase 3 — Sequencing:
7. Break the migration into atomic phases that each leave the system working
8. Phase ordering rule: never leave the system broken between phases
9. Identify which phases can be deployed independently vs. require coordinated deployment

Phase 4 — Write the plan:
Output to .claude/migration-plan.md:
- Summary (1 paragraph)
- Blast radius assessment
- Phase breakdown (each phase: what changes, how to verify, how to rollback)
- Data migration scripts (if applicable)
- Rollback procedure
- Validation checklist

STOP here. Do not write any code yet. Wait for plan approval.

Verification Steps

• All affected files/tables/endpoints inventoried
• Rollback procedure is concrete and testable
• Each phase leaves the system in a working state
• Plan written to .claude/migration-plan.md
• Plan reviewed and approved before any code written

Subagent Opportunities

• Use a subagent to enumerate all import sites of modules being moved
• Use the principal-engineer-strategist agent for risk review of the plan

Common Failure Modes

• Skipping the plan: going straight to code on large migrations
• Missing consumers: not finding all callers of an API or all readers of a database table
• No rollback: planning forward-only migrations
• Big bang: not breaking the migration into deployable phases

Completion Checklist

• .claude/migration-plan.md written and reviewed
• Rollback procedure documented and tested mentally
• Go-ahead explicitly given before any code changes