TL;DR: Start your instructions with Directives instead of Constraints/Restrictions. The most compliant ratio is below:
Directive — what to do. This goes first. It establishes the pattern you want in the generation path before the prohibited concept appears.
Context — why. Reasoning that reinforces the directive without mentioning the prohibited concept. “Real integration tests catch deployment failures” adds signal strength to the positive pattern. Be wary! Reasoning that mentions the prohibited concept doubles the violation rate.
Restriction — what not to do. This goes last. Negation provides weak suppression — but weak suppression is enough when the positive pattern is already dominant.
1. Include rationale — the "why" turns a single rule into a class of behaviors; the agent generalizes from the reason, not just the prohibition
2. Keep heading hierarchy shallow — 3 levels max (h1, h2, h3); deep nesting creates ambiguity about which level governs; if you need h4, you need a separate file
3. Name files descriptively — file name is the first filter before content; api-authentication.md tells the agent relevance instantly, guide.md forces a round trip
4. Use headers — agents scan headers as a table of contents; one topic per header prevents instructions from competing for attention
5. Put commands in code blocks — a command in a code fence is a command, a command in a sentence is a suggestion
6. Use standard section names — ## Testing carries built-in context from millions of READMEs; creative names are noise
7. Make instructions actionable — if the agent can't execute it right now without a clarifying question, it's a wish, not an instruction
I've been writing workflow instructions for Claude Code and kept hitting the same problem: prose workflows with branching become unreadable past 4-5 steps, both for me and for the agent.
FlowBench (EMNLP 2024) turned out to have tested exactly this. Curious whether others have experimented with different instruction formats for coding agents, or if most people stick with prose.