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