Force an Assumptions Block Before Any Non-Trivial Task
The four-line block that kills AI rework.
The single most common failure mode of a coding agent isn't a syntax error. It's the agent quietly filling an ambiguous requirement with a plausible-but-wrong assumption and then building fifty files on top of it. By the time you notice, the mistake is load-bearing. The fix is not a better prompt for the task itself. It's a standing rule that forces the agent to surface its assumptions before it writes any code.
The failure mode: silent guessing
Requirements are almost never complete. When you say "add caching," the agent has to decide: cache where, invalidate how, per-user or global, what TTL. A good human engineer asks. An agent, optimized to be helpful and to produce output, guesses and proceeds. Each guess is individually reasonable. Stacked together they drift from what you actually wanted, and the drift is invisible until you read the diff.
The cost is asymmetric. Catching a wrong assumption in one sentence of English is nearly free. Catching it after the agent has restructured your module is expensive and demoralizing.
The mechanism: an assumptions block
Add a rule to your CLAUDE.md, AGENTS.md, or system prompt that fires on any non-trivial task:
## Before non-trivial work
Before writing code for any non-trivial task, output an ASSUMPTIONS block:
- **Requirements** — what I'm inferring about the desired behavior
- **Architecture** — where this fits, what it touches, what I'll change
- **Scope** — what's in, what's explicitly out
End with: "Correct me now or I proceed."
Then wait for my reply before touching files.The magic is the last line. It converts an implicit guess into an explicit checkpoint that you have to acknowledge. You read four bullets, catch the one wrong inference, and redirect in a sentence.
Why this beats "just ask more questions"
Telling an agent to "ask if unsure" underperforms because the agent rarely feels unsure. It has a confident answer for every ambiguity. An assumptions block sidesteps confidence entirely: it doesn't ask the agent to detect uncertainty, it forces it to enumerate its own inferences where you can see them. You supply the judgment about which inference is wrong.
| Approach | What the agent does | Where errors surface |
|---|---|---|
| No rule | Guesses silently, proceeds | In the final diff, after the work |
| "Ask if unsure" | Rarely triggers; feels certain | Still in the diff |
| Assumptions block | Lists every inference, waits | In four bullets, before any code |
Power moves
- Scope it to "non-trivial." You don't want an assumptions block for "rename this variable." Define the threshold in the rule so it fires on features and refactors, not one-liners.
- Make the block a template. Fixed headings (Requirements / Architecture / Scope) make it skimmable and force the agent to cover blind spots it would otherwise skip.
- Keep the "correct me now or I proceed" line. Without an explicit gate, agents treat the block as narration and barrel ahead anyway.
- Reuse it as a spec. The approved assumptions block doubles as a lightweight design record. Paste it into the PR description so reviewers see the decisions that were made.
Resources
- Anthropic — Claude Code best practices
- Anthropic docs — Manage Claude's memory (CLAUDE.md)
- AGENTS.md — a simple, open format for agent instructions
- Anthropic — Building effective agents
Shipping AI or cloud systems? Yeda AI audits and hardens production LLM and agent pipelines. Talk to us · Read the blog