I watched a teammate spend 20 minutes complaining that Copilot “doesn’t understand our codebase.” Then I looked at the repo. No README. No architecture docs. No module descriptions. Just code.
Here’s the uncomfortable truth: most AI code quality problems aren’t AI problems. They’re context problems.
The experiment that changed my mind
I took the same task — “add pagination to the users endpoint” — and tried it two ways:
Round 1: Just the prompt. AI generated something that technically worked but used the wrong ORM pattern, wrong error handling style, and a pagination approach nobody on the team uses.
Round 2: Same prompt, but I added a 40-line AGENTS.md file describing our project conventions: ORM patterns, error handling approach, pagination style, test expectations.
The difference was night and day. Not because the AI got smarter between attempts — the context did.
Why this matters more than model upgrades
Everyone’s waiting for GPT-5 or Claude Next or whatever to “finally get it right.” But I’ve found that well-documented context with a mediocre model outperforms zero context with a frontier model.
Think about it like onboarding a new developer. You wouldn’t drop a senior engineer into your codebase with zero documentation and expect them to match your team’s patterns on day one. Why do we expect that from AI?
What actually works: the AGENTS.md pattern
I keep a simple markdown file at the project root that describes:
# AGENTS.md
## Project Overview
Express API with PostgreSQL, using Knex for queries.
## Conventions
- Error handling: wrap in try/catch, use AppError class
- Pagination: cursor-based, not offset
- Tests: co-located with source, use test factories
- Naming: camelCase for JS, snake_case for DB columns
## Common Gotchas
- Don't use the `users` table directly — go through UserService
- Rate limiting is middleware-level, don't add it per-route
That’s it. 30 lines. Takes maybe an hour to write well.
The key insight: this file is portable. I’ve used variations of it with Cursor, Copilot, and Claude Code. The format changes slightly, but the content — your project’s actual knowledge — stays the same.
The trade-off nobody talks about
I won’t pretend this is free. The setup cost is real — maybe 2-3 days to get your context files right for a large project. And they need maintenance. When your patterns evolve, your AGENTS.md needs to evolve too.
It also doesn’t solve everything. Greenfield projects where you don’t have established patterns yet? AI is still going to hallucinate conventions. And for high-stakes code — auth, payments, data migrations — I still do manual review regardless of how good the context is.
But for the 80% of code that follows established patterns? Context files are the highest-leverage investment I’ve found.
The question I’m still working through
Here’s what I haven’t figured out: how do you keep context files in sync with a fast-moving codebase?
I’ve tried pre-commit hooks that validate AGENTS.md against actual code patterns. It sort of works. But I’m curious — has anyone found a better approach? Or do you just accept some drift and do periodic manual updates?
P.S. I’ve been packaging the workflow patterns I use daily into a toolkit — project templates, AGENTS.md examples, verification scripts. If you’re interested, I share more at updatewave.gumroad.com.