The #1 skill for Claude Code productivity is writing specific prompts. This guide shows real before/after examples so you can see the difference.
The Rule
Specific prompts get specific results. Vague prompts get generic results.
The time you spend writing a clear prompt is always less than the time you’d spend fixing Claude’s generic output or going back and forth with follow-ups.
Example 1: Refactoring
Vague
Refactor this code.What Claude does: Makes random improvements. Might rename variables, add comments, reorganize methods — but probably not what you actually wanted.
Specific
Read @src/OrderProcessor.java. Extract the discount calculation
(lines 80-115) into a separate method called calculateDiscount
that takes a subtotal and discount code, and returns the discount
amount. Keep the behavior identical. Run the tests.What Claude does: Exactly what you asked. Testable, reviewable, focused.
Example 2: Bug Fixing
Vague
Fix the bugs in this file.What Claude does: Might find some bugs, might change things that aren’t actually bugs, might miss the real issue entirely.
Specific
The sell() method on line 54 of @lib/inventory_manager.rb has the
comparison backwards — it returns nil when the sale SHOULD succeed.
Fix the comparison operator and run the tests to verify.What Claude does: Fixes exactly one bug, verifies it, moves on.
Also specific (when you DON’T know the root cause)
Running `bundle exec rspec` gives this failure:
expected: 89.97 (± 0.01)
got: nil
Read the test and the source code. Why does sell() return nil when
there's enough inventory? Find and fix the root cause.What Claude does: Diagnoses from the evidence, fixes the actual cause.
Example 3: Building a Component
Vague
Build a dropdown component.What Claude does: Builds something. Maybe it’s searchable, maybe it’s not. Maybe it handles keyboard navigation, maybe it doesn’t. You’ll spend more time going back and forth than you would have writing a clear prompt.
Specific
Build a SearchableDropdown component. Requirements:
1. Text input filters options as you type (case-insensitive)
2. Dropdown appears on focus, hides on Escape or outside click
3. Arrow keys navigate options, Enter selects, Escape closes
4. Works with any object that has { id: string, label: string }
5. Use our existing useDebounce hook for the filter input
6. Follow the component patterns in src/components/What Claude does: Builds exactly this, with keyboard navigation, proper generics, and your existing patterns.
Example 4: Writing Tests
Vague
Write tests for this.What Claude does: Writes a few happy-path tests. Misses edge cases. Might not use your testing framework correctly.
Specific
Write Jest tests for @src/cart.ts. Cover:
- addItem: single item, duplicate SKU, zero quantity (should throw)
- removeItem: partial removal, full removal, non-existent SKU (should throw)
- subtotal: empty cart (0), single item, multiple items, quantity discount
- coupon: percentage coupon, flat coupon, coupon exceeding subtotal (cap at subtotal)
Use describe/it blocks. One assertion per test. No mocks needed.What Claude does: Writes thorough tests covering every scenario you specified.
Example 5: Code Review
Vague
Review this code.What Claude does: Gives a mix of style nits and real issues. Hard to tell which findings actually matter.
Specific
Review @src/auth/AuthService.java for security issues only.
For each finding:
- Severity (Critical / High / Medium / Low)
- OWASP category
- The vulnerable line
- The fixed versionWhat Claude does: Gives you a prioritized, actionable security audit.
Example 6: Explaining Code
Vague
What does this code do?What Claude does: Gives a surface-level summary.
Specific
Read @src/services/OrderProcessor.java. Explain:
1. What happens when processOrder is called with a rush delivery order?
2. How are volume discounts calculated? Is the logic correct?
3. What happens if two orders are processed simultaneously — any race conditions?What Claude does: Gives deep, targeted analysis of the three things you actually care about.
Example 7: Database Work
Vague
Write a query to get customer data.What Claude does: SELECT * FROM customers — not useful.
Specific
Using the schema in @db/schema.sql, write a query to find customers
who placed an order in the last 30 days but haven't logged in since
their last order was delivered. Include: name, email, last order date,
last login date. Sort by last order date descending.What Claude does: Writes a query with the correct JOINs, date logic, and sorting.
The Specificity Checklist
Before sending a prompt, check:
- WHAT should change? (specific methods, files, behavior)
- WHERE should the code go? (file paths, directories)
- HOW should it work? (algorithm, pattern, convention)
- WHAT SHOULDN’T change? (preserve existing behavior, don’t modify tests)
- HOW TO VERIFY it works? (run tests, build, manual check)
You don’t need all five every time. But the more you include, the better Claude’s output will be.
When Vague is OK
Sometimes a vague prompt is fine:
- Exploring: “What does this file do?” is fine when you’re just learning
- Brainstorming: “What are some ways to improve this?” is fine for ideation
- Quick questions: “What’s the difference between let and const?” is fine
The rule: if you need specific output (code, a fix, a review), be specific. If you’re just learning or exploring, vague is fine.