
Most projects write READMEs for humans. We wrote a 400-line markdown file specifically for Claude, Copilot and Cursor and it changed how we build software.
It's called AGENTS.md. And it's the most unusual piece of documentation in our codebase.
AGENTS.md file reduced AI-generated bugs by catching wrong assumptions before code was written.In 2026, Gartner reported that over 60% of professional developers now use AI coding assistants daily. These tools read your entire codebase before suggesting changes. But they don't understand your conventions they guess based on patterns from millions of other repos.
When we started building Labas an open-source AI-powered examp practice platform our first AI-generated PR used pnpm (we use Bun), assumed Next.js (we use Vite + TanStack Router), and imported components directly from apps/web instead of our shared packages/ui.
Every mistake was technically correct code. Just wrong for our project.
That's when we realized: AI assistants need onboarding too. Not a conceptual architecture diagram. Not a "getting started" guide. A literal list of rules, patterns, and pitfalss written in the exact format an LLM can consume and apply to every code change.
AGENTS.md, AI-generated PRs that required human correction for convention violations dropped from roughly 4 out of 5 to fewer than 1 in 5. The file didn't make the AI smarter it made our expectations explicit.The file lives at the repo root, right next to README.md. It's structured as a series of imperattive directives, organized by topic. Here's the anatomy:
The first section tells the AI what this project isn't. This is critical because AI assistants are trained on the most common patterns in the ecosystem and our project deliberately chose less common ones.
The "DO NOT" pattern is intentional. AI assistants default to npm/pnpm because those appear in 90%+ of Javascript repos. Without explicit negation, the AI will suggest pnpm install in every PR.
A compact table mapping each layer to its technology, with explicit "Not X" notes:
The "Not Prisma" and "Not Next.js" notes aren't redundant they're defensive. When an AI sees "React + Database," it statistically defaults to Next.js + Prisma. Explicit negation breaks that pattern.
This single rule prevents the most common architectural drift in monorepos: apps importing from each other instead of through shared packages. Without it, an AI might suggest import { something } from "../../server/src/utils" which works locally but breaks the package boundary.
We documented specific UI patterns that repeat across components:
The key insight: show, don't tell. AI assistants learn better from concrete code examples than from abstract descriptions. The pattern includes the exact component names where it's used, so the AI can grep for siblings when adding new instances.
This section prevents the AI from suggesting Docker-based test databases or SQLite mocks. PGlite is unusual enough that without explicit documentation, an AI would never guess it's the project's testing strategy.
Writing AGENTS.md taught us something unexpected: documentation for AI requires a fundamentally different structure than documentation for humans.
Human docs | AI docs |
Concepntual explanations | Imperative commands |
"Why we chose X" | "Use X, not Y" |
Architecture diagrams | File paths and line numbers |
Tutorials | Concrete code examples |
Version History | Current state only |
Humans want context. AI wants constraints.
The file reads like a combination of style guide, architecture decision record, and prompt injection database defense. It's not meant to be read cover-to-cover it's meant to be referenced by an AI assistants before every code change.
AGENTS.md is the antidote: it makes implicit convetions explicit before the AI guesses wrongIf you're building a project with non-standard choicse, here's a minimal template:
bun run dev do vs bun run build? What's the test command? AI assistants will guess give them the right answers..editorconfig handles formatting (indentation, line endings). AGENTS.md handles architectural and conventional decisions which framework to use, how to struture imports, what patterns to follow. It's closer to an ADR (Architecture Decision Record) that an AI can actively reference during code generation.