My AGENTS.md File for Building Plans You Actually Read
A tutorial by Matt Pocock. Featured in the OTF curated resource library.
The Wall-of-Text Problem
AI-generated plans and documents have a reputation for being verbose, repetitive, and hard to scan. Ask Claude to 'write a project plan' and you'll get a perfectly structured document that nobody will read past page one.
The problem isn't the AI's writing ability — it's the lack of constraints on formatting and conciseness. Without explicit instructions about how the document should be structured, AI defaults to academic-style prose: long paragraphs, formal tone, and exhaustive coverage of every edge case.
The fix is an AGENTS.md file specifically tuned for writing quality. Not code quality — writing quality. Formatting rules, word count limits, and explicit anti-patterns that force the AI to produce concise, scannable, actionable documents.
The AGENTS.md for Writing
Here's the core of the AGENTS.md I use for any document generation task:
Tone: Direct and clear. No filler words. No 'in order to' (say 'to'). No 'it is important to note that' (just say it). Write like a senior engineer explaining something to another senior engineer.
Structure: Every document starts with a 2-3 sentence summary. Sections have descriptive headings. Use bullet points for lists of 3+ items. Tables for comparisons. Code blocks for anything technical.
Length limits: No paragraph longer than 4 sentences. No bullet point longer than 2 sentences. If a section exceeds 200 words, split it or condense it.
Actionability: Every section ends with a clear next step or decision point. Documents should drive action, not just inform.
Formatting Rules That Work
Lead with the Conclusion
Start every document, section, and paragraph with the most important information. Readers scan — front-load your key points. If they only read the first sentence of each section, they should get 80% of the value.
Use Headers as a Summary
Headers should be descriptive enough that reading just the headers tells the story. 'Authentication' is weak. 'Use OAuth 2.0 for all third-party authentication' is strong.
Bullets Over Paragraphs
If you have 3+ related points, use bullets. Paragraphs bury information in prose. Bullets make each point scannable and independently digestible.
Bold the Key Phrase
In every paragraph or bullet point, bold the most important phrase. Readers scanning the page will catch the bold text and get the gist without reading everything.
Writing Anti-Patterns to Forbid
No Filler Phrases
Explicitly ban: 'it is worth noting,' 'as mentioned above,' 'in today's fast-paced world,' and 'it goes without saying.' These phrases add zero information and waste the reader's time.
No Repetition
If you've said it once, don't say it again in different words. AI loves to rephrase the same point three ways. Forbid it: 'State each point once. Do not rephrase or restate.'
No Vague Recommendations
Ban: 'consider implementing,' 'it might be beneficial,' 'teams should explore.' Replace with: 'implement X by Friday,' 'use Y for this use case,' 'choose between A or B.'
No Over-Explaining the Obvious
If the audience is technical, don't explain what a database is. Specify the audience level: 'Write for senior engineers who understand cloud architecture. Don't explain basic concepts.'
