The instinct when working with AI agents is to write more. More instructions, more constraints. Turns out that’s exactly wrong.

Addy Osmani, writing for O’Reilly, digs into the research:

Research has confirmed what many devs anecdotally saw: as you pile on more instructions or data into the prompt, the model’s performance in adhering to each one drops significantly. One study dubbed this the “curse of instructions”, showing that even GPT-4 and Claude struggle when asked to satisfy many requirements simultaneously. In practical terms, if you present 10 bullet points of detailed rules, the AI might obey the first few and start overlooking others.

So the answer is a smarter spec, not a longer one. Osmani pulls from GitHub’s analysis of over 2,500 agent configuration files and finds that effective specs cover six areas: commands, testing, project structure, code style, git workflow, and boundaries.

The boundaries piece is worth lingering on. Osmani recommends a three-tier system:

Always do: Actions the agent should take without asking. “Always run tests before commits.” “Always follow the naming conventions in the style guide.”

Ask first: Actions that require human approval. “Ask before modifying database schemas.” “Ask before adding new dependencies.”

Never do: Hard stops. “Never commit secrets or API keys.” “Never edit node_modules/ or vendor/.” “Never remove a failing test without explicit approval.”

That framing—always, ask first, never—gives the AI a decision framework instead of a wall of instructions. It maps to how you’d manage a person, too. Osmani quotes Simon Willison on the comparison: getting good results from a coding agent feels “uncomfortably close to managing a human intern.”

Klaassen’s compound engineering is one version of this. Osmani’s spec framework is another. The principle underneath both: teach fewer things well rather than everything at once.