The difference between agents that work well and agents that flail is mostly project setup, not prompt wording. Three things account for most of it.

1. Give it a way to check its own work

This is the big one. An agent that can run tests, a type check, a linter, or start the app and hit an endpoint can catch and fix its own mistakes before you see them. An agent with no feedback loop makes a change, asserts it works, and neither of you knows.

If your project has any verification at all, tell the agent about it explicitly: "run npm test after every change and fix anything you break."

If it has none, adding one test and one command is the highest-value thing you can do for agent effectiveness — more than any prompt.

2. Write down what it can't infer

Agents read your code. They can't read your intentions, your constraints, or the reason the obvious approach doesn't work here.

A project instructions file — CLAUDE.md or your tool's equivalent — should hold: the commands to build, test and run; the conventions you follow; what's deliberately unusual and why; and anything you find yourself explaining twice.

Every time you correct an agent about the same thing, that correction belongs in the file.

3. Scope tasks to something reviewable

The failure mode is a vague task producing a sprawling diff. "Improve error handling" has no boundary; "add error handling to the three functions in upload.js that call S3" is finishable and reviewable.

agent-task.txt
Task: <specific, finishable>

Constraints:
- Only these files may change: <list>. If another must change, stop
  and tell me why.
- Don't reformat, rename or refactor outside the task.
- Don't add dependencies without asking.
- Don't modify tests to make them pass — a failing test is a finding.

Plan first: what you'll read, what you'll change, what you're unsure
about. Wait for my go-ahead.

After changes, run <test command> and report the result.

Then read the diff

All of it. The problems are rarely in the part you asked for — they're in the file that got reformatted, the dependency added, the test quietly changed.

If a diff is too big to read, that's a fact about the task. Revert, halve it, run again.

Commit before every agent task. It converts every bad outcome from a salvage operation into git restore ..