The frustrating thing about vague prompts is that they feel complete when you write them. "Implement rate limiting for the API" seems like a clear instruction. The model has all the words it needs. And yet the output misses your Redis setup, returns a synchronous implementation when you need async, and handles none of the three error cases you actually care about.
This is not a model intelligence problem. It is an information problem. Here are the five root causes — and what to do about each one.
Writing a vague prompt takes five seconds. Correcting its output takes two minutes. That asymmetry runs in the wrong direction. The developer who writes "implement rate limiting" saves five seconds and spends two minutes correcting the result. The developer who spends fifteen seconds writing "implement a Redis-backed token bucket rate limiter in our FastAPI async context, handling 429 responses gracefully with Retry-After headers" usually accepts the first output.
The math consistently favors specificity. The challenge is that specificity is hard to apply under deadline pressure, when you are in flow, or when the requirement feels obvious to you because you wrote the surrounding code.
The cost of a single Claude Haiku prompt rewrite. At 20 complex prompts per day, automatic optimization via PrePrompt costs approximately $0.60/month — less than a cup of coffee, for prompts that get it right the first time.
When you ask Claude Code to "write a function to handle token validation", the model must guess: Is this a function or a class? Async or sync? What does it return — a boolean, a decoded payload, or a user object? What should it raise on failure?
Every one of those guesses is a divergence point. The fix takes one sentence: "Write an async Python function validate_token(token: str) -> TokenPayload that raises AuthError on any failure."
The model does not know your stack unless you tell it. It does not know you are on Python 3.11, using FastAPI with Pydantic v2, storing sessions in Redis, and deploying to a serverless environment. It will produce output that looks reasonable for a generic Python project — which may be entirely wrong for yours.
The fix: ten words at the start of your prompt. "In our FastAPI/Redis/Python 3.11 codebase:" makes every downstream assumption more accurate.
Prose descriptions of multi-step tasks are easy to partially implement. "Handle authentication with proper session management and logging" contains three discrete requirements. The model might implement two well and one poorly, or merge them in a way that makes the logging hard to test separately.
The fix: number them. "(1) Validate the JWT, (2) write a session record to Redis with a 24h TTL, (3) log the auth event with user ID and timestamp." Each requirement is now individually checkable.
AI coding assistants will handle errors — but which ones? Without guidance, they make plausible defaults that may not match your production requirements. Network timeouts might get a generic exception. A 403 from the upstream API might be treated the same as a 401.
The fix: name the cases you care about. "Handle: (a) network timeout after 3 seconds, (b) 401 from the token endpoint, (c) malformed JSON response from the user service." This takes fifteen seconds and eliminates a whole class of follow-up prompts.
"Update the token validation function" requires the model to find the right file, identify the right function, understand its current signature, and guess what change you want. Each of those steps is an opportunity for the wrong assumption.
The fix: ground your prompt in the actual code. "In auth/middleware.py, update validate_token(token: str) -> bool to return TokenPayload instead of a boolean. Raise AuthError('invalid_token') on any failure." The model now has zero ambiguity about what to change.
A: Claude Code misunderstands prompts when the prompt omits information that you consider obvious but the model cannot infer: the framework, the output format, the error cases you care about, or which specific function to modify. The model makes reasonable assumptions that diverge from your actual requirements. Specificity is the fix — not a smarter model.
A: Specify the output format (function name, return type, language), state technical constraints upfront (framework, library, version), number multi-step requirements, name the error scenarios you care about, and reference the existing file or function when modifying code. Each of these eliminates a category of assumption the model would otherwise make on your behalf.
You have two approaches to this problem. They are not mutually exclusive.
| Manual (apply the 5 patterns yourself) | Automatic (PrePrompt) | |
|---|---|---|
| Time cost | 10–20 seconds per complex prompt | 0 seconds (happens on submit) |
| API cost | $0 | ~$0.001 per optimized prompt |
| Best for | When you have time to think; builds good habits | When you're in flow; catches quick, vague prompts |
| Coverage | Only the prompts you consciously apply it to | Every prompt above the quality threshold |
| Stack memory | You remember your constraints yourself | PrePrompt learns and injects them automatically |
The practical recommendation: learn the five patterns so you internalize them, and use PrePrompt to handle the prompts you write quickly. The classifier will not fire on prompts you already wrote well — it only rewrites the ones that need it.
To install PrePrompt:
Yes. PrePrompt is an open-source MCP server (MIT license, pip install preprompt) that intercepts prompts in Claude Code and Cursor, scores them with a local heuristic classifier in under 1ms, and rewrites vague ones via Claude Haiku before they reach the LLM. It runs entirely locally and uses your own Anthropic API key.
PrePrompt uses Claude Haiku, which costs approximately $0.001 per optimized prompt. The heuristic classifier routes simple prompts (questions, already-structured tasks) through untouched at zero cost. At 20 complex prompts per day, the monthly API cost is roughly $0.60. The paid hosted tier ($8/month) is for teams who want cloud logging and a managed dashboard.
Yes, measurably. Better-structured prompts eliminate the most common source of follow-up rounds: the model guessing wrong about format, framework, error handling, or function scope. In PrePrompt's real-world data, prompts intercepted and rewritten show significantly fewer follow-up correction prompts in the same session.
PrePrompt currently integrates with Claude Code (fully automatic), Cursor (Agent mode), Windsurf, and Zed. VS Code support is in development. For other tools, the preprompt-optimize CLI command lets you optimize any prompt from the terminal and paste it into any tool.