Claude Code is the terminal agent that most solo developers underuse. They open it, type "refactor this", and walk away disappointed when it scatters changes across files they didn't expect. The problem isn't the tool. It's that nobody told you the patterns.
Five workflow patterns separate the people who ship from the people who fight the agent all day. Each one maps to a real solo-dev task and each one has a CLAUDE.md snippet that keeps it safe.
Claude Code follows instructions about 70 percent of the time. The other 30 percent is where you stop trusting it and start scaffolding it.
The Five Claude Code Workflow Patterns Worth Mastering
The five patterns are sequential, operator, split-and-merge, agent teams, and headless. They sit on a spectrum from "one file at a time" to "forty files in parallel," and the trick is knowing which one fits the task in front of you.
Most developers reach for operator mode for everything and then wonder why a small refactor turned into a thirty-file diff they have to review by hand. The right pattern saves you the review tax. The wrong one creates it.
Pattern One: Sequential For Single-File Refactors
Sequential is the smallest pattern. You feed one file or one function, ask one question, and let Claude edit it in place. Nothing happens outside that file unless you explicitly mention it.
The fit is obvious. Rename a variable across one module. Extract a helper from a long function. Convert a class to hooks in a React component. Anything where the blast radius is one editor pane.
The CLAUDE.md snippet for this pattern is simply a scope rule. "When asked to refactor, modify only the file mentioned. Do not touch imports in other files unless explicitly asked." That one line stops sixty percent of accidental cross-file edits.
Pattern Two: Operator For Multi-File Features
Operator is the default Claude Code mode. You describe a feature, the agent reads the repo, makes a plan, edits multiple files, and runs your tests. This is where it earns its keep on real product work.
The fit is anything that spans two to ten files. Adding a new API route with its handler, types, validation, and test. Wiring a Stripe webhook from the route through the service layer into the database. Building a new UI component plus the data hook it needs.
The CLAUDE.md guardrail for operator mode is a plan-first rule and a test rule. Force the agent to write the plan as a numbered list before touching code. Then require it to run the test suite after every batch of edits.
Pattern Three: Split And Merge For Large Migrations
Split-and-merge is what you reach for when a single conversation can't fit the work. Framework upgrades, database migrations, monorepo restructures. The kind of change that touches forty files and a context window can't hold.
The pattern is exactly what it sounds like. Split the work by domain (auth, billing, dashboard), launch one Claude Code session per domain, then merge the branches at the end. Use git worktrees so the sessions don't fight each other for the same file lock.
The CLAUDE.md piece here is a contract file. Write the migration plan once, commit it, and reference it as @docs/migration-plan.md at the top of every CLAUDE.md across the worktrees. Each session reads the same plan and stays in lane.
Running ten parallel Claude sessions on a single migration sounds insane until you do it once and the upgrade lands in an afternoon instead of two weeks.
Pattern Four: Agent Teams For Codebase Audits
Agent teams is the pattern for read-mostly work where you want multiple independent perspectives. Security audits, accessibility passes, performance reviews, dead-code hunts. The agents read, report, and don't edit.
Launch each agent with a tight CLAUDE.md scoped to its job. The security one looks for unsanitized inputs and missing rate limits. The accessibility one looks for missing alt text and aria attributes. The performance one looks for N+1 queries and unindexed columns.
The trick that makes this work is forcing every agent to write its findings to a single file like reports/audit-. You read the reports at the end, prioritize the issues, and only then do you start fixing.
Pattern Five: Headless For Recurring Chores
Headless is Claude Code without the interactive prompt. You pipe a task in, the agent runs, the result goes back to stdout. This is the pattern for cron jobs and CI workflows.
Use cases that pay back instantly are dependency upgrades (run weekly), changelog generation, stale-issue triage in your GitHub repo, and PR description drafting. Each one used to eat thirty minutes a week and now eats zero.
The setup is the claude CLI piped from a shell script. The CLAUDE.md for headless mode is the strictest one you'll write. Specify the output format exactly, forbid file edits unless they're in the explicit allowlist, and require the agent to exit with status code 1 if anything goes wrong.
Writing A CLAUDE.md That Keeps All Five Safe
The single best advice on CLAUDE.md from production teams is to keep it under 200 lines. Beyond that, adherence drops sharply because the agent allocates attention to roughly the first 150 instructions.
Structure the file in three sections. First, the non-negotiables (don't push to main, don't delete tables, don't commit secrets). Second, the conventions (file naming, commit format, test commands). Third, the workflow defaults (which pattern to use for which kind of task).
For anything truly critical, don't trust the CLAUDE.md alone. Use a Claude Code hook instead. PreToolUse hooks can block rm -rf, refuse writes to /etc, or require explicit confirmation for destructive bash. That gap from 70 percent to 100 percent compliance is what hooks exist to close.
Permission Modes And Where Each One Belongs
Claude Code has three permission modes that map cleanly to the five patterns. Default mode asks before every edit, which is right for unfamiliar codebases and sequential refactors.
Acceptedits mode skips edit confirmations but still asks for bash and write operations. This is the operator-mode default once you trust the repo's tests to catch mistakes.
Bypass permissions mode is the headless and split-and-merge mode. Use it inside git worktrees that you're prepared to throw away. Never use it on your main branch.
The git worktree plus bypass-permissions combo is the single biggest productivity unlock in Claude Code workflows. Treat the worktree as disposable and the agent as ambitious.
Prompt Caching And The Cost Curve At Scale
The default Claude Code conversation re-sends your full repo context on every turn. At twenty turns, that's twenty repo reads and a bill that compounds. Prompt caching cuts the repeated context cost to ten percent of the normal rate.
Caching kicks in automatically when you keep the same conversation open. The CLAUDE.md, the project files Claude already read, the system prompt, all get cached for five minutes after each turn. The longer the session, the better the savings.
For headless and split-and-merge, point sessions at the same cached prefix by reading the same CLAUDE.md first. The Anthropic prompt caching docs walk through the cache breakpoints in detail.
The Three Anti-Patterns We Stopped Reaching For
Three patterns that look productive on paper and aren't. First, the "do everything from one prompt" approach. Big prompts produce big bad diffs. Break the work into the smallest unit that produces a meaningful commit.
Second, the "let it pick the model" trick. Always be explicit about Sonnet versus Opus. Sonnet is the right default for repetitive code edits. Opus pays off on planning, refactor reasoning, and complex debugging.
Third, the never-restart trap. After eight or ten turns the context gets noisy with old tool calls and partial states. Open a new session, paste the latest plan, and let it start clean.
Skills And Subagents: The Reusable Workflow Layer
Skills are the 2026 evolution of CLAUDE.md. A skill lives in .claude/skills/<n>/SKILL.md and packages a repeatable workflow with its own prompts, tools, and references. Release deployment, dependency upgrade, doc generation, security review, all good fits.
The pattern that took longest to internalize was treating skills like git aliases. You don't write a skill the first time you do something. You write it the third time. By then the workflow has stabilized and the skill captures real value.
Subagents push the same idea further. A subagent runs in its own context with its own model and its own tools, returns a focused answer to the main session, and disappears. Use them for research-shaped tasks (find all the places X is referenced) and review-shaped tasks (check this PR for security issues).
What Changed In Late 2025 And Early 2026
The biggest shift was the move from "Claude Code can edit one repo" to "Claude Code can coordinate ten parallel sessions across one repo." Worktree-aware workflows became the default for any non-trivial migration or refactor.
The second shift was hooks reaching production maturity. PreToolUse, PostToolUse, and Stop hooks let you wire deterministic checks into the agent loop without trusting the model to enforce them itself. That's the gap-closer for the 30 percent of the time the model doesn't follow CLAUDE.md.
The third shift was module-level CLAUDE.md imports through @docs/section.md syntax. You can now keep a thin top-level CLAUDE.md and import the relevant deep file per task. The 200-line ceiling becomes much easier to respect when each invocation only loads the bytes it needs.
For the broader comparison of Claude Code against IDE-native agents, see the AI coding assistants roundup. And if you're picking between Cursor and Claude Code for a fresh project, the Cursor versus Windsurf versus Claude Code piece covers the IDE-versus-terminal split in detail. Anthropic's official Claude Code best practices documents the canonical CLAUDE.md patterns.
Frequently Asked Questions
How long should CLAUDE.md actually be?
Under 200 lines. Past that, adherence drops measurably. Use @imports to split larger files into modules and only load the relevant slice per task.
When does Claude Code beat Cursor and when does Cursor win?
Claude Code wins on cross-file refactors, large planning tasks, and headless automation. Cursor wins on single-file edits where you want the diff visible in the editor before accepting.
Can I run Claude Code on legacy languages like PHP or Java?
Yes, and it handles them well. The pattern is the same: tight CLAUDE.md, plan first, run tests. PHP and Java repos benefit even more from sequential mode because the files are bigger and the radius is wider.
What's the cheapest way to use Claude Code daily?
Use Sonnet as the default, switch to Opus only for planning and hard debugging, and lean on prompt caching by keeping sessions open across related tasks.
Is split-and-merge worth the worktree setup overhead?
For any migration that touches more than fifteen files, yes. For a small feature, no. The break-even point is roughly the point where one conversation can't hold the context.
How do I keep Claude Code from hallucinating APIs that don't exist?
Pin it to your codebase. Tell it explicitly to only use functions and types it can grep for. The CLAUDE.md line "never invent an import. If you need a function, grep for it first" cuts hallucinations sharply.
Do hooks slow the workflow down?
Negligibly. A PreToolUse hook is a shell script that runs in under a second. The protection it gives on destructive commands is worth a thousand of those seconds.
What's the right test command in CLAUDE.md?
The fastest one. If your full suite takes ninety seconds, write a fast subset and put that in CLAUDE.md. Claude Code runs the test after most edits and slow tests train it to skip them.
