Most repositories I work with now have some sort of instruction file for coding agents. It might be an AGENTS.md, a CLAUDE.md, or a set of rules stored in tool-specific directories.

At first, these files seemed like a convenience. Put the build commands and a few coding preferences in Markdown, and you don’t have to repeat yourself whenever you start a new agent session.

I think that description is becoming inadequate.

If an agent can only suggest a change that I will read and test myself, the instructions mainly help it work faster. If that same agent can modify several parts of a codebase, run a deployment, review someone else’s work, or merge a pull request, those instructions have a much more serious role.

We are starting to use plain text files to tell software agents what they are allowed to do, what evidence they must produce, and when they must stop. We ought to take that seriously.

What the open-source projects are doing

I recently read an analysis by the team at Blume, where they examined the 155 most-starred TypeScript, Python, Rust, and Go repositories on GitHub for root-level CLAUDE.md and AGENTS.md files.

Of those 155 projects, 67 had at least one of the files. Within that group, 46 used AGENTS.md as the main source of instructions. Several kept CLAUDE.md as a pointer or import for tools that expected it.

The authors also measured the effective length of those 67 instruction files. The median was about 5,400 characters, but the largest was almost 75,000. They scored ten files against a set of recommendations based on Anthropic’s guidance.

The interesting part was not which project scored highest. It was that some of the longest instruction files belonged to projects making extensive use of coding agents.

OpenClaw, for example, had a root instruction file of roughly 36,000 characters and more than twenty scoped AGENTS.md files. Much of the root file described how agents should review code, check evidence, and assess changes before they were accepted.

That doesn’t prove longer files make agents better. The study scored only ten files, and a score based on a writing rubric is not a measure of production reliability. But the examples do expose a real difference in what teams expect these files to accomplish.

The right length depends on the job

Anthropic’s guidance for Claude Code recommends keeping each CLAUDE.md under 200 lines. It makes sense. Every instruction consumes context, and an agent can miss important rules when they’re surrounded by material it doesn’t need.

For a small project where I review every change, I would much rather give an agent twenty precise lines than twenty pages of general advice.

But suppose the task is to review and merge a pull request without a person checking every step. Now I care about more than formatting and where the test files live.

What evidence counts as a valid test run? Can the agent approve a change that modifies authentication or billing? What should happen if a dependency is unavailable and a check cannot run? Does it need to ask before changing a migration? When is a failed check a reason to stop instead of an invitation to keep guessing?

Those questions require specific answers. Some projects will need many of them.

The trade-off isn’t simply short versus long. It is the cost of reading an instruction versus the cost of the mistake it may prevent. A rule that saves a minute during every session might not deserve space in the instructions. A rule that prevents an unsafe production change probably does.

There is an important limit, though: a Markdown file is still a set of instructions to a model, not a security control. If an agent must not merge into master without approval, enforce that with branch rules and permissions. If it doesn’t need production credentials, don’t give it those credentials. The text should explain the process; the system should enforce the boundaries that matter.

Specific instructions beat good intentions

The most useful part of the Blume analysis was much less dramatic than the size debate. Several otherwise good files missed the command for running a single test.

That is the sort of detail I want an agent to know. If it changes one validator, I don’t want it to run an entire suite after every edit when a focused check would give faster feedback. I also don’t want it to skip testing because it couldn’t work out which command was appropriate.

The difference between these instructions is substantial:

Write clean code and make sure it works.

And:

Run bundle exec rake test:frontmatter after changing a blog post’s metadata. Run the full site tests before opening a pull request.

The second one tells an agent what action to take and when. It can verify whether it complied. The first one leaves almost everything to interpretation.

For the same reason, I am not convinced by instruction files filled with directory listings, generic coding principles, or summaries the agent can get from the repository itself. Those lines cost context and become outdated. I would rather use the space for non-obvious rules, known failure cases, and the checks that matter to this project.

Keeping two files creates another problem

There is a small example in this blog’s own repository. It has both AGENTS.md and CLAUDE.md.

The former explains the Jekyll setup, the post format, tests, and deployment details. The latter covers some of the same ground and points back to AGENTS.md for more detail. That arrangement works today, but it also gives me something to maintain.

If we change the build process, add a new validation rule, or alter how previews are deployed, which file needs updating? Both? Will the next agent read the right one? What happens when one describes a command that no longer exists?

Tool support also changes. An older workaround may no longer be needed; Claude Code’s current memory documentation now describes how it can load AGENTS.md directly. A setup that made sense when the file was first added can become needless duplication.

I increasingly prefer one clear source for shared project rules, with tool-specific files limited to what those tools actually need. More importantly, I want changes to these instructions reviewed as part of the same pull request that changes the workflow they describe.

An instruction file can be syntactically valid, neatly written, and still wrong about the repository. That makes it a maintenance issue, not a writing issue.

Review the rules when an agent gets something wrong

At Renderbit, we build and maintain software for clients. The work includes old applications, third-party services, infrastructure changes, and decisions made long before the current engineer joined the project.

I want agents to help with more of that work. But when an agent makes a mistake, I don’t want the only fix to be correcting it in the current conversation and hoping the next session goes better.

If an agent ran the wrong test, perhaps our instructions need a focused test command. If it changed a database schema without considering existing data, perhaps the repository needs a migration checklist. If it made an assumption about a client workflow, perhaps we need to record the business rule and the point at which it must ask for confirmation.

That does not mean every mistake deserves a new permanent rule. Some errors are one-offs. Others are better prevented with tests, lint rules, access restrictions, or simpler code. And an instruction that no longer helps should be removed.

When I review an AGENTS.md or CLAUDE.md, these are the questions I now want to ask:

1. Does this rule prevent a real mistake? If not, why is it here?
2. Can the agent act on it and check the result? Or is it just a vague preference?
3. Does it apply to every task? If not, can it live closer to the code or workflow it concerns?
4. Does anything enforce it? Especially when a mistake could affect data, security, or production.
5. Is it still true? Would a new engineer following it today get the right result?

I suspect this will tell us much more than counting lines or awarding a file a score out of 100.

The standard should rise with the autonomy

I still want short instruction files wherever possible. I don’t want agents spending time reading rules that don’t apply, or following old guidance because nobody thought to remove it.

But I also don’t want us to optimise for a small context window while quietly giving agents broader authority. If an agent can take actions with lasting effects, it needs clear boundaries and reliable ways to prove what it did. Some of those details belong in its instructions. Others belong in tests, permissions, and review processes.

The important question is not whether your AGENTS.md has fifty lines or five hundred. It is whether the agent understands the project’s real constraints, whether we can verify its work, and whether the amount of freedom it has matches the controls around it.

As we give coding agents more responsibility, the rules we give them become part of our engineering work. We should write, test, review, and maintain them accordingly.