Module 5 of 6
Writing Effective Prompts
The quality of what Claude produces is bounded by the quality of what you ask for. This module walks through a practical structure for prompts, common failure patterns, and worked before/after examples you can reuse on the job.
Why prompt quality matters more with agents
In a single chat turn, a vague prompt just gets you a mediocre answer you can immediately correct. In Claude Code, a vague prompt can send an agent off to read the wrong files, edit the wrong thing, or run for several minutes before you notice it misunderstood the goal. Because agentic tools act autonomously across many steps, the cost of an ambiguous instruction is multiplied. Investing thirty extra seconds in how you phrase a task routinely saves minutes of rework.
The five-part prompt structure
Not every prompt needs all five parts, but for anything non-trivial, working through this checklist mentally (or literally) produces dramatically better results than typing the first phrasing that comes to mind.
1. Goal
State the outcome you want in one sentence, before any details. What does "done" look like?
2. Context
Give the background Claude can't infer: which files, which system, which constraints, who the audience is.
3. Constraints
Say what must NOT change, length limits, style rules, libraries to avoid, performance requirements.
4. Format
Specify the shape of the output: a table, a diff, a bulleted list, plain prose, a specific file.
5. Examples (optional)
For anything with a "house style," one good example is worth several sentences of description.
Rule of thumb: if you can imagine two reasonable people interpreting your request differently, Claude can too. Resolve the ambiguity in the prompt, not after you see the result.
Before & after: vague vs. specific
Example 1 — asking for a summary
| Version | Prompt |
|---|---|
| Vague | Summarize this document. |
| Specific |
Summarize the attached incident report in 5 bullet points for an
engineering leadership audience. Focus on root cause, customer impact,
and the one action item owned by our team. Skip timeline minutiae.
|
The specific version fixes the audience (goal/context), the length (constraint), and the emphasis (what to include and skip) — three of the five parts in two sentences.
Example 2 — asking for a code change
| Version | Prompt |
|---|---|
| Vague | Fix the bug in the login flow. |
| Specific |
In src/auth/login.ts, users with an expired session token get a
raw 500 error instead of being redirected to /login. Reproduce with an
expired JWT, fix the redirect, and add a unit test for the expired-token
case. Don't touch the OAuth code path.
|
Notice the specific version names the file (context), describes the exact wrong behavior and the correct behavior (goal), asks for a test (format/definition of done), and explicitly protects unrelated code (constraint).
Example 3 — asking for content in a house style
| Version | Prompt |
|---|---|
| Vague | Write a release note for this feature. |
| Specific |
Write a release note for the new CSV export feature, in the same
style as this example: "Bulk delete: Select multiple records in the
table view and remove them in one action — no more one-by-one clicks."
One sentence, active voice, customer-facing benefit first.
|
Here a single example does more work than a paragraph of stylistic instructions would. When "you know it when you see it" applies, show, don't just tell.
Common failure patterns
The kitchen-sink prompt
Cramming five unrelated asks into one message ("also can you check the tests, and also update the README, and also look at performance...") makes it hard for Claude to prioritize and hard for you to verify the result. Break large requests into a sequence of focused prompts, or clearly numbered sub-tasks with an explicit order.
Missing the "why"
"Make this faster" is under-specified: faster at what cost? Compile time? Runtime? Readability? Explaining the underlying goal ("this endpoint is timing out under load, keep the code readable") lets Claude make good tradeoffs instead of guessing.
Assuming shared context that wasn't given
Claude only knows what's in the current context window — this conversation, any files it has read, and its training knowledge. It doesn't know your team's internal acronyms, your ticket numbers, or what "the usual way" means at your company unless you say so or it's available in the project.
Negative-only instructions
"Don't make it too long" is weaker than "keep it under 150 words." Wherever possible, replace a negative constraint with a positive, checkable one.
Re-explaining instead of correcting
If a first attempt misses the mark, it's usually faster to give targeted feedback on what to change ("good structure, but shorten the intro and drop the third bullet") than to restate the entire original prompt from scratch.
Iterating instead of front-loading everything
You don't have to get the perfect prompt on the first try. A common and effective pattern is to start with a reasonably scoped request, look at the result, and then refine with follow-up instructions — much like reviewing a draft with a colleague. This is especially natural in Claude Code, where you can ask for a plan first ("outline your approach before making changes") and correct direction before any files are touched.
Try it: for a non-trivial task, ask Claude to restate its understanding of the goal and propose a short plan before doing the work. Confirming the plan costs a few seconds and catches misunderstandings early — especially valuable for agentic, multi-step tasks.
Quick checklist
- Is the goal stated in one clear sentence?
- Have I given the context Claude can't infer (files, audience, constraints)?
- Have I specified the output format I want?
- Are my constraints positive and checkable, not just "don't do X"?
- For anything with a house style, have I included one good example?
- For big or risky changes, have I asked for a plan before execution?