Anti-Patterns for AGENTS.md
Detailed explanations of what NEVER to include in AGENTS.md files and why.
Critical Anti-Patterns with Reasoning
NEVER Include Welcome Language
Examples: “Welcome to…”, “This document explains…”, “You should…”
Why this is problematic:
- Token waste: AI systems don’t need social pleasantries or introductions
- Processing overhead: Every token counts in context window management
- Scanning inefficiency: AI systems scan for actionable information, not narrative flow
- Redundant information: The fact that it’s documentation is already clear from context
NEVER Use Placeholder Examples
Examples: <your-file>, [replace-with-actual-path], TODO: add example
Why this is problematic:
- Pattern recognition failure: AI systems learn patterns from concrete examples, not abstractions
- Implementation uncertainty: Placeholders force AI to guess real file structures
- Context switching: AI must mentally map placeholders to actual project structure
- Reduced utility: Placeholder examples provide no actionable guidance
NEVER Write Long Prose Paragraphs
Examples: Multi-sentence explanations, narrative descriptions, background context
Why this is problematic:
- Scan vs read: AI systems scan for actionable items, not reading comprehension
- Information density: Bullets and code blocks are faster to parse than prose
- Action extraction: AI needs to extract “what to do” from narrative text
- Token efficiency: Headers + bullets convey same information in fewer tokens
NEVER Duplicate Content from Skills
Examples: Copying testing patterns, development workflows, code standards
Why this is problematic:
- Redundant loading: Same information loaded multiple times wastes context
- Maintenance burden: Updates required in multiple locations
- Version conflicts: Outdated copies create inconsistency
- Skill undermining: Reduces value of specialized skill system
NEVER Include Obvious Instructions
Examples: “run tests”, “write clean code”, “handle errors properly”
Why this is problematic:
- Baseline knowledge: AI systems already know standard development practices
- Signal dilution: Obvious content reduces the signal-to-noise ratio
- Expert knowledge displacement: Token space better used for project-specific insights
- Credibility reduction: Stating obvious things reduces trust in non-obvious guidance
NEVER Explain “Why” Unless Non-Obvious
Examples: “We use React because it’s popular”, “Tests are important for quality”
Why this is problematic:
- Action focus: AI systems need “what to do”, not “why it matters”
- Assumed knowledge: AI systems understand standard technology rationales
- Implementation priority: Limited tokens should focus on “how”, not “why”
- Expert knowledge: Only include “why” for non-obvious trade-offs and decisions
NEVER Include Framework Tutorials
Examples: “How to write a React component”, “Express.js routing basics”
Why this is problematic:
- Baseline competency: AI systems already know framework fundamentals
- Documentation duplication: Official framework docs are authoritative source
- Project-specific focus: AGENTS.md should cover project patterns, not framework basics
- Maintenance overhead: Framework tutorials become outdated quickly
Good vs Bad Examples
❌ Bad Example
# Welcome to Our Project
This document explains how to work with our codebase. You should read this carefully before making changes.
## About React Components
React components are reusable pieces of UI. In our project, we organize them in folders like this:
- `src/components/<ComponentName>/index.tsx` - Your component goes here
- `src/components/<ComponentName>/styles.css` - Your styles go here
Remember to write tests for your components! Testing is important for code quality.✅ Good Example
# Project Name
## Component Organization
- Components: `src/components/Button/index.tsx`, `src/components/Modal/index.tsx`
- Styles: Colocated `.css` files
- Tests: `Button/Button.test.tsx`
- Example: Copy pattern from `src/components/Button/`Usage in Main SKILL.md
Reference this file with explicit loading trigger:
**MANDATORY - READ ENTIRE FILE**: Before writing any AGENTS.md content,
load `references/anti-patterns.md` to understand what to avoid.
**Do NOT load** other reference files for anti-pattern review.