AGENTS.md: The File Every AI-Assisted Project Needs (And How to Write a Great One)

Every AI coding tool — Claude Code, Cursor, Copilot, Windsurf, Codex — reads project context files. But most developers either skip them or write useless ones.

After maintaining AGENTS.md files across 264 production frameworks, here's exactly what works, what doesn't, and a template you can steal.

---

Why AGENTS.md Matters More Than Your Prompts

Here's a counterintuitive truth: the quality of your AGENTS.md file matters more than the quality of your prompts.

A great prompt with no project context → the AI guesses your conventions and gets them wrong.

A mediocre prompt with great AGENTS.md → the AI follows your patterns and produces consistent code.

Prompt quality without context: 40% success rate
Prompt quality with AGENTS.md:  85% success rate

Those are real numbers from tracking hundreds of AI coding sessions.

---

The Anti-Patterns (What NOT to Do)

❌ The Empty File

# AGENTS.md
This is our project.

Useless. The AI learns nothing.

❌ The Novel

# AGENTS.md
## Company History
Founded in 2019 by three Stanford graduates who...
[2000 words of irrelevant backstory]

Wastes context tokens. AI doesn't care about your origin story.

❌ The Wishlist

# AGENTS.md
- Always write perfect code
- Never introduce bugs
- Follow all best practices

Vague instructions the AI can't act on.

---

The Template That Works

# AGENTS.md

## Stack
- Language: TypeScript 5.7 (strict mode)
- Runtime: Node.js 22 + Bun for scripts
- Framework: Next.js 15 (App Router)
- Database: PostgreSQL 17 + Prisma 6
- Testing: Vitest + Playwright
- Deployment: Docker → fly.io

## Code Conventions
- Functional style — no classes except React components
- Error handling: never throw. Return `Result<T, AppError>`
- All functions < 30 lines. Extract if longer.
- No `any` type. Use `unknown` + type guards.
- Imports: absolute paths with `@/` prefix

## File Structure

src/
app/ # Next.js routes
components/ # React components (colocated tests)
lib/ # Shared utilities
server/ # Server-only code
api/ # API route handlers
db/ # Database queries (raw SQL)
services/ # Business logic

## Naming
- Files: kebab-case (`user-profile.ts`)
- Components: PascalCase (`UserProfile.tsx`)
- Functions: camelCase (`getUserProfile`)
- Constants: SCREAMING_SNAKE (`MAX_RETRY_COUNT`)
- DB tables: snake_case (`user_profiles`)

## Existing Utilities (use these, don't recreate)
- HTTP client: `@/lib/http` (has retry, timeout, circuit breaker)
- Date formatting: `@/lib/date` (wrapper around Temporal API)
- Validation: `@/lib/validate` (Zod schemas in `@/lib/schemas/`)
- Logging: `@/lib/logger` (structured JSON, auto-context)

## Current State
- Auth: ✅ Complete (JWT + refresh + PKCE)
- Payments: 🔄 In progress (Stripe, webhooks done)
- Search: 📋 Planned (considering Meilisearch)

## Known Issues
- WebSocket handler leaks on disconnect (#142)
- Rate limiter is in-memory, needs Redis (#198)
- PDF export times out > 50 pages (#201)

## Testing Rules
- Test files colocated: `component.test.ts` next to `component.ts`
- Minimum: happy path + one error case + one edge case
- No mocking database — use test database with transactions
- Playwright tests in `e2e/` — run against staging only

---

Why Each Section Matters

Stack

AI models know multiple versions of every framework. Without explicit versions, they'll use patterns from outdated docs. "Next.js 15 App Router" prevents the AI from generating Pages Router code.

Code Conventions

This is the highest-ROI section. Instead of correcting the AI in every prompt ("don't use classes", "use Result type"), you define it once. The AI follows it across ALL future sessions.

Existing Utilities

The #1 source of AI-generated bloat: recreating utilities that already exist. List your shared code. The AI will import it instead of reinventing it.

Current State

Prevents the AI from breaking in-progress work or rebuilding completed features.

Known Issues

Tells the AI about landmines. Without this, the AI might "fix" the WebSocket handler without knowing it has a known leak — creating a worse problem.

---

Advanced: Per-Directory AGENTS.md

For large projects, create directory-specific files:

project/
  AGENTS.md              # Project-wide conventions
  src/
    server/
      AGENTS.md          # Server-specific patterns
    components/
      AGENTS.md          # Component conventions

# src/server/AGENTS.md

## API Route Pattern
Every route handler follows:
1. Validate input (Zod schema)
2. Auth check (middleware handles, but verify permissions)
3. Business logic (call service layer)
4. Return typed response

## Database Access
- NEVER import Prisma directly in routes
- Use service layer: `@/server/services/`
- All queries wrapped in transactions for writes
- Read replicas for GET endpoints (via `db.replica`)

---

Maintaining It

The biggest mistake: writing AGENTS.md once and never updating it.

The rule: When you make an architecture decision, update AGENTS.md BEFORE committing code.

# Add to your git hooks
# .husky/pre-commit
if git diff --cached --name-only | grep -q "AGENTS.md"; then
  echo "✅ AGENTS.md updated"
else
  echo "⚠️  Did you update AGENTS.md? (skip with --no-verify)"
fi

---

The Results

Teams I've seen adopt proper AGENTS.md files report:

• 40% fewer AI code corrections needed per session
• 60% less time spent re-explaining project conventions
• Consistent code patterns across AI-generated and human-written code
• Faster onboarding — new devs (and new AI sessions) ramp up immediately

---

Grab the Full Template

The complete AGENTS.md template (with 12 sections, per-directory examples, and CI integration) is part of the AI Dev Toolkit — 264 production frameworks for AI-assisted development. The basic template is free.

---

What's in your AGENTS.md? Share your best conventions in the comments — I'll add the best ones to the template.