{"slug": "agents-md-is-becoming-the-new-code-review-contract", "title": "AGENTS.md is becoming the new code review contract", "summary": "GitHub's Copilot code review now reads repository-level AGENTS.md instructions, allowing teams to encode engineering judgment and local conventions into automated review comments. This shifts code review from style rules to machine-readable team taste, raising questions about ownership and governance of the instruction file.", "body_md": "GitHub added a small Copilot code review feature this week that feels bigger than the changelog entry.\n\nCopilot code review can now read repository-level `AGENTS.md`\n\ninstructions.\n\nThat sounds like a nice quality-of-life improvement. Put your preferences in a file. Tell the agent how the project works. Get fewer weird review comments. Fine.\n\nBut I think the more interesting version is this: code review is starting to depend on machine-readable engineering judgment.\n\nNot only style rules. Not only lint. Not only \"please use pnpm.\"\n\nActual team taste.\n\nThe little rules that senior engineers carry around in their heads. The migration scars. The local architecture boundaries. The places where the codebase looks flexible but really is not. The patterns that are tolerated in one folder and forbidden in another. The test strategy that makes sense only if you know the history of the service.\n\nFor years, that knowledge lived in code reviews as repeated comments from tired humans.\n\nNow we are being asked to write it down for agents.\n\nGood.\n\nAlso uncomfortable.\n\nThe easiest part of code review to automate is the part we should have automated already.\n\nFormatting. Dead imports. Missing null checks. Basic security mistakes. Naming that violates a clear convention. Tests that obviously do not run. Dependencies that should not be added.\n\nThose are useful checks, but they are not the reason code review matters.\n\nThe hard part of review is judgment.\n\nDoes this change belong in this layer? Is this abstraction premature? Is this behavior compatible with the migration we are halfway through? Is this the right place to pay down debt, or is it a distraction from the actual risk? Does this test prove the thing users care about, or only the implementation we happen to have today?\n\nHumans answer those questions with context.\n\nSome of that context is in the repository. Some is in docs. Some is in tickets. Some is in the memory of the person who has reviewed every painful refactor since 2021.\n\nAgents can read a lot, but they are not automatically part of that memory.\n\n`AGENTS.md`\n\nis one way to give them a map.\n\nThere is a tempting bad version of this.\n\nA team creates an `AGENTS.md`\n\nfile that says things like:\n\nThis is better than nothing in the same way a motivational poster is better than a blank wall.\n\nIt does not create a review contract.\n\nA useful agent instruction file should be more local and more opinionated. It should say the things that are true here, in this repository, for this team, because of the system you actually maintain.\n\nFor example:\n\nThat is the useful stuff.\n\nIt is not universal. It is not glamorous. It is the team telling the agent where the rails are.\n\nAnd once Copilot code review reads those instructions, they stop being documentation that maybe someone remembers. They become part of the review surface.\n\nThe awkward question is who gets to write the file.\n\nIf `AGENTS.md`\n\ninfluences automated review comments, then it is not just a developer convenience. It is part of the engineering control plane.\n\nThat means it needs ownership.\n\nNot heavy bureaucracy. Please no.\n\nBut the file should not become a dumping ground for every frustrated reviewer to encode their personal preference. It should not become a prompt-shaped style guide with 300 rules nobody agrees with. It should not be rewritten casually by the same pull request it is supposed to constrain.\n\nThe best version probably looks like any other important repository policy:\n\nThis is where the \"agents replace reviewers\" story gets too shallow.\n\nAgents do not remove human judgment. They make the written parts of human judgment more valuable.\n\nIf the team cannot explain what it wants, the agent will mostly learn the easy surface: syntax, file names, nearby patterns, and generic advice from the internet.\n\nThat may be enough for small changes.\n\nIt is not enough for the weird parts of real systems.\n\nWe have been here before, just with smaller tools.\n\nLinters turned some taste into executable rules. Formatters ended whole categories of review comments. Type systems moved mistakes earlier. CI made \"works on my machine\" less persuasive. Policy-as-code moved some operational rules out of meetings and into checks.\n\nEach step changed code review.\n\nThe reviewer stopped spending time on semicolons and started spending more time on behavior. Or at least that was the promise.\n\nAgent instructions are a similar move, but less deterministic.\n\nA linter either reports a rule violation or it does not. An agent reads an instruction, mixes it with code context, model behavior, and whatever else is in the prompt, then produces a comment that may or may not be useful.\n\nSo we should not pretend `AGENTS.md`\n\nis the same as a test suite.\n\nIt is softer than that.\n\nBut soft does not mean useless.\n\nEngineering organizations already run on soft contracts: architecture principles, design review norms, escalation rules, ownership boundaries, deploy expectations, and the informal \"we do not do that here\" knowledge every healthy team has.\n\nThe difference is that agents need those soft contracts in writing.\n\nThere is a failure mode I expect to see a lot.\n\nThe agent starts leaving confident comments based on stale or vague instructions.\n\nIt tells people not to use a pattern that is now approved. It repeats a rule that only applied during a migration that ended months ago. It blocks a reasonable local exception because the file says \"never.\" It comments on every pull request with the same generic architecture sermon.\n\nThat will make developers hate the tool quickly.\n\nThe fix is not to abandon repository instructions. The fix is to treat them as living code.\n\nIf an instruction produces bad review comments, change the instruction. If the instruction is correct but the agent applies it poorly, make it narrower. If a rule has exceptions, name the exceptions. If the rule is actually preference dressed up as architecture, remove it.\n\nThis is boring maintenance work.\n\nThat is why it matters.\n\nThe teams that get value from AI review will not be the teams with the longest instruction files. They will be the teams with the clearest ones.\n\nOne thing I would like to see more of in AI-assisted review is provenance.\n\nIf Copilot leaves a comment because of `AGENTS.md`\n\n, say that.\n\nPoint to the instruction. Let the author and reviewer see which local rule was involved. Make it easy to tell the difference between a generic model concern and a repository-specific contract.\n\nThat matters because humans need to debug the system.\n\nWhen a human reviewer gives bad feedback, you can talk to the human. When an agent gives bad feedback, you need to know which part of the system produced it: the model, the code context, the prompt, the repo instructions, a stale doc, or a missing exception.\n\nWithout that trail, teams will either trust the comments too much or ignore them entirely.\n\nNeither is good.\n\nGood AI review should feel less like a mysterious second reviewer and more like a visible extension of the team's own standards.\n\n`AGENTS.md`\n\nsupport in Copilot code review is a small feature with a serious implication.\n\nRepositories are becoming places where teams encode not only code, tests, and configuration, but also instructions for non-human collaborators.\n\nThat is the right direction.\n\nThe codebase should explain itself to the tools that work inside it. The review agent should know more than generic best practices. It should know the local contracts that make this system maintainable.\n\nBut this only works if teams take the file seriously.\n\nWrite down the judgment you actually want repeated. Keep it short. Keep it local. Review changes to it with the same care you give other policy files. Remove stale rules. Prefer concrete constraints over vague taste. Watch whether the comments get better.\n\nThe model is not going to magically learn your engineering culture from folder names.\n\nIf you want agents to review like members of the team, you have to give them the team's standards in a form they can use.\n\nThat is what `AGENTS.md`\n\nis becoming.\n\nNot a prompt.\n\nA review contract.\n\nTo test my projects, I use [Railway](https://railway.com?referralCode=G_jRmP). If you want $20 USD to get started, [use this link](https://railway.com?referralCode=G_jRmP).", "url": "https://wpnews.pro/news/agents-md-is-becoming-the-new-code-review-contract", "canonical_source": "https://dev.to/pvgomes/agentsmd-is-becoming-the-new-code-review-contract-17c9", "published_at": "2026-06-19 00:01:42+00:00", "updated_at": "2026-06-19 00:29:51.015153+00:00", "lang": "en", "topics": ["developer-tools", "artificial-intelligence", "large-language-models", "ai-agents"], "entities": ["GitHub", "Copilot"], "alternates": {"html": "https://wpnews.pro/news/agents-md-is-becoming-the-new-code-review-contract", "markdown": "https://wpnews.pro/news/agents-md-is-becoming-the-new-code-review-contract.md", "text": "https://wpnews.pro/news/agents-md-is-becoming-the-new-code-review-contract.txt", "jsonld": "https://wpnews.pro/news/agents-md-is-becoming-the-new-code-review-contract.jsonld"}}