Claude Code prompts — what works and what wastes your time

Why Claude Code prompts are different from chat prompts

In a regular Claude conversation, the model answers and waits. In Claude Code, the model reads your files, runs commands, edits code, and iterates — all before you see the result. That autonomy changes what a good prompt looks like.

The biggest mistake: treating Claude Code like a search engine or a rubber duck. Asking "why isn't this working?" gets a guess. Asking "users report login fails after session timeout — check src/auth/, especially token refresh, write a failing test that reproduces it, then fix the root cause" gets a fix.

The context window is also a real constraint — Anthropic's documentation states that performance degrades as it fills. Every file Claude reads, every command output, every correction eats into that budget. Prompts that scope work tightly and give Claude a way to verify its own output produce better results than open-ended instructions.

The five parts of a prompt that actually works

Most prompts that produce weak output are missing at least two of these:

1. Goal — What is the end state? Not "improve performance" but "the page should load in under 1.5s on a 4G connection."

2. Context — What does Claude need to know that it can't get from reading code? The tech stack, constraints, the reason the current implementation exists. Reference files with @ so Claude reads them rather than guessing.

3. Constraint — What is off-limits? "Don't change the public API." "No new dependencies." "Keep all existing tests passing."

4. Verification — How will you and Claude both know it's done? A test to run, a build to pass, a screenshot to compare. Without this, Claude stops when "looks done" is the only available signal — and that becomes your job.

5. Next action — What should Claude do first? "Start by reading the git history for this file" gives Claude a path. "Start by writing a failing test" prevents it from writing code before understanding the problem.

A short example. Before: "add tests for the payment module". After: "Write tests for @src/payments/checkout.ts covering the edge case where the coupon code has expired. Don't mock the database — use the existing test helpers in @test/helpers.ts. Run the tests after writing them."

The after version is longer by two sentences, and it produces output you'd actually merge.

What to put in CLAUDE.md — and what to leave out

CLAUDE.md is a file Claude reads at the start of every session. It's the right place for things Claude can't infer from code: your test runner, the branch naming convention, the non-obvious environment variable that has to be set.

It's the wrong place for things Claude already knows (standard language conventions) or things that change per task (task-specific instructions).

The test Anthropic recommends: for every line, ask "would removing this cause Claude to make a mistake?" If not, cut it. A bloated CLAUDE.md causes Claude to ignore it — the important rules get lost in the noise.

Include:

• Bash commands Claude can't guess (bun test, not npm test, if you're on Bun)
• Code style that differs from defaults (ES modules, not CommonJS)
• Testing preferences (avoid mocks; use fixtures in /test/fixtures)
• Repository etiquette (branch naming, PR conventions)
• Non-obvious gotchas (NEXT_PUBLIC_ vars must be in .env.local, not .env)

Leave out:

• API documentation (link to docs instead)
• Standard conventions Claude already follows
• Anything that's only relevant to one task — put that in the prompt

Run /init to generate a starter CLAUDE.md from your project structure, then prune it down.

How context management affects prompt quality

A single debugging session can consume tens of thousands of tokens. As the window fills, Claude's adherence to earlier instructions drops — it's not a judgment call, it's a mechanical constraint.

Three habits that help:

/clear between unrelated tasks. Don't carry the context of a debugging session into a new feature. A clean session with a precise prompt consistently outperforms a long session with accumulated noise.

Use subagents for investigation. "Use a subagent to explore how our authentication system handles token refresh" keeps the research out of your main context. The subagent reads dozens of files and reports back a summary — you get the answer without paying the token cost in your working session.

Plan before you code. Press Ctrl+G to enter plan mode. Claude reads files and answers questions without making any changes, then produces an implementation plan you can edit before it starts writing code. This prevents the expensive failure mode: Claude solves the wrong problem for ten minutes before you notice.

Prompt structures for specific tasks

A few patterns that work well in practice:

Debugging: "The build fails with this error: [paste error]. Fix it and verify the build succeeds. Address the root cause — don't suppress the error."

Feature implementation: "Read @src/payments/ to understand the current flow. Then implement a coupon code validator that returns an error for expired codes and a discount amount for valid ones. Write tests before the implementation. Don't change the public API surface of checkout.ts."

Refactoring: "Refactor @src/auth/session.ts to improve readability and reduce duplication. Preserve all existing behavior exactly — run the test suite before and after to confirm nothing changed."

Codebase exploration: "Use a subagent to understand how we handle session tokens across @src/auth/. I want to add Google OAuth — what files would need to change, and what's the session flow? Write a plan to PLAN.md."

For non-technical makers and PMs: "I want to build a dashboard that shows weekly signups by source. Interview me using the AskUserQuestion tool — ask about edge cases, data sources, and what the team needs to act on. When we've covered everything, write a spec to SPEC.md."

The interview pattern is particularly useful if you're not technical: Claude asks the hard questions you might not have thought to ask, and you get a spec you can hand to an engineer — or hand back to Claude in a fresh session with clean context.

After Claude builds something: the review problem

Getting Claude to build the thing is now the easy part. The hard part is what happens next: a spec, a prototype, a one-pager, or a report that five people need to look at and comment on.

The default workflow — screenshot it, paste it into Slack, collect "the button feels off" in replies — doesn't tell you which button or what off means. You spend a revision cycle guessing.

This is the step that makes the prompt-to-output loop useful to people who aren't in the terminal with you. The artifact travels from Claude Code to a link your stakeholders can annotate — and the feedback travels back to Claude Code without copy-pasting.

The most common prompt failure modes

Kitchen sink sessions. You start with a bug, fix it, then ask about something unrelated, then come back to the bug. Context is full of irrelevant output. → Fix: /clear between unrelated tasks.

Two corrections, same mistake. Claude does something wrong, you correct it, still wrong, you correct again. The context now contains failed approaches that crowd out working ones. → Fix: After two failed corrections, /clear and write a sharper initial prompt that incorporates what the failed attempts revealed.

CLAUDE.md too long. You've added every preference and rule you've ever had. Claude ignores half of it. → Fix: Ruthlessly prune. If Claude does the right thing without the instruction, delete it.

No verification condition. You ask Claude to implement something and it does — but "looks done" is the only check. You find the edge case two days later. → Fix: Every prompt for non-trivial work should include "run the tests" or "verify the build passes" or "take a screenshot and compare it to the design."

Infinite exploration. "Investigate why performance is slow." Claude reads hundreds of files. → Fix: Scope narrowly, or use "Use a subagent to investigate X" so the exploration doesn't consume your main context.