Back
55/65
Lesson 55
8 min
AGENTS.md Mastery
Write effective AGENTS.md files that make any project agent-ready
Ready to level up?
Mark complete to track your learning progress.
Write effective AGENTS.md files that make any project agent-ready
Mark complete to track your learning progress.
Write AGENTS.md files that transform any project into an agent-ready workspace — the single most important file for AI coding agent onboarding.
Every AI agent — Claude Code, Codex, Antigravity — reads AGENTS.md at session start. It's the "API contract" between you and the agents working in your project. Without it, agents guess conventions, make wrong assumptions, and produce inconsistent code.
All major AI coding agents read AGENTS.md
Agents become productive in seconds
Rules applied consistently across sessions
Every agent follows the same patterns
Here is the canonical structure based on real-world battle-tested templates. Every AGENTS.md should follow this general shape:
# AGENTS.md — Project Name## RULE 0 - THE FUNDAMENTAL OVERRIDE PREROGATIVEIf I tell you to do something, even if it goes against whatfollows below, YOU MUST LISTEN TO ME. I AM IN CHARGE, NOT YOU.## Toolchain- Language: Rust / TypeScript / Python- Build: rch exec -- cargo build --release- Test: rch exec -- cargo test- Lint: rch exec -- cargo clippy -- -D warnings## ArchitectureBrief description of modules, key files, data flow.## Conventions- Error handling: use thiserror, not anyhow- Tests go in tests/ directory- API follows REST conventions## Safety Rules- DCG is installed — do not bypass it- Run ubs before every commit- Never force-push to main## Agent Coordination- Check agent mail: am check-inbox- Reserve files before editing- Update beads when completing tasks
Customize your AGENTS.md for your tech stack and workflows. Here's what a Rust project section looks like:
## Rust-Specific### Build & Testrch exec -- cargo build --release # Always release mode for benchmarksrch exec -- cargo test -- --nocapture # Show println! output in testsrch exec -- cargo clippy -- -D warnings # Treat warnings as errors### Workspace Layout├── crates/│ ├── core/ # Library crate (no binary)│ ├── cli/ # Binary crate (depends on core)│ └── server/ # HTTP server (depends on core)### Dependencies- tokio: async runtime (use #[tokio::main])- serde: serialization (always derive Serialize, Deserialize)- tracing: logging (not log or println!)### Generated Files — NEVER Edit- src/generated/ # All files auto-generated from schema- Modify the generator in build.rs, not the output
And here's a Next.js project example:
## Next.js-Specific### Framework- Next.js 16 App Router (NOT Pages Router)- Runtime: Bun (never npm/yarn/pnpm)- CSS: Tailwind CSS 4.x (not styled-components)### File Conventions- Pages: app/route/page.tsx- Components: components/feature-name.tsx- Server actions: app/actions/- API routes: app/api/route/route.ts
What NOT to put in AGENTS.md. These anti-patterns actively harm agent performance:
Too long (>500 lines) — agents compact context and lose later sections.
Duplicating README content — link to it instead of copying.
Vague rules ("write good code") — be specific ("use thiserror for error types").
Missing safety rules — agents will run destructive commands without explicit prohibitions.
No build/test commands — agents will guess and get them wrong.
# BAD — vague, wastes tokens## Code QualityPlease write clean, well-documented, maintainable codefollowing industry best practices and design patterns.# GOOD — specific, actionable## Code Quality- Functions > 50 lines must be split- No unwrap() in library code (use ? operator)- Every public function needs a /// doc comment
How to maintain consistent AGENTS.md across 20+ projects. Use a gold standard template and customize per-project:
# Keep a reference templatecat ~/projects/frankensearch/AGENTS.md # Gold standard# Standardize across fleet with RUru list --paths | while read -r repo; do# Compare each project's AGENTS.md to templatediff <(head -50 "$repo/AGENTS.md") <(head -50 ~/reference/AGENTS.md)done# Mass update: broadcast the same instruction to every agent in a swarm# (one pane per repo), then review the diffs before committingntm send myproject --all "Update AGENTS.md to matchthe gold standard template structure while preservingall project-specific sections"
The ACFS newproj wizard auto-generates AGENTS.md for new projects. It detects tech stacks and generates appropriate sections automatically: