Claude Code Development Workflows

Claude Code can explore a codebase deeply. On non-trivial work, the harder problem is convergence. While designing an account-recovery flow, Claude may find a real inconsistency in token handling and spend most of the design on it, leaving the requested recovery behavior vague.

claude-code-workflows keeps that exploration pointed at an agreed result. It agrees on the outcome and exclusions before design, checks designs against the repository, verifies each task before commit, and, on larger changes, independently reviews the finished implementation for intended behavior and security. Within that scope, Claude chooses the implementation details from the codebase.

Use Claude Code directly when the outcome and safe implementation boundary are already clear. Use these workflows when a change needs scope agreement, durable design decisions, a reliable handoff between contexts, or independent verification.

---

When is the workflow useful?

The workflow adds agent calls and artifacts, so it should earn that cost. Use it when a real side finding could pull a larger change away from its intended result, a design could be internally consistent but miss the requested behavior, or a passing test could fail to observe what it claims to prove.

Once the implementation scope is approved, Claude carries the tasks through focused verification, repository quality checks, commits, and final review without asking for routine implementation decisions. Product changes and major design changes return to the user; reversible implementation choices remain with Claude. Because the process is packaged as a Claude Code plugin, a team can apply the same controls across repositories without prescribing Claude's steps.

---

Quick Start

Requires a Claude Code release with plugin marketplace support.

Choose a path

| What do you need? | Start with | Plugin | |---|---|---| | Deliver a backend, API, CLI, or general change end to end | /recipe-implement | dev-workflows | | Design a backend or general change before implementation | /recipe-design | dev-workflows | | Design and build a React / TypeScript frontend | /recipe-front-design → /recipe-front-plan → /recipe-front-build | dev-workflows-frontend | | Deliver a backend and React frontend change together | /recipe-fullstack-implement | dev-workflows-fullstack | | Review an implementation against its design | /recipe-review or /recipe-front-review | dev-workflows or dev-workflows-frontend | | Investigate a problem before choosing a fix | /recipe-diagnose | Any workflow plugin | | Document an existing system from its code | /recipe-reverse-engineer | dev-workflows or dev-workflows-fullstack | | A throwaway experiment or prototype | Use Claude Code directly | None |

Common setup

# 1. Start Claude Code
claude

# 2. Add the marketplace
/plugin marketplace add shinpr/claude-code-workflows

Install one workflow plugin

Install the plugin that matches your project. If the install tells you to run /reload-plugins, do that before invoking the recipe.

# Backend or general
/plugin install dev-workflows@claude-code-workflows
/recipe-implement "Add rate limiting to the public API"

# Frontend
/plugin install dev-workflows-frontend@claude-code-workflows
/recipe-front-design "Add account recovery screens"

# Full-stack
/plugin install dev-workflows-fullstack@claude-code-workflows
/recipe-fullstack-implement "Add user authentication with JWT + login form"

Install only one workflow plugin. dev-workflows-fullstack already contains the backend and frontend workflows. If you previously used full-stack recipes from dev-workflows, migrate to dev-workflows-fullstack.

/recipe-front-design stops after the applicable UI Spec and Design Doc are reviewed and approved. Run /recipe-front-plan and /recipe-front-build when you are ready to continue. For a backend or general change, /recipe-design, /recipe-plan, and /recipe-build provide the same staged path.

Team setup

Claude Code supports project-scoped marketplaces and plugins. Commit the resulting .claude/settings.json so contributors are prompted to use the same workflow plugin.

claude plugin marketplace add shinpr/claude-code-workflows --scope project
claude plugin install dev-workflows-fullstack@claude-code-workflows --scope project

Replace dev-workflows-fullstack with the plugin that matches the repository. See the Claude Code plugin documentation for project and managed installation options.

---

How It Works

flowchart LR
    A[Request] --> B[Agree on outcome and exclusions]
    B --> C{One evident implementation path?}
    C -->|Yes| S[Direct task cycle]
    S --> J[Complete]
    C -->|No| D[Inspect, design, and review]
    D --> E[Approve implementation scope]
    E --> F[Per task: implement, verify, quality-check, commit]
    F --> I[Independent implementation and security review]
    I -->|Correction| F
    I -->|Boundary changed| B
    I -->|Passed| J[Complete]

The number of product and design decisions determines the route, not file count or the amount of implementation work:

| Scale | What the change needs | What happens | |-------|-----------------------|--------------| | Small | One outcome that follows an existing pattern within one responsibility | Direct task cycle → focused and repository checks → security review | | Medium | One outcome that crosses responsibilities or needs a lasting design decision | Reviewed Design Doc, plus UI Spec / ADR when required → selected integration/E2E proof → reviewed Work Plan → task cycles → final review | | Large | Multiple independent product outcomes that need separate design decisions | Reviewed PRD and Design Docs, plus UI Spec / ADR when required → selected integration/E2E proof → reviewed Work Plan → task cycles → final review |

UI Specs, ADRs, and integration or E2E test skeletons appear only when their decisions or proof boundaries apply.

Generating an artifact does not advance the workflow on its own. Design claims are checked against the repository before approval. The Work Plan is reviewed for coverage, dependency order, and executable verification before it authorizes implementation. Each task is committed only after its focused checks and applicable repository checks complete. When staged implementation is finished, separate reviews examine design consistency, observable coverage, and security.

The main session decides which findings belong to the current outcome, resolves implementation questions from the repository, and keeps unaffected work moving. Review suggestions do not become work automatically. An accepted correction returns through implementation and the affected verification gates.

How decisions survive fresh contexts

Fresh contexts keep one phase's reasoning from silently becoming the next phase's authority. The included Work Plan template requires every approved technical requirement from a Design Doc to have a covering task or an explicit gap. It does not turn every document section or review suggestion into a task. A gap means an approved requirement has no implementation or verification task yet.

| Design Doc | DD Section | DD Item | Category | Covered By Task(s) | Gap Status | Notes |
|---|---|---|---|---|---|---|
| docs/design/example.md | API contract | Preserve the error response shape | contract-change | Phase 2 Task 1 | covered | |
| docs/design/example.md | Verification | Exercise cache invalidation | verification | | gap | Add a covering task before approval |

The Task template carries binding decisions and observable contract values into implementation, each with a yes-or-no compliance check. After execution, the applicable repository checks run against the complete task change before commit. The final reviewers read the same approved sources and the completed code instead of relying on the implementation conversation.

A real workflow run

The incremental sync feature in mcp-local-rag was a 42-file change across filesystem scanning, storage, and both the CLI and MCP surfaces. An independent security review sent the implementation back twice. It caught file reads happening before validation and a path-containment escape through a symlinked parent.

The run began with an existing Work Plan that referred to an ADR and Design Doc that were not present, leaving the approved source for its technical decisions unclear. The user chose to treat the Work Plan as the source of truth, and the recipe divided it into 13 planned tasks. The final implementation included the changes needed to verify the approved behavior, while the PR records why watch mode and persistent jobs were left out.

What to inspect after the first run

After the first run, inspect the artifacts:

• Did the agreed approach extend what already exists and give evidence for each addition?
• Can you follow each requirement into a task and an observable verification method?
• Did every completed task pass its focused and repository quality checks before commit?
• Did final review compare the whole change with the intended behavior and security requirements?
• When a reviewer proposed more work, did the report show why it was applied or declined?

---

Typical Workflows

End-to-end backend or general development

/recipe-implement "Add rate limiting to the public API"

The recipe scopes the change, inspects the current implementation, creates only the documents required by its decisions, pauses when a decision is needed, and carries the plan through implementation and final review.

Design first, implement later

# Backend or general
/recipe-design "Design rate limiting for the public API"
/recipe-plan
/recipe-build

# React frontend
/recipe-front-design "Build a user profile dashboard"
/recipe-front-plan
/recipe-front-build

The design recipes inspect the existing code, confirm the scope, create the required documents, run an independent consistency review, and stop for approval. Planning and implementation can continue later, in a new context or by another contributor, from those approved artifacts.

The frontend path adds UI analysis and a UI Spec when UI structure or behavior remains to be designed, plus component architecture, React Testing Library, and TypeScript checks.

For example, two dashboard components may each handle loading correctly while the combined screen has no defined behavior when one is loading and the other has failed. The UI Spec records that state combination and traces it into design and test work before integration.

Full-stack development

/recipe-fullstack-implement "Add user authentication with JWT + React login form"

When the change has multiple independent product outcomes, one PRD covers the whole feature. Backend and frontend design stay separate, design-sync checks the boundary between them, and the work plan uses vertical slices so integration is exercised before the end.

Use /recipe-fullstack-build to continue from an existing full-stack work plan. The full-stack plugin also includes the applicable backend and frontend recipes.

<details> <summary>M