Claude Code recipes

Recipe: debug a failing test

A failing test is a reproducible signal: it tells you exactly what the code promised and what it actually did. Claude Code turns that signal into a fix by following a four-step loop: Reproduce, Isolate, Fix, Confirm.

Reproduce means running the test command so Claude sees the exact error output in context. Isolate means narrowing the cause to one function, one assertion, or one bad assumption. Fix means changing only the code that caused the failure. Confirm means running the test again and reading a green result before closing the task.

The key discipline is: do not ask Claude to fix anything before it has read the error. Paste the full test output (the stack trace, which is the chain of function calls that led to the crash) into your prompt. Without it, Claude guesses.

1. Run your test suite and copy the failure output.
2. Open Claude Code and paste the output with a clear goal.
3. Let Claude read the relevant source files and propose a fix.
4. Apply the fix, re-run the tests, and confirm green before moving on.

Recipe: refactor safely

Refactoring means changing the internal structure of code without changing what it does from the outside. The danger is silent breakage: you move things around, and a feature quietly stops working. The antidote is a test lock, a suite of automated tests that proves behavior before you touch a single line of logic.

The recipe has three steps in strict order:

1. Write or generate tests first. Ask Claude Code to read your file and produce tests that cover the current behavior. Commit those tests. They are your safety net.
2. Run the tests in watch mode. Use /terminal inside Claude Code or your own shell to keep the test runner alive. Every time Claude changes a file, the runner re-executes and turns red the moment something breaks.
3. Ask Claude Code to refactor, one concern at a time. Small, focused changes make failures easy to trace. If a test goes red, Claude Code can read the failure output and fix it before moving on.

Claude Code reads test output automatically when you paste or pipe it into the conversation. That feedback loop, write test, refactor, read failure, fix, is what makes AI-assisted refactoring reliable rather than reckless.

Recipe: build a feature test first

Test-Driven Development (TDD) is a workflow where you write a failing test before you write the code that makes it pass. The cycle has three steps: red (test fails), green (code passes the test), refactor (clean up without breaking the test). Claude Code is a natural fit because you can describe intent in plain language and let it generate both the test and the implementation in the right order.

To start, give Claude Code a clear feature description and tell it explicitly to write the test first. The key phrase is: "write a failing test, then make it pass." Without that instruction Claude will often jump straight to the implementation.

Once Claude produces the test file, run it immediately. Confirm it is red (failing) before asking Claude to write the implementation. This one checkpoint prevents the most common TDD mistake: writing a test that was never actually testing anything.

• Red: Claude writes the test, you run it, it fails.
• Green: Claude writes the minimum code to pass the test.
• Refactor: Ask Claude to clean up duplication or naming, then re-run.
• Repeat: Add the next test for the next piece of behaviour.

Recipe: review a pull request

A pull request (PR) is a proposal to merge a set of code changes into a project. The changes are presented as a diff (short for difference), a file-by-file view showing lines removed in red and lines added in green. Reading a diff carefully is how bugs and unclear logic get caught before they reach production.

Claude Code can read a diff and act as a second reviewer. You point it at a branch or a PR URL, and it flags issues across several dimensions:

• Correctness bugs: logic errors, off-by-one mistakes, unhandled edge cases.
• Clarity problems: variable names that mislead, missing comments on non-obvious code.
• Regressions: changes that silently break existing behavior covered elsewhere in the codebase.
• Security signals: hardcoded secrets, unchecked user input, unsafe use of dependencies.

The /code-review skill inside Claude Code orchestrates this automatically. It reads staged changes or a named branch diff, runs analysis, and returns structured findings. You control depth with an effort flag: --effort low for a quick pass, --effort high for broader coverage including uncertain findings. Add --comment to post findings directly as inline PR comments on GitHub, or --fix to apply safe fixes to the working tree.

Recipe: build a feature end to end

A feature build is the full arc from a plain-English request to a working, tested change committed in your repo. Claude Code handles every step, but you get better results when you structure that arc deliberately.

The recipe has four phases:

1. Scope. Open Claude Code in your project root and describe what you want in one clear sentence. Ask it to list the files it will touch before writing anything: /plan or just say "list the files you will change and why, then wait for my go-ahead."
2. Implement. Approve the plan, then let Claude Code write the code. Watch the tool calls in the terminal. If a call looks wrong, type /stop to interrupt without losing context.
3. Verify. Ask Claude Code to run the relevant tests or linter: run the tests for this module and show me the output. For a UI change, use the /run skill or ask it to start the dev server and describe what to check.
4. Commit. Once tests pass, ask Claude Code to stage only the changed files and write a commit message. Review the diff it shows before confirming.

Two habits that prevent rework: always read the plan before you approve it, and always run tests inside Claude Code rather than trusting a visual inspection alone.

Recipe: fix a bug systematically

Jumping straight to a fix without understanding the root cause is the fastest way to create two bugs instead of one. The systematic approach forces diagnosis first, patch second. Claude Code supports this discipline through a set of commands that read, trace, and test before touching any code.

The workflow has four phases. Reproduce: confirm the bug is real and isolated. Trace: find the exact line and reason it fails. Hypothesize: state one specific cause before writing any fix. Verify: run the tests again after the patch to confirm the symptom is gone and nothing new broke (this is called a regression check).

Claude Code's /systematic-debugging skill enforces this order. You can also drive it manually with plain prompts. Either way, the key rule is: do not accept a patch that Claude proposes unless it also explains why the bug happened.

• Open with: what is the root cause of this error?, not fix this error.
• Ask Claude to show the call stack (the chain of function calls that led to the crash) before suggesting a change.
• Request a minimal reproduction: the smallest piece of code that still triggers the bug.
• After the patch, run claude --print "run the existing test suite and report any failures" to catch regressions.

Recipe: migrate or upgrade a dependency

A dependency is an external library your project relies on (for example, a date formatter or an HTTP client). Upgrading one means changing a version number, fixing every breakage, and confirming the app still works. Claude Code turns that multi-step chore into a guided conversation.

The recipe has four stages:

1. Plan: ask Claude Code to read the current version, check the changelog, and list breaking changes that affect your code.
2. Change: let it edit package.json (or the relevant manifest) and run the install command.
3. Run: execute your build and test suite so errors surface immediately.
4. Verify: review the diff, confirm tests pass, and do a quick smoke test of the affected feature.

Because Claude Code can read files, run shell commands, and iterate in one session, it catches cascading errors (where fixing one import breaks another) without you switching between terminal tabs. Always commit your code before starting so you have a clean rollback point.

Recipe: onboard an unknown codebase

When you open a codebase you have never seen before, jumping straight into editing is the fastest way to break things. The professional move is to map the territory first: understand what exists, where the entry points are, and only then act. Claude Code can do most of this work for you in one session.

Start with a broad reconnaissance pass. Ask Claude Code to describe the project structure, list the main directories, and identify entry points (the files where execution begins, such as index.js, main.py, or app.ts). Then ask it to find the key configuration files: package managers (package.json, pyproject.toml), environment templates (.env.example), and CI definitions (.github/workflows/).

Once you have a mental map, the most valuable thing you can do is write a CLAUDE.md file at the root of the project. This plain-text file is automatically read by Claude Code at the start of every session. It acts as a persistent briefing: it tells Claude Code how to build the project, which commands to avoid, which directories matter, and any team conventions. Without it, every new session starts from zero.

A good CLAUDE.md covers four things:

• Build and run commands: how to install dependencies and start the app.
• Test command: the single command that runs the full test suite.
• Architecture notes: which folders own which concern (API layer, UI layer, database layer).
• Off-limits rules: files or patterns Claude Code must never modify without explicit permission.

Recipe: generate and maintain docs

Documentation that diverges from the code is worse than no documentation: it misleads. The solution is to treat docs as a build artifact, generated and updated by Claude Code whenever the code changes. The core idea is docs-as-code: your README, API reference, and changelogs live in the repo and are regenerated on demand.

Claude Code can read your entire codebase in one pass and produce accurate, structured documentation. The key flags are --print (non-interactive, pipes output to a file) and --allowedTools "Read,Write" (restricts Claude to only reading source and writing docs, nothing else). Always scope the prompt tightly: name the files to read and the file to write.

For ongoing sync, two patterns work well:

• Git hook: a pre-commit hook runs claude --print and stages the updated doc file automatically, so docs are never committed out of date.
• CI step: a GitHub Actions or other pipeline step regenerates docs on every merge to main, then opens a pull request if anything changed.
• Targeted refresh: after editing a specific module, run Claude Code scoped to that file only, keeping the cost and latency low.
• Changelog generation: pass git log --oneline output directly in the prompt and ask Claude to produce a human-readable changelog section.

The model id for everyday doc tasks is claude-sonnet-4-6: fast and accurate enough for structured output. Reserve claude-opus-4-8 for architecture-level documentation that requires deep reasoning about design decisions.

Recipe: automate a repetitive chore

A repetitive chore is any task you run more than two or three times with the same shape: rename a batch of files, convert a report to a different format, pull data from an API and format it, clean up logs. These are prime candidates for automation with Claude Code.

The first step is to spot the pattern. Ask yourself: what inputs change each time, and what stays fixed? The fixed part becomes the script; the changing part becomes a parameter (a variable input you pass in). Claude Code can write, run, and refine that script in one conversation.

The second step is to capture the recipe so you never type it from scratch again. Claude Code gives you two options:

• A script file: a Node, Python, or shell script saved in your project that you invoke with one command whenever you need it.
• A slash-command (skill): a short markdown file placed in ~/.claude/skills/ that becomes a /your-command you can trigger in any future session.

Once the recipe exists, running the chore costs you nothing but a single command. Claude Code reads the script, confirms the parameters, and executes, giving you a log you can review before any files change.

Recipe: write and run a one-off script

Sometimes you need a throwaway script: a small program that does one job right now and is never needed again. Examples include renaming 200 files, parsing a CSV, or hitting an API to fetch data. Writing it by hand is slow. Claude Code can write and run it for you in one go.

The recipe has three steps. You describe the job in plain language, Claude Code generates the script (usually a short Node.js or Python file), and then it runs the script immediately. You get the output without ever opening a text editor.

Key things to include in your request so Claude Code gets it right the first time:

• Input: what data or files does the script read? Give a real example if you can.
• Output: what should the result look like? A printed list, a new file, a number?
• Runtime: Node.js (CommonJS with require) or Python? If you do not say, Claude Code will pick one based on what is available.
• Disposable flag: say "run it and delete it" if you do not want the file kept.

Claude Code writes the file to a temp path, executes it, streams the output back to you, and can delete the file automatically. No leftover clutter, no manual cleanup.

Recipe: explain confusing code

When you open an unfamiliar file and the logic is opaque, Claude Code can walk you through it line by line. The key is giving enough context: the file, the specific section, and what you already know (even if that is "nothing").

The fastest path is the at-mention syntax. In the Claude Code chat panel, type @filename to attach a file directly to your message. Claude then explains it with full visibility into the actual source, not a paste you might have trimmed.

For a targeted explanation, narrow the request to a function, a class, or even a single expression. Broad requests ("explain this whole repo") produce broad answers. Focused requests produce actionable answers.

• @file mention: attach the source file so Claude reads it directly
• Line range: ask about lines 42-67 if the rest is clear
• Analogy flag: add "explain with a real-world analogy" for abstract logic
• Glossary mode: ask Claude to define every unfamiliar term it uses in the explanation