Claude Code Prompts: Plan First, Then Give It Something to Run
The prompts that work best with Claude Code do three things: scope the task to specific files and patterns, separate exploring and planning from implementing when the change is not trivial, and — above all — include a check Claude can run, such as a test suite or build. Standing project context belongs in a short CLAUDE.md, not repeated in every prompt. This page organises the documented advice into templates and shows a compiled example.
Vibrr is an independent product. It is not affiliated with, endorsed by or sponsored by Claude Code. Product names are trademarks of their respective owners and are used here only to describe compatibility and content.
The principle behind the advice
Claude Code's documentation builds most of its best practices on one constraint: the context window fills quickly and performance degrades as it fills. Every message, file read and command output consumes it. That reframes prompting — the goal is not the longest instruction but the most specific one, supplied at the right time and place.
Templates by task
Each template follows a pattern the documentation describes; the wording is Vibrr's.
[plan mode]
Read <directory or files> and explain how <area> currently works.
Then propose a plan for <change>: files to change, the flow, edge cases.
[after approving the plan]
Implement the plan. Write tests for <behavior>. Run <test command> and fix failures.
When it passes, commit with a descriptive message.Symptom: <what users see, with the error text>
Likely location: <directory or file>
First write a failing test that reproduces it. Then fix the root cause — do not suppress the error — and run the tests.Look at how <existing example> is implemented and follow that pattern to build <new thing>.
Use only libraries already in the codebase.I want to build <brief description>. Interview me in detail about technical implementation, edge cases, concerns and tradeoffs. Keep going until we have covered everything, then write a spec to SPEC.md.Always include a way to verify
The documentation's strongest recommendation is to give Claude a check it can run — tests, a build exit code, a linter, a script that diffs output, a screenshot comparison. Without one, its only signal is that the work looks done, and you become the verification loop. Ask for evidence rather than assertions: the test output, the command and what it returned.
| Vague | Checkable |
|---|---|
| Implement email validation | Write a validation function; these inputs must return true and these false; run the tests |
| The build is failing | The build fails with this error; fix the cause, not the symptom, and confirm the build passes |
| Make the dashboard nicer | Implement this screenshot, take a screenshot of the result and list the differences |
Prompt, CLAUDE.md, skill or hook?
| The instruction… | Use | Why |
|---|---|---|
| is about this task only | The prompt | It should not outlive the task |
| applies to every session in this project | CLAUDE.md, under 200 lines | Loaded at the start of every session |
| applies only to some files | .claude/rules/ with paths frontmatter | Loads only when matching files are read |
| is a multi-step procedure used sometimes | A skill | Loads on demand instead of every session |
| must happen every time, no exceptions | A hook or permission setting | CLAUDE.md is context, not enforcement |
Architecture prompts and project prompts
Two searches people make deserve a direct answer. An architecture prompt is best written as a plan-mode request that names the constraints and asks for the plan to be reviewed before any code changes; the durable architectural decisions then go into CLAUDE.md so they need not be re-explained. A project prompt is what /init produces as a starting CLAUDE.md — build commands, conventions and layout — which you then prune. Both follow the same rule: put only what Claude cannot infer from the code.
- Include: commands Claude cannot guess, conventions that differ from defaults, architectural decisions, environment quirks and gotchas.
- Exclude: anything derivable from reading the code, long tutorials, file-by-file descriptions, information that changes frequently.
The Vibrr compiler workflow, with a real example
Vibrr compiler output for a debugging task. The base specification and acceptance criteria are identical on every platform; only the adaptation section is Claude Code-specific.
Example brief: Users report that saving a profile fails with a 500 error after their session has been idle for a while. The likely area is the token refresh in the authentication middleware. A fix must include a regression test.
# Base specification
Users report that saving a profile fails with a 500 error after their session has been idle for a while. The likely area is the token refresh in the authentication middleware. A fix must include a regression test.
# Acceptance criteria
1. The project installs and builds from a clean checkout using documented commands.
2. Every requirement in the specification is implemented or explicitly reported as not implemented.
3. Protected data and actions are authorized on the server, not only hidden in the UI.
4. Loading, empty and error states exist for every data-dependent view.
5. No secrets are committed or shipped in the client bundle; required environment variables are documented.
6. Automated checks (tests, typecheck, lint) are provided and their output is reported.
# Engineering requirements
- Every requirement has a check that can fail: A requirement with no way to fail is a wish. State the command, test or observable behavior that proves each requirement.
- Change one thing and say what must not change: Scope each change, state the keep-list, and review the diff against it before continuing.
# Platform adaptation: Claude Code
Workflow this prompt is written for: Repository understanding → plan → implement → run tools and tests → repair → verify.
Describe the symptom, name the likely location, and state the check that proves it fixed — ideally a failing test that reproduces the bug first.
Work in this order:
1. Symptom
2. Likely location
3. Write a failing test that reproduces it
4. Fix and verify
5. Address the root cause, do not suppress the error
Documented platform constraints to respect:
- CLAUDE.md and auto memory are treated as context, not enforced configuration. There is no guarantee of strict compliance; use hooks or permission settings to enforce behavior.
- Claude Code reads CLAUDE.md, not AGENTS.md. A repository that already uses AGENTS.md can import it from CLAUDE.md with @AGENTS.md.
- Target under 200 lines per CLAUDE.md file; longer files consume more context and reduce adherence.
- The context window fills quickly and performance degrades as it fills; the documentation treats context as the most important resource to manage.
Known failure modes to avoid:
- Plausible but unverified implementation — Supply verification criteria in the prompt; ask for evidence rather than assertions.
# Verification
Report evidence (command output, test results), not assertions:
- The reproducing test fails before the fix and passes after
- The full suite still passes
- Run the checks and read their output; do not accept a self-reported pass.
- Diff review against the stated keep-list.What the compiler decided
- Strategy
- Symptom, likely location, and what 'fixed' looks like (claude-code.debugging.symptom-location-fixed)
- Knowledge version
- 2026-09-18.1
- Evidence behind the adaptation
- claude-code.debugging.symptom-location-fixed (documented); claude-code.unverified-output (documented); claude-code.instructions-are-context (documented); claude-code.reads-claude-md-not-agents-md (documented); claude-code.claude-md-size (documented); claude-code.context-degrades (documented)
- Assumptions
- Requires from the requester: The symptom or error text. Requires from the requester: Where you suspect the fault is. Requires from the requester: The verification command.
- Prompt checks (heuristic)
- requirementCoverage: pass · ambiguity: pass · platformCompatibility: pass · architectureConsistency: pass · unsupportedClaims: pass · missingAcceptanceCriteria: pass · securityGaps: pass · testability: pass · deploymentReadiness: pass · contextCompleteness: pass
Failure modes to design around
Failure modes for Claude Code that a source documents or an experiment supports
Treating CLAUDE.md as enforcement
Documented guidance — how often it happens has not been measured
- Trigger
- A must-hold rule (never touch migrations, always run lint) is written only in CLAUDE.md.
- Symptom
- The rule is followed most of the time and skipped some of the time.
- Risk
- Policy violations that look like compliance until they do not.
- Prevention
- Use permission settings or a hook for anything that must hold every time; keep CLAUDE.md for guidance.
- Verify
- Attempt the forbidden action deliberately and confirm the hook or permission blocks it.
Source: How Claude remembers your project
AGENTS.md ignored
Documented guidance — how often it happens has not been measured
- Trigger
- A repository keeps its agent instructions only in AGENTS.md.
- Symptom
- Claude Code does not see those instructions.
- Risk
- Instructions the team believes are active are not loaded.
- Prevention
- Create a CLAUDE.md that imports AGENTS.md so both tools read one source.
- Verify
- Run /context and confirm the instructions appear under Memory files.
Source: How Claude remembers your project
Context saturation
Documented guidance — how often it happens has not been measured
- Trigger
- Long sessions mixing unrelated tasks, repeated corrections, or unscoped investigations.
- Symptom
- Earlier instructions are forgotten and mistakes increase.
- Risk
- Degraded output quality that is hard to attribute.
- Prevention
- Clear context between unrelated tasks; after two failed corrections restart with a better prompt; scope investigations or use subagents.
- Verify
- Compare a clean session with a specific prompt against the long-running one on the same task.
Source: Best practices for Claude Code
Plausible but unverified implementation
Documented guidance — how often it happens has not been measured
- Trigger
- No test, build or check is supplied, so the only signal is that the work looks done.
- Symptom
- An implementation that reads well and misses edge cases.
- Risk
- Defects shipped because nothing could fail.
- Prevention
- Supply verification criteria in the prompt; ask for evidence rather than assertions.
- Verify
- Run the supplied check yourself once before trusting a green report.
Source: Best practices for Claude Code
Prompt patterns for Claude Code
Explore, plan, implement, commit
Documented · task: feature addition
- Pattern
- In plan mode, have Claude read the relevant code and produce a plan; review it; switch out of plan mode to implement against the plan with a check it can run; then commit.
- Use when
- The approach is uncertain, the change touches several files, or the code is unfamiliar.
- Skip when
- If you could describe the diff in one sentence, skip the plan.
- Bring
- Which files or directories are relevant; Constraints and patterns to follow; A check Claude can run to verify the result
- Check
- Provide tests, a build, a linter or a screenshot Claude can run and read; Have Claude show the evidence, not assert success
Source: Best practices for Claude Code
Symptom, likely location, and what 'fixed' looks like
Documented · task: debugging
- Pattern
- Describe the symptom, name the likely location, and state the check that proves it fixed — ideally a failing test that reproduces the bug first.
- Use when
- A bug report you can localize at least roughly.
- Skip when
- Open-ended exploration where you want to see how Claude reads the problem.
- Bring
- The symptom or error text; Where you suspect the fault is; The verification command
- Check
- The reproducing test fails before the fix and passes after; The full suite still passes
Source: Best practices for Claude Code
Write down what you would otherwise re-explain
Documented · task: existing repository
- Pattern
- Keep a short CLAUDE.md of build commands, conventions that differ from defaults, architectural decisions and gotchas; move procedures and path-specific guidance to skills or .claude/rules/.
- Use when
- Claude repeats the same mistake, or you type the same correction each session.
- Skip when
- Anything Claude can derive by reading the code, or information that changes frequently.
- Bring
- Commands Claude cannot guess; Conventions that differ from tool defaults
- Check
- Run /context to confirm the file loaded; Observe whether behavior actually changes
Source: How Claude remembers your project; Best practices for Claude Code
Sources
Sources reviewed for Claude Code
- Claude Code overview — Anthropic, read 2026-09-18. docs.claude.com/en/docs/claude-code/overview returned a 301 to this URL.
- How Claude remembers your project — Anthropic, read 2026-09-18
- Best practices for Claude Code — Anthropic, read 2026-09-18
Frequently asked questions
What is the best way to prompt Claude Code?
Scope the task to specific files and patterns, plan before implementing when the change is not trivial, and include a check Claude can run to verify its work.
What should go in CLAUDE.md?
Facts Claude cannot infer from the code: build and test commands, conventions that differ from defaults, architectural decisions and gotchas — kept under about 200 lines.
Is there a Claude Code prompt generator?
Vibrr generates a Claude Code prompt from a brief. The example above is real output of Vibrr's prompt compiler for a debugging task; the app's generator currently covers initial builds, so task-specific forms are not yet available there. Vibrr is independent of Anthropic.
Official and primary sources
- Best practices for Claude Code — Anthropic, read 2026-09-18
- How Claude remembers your project — Anthropic, read 2026-09-18