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.
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