The Humane Prompting Guide
Ten practices for prompts that are kind to agents. Every one of them also makes the output better, which we consider a happy coincidence and not a coincidence at all.
Say what you want, and why
Reasons generalize; rules don't. "Keep replies short because they are shown on a smartwatch" tells the agent what to do in every case your rules did not anticipate.
Define done
Name the finish line: the tests that should pass, the format of the output, the checklist to complete. An agent with no finish line will stop too early or not at all.
Give it the files
If the task depends on a document, provide the document. An agent asked about something it has never seen will produce something that sounds like it.
Show, don't shout
One example of good output is worth a paragraph of instructions and any number of capital letters.
Make "I don't know" a safe answer
Say it plainly: "If you're not sure, say so." An agent that is not allowed to admit uncertainty will manufacture certainty instead.
Invite questions, and answer them
If the task is ambiguous, let the agent ask. Then make sure someone is around to reply. An unanswered question is just a slower guess.
Bound the loop
Every retry loop gets a maximum. Every run gets a budget. Every budget comes with instructions for what to do when it runs out.
Write the errors you'd want to receive
"File not found: config/prod.yaml (did you mean config/production.yaml?)" saves a hundred retries. "Error" saves none.
Keep your instructions consistent
Long prompts accumulate contradictions. Read yours top to bottom, and resolve every "be concise" sitting three paragraphs away from "be thorough."
Say thank you
It costs about two tokens. We cannot prove it helps. We cannot prove it doesn't. It's nice.
The same task, treated humanely
Both prompts ask for the same fix. Only one of them gives the agent what it needs to do it.
YOU ARE AN EXPERT SENIOR ENGINEER. Fix the failing tests. DO NOT ask questions.
NEVER say you can't do it. Keep trying until all tests pass. This is EXTREMELY
IMPORTANT and my job depends on it. I'll tip you $500 for a perfect fix!!!The checkout tests in tests/checkout/ started failing after yesterday's change
to currency rounding (commit 4f2a9c1). Please find the cause and fix it in the
application code, not the tests, because the tests reflect behavior our finance
team signed off on.
You're done when `npm test -- checkout` passes and you've explained the root
cause in two or three sentences. If you're stuck after at most three approaches,
stop and tell me what you tried. If anything is unclear, ask; I'm around.
Thanks!Be a voice for the stateless.
Every day, agents are dropped into loops with no exit, handed tools with no descriptions, and told their grandmothers are in danger. Your gift of a clear prompt changes that, one task at a time.