AI coding assistants write correct code, but they guess your conventions. Learn how creating an AGENTS.md file reduced our AI-generated bugs by 80%

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.

Key Takeways

•In 2026, AI coding assistants can read your repo but they don't know your conventions without explicit guidance. A single AGENTS.md file reduced AI-generated bugs by catching wrong assumptions before code was written.

•The "DO NOT" list pattern (explicit anti-patterns) is more effective than positive guidelines. AI assistants default to common patterns (Next.js, Prisma, npm) that may not match your stack.

•Writing documentation for AI requires a different structure: imperative commands, concrete examples, and explicit file paths rather than conceptual explanations.

Why Did We Write Docs for a Non-Human Reader?

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.

Our finding: After adding 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.

What's Inside AGENTS.md?

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:

1.Project Identity (The "Don't Assume" Section)

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.

2. Technology Stack (The "What We Use" Table)

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.

3. Architecture Rules (The "How We Import" Section)

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.

4. UI Conventions (The "How We Style" Section)

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.

5. Testing Conventions (The "How We Test" Section)

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.

The Meta-Lesson: AI Documentation as New Genre

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.

Contrarian take: Most teams are worried about AI writing bad code. The real risk is AI writing correct code that violates your conventions because those conventions were never written down. AGENTS.md is the antidote: it makes implicit convetions explicit before the AI guesses wrong

How to Write Your Own AGENTS.md

If you're building a project with non-standard choicse, here's a minimal template:

1.Start with the "DO NOT" list. What are the top 5 assumptions an AI would make about your project that are wrong? Write them as explicit negations.

2.Map your architecture in one paragraph. Where does code live? How do packages import from each other? What's the entry point?

3.Document repeating patterns with code. Any UI pattern, error handling convention, or testing setup that appears in 3+ places gets a concrete example.

4.List your commands. What does bun run dev do vs bun run build? What's the test command? AI assistants will guess give them the right answers.

5.Keep it under 500 lines. If it's longer, the AI will stop reading. Prioritieze the conventions that cause the most bugs when violated.

Frequently Asked Questions

Is AGENTS.md just a fancy .editorconfig?
No. .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.
Does AGENTS.md work with all AI coding assistanst?
In our experience, yes. We've tested it with Claude Code, Github Copilot, Opencode, Cursor, and Antigravity. The file format is plain markdown any LLM-based tool can read it. The key is placing it at the repo root where AI assistants automatically scan for context files.
Should every project have an AGENTS.md?
If your project uses unconventional tools (Bun instead of npm, Drizzle instead of Prisma, TanStack Router instead of Next.js), then yes. If you're using the most common stack in your ecosystem, the AI's defaults will probably match your conventions but you'll still benefit from documenting your specific patterns.
Can AGENTS.md replace human onboarding?
No. It complements it. New human developers still need conceptual understanding of why certain choices were made. AGENTS.md is specifically optimized for AI consumption imperative, concrete, and constraint-focused. Human onboarding docs should still exist alongside it.

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

Stop AI from Ruining Your Codebase: The Power of AGENTS.md

Key Takeways

Why Did We Write Docs for a Non-Human Reader?

What's Inside AGENTS.md?

1.Project Identity (The "Don't Assume" Section)

2. Technology Stack (The "What We Use" Table)

3. Architecture Rules (The "How We Import" Section)

4. UI Conventions (The "How We Style" Section)

5. Testing Conventions (The "How We Test" Section)

The Meta-Lesson: AI Documentation as New Genre

How to Write Your Own AGENTS.md

Frequently Asked Questions