Prompt Engineering for Coding Agents: The Difference Between 'Fix the Bug' and a Prompt That Works
"Fix the failing test." I typed this into a coding agent and watched it read 47 files, change 3 things that weren't broken, introduce a new bug, and then spend 20 minutes trying to fix the bug it just created. Total cost: $4.20 in tokens and 35 minutes of wall time.
The next day I typed: "The test ContactServiceTest.testFindByEmail fails with NPE at
ContactService.java:142. The emailNormalizer field is null — it's missing @Inject.
Add the injection and verify the test passes." Same agent, same model. Fixed in 90 seconds.
Cost: $0.12.
The difference wasn't the agent. It was the prompt.
The one thing to take from this post: a good agent prompt has three parts — the symptom, the evidence, and the boundary. Miss any of them and the agent guesses.
The anatomy of an effective prompt
1. The symptom (what's wrong)
Name the specific failure, not the category of problem.
1Bad: "There's a performance issue in the API."
2Good: "The GET /rest/v1/documents endpoint returns in 8s for client ACME.
3 Expected: under 500ms. Started after commit abc1234."
The bad prompt forces the agent to investigate what "performance issue" means. The good prompt tells it exactly what to measure against.
2. The evidence (what you already know)
Share what you've already found. Every clue you give saves the agent 5-10 file reads.
1Bad: "Fix the NPE."
2Good: "NPE at ContactService.java:142. Stack trace shows emailNormalizer
3 is null. The field exists but has no @Inject annotation. The service
4 was recently moved from ic-core where it used field injection."
The agent doesn't need to rediscover what you already know. Give it your diagnosis and let it verify + fix.
3. The boundary (what to do and what NOT to do)
Agents are eager. Without a boundary, they'll optimize, refactor, and "improve" things you didn't ask about.
1Bad: "Fix the authentication bug."
2Good: "Fix the authentication bug in JwtAuthenticationFilter.java.
3 Change only the token validation logic — do not modify
4 SecurityConfig, do not change endpoint permissions,
5 do not update dependencies."
Six prompt patterns that work
Pattern 1: Bug fix (symptom + trace + boundary)
1Bug: {test/endpoint/feature} fails with {exact error}.
2Location: {file:line}.
3Cause: {what you think is wrong}.
4Fix: {what you want changed}.
5Boundary: change only {these files}. Run {this test} to verify.
Pattern 2: Feature implementation (spec + examples + constraints)
1Add {feature} to {component}.
2Behavior: when {trigger}, then {result}.
3Example: {concrete input → expected output}.
4Constraints: follow the pattern in {existing similar feature}.
5Test: add a test that covers {the main scenario}.
Pattern 3: Investigation (question + scope + output)
1Investigate: why does {X} happen when {Y}?
2Start from: {entry point file/class}.
3Scope: read at most {N} files.
4Output: root cause + list of affected files + proposed fix (don't implement).
Pattern 4: Refactoring (what + pattern + verify)
1Refactor: extract {method/class/module} from {source}.
2Follow the pattern used in {existing example}.
3Preserve all existing behavior — run {test suite} before and after.
4No functional changes.
Pattern 5: Code review (diff + criteria + format)
1Review the changes in {branch/PR/file list}.
2Check for: {security issues, performance, correctness, conventions}.
3For each finding: cite the file:line, state the problem, suggest a fix.
4Format: markdown table with columns: File | Line | Finding | Suggestion.
Pattern 6: Migration (from + to + verify)
1Migrate {component} from {old} to {new}.
2Reference: {migration guide or example that's already done}.
3Steps: {ordered list of what needs to change}.
4Verify: {tests that must pass after migration}.
5Do not migrate {things that should stay on the old version}.
Before/after: real examples
Example 1: Vague → Specific
1Before: "The document upload is broken."
2
3After: "DocumentUploadResource.uploadDocument() returns 500 for
4 multipart uploads larger than 10MB. The error log shows
5 'Request entity too large' from the Jersey layer. This
6 worked before the Spring Boot 3 migration. Check if the
7 multipart config in application.properties has the correct
8 property names for Spring Boot 3
9 (spring.servlet.multipart.max-file-size)."
Example 2: Too broad → Bounded
1Before: "Improve the test coverage."
2
3After: "Add unit tests for FundInvestorService.createFundInvestor().
4 Cover: successful creation, duplicate detection (should throw
5 DuplicateFundInvestorException), and null fund ID (should throw
6 IllegalArgumentException). Follow the pattern in
7 FundServiceTest.java. Use JUnit 5 with @ExtendWith."
Example 3: Outcome-focused → Process-focused
1Before: "Make the email sending more reliable."
2
3After: "Investigate why emails in DistributionListService.sendEmails()
4 are occasionally sent twice. Check the idempotency key logic in
5 EmailService.send(). The deduplication window is 30 minutes
6 (ic.requestIdempotency.emailDuplicationPreventionMinutes).
7 I suspect the key is generated from the wrong fields.
8 Don't fix yet — report what you find."
The mistakes that waste the most tokens
1. No stopping condition
"Make the code better" has no definition of done. The agent will iterate forever (or until it hits the token limit). Always give a concrete stopping condition: a test that passes, an error that disappears, a metric that improves.
2. Multiple unrelated tasks in one prompt
"Fix the NPE in ContactService AND update the Swagger docs AND add the new endpoint." The agent will context-switch between these, likely breaking one while fixing another. One task per prompt. Chain them if needed.
3. Telling the agent HOW instead of WHAT
"Open ContactService.java, go to line 142, add @Inject before the emailNormalizer field,
then save the file and run the test." This micro-management prevents the agent from using its
judgment — and if any detail is wrong, it follows your instructions into the wall.
Better: tell it what's wrong and what "fixed" looks like. Let it figure out how.
Exception: when the agent has demonstrated that it picks the wrong approach, then constrain the how. But start with what.
4. Assuming the agent remembers
The agent starts fresh every session. If you told it about your project conventions yesterday, it doesn't know today. This is what rules and skills solve — persistent instructions that survive across sessions.
5. Not including the error message
"The test is failing" forces the agent to run the test and read the output — two tool calls that cost tokens and time. If you already have the error, paste it. The agent skips straight to analysis.
The prompt quality checklist
Before sending a prompt, check:
- Specific failure? Can someone who's never seen the code reproduce from your description?
- Evidence included? Stack traces, error messages, relevant file names?
- Boundary set? What files/modules are in scope? What's off-limits?
- Stopping condition? What does "done" look like? Which test to run?
- Single task? One problem per prompt?
- No assumed context? Would this prompt work in a fresh session?
If you can check all six, the prompt will likely produce a good result on the first try. If you can't check three or more, expect iteration — and iteration is where costs multiply.
Related: Getting Started with Agentic Development for the fundamental concepts, and The 2-Retry Limit for what happens when prompts aren't specific enough and the agent enters a retry loop.