AGENTS.md: The Universal Agent Configuration File
A tutorial by Geoffrey Huntley. Featured in the OTF curated resource library.
Why AGENTS.md Matters
Every AI coding agent faces the same problem: it needs to understand your project's conventions, architecture, and preferences before it can write useful code. Without this context, agents produce generic output that doesn't match your codebase.
AGENTS.md solves this by providing a standardized location and format for project-level AI instructions. It's the equivalent of .editorconfig for AI coding agents—a single file that communicates your project's rules to any compatible tool.
The key insight is that most project conventions are implicit knowledge locked in developers' heads. AGENTS.md makes this knowledge explicit and machine-readable, so every AI interaction starts with the right context.
Anatomy of an AGENTS.md File
A well-structured AGENTS.md covers five key areas. Here's how to build one from scratch.
Project Overview
Start with a brief description of what the project is, its tech stack, and its purpose. This gives agents immediate context.
# AGENTS.md ## Project KOSH AI — a curated directory for AI-assisted builds. Stack: React + Vite + TypeScript, Tailwind CSS, React Query. Hosted on Blink with edge functions for the API layer.
Architecture & File Structure
Describe where things live. Include your directory structure conventions, naming patterns, and how different layers connect.
## Architecture - Pages: src/pages/ (one file per route) - Components: src/components/ (shared/, layout/, ui/) - Hooks: src/hooks/ (custom React hooks) - Data fetching: React Query hooks that call src/lib/api.ts - Edge functions: functions/ directory (Deno runtime)
Coding Conventions
List your specific preferences: naming conventions, component patterns, state management approach, testing strategy, and any patterns to avoid.
## Conventions - Use functional components with named exports - Keep components under 150 lines; split if larger - Use Tailwind utility classes, not custom CSS - Prefer composition over prop drilling - Boolean DB fields return "0"/"1" strings from SQLite
Do's and Don'ts
Explicitly state what the agent should and shouldn't do. This prevents common AI antipatterns specific to your project.
Current Context
Add a section for current work-in-progress. This is the most dynamic part—update it as you switch tasks so the agent always knows what you're focused on.
Writing Effective Instructions
Be Concrete, Not Abstract
Instead of "write clean code," say "use named exports, keep functions under 30 lines, and add JSDoc comments for public APIs." Agents interpret concrete instructions much more reliably.
Include Examples
Show the pattern you want, not just the rule. A 5-line code example is worth a paragraph of description. Agents learn patterns faster from examples.
Prioritize Your Rules
Put the most important conventions first. AI agents process information sequentially—front-loaded rules have more impact on output quality.
Update It as Your Project Evolves
AGENTS.md should be a living document. When you add a new pattern or deprecate an old one, update the file. Stale instructions lead to inconsistent code.
Real-World Examples
Here's how production teams structure their AGENTS.md files:
Startups (small codebase, fast iteration): Keep it short—project overview, tech stack, 5-10 key conventions, and current sprint context. Update the context section daily.
Agencies (multiple projects): Create a base template with common conventions, then customize per project. Include client-specific requirements like branding guidelines and API constraints.
Enterprise teams (large codebase, many contributors): Use nested AGENTS.md files. A root file for global conventions, plus directory-level files for subsystem-specific rules (e.g., api/AGENTS.md for backend conventions, frontend/AGENTS.md for UI patterns).
The common thread: specificity wins. The more precise your instructions, the more useful the agent's output.
Cross-Tool Compatibility
AGENTS.md is designed to work across all major AI coding tools:
- Claude Code: Reads AGENTS.md automatically from the project root. Also supports CLAUDE.md as an alias.
- Cursor: Supports .cursorrules but also reads AGENTS.md when available. Place it in the project root.
- GitHub Copilot: Reads repository-level instruction files. AGENTS.md at the root provides context for Copilot's suggestions.
- Codex / ChatGPT: Can be referenced explicitly in prompts or included via custom instructions.
The beauty of a standardized format is that switching between tools—or using multiple tools on the same project—doesn't require rewriting your conventions.
Advanced Patterns
Scoped Agent Files
Place AGENTS.md files in subdirectories for context-specific rules. A file in `src/components/` can describe component conventions without cluttering the root file.
Version Your Agent Config
Commit AGENTS.md to git and review changes in PRs. This ensures the team agrees on conventions and provides an audit trail of how instructions evolve.
Link to Living Documentation
Reference your team's style guide, architecture decision records, or Notion docs directly in AGENTS.md. Agents with web access can follow these links for deeper context.
