Your coding agent doesn't need more docs 🔥

Hey tech adventurers! 👋

Everyone keeps saying it: if your coding agent is struggling, give it more docs. Another AGENTS.md. A folder of ADRs. Twenty more skills.

I think that's backwards. Here's why.

I run a handful of coding agents every day that write, review and fix PRs, so I see a lot of agent-written code, and a lot of agents ignoring docs.

I know, I know. You're clutching your AGENTS.md or CLAUDE.md right now. Hear me out.

Your agent doesn't need more docs. It needs fewer. And before we're done, I'm coming for your docstrings too. 🌶️

The moment I gave up on docs 🫠

🧾 Ticket #1: show when a todo was created. The agent ships it and dutifully writes a doc: "Timestamps render as 12-hour time, e.g. 3:45 PM." ✅

🧾 Ticket #2, two weeks later: add a 24-hour (military time) setting. The agent ships a use24h flag. Nobody touches the doc. Nothing fails. Docs don't fail.

🧾 Ticket #3: the next agent opens the repo and finds this:

# docs/time.md
Timestamps render as 12-hour time.

// src/time.ts
formatTime(date, { use24h })

Pick one. The agent has to.

So you tell the agent in the prompt: "Please read the docs before you start."

The agent says "Absolutely!" and opens a PR that ignores half of them.

🔧 Quick aside: why "Absolutely!" and then nothing? Models are trained on human feedback, and humans reward agreeable answers. So "Absolutely!" is manners, not a plan. Meanwhile "read the docs" is one sentence competing with everything else in the context. And a prompt is a suggestion, not a rule. Only what the harness enforces always happens: hooks, CI, failing checks.

So if you have to remind your agent the docs exist, and it still doesn't follow them, the problem isn't the agent being lazy. It's not a skill issue either. 🍪 (You made it this far. That's your cookie.)

Your agent isn't bad at reading docs. Your docs are bad at being true. The code is the only thing that is.

Why docs fail agents 📉

Docs and code live separate lives. Code gets executed, tested and changed every day. Docs only change when someone remembers. Nothing breaks when a doc is wrong, so nobody notices when it drifts.

For a human being, that's annoying. For an agent, it's actively harmful.

An agent doesn't know which paragraph is from last week and which one is from two rewrites ago. It doesn't even know what time it is right now. Karpathy once had a model flat-out refuse to believe it was 2025 until he turned on search.

So where does the disagreement come from? Every code change that doesn't touch the doc. The doc was true once. Then the code moved. Add the model's training memory, and the agent is weighing three versions of the truth: the code, the doc, and whatever was popular on GitHub when it was trained.

It has to guess. Follow the doc and break the code, or follow the code and ignore the doc. Either way you paid for context that made the result worse.

So outdated docs don't just fail to help. They make the agent worse.

Docstrings are docs too 🧾

Here's the spicy one I promised: I'd remove most docstrings from the source code as well.

A docstring is the same problem at a smaller scale: a second description of the code that goes stale just as quietly. When the function changes and the docstring doesn't, the agent reads a comment that's lying to it, right above the line it's about to edit.

To be fair: an accurate comment can help. But nothing keeps it accurate. So the target is the stale and redundant ones: the docstring that restates the signature, the "temporary" workaround from 2023.

If a function needs a paragraph to explain it, fix the function: a better name, smaller pieces, clearer types. The code can't be out of date with itself.

The one exception: comments about things outside your control. The weird browser quirk, the API that lies about its status codes. The code can't explain those, because the reason isn't in your repo. It's in a vendor's bug tracker or a 2 a.m. incident. Code shows what you did, never why the obvious version broke. Delete it and the next agent helpfully "cleans up" your workaround. So keep those. Everything else goes.

ADRs are the new rules file 📜

Remember the start of this year? Everyone piled rules files onto their agents. The agents didn't read them, and they didn't follow them.

Now the same thing is happening with ADRs.

Instead of writing down what the agent can't find in the code, people define everything in there. How pagination works. That we have a REST API. The default error codes, again.

The code already says all of that. And the day the code moves and the ADR doesn't, you're back to the timestamp problem: two answers, one agent, no way to know which is current.

A good ADR holds what the code can't:

• Context from outside the repo. A customer or compliance constraint. A decision you made with another team.
• The why behind something that looks inconsistent. Why one kind of data is encrypted one way and another kind a different way. The agent can read how each one is encrypted. It can't read why, so it helpfully "fixes" the difference.

Everything else? Make the code say it. A clean, consistent codebase beats another ADR every time. Write an ADR only for the "why" the code can't hold.

And wire the ones you keep into review: a CI job or a review bot that checks every PR against them. An ADR nothing checks is just another rules file. (Same goes for any doc: if the codebase generates it and CI checks it, it's not a doc anymore. It's infrastructure.)

"Just have the agent write the docs" 🤖✍️

The obvious fix: let agents write the docs. Concise, agent-friendly, problem solved.

Don't trust me. Theo put it bluntly: 'You should delete your CLAUDE.md/AGENTS.md file. I have a study to prove it.'

Agent-written docs are the worst offenders. They drift back to what models love: verbose, hedge-everything prose that buries the one rule that matters. Then the next agent skims it and does its own thing anyway.

We end up building a machine that writes documentation nobody reads, for a machine that doesn't read it either.

More instructions is not more skill 🎒

Skills, rules files, system prompts, MCP servers, tool descriptions: same story. Everything in context competes for the same attention. And you know the loop:

1. The agent messes up.
2. You add a rule.
3. Repeat for six months.
4. Congrats, you built a junk drawer nobody reads. 🗃️

Skills load on demand, so 30 installed doesn't mean 30 full skills in every prompt. So why care? Because the menu is always there. Every installed skill still puts its name and description in context on every task, asking to be picked. Rules files and always-on prompts don't even wait to be picked.

The more you pile on, the less weight any single one gets, and the harder it is for the agent to tell what matters for the task in front of it.

The exception: scripts and hooks. They don't ask the model to remember anything. They just run.

So the question isn't "how many skills can I install?" It's "which of these would I miss if I deleted it?"

Start with none, and add one only when you see the same mistake twice.

And when you do, ask first: could this be a lint rule or a type instead of a sentence? lauren (SpaceXAI, ex-Cursor) puts it this way: every mistake you see from agents "needs to turn into a constraint", because your codebase is their memory. "forget rules and skills. you can add those later."

The Claude Code team did this to their own product: they cut over 80% of the system prompt with no measurable drop on their coding evals. Their advice, via Addy Osmani: "remove some, then add back only those that the model misses."

So what actually works? 🧹

Less. Seriously.

A uniform codebase. Agents learn by example from the code around them. If every module follows the same patterns and naming, the agent picks it up from reading two files. If every module is a snowflake, no amount of docs will save you.

Consistency is the documentation.

But consistency you hope for isn't consistency. Enforce it. Turn the architectural rule into a lint rule, shape the types so there's only one way to do the thing, make the wrong import fail the build. A rule in a markdown file can be ignored. A failing check can't.

None of this is new. It's what we always did for the new hire who never read the wiki. The agent is just a new hire who starts over every morning.

Small context, not small intent. Agents can work out how to build something from the code in front of them. What they need from you is the what and the why, stated clearly. What doesn't help is dictating every line or stuffing the prompt with background it can read from the code. Then the agent spends its attention on your essay instead of the problem.

A clear definition of done. This is the one thing I do write down, because "done" is where agents actually go wrong. They don't fail because they skipped the architecture guide. They fail because they stop too early, skip a check, or claim something works that they never verified.

Boris Cherny from Anthropic's Claude Code team calls this the most important thing: give the agent a way to verify its work and it'll 2-3x the quality of the result.

Addy says the same: one clear goal, plus how to verify it. Ideally a pass/fail check or a number to beat, so the agent can keep going without you watching.

And unlike docs, a definition of done can be checked, so it doesn't rot. Not a wiki. Not an ADR. Just the finish line. 🏁

Less is more 🪦

Everyone's answer is more: more docs, more rules, more skills. I think it's the opposite. Make the codebase obvious, tell the agent what "done" looks like, check that it got there, and get out of the way.

So, honestly: how much of your docs folder did your agent actually read last week? 👀

Don't know? Paste this into your agent:

"Go through AGENTS.md and everything in docs/. For each rule, tell me whether the code enforces it, contradicts it, or ignores it."

Send me what it finds. Every few months, audit how you work, so you aren't building for how older models used to work.

Then delete one doc this week and see if anything breaks. 🪦

Comments

[Reid Marlow]

The drift gets worse once an agent has shell or database access. Putting operational rules into markdown files, like telling the model to run a migration with a dry-run flag or stay out of a specific directory, leaves enforcement up to context attention. When an agent hits an error loop, it routinely ignores the doc and runs the raw command anyway. The setup that holds up in practice is pulling those constraints out of prompt text and into the execution boundary. Dropping write capabilities at the database connection level, blocking dangerous subcommands inside the shell wrapper, and requiring a clean git diff before accepting a completion token turn suggestions into hard stops. An agent can skip a markdown rule, but it cannot negotiate with an exit code.