Write It Down or the Agent Makes It Up

Here's an uncomfortable pattern I keep seeing: a team rolls out coding agents, results are wildly uneven across repos, and everyone blames the model. Then you look closer and the repos where agents do well are the ones with decent documentation — a real README, a build that works from a fresh clone, conventions written down somewhere. The repos where agents flail are the ones held together by tribal knowledge.

The model was never the variable. The context was.

Tribal knowledge just became a liability with a price tag

Every engineering org runs on undocumented knowledge. Which service is the real source of truth. Why you never touch that config file. The deploy step that isn't in the runbook because "everyone knows." For years this was survivable because humans absorb tribal knowledge through osmosis — you sit next to someone for six months and you just know.

Agents don't sit next to anyone. An agent lands in your repo with zero history, reads what's written down, and acts. If the real rules aren't written down, the agent does the plausible-looking wrong thing — confidently. It will use the deprecated internal library because nothing says it's deprecated. It will write tests in the style of the oldest files it found. It will "fix" the weird config that's weird for a reason.

People call this hallucination. Most of the time it's something more mundane: the agent filled a documentation vacuum with a reasonable guess, and your org's reality happens to be unreasonable.

The industry already converged on a fix

The good news is you don't need to invent anything. AGENTS.md — a plain markdown file at the repo root with instructions for coding agents — was formalized as an open spec in August 2025 and has since been adopted by more than 60,000 open-source projects, with stewardship now under the Linux Foundation's Agentic AI Foundation. Codex, Cursor, GitHub Copilot's coding agent, Devin, Gemini CLI, and most other serious tools read it natively; Claude Code has its own CLAUDE.md convention that serves the same role and can simply reference it.

The format matters less than the discipline. What goes in the file is the stuff a senior engineer would tell a new hire in their first week: how to build and run tests (exact commands, not vibes), which patterns to follow and which directories are legacy, what "done" means (lint passes, tests pass, no new dependencies without a note), and the landmines — the things that look wrong but are load-bearing.

How to actually do this without a documentation death march

Nobody has time for a six-month documentation initiative, and you don't need one. Three moves:

1. Seed it with the agent itself. Point a coding agent at the repo and ask it to draft the AGENTS.md: infer the build steps, the test commands, the conventions. It'll get 70% right. Then — and this is the step that matters — have the two or three people who actually hold the tribal knowledge spend an hour correcting it. An hour of a staff engineer's time per repo. That's the whole investment.

2. Treat agent failures as documentation bugs. When an agent does something dumb, the retro question isn't "why is the model bad," it's "what wasn't written down?" Agent used the wrong HTTP client? Add a line. Agent broke the migration ordering? Add a line. The file compounds. Within a quarter, the repos with active agent usage have better onboarding docs than anything your last documentation push produced — because the feedback loop is daily, not annual.

3. Review the file like code. AGENTS.md goes in the repo, changes go through PRs, and it gets updated when conventions change. A stale instruction file is worse than none — the agent will follow it off a cliff.

The side effect is the real payoff

Here's the part I find most interesting as a leader: the documentation you write for agents is exactly the documentation you always owed your humans and never wrote. New hires read AGENTS.md too. Contractors read it. The engineer who inherits the service in two years reads it.

For a decade we've accepted that documentation decays because nothing enforces it. Now something enforces it: every day, an agent reads your docs and acts on them, and you feel the gap immediately as bad output. Agents turned documentation from a virtue into a dependency. Dependencies get maintained.

There's an early research signal that this pays off in efficiency terms — one 2026 study looked specifically at the impact of AGENTS.md files on coding-agent efficiency — but honestly, you don't need a paper. Run the experiment on your own repos: pick two comparable services, give one a real AGENTS.md, and compare a week of agent PRs. The difference is not subtle.

The takeaway

Before you buy more agent seats or argue about which model is smarter, audit your repos for what's written down. The cheapest, highest-leverage AI investment available to most engineering orgs right now is an hour per repo of a senior engineer's time turning tribal knowledge into a markdown file. Your agents get better on day one. Your humans get better forever.