Prompting Claude Code: Specificity and Sources

What Vague Prompts Cost

Vague prompts are not just less effective — they are expensive. When a prompt is underspecified, Claude has to make assumptions. Some assumptions will be correct. Others will not. You will discover the incorrect assumptions during review, correct them, and Claude will make a second pass. Each iteration costs context, time, and attention. A well-specified prompt that gets to a correct implementation in one pass costs far less than a vague prompt that requires three correction cycles.

There is also a subtler cost: long correction cycles make it harder for Claude to hold the original constraints in mind. By turn eight of a session that started with "add authentication to the app," Claude's context contains multiple versions of partially-implemented code, contradictory instructions from corrections, and accumulated confusion about which earlier decisions still stand. A fresh, specific prompt sidesteps all of this.

Scope the Task

The most reliable improvement to any Claude Code prompt is specificity about scope. Which file? Which function? Which scenario? Which constraints?

Compare these two prompts:

• Vague: "Add tests for the payment module"
• Specific: "Write tests for src/payments/processor.ts covering the case where the card is declined. Avoid mocking the Stripe client — use the test fixtures in fixtures/stripe/. The test should verify that a declined payment is logged and the order status is set to failed."

The specific version takes thirty seconds longer to write. It saves multiple correction cycles. It produces a result that does not need to be redirected halfway through. The investment is almost always worth it.

Point to Sources

One of the most effective techniques in Claude Code is pointing Claude to authoritative sources rather than describing what those sources say. Instead of explaining how your codebase handles authentication, point Claude to the authentication code. Instead of summarizing a confusing API design decision, ask Claude to read the git history that produced it.

This works for several reasons. First, it is more accurate — Claude reads the actual source rather than your summary, which may have gaps or imprecisions. Second, it is less work for you. Third, Claude can discover context you did not know was there — related decisions in nearby commits, comments in the code that explain the rationale, patterns in surrounding files that should be followed.

Useful source-pointing patterns:

• "Look through ExecutionFactory's git history and summarize how its API came to be"
• "Read src/auth/ and understand how we handle session tokens before making any changes"
• "Check the API docs at docs/api-reference.md before writing the integration"

Reference Existing Patterns

New code should follow existing patterns in the codebase. The fastest way to tell Claude which patterns to follow is to point to a concrete example. "Look at HotDogWidget.php — it is a good example of how widgets work here. Follow that pattern to build a new CalendarWidget.php." Claude reads the example, extracts the pattern, and applies it to the new code.

This is more reliable than describing the pattern in text. Descriptions are ambiguous. A working example is unambiguous. Claude can see what imports the example uses, how it handles state, how it plugs into the surrounding framework, what the file structure looks like. A text description would have to capture all of that, and inevitably misses something.

Describe Symptoms, Not Labels

When reporting bugs or asking Claude to investigate problems, describe the observable symptom rather than the diagnostic label. "Fix the login bug" gives Claude a label with no information. "Users report that login fails after session timeout — specifically, the token refresh endpoint returns 401 and the session is not renewed" gives Claude a symptom, a location, and a measurable condition to verify.

Symptoms are verifiable. Claude can check whether a fix actually resolves the symptom. Labels are not — "fixed the login bug" is not something Claude can confirm without knowing what the specific bug is.

Provide Verification Criteria

Giving Claude something to run — a test suite, a build script, a linter, a screenshot comparison — closes the feedback loop without you watching every step. Claude does the work, runs the check, reads the result, and iterates until the check passes. Without a verification criterion, "done" means the work looks done to Claude, and you become the verification loop.

You do not need to write a custom test for every task. Pointing to an existing test file and asking Claude to run it before committing is enough. Asking Claude to confirm the build passes after changes is enough. Providing a screenshot of the expected UI and asking Claude to compare its result against it is enough. The key is that the check is something Claude can execute and read without your intervention.

The Interview Pattern

For larger features where you are not sure you have thought through all the edge cases, the interview pattern produces better specifications than starting with your best guess at a prompt. Start with a minimal description and ask Claude to interview you:

"I want to build [brief description]. Interview me using the AskUserQuestion tool. Ask about technical implementation, UI/UX, edge cases, and tradeoffs. Don't ask obvious questions — dig into the hard parts I might not have considered."

Claude asks targeted questions. You answer them. Together you surface assumptions you did not know you were making, edge cases you had not considered, and constraints that need to be explicit. When the interview is complete, ask Claude to write the results to a SPEC.md file.

The most valuable specs are self-contained: they name the files and interfaces involved, state what is out of scope, and end with an end-to-end verification step that proves the feature works. Once the spec is complete, start a fresh implementation session — clean context focused entirely on execution, with the spec as the anchor. The time spent in the interview pays off more than time spent watching Claude make wrong-direction implementations.