I lost about half an hour last month working out why my agent kept running the wrong test command. It wasn’t the agent. Someone had updated the build section in our AGENTS.md two weeks earlier, I reviewed that PR, and I approved it in maybe four seconds because it was “just a docs change”. It wasn’t a docs change. It was a config change wearing a markdown hat, and I’d waved it through.
Why is there suddenly so much markdown in pull requests?
Because a whole file category showed up that didn’t exist before. AGENTS.md was introduced on 19 August 2025, out of a collaboration across OpenAI Codex, Sourcegraph’s Amp, Google’s Gemini and Factory. It’s a plain markdown file that tells a coding agent how to build, how to test, and what conventions to follow. The agents.md site now says it’s used by over 60,000 open-source projects, with stewardship at the Agentic AI Foundation under the Linux Foundation.
Put those two facts side by side: a file format that didn’t exist before August 2025 is now in 60,000+ open-source projects. Then add the siblings sitting next to it, CLAUDE.md, copilot-instructions.md, per-directory instruction files, rule folders. That’s a brand new kind of file landing in repos that never had one, and every single one of them arrives and gets edited through a pull request. Mine included, apparently reviewed in four seconds.
What makes an instruction file load-bearing?
It isn’t documentation about the system, it’s an input to the thing that changes the system. A wrong build command, a path that moved, a rule that quietly contradicts the rule three sections above it: the agent reads all of it and acts on it, every session, in every future PR. And it doesn’t fail loudly, which is the annoying part. It just produces plausible changes that are slightly wrong, again and again, and nobody connects that back to a docs edit that shipped with an LGTM.
It’s the same reasoning as capturing intent while the agent is working and the same reasoning as tiering review rigor by blast radius. A file that steers an agent reaches further than most one-line code changes, because it applies to work nobody has written yet. Osmani makes the general version of this point: generation got cheap, understanding didn’t. Instruction files are where one unread line buys you the most future confusion.
The boring markdown matters too, just for a duller reason. Microsoft Research found, in its study of modern code review, that understanding the change is the reviewer’s hardest problem, and that knowledge transfer is one of the real payoffs of reviewing at all. Specs, ADRs and runbooks are how that understanding survives past the person who had it.
Why is raw diff the worst possible view of a document?
GitHub renders markdown beautifully everywhere except the one place it matters most. In a PR, a .md file is diff text, so you end up reviewing the syntax instead of the document. Fine for a paragraph edit. Actively misleading for everything else, because the constructs that are hardest to read as raw markdown are exactly the ones people use when a document is doing real work.
A table diff is a wall of pipes and dashes with nothing lined up, and a row missing a separator does not fail loudly: markdown pads the row out with an empty cell, so it still renders and your value just sits in the wrong column. A nested list changes meaning based on indentation you can’t really see in a diff gutter. A link like [the config](../ops/config.md) reads fine and resolves to nothing once the file it points at gets moved in the same PR. An image is a URL, not an image. All of that is invisible in source and obvious in a render, which is a strange place to end up for a format whose entire job is to be rendered.
What should you actually check in a markdown diff?
Nothing exotic, just the things a raw diff can’t help you with. These belong on the same list as the rest of your review checklist.
- Read the render first, then the diff. The render tells you what changed for the reader, the diff tells you what changed in the file, and you want them in that order.
- Click every changed link, including anchors to headings. Rename a heading and you silently break every link pointing at it, inside the repo and outside it.
- Check tables are still tables and nested lists still nest. Those two fail into unreadable prose rather than into an error, so nothing warns you.
- For instruction files, read for behavior, not for prose quality. What will an agent do differently after this merges? Does the new rule fight an existing one? Does that build command still exist?
- Look at what got deleted, not just what got added. Prose review is more about removals than most people expect.
What I do about it now
I got tired enough of this that we built rendered document review into our own reviewer (disclosure: I work on Pyor). Any renderable file in a PR gets a toggle between the source diff and a rendered preview, which is the default for Markdown and MDX (a Source button flips back to the raw diff), plus a switcher for the head version, the base version, or the diff. The rendered diff does word-level inserts and deletes inside a block, so a changed table cell reads like a changed table cell instead of a wall of pipes. You can comment on the rendered document itself, and comments left on the diff show up on the render, so the conversation doesn’t fork by view.


You don’t need our thing to fix this, though. The habit is the part that matters: markdown went load-bearing faster than review habits caught up, and the gap shows up as instruction files merged unread and docs that render broken on main. Stop treating a markdown diff as a formality and read the document the way its audience will, whether that audience is a new teammate or an agent reading it a hundred times a month.
Frequently asked questions
Why does markdown in pull requests need real review now?
Because a lot of it stopped being decoration. Agent instruction files steer what a coding agent does to your codebase, so a wrong path or a stale build command in one of them produces wrong changes over and over, in every future session that reads the file. That is a defect with a blast radius, not a typo.
What is AGENTS.md and who maintains it?
AGENTS.md is a plain markdown file that tells coding agents how to work in a repository: how to build, how to test, what conventions to follow. It was introduced in August 2025 by a group of agent vendors, and the agents.md site says it is now used by over 60,000 open-source projects. Stewardship sits with the Agentic AI Foundation under the Linux Foundation.
What does a raw markdown diff hide?
Three things break silently in source view. Tables, where a row missing a pipe still renders but drops your value into the wrong column. Links, where a relative path or a heading anchor looks fine and resolves to nothing. Images, which show up as a URL instead of the thing your reader actually sees. All three are obvious the second you look at the render.