AGENTS.md is the new CONTRIBUTING.md. Kind of.

Every agent starts as a new hire

You ask an agent to fix a small bug. It fixes the bug, reformats an unrelated file, and makes a private helper public along the way. Now you have a working patch and a review you hadn't budgeted for.

This is the appeal of AGENTS.md: somewhere to put the things you are tired of explaining. CONTRIBUTING.md does a similar job for people joining a project. An agent needs that introduction every time it starts without the relevant context.

On August 19, 2026, a Hacker News discussion about support for AGENTS.md drew 379 points and 219 comments. The author wanted one file that worked across vendors, so collaborators could stop hunting through tool-specific files for the project's rules. Fair enough. Nobody needs a second onboarding process just because they changed their coding assistant.

Stop leaving the same review comment

Fabien Sanglard's August 2026 account follows a familiar progression. His first generated Rust code did not compile. Later attempts worked, but the code was spaghetti. He started putting recurring review feedback into agent.md: keep changes small, respect layer boundaries, write a test before fixing a bug, and stop widening visibility without a reason.

That post reached 415 points and 176 comments on Hacker News four days later. You can see why it resonated: writing down a review comment once is much more appealing than leaving it on every patch.

He still had to review the code. In his account, the file let him spend more of that attention on architecture and design, with less time spent correcting style. That is a useful improvement on its own.

Some rules deserve a failing build

“Ask before making this helper public” belongs in an instruction file. It calls for judgment. “Use our formatter” can point to a command that does the job for you.

The same goes for forbidden imports, dead code, and tests that must pass. Where a tool can check a rule, wire it into the workflow and tell the agent how to run it. Otherwise, you are volunteering to enforce it yourself at review time.

Clean code helps the agent find its way

A controlled 2026 study discussed at 210 points on Hacker News ran 660 Claude Code trials across 33 tasks and six repository pairs. In that study, cleaner code did not improve task pass rate, but it used 7–8% fewer tokens and caused 34% fewer file revisits.

Claude Code trials

660

33 tasks across six repository pairs in a controlled preprint.

Tokens on cleaner code

−7–8%

The study found a smaller operational footprint, not a higher pass rate.

File revisits

−34%

An agent found its way through cleaner code with less backtracking.

That result is about navigation, so it supports a modest point: readable code can save an agent some backtracking. If your instructions say the domain layer must never call the database, it helps when the code actually respects that boundary. Otherwise, you are asking the agent to follow a rule while showing it examples of how to break it.

Databricks' July 2026 benchmark used reviewed tasks in a multi-million-line codebase. With the same model and thinking effort, changing the harness moved cost per task by more than 2× in some cases while quality stayed the same. Pi sent about 3× less context per turn. The software around the model matters too; an instruction file is only one part of what the agent sees.

Please don't paste the whole wiki

It is tempting to add a rule after every disappointing patch. Keep doing that and the file becomes a history of everything that has ever annoyed you. The next agent still has a small bug to fix.

In an August 2026 guide, Anthropic advises keeping the always-loaded repository file to specific instructions and moving workflow-specific guidance into on-demand skills. In Claude Code, loaded files and tool output remain in the conversation and are resent on later turns as the session grows.

Sanglard starts a new session for each feature and reloads agent.md when quality declines. His explanation is a practitioner hypothesis, not a controlled result. It is worth keeping that distinction when borrowing someone else's workflow.

Keep the everyday instructions close: how to run a targeted test, which client to use for outbound calls, which directory needs special care. Link to the release checklist and migration guide so the agent can read them when the task calls for it. A typo fix does not need the full release ceremony.

Give the rules a home

The case for a shared filename is easy to like. Your team's engineering rules should survive a subscription change.

Keeping several copies of those rules is less appealing. Update one, forget another, and now two agents can follow instructions perfectly and disagree. Keep shared facts in the documents people already maintain, whether that is an architecture decision, an API contract, or CONTRIBUTING.md.

Let AGENTS.md point to those documents and explain when to read them. Someone changing an API needs the API contract. They should be able to find it without reading the deployment runbook first.

The agent still needs to know what you want

A perfectly followed instruction file can still produce the wrong feature if the task was vague. In his May 2026 lessons for agentic coding, Dan Breunig describes how the pieces fit together. End-to-end tests protect behavior as the implementation changes. Documentation records the reasoning tests cannot capture, and specifications need updating when building the feature teaches you something new. His post received 270 points on Hacker News.

Say you want to change a retry policy. The repository instructions can tell the agent where the networking code lives and how to test it. The task still needs to say which failures to retry and when to give up. Those decisions belong with the change, where a reviewer can compare the requested behavior with the tests.

Start with the comment you keep repeating

You probably already know a useful first entry for your file. It is the instruction you gave twice last week: use this test command, leave that generated directory alone, read this document before changing authentication.

Write it down. If a check can catch the mistake, add the check and include its command. If the explanation already lives in a maintained document, link to it. Keep enough detail for someone new to act without having to ask you what you meant.

That is the useful part of the CONTRIBUTING.md analogy: a little care for the next person, or agent, trying to help. Start with the thing that would have saved you a review comment yesterday.