Claude Code Workflows: A Sensible Sample Information

Why Workflow Patterns Matter for Claude Code

The hole between ad-hoc prompting and structured Claude Code workflows reveals up as inconsistent outputs and guide rework on each iteration. Builders who deal with Claude Code as an interactive chatbot quite than a configurable growth instrument routinely encounter hallucinated imports, ignored venture conventions, and outputs that require line-by-line correction. Claude Code workflow patterns, anchored by well-crafted CLAUDE.md configuration, remodel this dynamic by giving the agent persistent, project-aware context it will probably reference throughout each session.

This information gives a structured taxonomy of CLAUDE.md finest practices and 5 repeatable workflow patterns constructed round them. It targets intermediate builders already comfy with CLI instruments and AI-assisted coding who need to transfer previous trial-and-error into deliberate, reproducible workflows utilizing a JavaScript and Node.js stack.

Stipulations

Earlier than following the patterns on this information, guarantee you could have:

• Claude Code CLI put in and accessible in your system PATH. Run claude --version to verify.
• Node.js ≥20 LTS and npm ≥8.x put in (confirm with node --version and npm --version).
• Claude Code authenticated on your setting. In CI or non-interactive environments (no TTY), configure authentication earlier than invoking claude; see the official documentation for non-interactive authentication strategies.
• Bash ≥4.0 accessible through #!/usr/bin/env bash. On macOS, the default Bash is model 3.2; the shell scripts on this information require Bash 4.0+ for dependable entice ERR habits. Set up a more moderen model through Homebrew (brew set up bash) if wanted.
• A package deal.json with the npm scripts referenced on this information (check, lint, construct, dev, db:migrate) outlined on your venture.

What Is CLAUDE.md and Why It is the Basis of Each Workflow

How CLAUDE.md Shapes Claude Code’s Conduct

CLAUDE.md is a Markdown file that capabilities as a project-level instruction set for Claude Code. In contrast to ephemeral system prompts that vanish between classes, CLAUDE.md persists within the repository. Claude Code reads it initially of each session, selecting up the venture’s tech stack, coding conventions, most popular instructions, and behavioral constraints. The consequence: Claude Code operates with a baseline understanding of the venture with out the developer re-explaining fundamentals every time.

Claude Code reads the file earlier than processing any consumer immediate, shaping the way it interprets and responds to each subsequent instruction inside that venture.

Claude Code workflow patterns, anchored by well-crafted CLAUDE.md configuration, remodel this dynamic by giving the agent persistent, project-aware context it will probably reference throughout each session.

The Three Scopes of CLAUDE.md

CLAUDE.md helps three distinct scopes. A project-level CLAUDE.md sits on the repository root and applies globally to all interactions inside that venture. Listing-level CLAUDE.md information could be nested inside subpackages or modules, permitting completely different conventions for various elements of a monorepo. A user-level file at ~/.claude/CLAUDE.md units private defaults that apply throughout all tasks, helpful for preferences like most popular response verbosity or common coding type.

When a number of scopes exist, they layer collectively. Listing-level information complement (quite than substitute) the root-level configuration, and user-level defaults yield to project-specific directives. In instances of battle, seek the advice of the official Claude Code documentation for the priority guidelines that apply to your model.

# CLAUDE.md

## Tech Stack
- Runtime: Node.js 20 LTS
- Framework: Categorical 4.x
- Language: JavaScript (ES2022+)

## Fashion
- Use named exports completely
- Favor async/await over uncooked Guarantees

## Instructions
- Run assessments: `npm check`

CLAUDE.md Finest Practices: What to Embody

Venture Context and Tech Stack Declaration

Declaring the runtime, framework, and key dependencies explicitly in CLAUDE.md reduces one of the frequent failure modes: hallucinated imports and version-mismatched API utilization. When Claude Code is aware of the venture makes use of Categorical 4.x quite than 5.x, it avoids suggesting APIs that don’t exist within the put in model. The identical applies to specifying Node.js model constraints, database drivers, and ORM variations.

Past dependencies, a quick venture construction overview helps Claude Code perceive the place to position new information and the way current modules relate to one another.

# CLAUDE.md

## Venture Overview
E-commerce REST API serving a React frontend.

## Tech Stack
# Exchange all model numbers under along with your venture's precise put in variations
- Runtime: Node.js 20.11 LTS
- Framework: Categorical 4.18.2
- Database: PostgreSQL 15 through `pg` 8.11
- ORM: None — uncooked SQL with parameterized queries
- Auth: `jsonwebtoken` 9.0, `bcrypt` 5.1

## Venture Construction
- `src/routes/` — Categorical route handlers
- `src/middleware/` — Auth, validation, error dealing with
- `src/db/` — Database queries and connection pool
- `assessments/` — Jest check information mirroring `src/` construction

Coding Conventions and Fashion Guidelines

Somewhat than duplicating each ESLint or Prettier rule, CLAUDE.md ought to reference current configuration information and spotlight conventions that static evaluation instruments don’t implement. This consists of architectural patterns (similar to all the time utilizing a service layer between routes and database queries), error dealing with methods (like wrapping async route handlers in a centralized error wrapper), and naming conventions for information and capabilities.

Command References and Construct Scripts

Offering the precise instructions Claude Code can invoke removes guesswork. When shell execution is enabled, Claude Code can run these instructions immediately; see the official documentation for the way to configure and limit permitted instructions earlier than enabling this functionality. Itemizing check, construct, lint, and deploy instructions ensures it runs the proper toolchain.

## Instructions
- Take a look at all: `npm check`
- Take a look at single file: `npm check -- --testPathPattern='routes/orders'`
  # Accepts a regex matched in opposition to the total file path.
  # Exchange 'routes/orders' along with your goal path phase.
- Lint: `npm run lint`
- Lint repair: `npm run lint:repair`
- Dev server: `npm run dev`
- Construct: `npm run construct`
- DB migrate: `npm run db:migrate`

Word: --testPathPattern accepts a regex matched in opposition to the total file path, not a literal filename. For instance, --testPathPattern='routes/orders' will match any check file whose path accommodates routes/orders.

Behavioral Guardrails

Guardrails outline what Claude Code ought to by no means do autonomously. These are vital for stopping harmful operations. Examples embrace directives like “by no means modify package-lock.json immediately,” “don’t delete or overwrite migration information,” and “all the time write assessments earlier than implementation.” Guardrails additionally set scope boundaries, similar to “don’t make adjustments outdoors the src/ listing with out express approval.”

CLAUDE.md Anti-Patterns: What to Exclude

Overly Verbose Directions

Excessively lengthy CLAUDE.md information scale back the context accessible on your precise prompts. Each token Claude Code spends studying bloated directions is a token it can’t spend in your code. The purpose is density: most helpful sign in minimal token depend.

Contradictory or Redundant Directives

Conflicting type guidelines, similar to one part demanding semicolons and one other part displaying examples with out them, produce inconsistent outputs. Equally, re-specifying guidelines already enforced by tsconfig.json, .eslintrc, or .prettierrc wastes context house and creates drift when these config information are up to date however CLAUDE.md shouldn’t be.

Secrets and techniques, Credentials, and Atmosphere-Particular Values

CLAUDE.md is usually dedicated to model management, making it seen to all group members and third-party code scanning instruments. Together with API keys, database connection strings, or different secrets and techniques creates a safety vulnerability. As a substitute, reference .env patterns and instruct Claude Code to make use of setting variables.

Here’s a bloated CLAUDE.md part refactored right into a concise model:

# ❌ Earlier than — Bloated
## Database
We use PostgreSQL.
Connection string format: postgres://<consumer>:<password>@<host>:<port>/<dbname>
# By no means embed actual credentials — use setting variables solely
At all times use PostgreSQL. Don't use MySQL. Don't use SQLite. Don't use MongoDB.
When writing queries, all the time use parameterized queries. By no means use string
concatenation for queries. This is essential. String concatenation is
harmful due to SQL injection assaults which may compromise the database...
[continues for 200 more words]

# ✅ After — Concise
## Database
- PostgreSQL 15 through `pg` 8.11
- Connection config: see `.env` and `src/db/pool.js`
- At all times use parameterized queries — no string concatenation

5 Sensible Workflow Patterns for On a regular basis Growth

Sample 1: The Function Implementation Workflow

This sample buildings characteristic growth as a sequential chain: specification, scaffold, implement, check, overview. Defining the anticipated output format for every step in CLAUDE.md prevents Claude Code from leaping forward or producing incomplete artifacts.

## Workflow: Function Implementation

### Steps
1. **Spec**: Summarize the characteristic necessities in a bullet checklist. Don't write code but.
2. **Scaffold**: Create file stubs with exported perform signatures and JSDoc feedback solely.
3. **Implement**: Fill within the perform our bodies. Observe patterns in current `src/routes/` handlers.
4. **Take a look at**: Write Jest assessments protecting blissful path, error instances, and edge instances.
5. **Overview**: Self-review in opposition to the Overview Guidelines under. Checklist any considerations.

### Output Format
- Every step have to be accomplished and confirmed earlier than continuing to the following.
- Checks should go (`npm check`) earlier than the Overview step.

A pattern immediate invoking this workflow for a JavaScript REST endpoint:

Observe the Function Implementation workflow. The characteristic: a GET /api/merchandise/:id
endpoint that returns a single product by ID from the merchandise desk. Return 404
with { error: "Product not discovered" } if the ID would not exist. Embody enter
validation for the ID parameter.

Sample 2: The Bug Triage and Repair Workflow

Somewhat than pasting a stack hint and asking “repair this,” a structured bug workflow gives copy steps, related log output, anticipated versus precise habits, and the file(s) probably concerned. A CLAUDE.md directive imposing “diagnose earlier than fixing” prevents Claude Code from instantly rewriting code earlier than understanding root trigger:

## Workflow: Bug Triage
When given a bug report, first clarify the possible trigger and affected code paths.
Don't modify information till you verify the prognosis.

Sample 3: The Code Overview and Refactor Workflow

Instructing Claude Code to research code in opposition to venture conventions earlier than suggesting adjustments produces evaluations that catch extra conference violations and flag lacking check protection. A overview guidelines part in CLAUDE.md provides Claude Code a concrete rubric to judge in opposition to, and limiting the scope of autonomous refactors prevents sprawling adjustments which are tough to overview.

## Overview Guidelines
When reviewing code, verify every merchandise and report go/fail:
- [ ] Named exports used (no default exports)
- [ ] Async route handlers wrapped in `asyncHandler` middleware (utilizing `express-async-handler` or an equal wrapper)
- [ ] Enter validation current for all request parameters
- [ ] Database queries use parameterized placeholders
- [ ] Error responses observe `{ error: string }` format
- [ ] Corresponding check file exists and covers error instances
- [ ] No hardcoded configuration values — use `course of.env`

A pattern overview immediate paired with this guidelines:

Overview src/routes/orders.js in opposition to the Overview Guidelines. Report every merchandise as
go or fail with a one-line clarification. Then counsel particular fixes for any failures.

Sample 4: The Take a look at Technology Workflow

Defining the check framework, assertion type, and protection expectations in CLAUDE.md standardizes generated assessments. Directives ought to specify: “Use Jest with anticipate assertions. Group assessments with describe blocks per perform. Embody not less than one check for the blissful path, one for invalid enter, and one for error propagation.”

Level Claude Code at an current implementation file and ask it to generate the corresponding check file following these constraints:

Generate a Jest check file for src/routes/orders.js. Observe the check conventions
in CLAUDE.md. Cowl the blissful path, one invalid-input case, and one error
propagation case. Output solely the check file.

Patterns 4 and 5 are deliberately shorter than Patterns 1-3. They require fewer CLAUDE.md directives as a result of the workflow itself is less complicated: one enter file, one output file, one go.

Sample 5: The Documentation Workflow

Composing Workflows: Chaining Patterns with Claude Code

Session Continuity and Multi-Step Orchestration

Claude Code’s session administration permits chaining the 5 patterns right into a full characteristic supply cycle: implement, then check, then overview, then doc, all inside a persistent context that references the identical venture conventions all through.

The sensible constraint is context window measurement. After 3-4 chained steps, gathered code output can crowd out the working context. Break chains at pure boundaries (after assessments go, as an illustration) and resume in a brand new session for a realistic stability between continuity and accessible context.

Each token Claude Code spends studying bloated directions is a token it can’t spend in your code. The purpose is density: most helpful sign in minimal token depend.

Utilizing Shell Scripts to Automate Workflow Sequences

For CI pipelines and repeatable workflows, wrapping Claude Code invocations in shell scripts utilizing the --print flag (which outputs outcomes to stdout with out interactive mode) allows automation. In CI environments, guarantee Claude Code is authenticated utilizing the suitable non-interactive methodology earlier than invoking this flag; see the official documentation for particulars.

#!/usr/bin/env bash
set -euo pipefail


if [[ "${BASH_VERSINFO[0]}" -lt 4 ]]; then
  echo "Error: Bash >= 4.0 required. Present: ${BASH_VERSION}" >&2
  echo "On macOS, set up through: brew set up bash" >&2
  exit 1
fi

CURRENT_STEP="init"
entice 'echo "Workflow failed at step: ${CURRENT_STEP}" >&2' ERR

mkdir -p output || { echo "Can't create output/ listing." >&2; exit 1; }

FEATURE_DESC="${1:-}"

if [[ -z "${FEATURE_DESC}" ]]; then
  echo "Utilization: $0 '<characteristic description>'" >&2
  exit 1
fi


if [[ ${#FEATURE_DESC} -gt 500 ]]; then
  echo "Error: Function description exceeds 500 characters." >&2
  exit 1
fi


if [[ "${FEATURE_DESC}" =~ [`$;|&<>] ]]; then
  echo "Error: Function description accommodates disallowed characters." >&2
  exit 1
fi

CURRENT_STEP="1: Implement"
echo "=== Step 1: Implement ==="
timeout 300 claude --print 
  "Observe the Function Implementation workflow for: ${FEATURE_DESC}" 
  > output/implement.md

CURRENT_STEP="2: Run Checks"
echo "=== Step 2: Run Checks ==="
npm check 2>&1 | tee output/check.log

CURRENT_STEP="3: Overview"
echo "=== Step 3: Overview ==="
timeout 300 claude --print 
  "Overview all information modified within the final commit in opposition to the Overview Guidelines" 
  > output/overview.md

echo "=== Accomplished ==="
echo "Implementation : output/implement.md"
echo "Take a look at log       : output/check.log"
echo "Overview         : output/overview.md"

Word: The timeout command is from GNU coreutils (accessible by default on Linux; on macOS set up through brew set up coreutils and use gtimeout). Make sure the output/ listing is listed in your .gitignore to keep away from unintentionally committing generated artifacts.

Register this script as an npm script ("workflow:characteristic": "bash scripts/feature-workflow.sh") for team-wide consistency.

Implementation Guidelines

Constructing Your Personal Sample Library

Begin with a single workflow sample and iterate. The characteristic implementation workflow is a pure place to begin as a result of it touches the commonest growth exercise and exposes gaps in CLAUDE.md configuration rapidly.

CLAUDE.md is a dwelling doc. It belongs in model management, must be reviewed in pull requests alongside code adjustments, and advantages from periodic trimming because the venture evolves and earlier directives turn out to be out of date. The implementation guidelines above works as each a place to begin and a recurring audit instrument.

Claude Code’s capabilities proceed to develop, with enhancements to context dealing with, instrument use, and multi-file enhancing arriving in successive releases. Workflow patterns which are express and modular in the present day will adapt cleanly to these adjustments. Tightly coupled or overly inflexible configurations will want rework.