Tech Update / Adventures with Claude Code #28

Good briefs – what I hand over to Claude

"Make the search faster." Sounds clear, but isn't. Faster for what, measured how, without breaking what? A new colleague would ask. Claude guesses.

Good results depend less on magic words than on four ingredients.

🎯 1. The goal, not just the activity

Instead of "Add a cache": "The customer list takes 4 seconds to load, the goal is under 1 second." That way Claude can find solutions you hadn't thought of.

📎 2. The right places

With @ you point to files and folders: @src/customers/list.ts. Claude doesn't have to search and doesn't guess which file you mean. An example of "this is how it should look" is often worth more than three paragraphs of description.

🚧 3. The boundaries

What must not change? "No new dependencies." "Public interface stays the same." "Only work in the customers folder." Whatever always applies belongs in CLAUDE.md.

✅ 4. The check

How do we know it's "done"? "Tests pass and npm run build is green." That's the lever from part 18: give a success criterion and the results check themselves.

💡 An example

The customer list (@src/customers/list.ts) loads too slowly,
currently about 4 seconds with 5,000 entries. Goal: under 1 second.
Measure first and name the cause, then propose a plan.
No new dependencies. Tests must be green afterwards.

A word of caution:

Longer isn't automatically better. Describe the outcome and the boundaries, not every step. And if you don't know the goal yourself yet: Plan Mode (part 10) and let Claude ask questions.

My rule of thumb:

  • Goal instead of instruction.
  • Name files with @.
  • Always include boundaries and a success check.

← Back to overview