If you're using AI coding tools without an AGENTS.md file, you're leaving 80% of their capability on the table.
AGENTS.md is rapidly becoming the standard way to give AI coding agents persistent project context. Claude Code reads it automatically. Cursor respects it. Copilot and Codex are adopting similar patterns.
Here are 5 patterns I've tested across real projects that dramatically improve AI output quality.
Pattern 1: The Context Pyramid
Problem: AI generates code that doesn't match your stack, conventions, or architecture.
# AGENTS.md
## Architecture
- Monorepo: apps/ (Next.js 15) + packages/ (shared libs)
- Database: PostgreSQL 16 + Drizzle ORM (NOT Prisma)
- Auth: Better-Auth v2 (NOT NextAuth)
- Styling: Tailwind CSS v4 + shadcn/ui
## Conventions
- File naming: kebab-case (user-profile.tsx, NOT UserProfile.tsx)
- Exports: named only (NO default exports)
- Error handling: Result<T, E> pattern (NO try/catch in business logic)
- Tests: Vitest + Testing Library (NO Jest)
## Do NOT
- Use `any` type — always explicit types
- Use relative imports across packages — use @repo/ aliases
- Create new API routes — use existing tRPC router
- Install new dependencies without asking
Why it works: Instead of explaining your stack every prompt, the AI reads this once and respects it across every interaction. The "Do NOT" section is critical — it prevents the AI's most common bad habits for your specific project.
Pattern 2: The Task Router
Problem: Different parts of your codebase need different AI behavior.
# AGENTS.md
## File-Specific Rules
### When editing `apps/web/**`
- Use React Server Components by default
- Data fetching: server-side only (NO useEffect for data)
- Follow existing patterns in apps/web/lib/
### When editing `packages/db/**`
- Always generate migration: `pnpm db:generate` after schema changes
- Include rollback in every migration
- Test with: `pnpm db:test`
### When editing `packages/api/**`
- Every new procedure needs: input validation (zod), auth check, rate limit
- Follow the pattern in `packages/api/src/routers/users.ts`
- Add to the barrel export in `packages/api/src/index.ts`
### When editing `*.test.ts`
- Use `describe/it` blocks (NOT `test()`)
- Mock external services with MSW (NOT jest.mock)
- Each test file mirrors source: `user-service.ts` → `user-service.test.ts`
Why it works: This creates implicit routing — the AI adapts its behavior based on which files it's touching. You write the rules once, and they apply contextually forever.
Pattern 3: The Decision Log
Problem: AI keeps suggesting approaches you've already rejected.
# AGENTS.md
## Architecture Decisions (DO NOT revisit)
### ADR-001: Drizzle over Prisma
- Decided: 2026-01-15
- Reason: Prisma's query engine adds 5MB+ to bundle, Drizzle is SQL-native
- Do NOT suggest migrating to Prisma or using Prisma syntax
### ADR-002: tRPC over REST
- Decided: 2026-01-20
- Reason: End-to-end type safety, no codegen step
- Do NOT create REST endpoints or suggest Express routes
### ADR-003: Monorepo over separate repos
- Decided: 2026-02-01
- Reason: Shared types, atomic deployments, single CI pipeline
- Do NOT suggest splitting into separate repositories
### ADR-004: No ORM abstraction layer
- Decided: 2026-02-15
- Reason: Direct Drizzle queries are readable and debuggable
- Do NOT create repository/service patterns that wrap Drizzle
Why it works: AI models tend to suggest "best practices" that may conflict with your actual choices. The decision log gives it context on why you chose differently, so it stops fighting you.
Pattern 4: The Safety Net
Problem: AI coding agents can run destructive commands.
# AGENTS.md
## Safety Rules
### Allowed (do freely)
- Read any file
- Run tests: `pnpm test`, `pnpm typecheck`, `pnpm lint`
- Git operations: status, diff, log, branch, commit
- Build: `pnpm build`
- Dev server: `pnpm dev`
### Ask first
- Any `rm` or `delete` command → use `trash` instead
- Database migrations in production
- Installing new dependencies
- Any git push or PR creation
- Environment variable changes
### Never (hard block)
- `rm -rf` anything
- Direct database writes to production
- Expose secrets in code or commits
- Push to main branch directly
- Run commands with `sudo`
### Recovery
- If something breaks: `git stash && git checkout main`
- Database rollback: `pnpm db:rollback`
- Restore deleted files: `trash-restore`
Why it works: Agentic AI tools like Claude Code and Cursor Composer can execute commands autonomously. Without guardrails, a coding agent might rm -rf node_modules when pnpm install fails. The safety net pattern prevents catastrophic mistakes while keeping the agent productive.
Pattern 5: The Living Docs
Problem: Your AGENTS.md goes stale as the project evolves.
# AGENTS.md
## Meta
- Last reviewed: 2026-03-24
- Review frequency: Every Monday
- Owner: @yourname
## Current Sprint Context
- Working on: Payment integration (Stripe → LemonSqueezy migration)
- Blocked by: Webhook signature verification (see #142)
- Priority: Ship payment flow by March 28
## Recent Changes (last 7 days)
- Migrated auth from NextAuth to Better-Auth (PR #138)
- Added rate limiting middleware (PR #140)
- Removed legacy REST endpoints (PR #141)
## Known Tech Debt
- [ ] `apps/web/lib/legacy-auth.ts` — delete after migration confirmed
- [ ] `packages/api/src/routers/old-users.ts` — deprecated, remove by April
- [ ] Payment types are `any` — needs proper Stripe→LS type migration
## Team Knowledge
- Webhook testing: use `stripe listen --forward-to localhost:3000/api/webhooks`
- Local dev requires: PostgreSQL 16, Redis 7, Node 22
- CI is slow on `packages/db` tests — known issue, run locally first
Why it works: This turns AGENTS.md from a static config into a living project document. The AI knows what you're actively working on, what changed recently, and what pitfalls to avoid. Update it weekly and it becomes your project's memory.
Combining Patterns: The Complete Template
# AGENTS.md
## Architecture (Pattern 1)
[your stack, conventions, anti-patterns]
## File Rules (Pattern 2)
[per-directory AI behavior rules]
## Decisions (Pattern 3)
[ADRs the AI must respect]
## Safety (Pattern 4)
[allowed/ask/never command categories]
## Context (Pattern 5)
[current sprint, recent changes, known issues]
Start with Pattern 1, add others as needed. Even just the Context Pyramid alone will noticeably improve your AI coding output.
Want the Full Production-Ready Kit?
I maintain a collection of 264 AI development resources including AGENTS.md templates, multi-agent patterns, cost optimizers, and more. Browse the toolkit →
Which pattern resonates most with your workflow? I'd love to hear what you've added to your own AGENTS.md — share in the comments.
Top comments (0)