AGENTS.md or CLAUDE.md?

Write one and mirror it. AGENTS.md is the cross-tool convention; several tools read CLAUDE.md specifically. Two files with the same content cost nothing; two files with different content is the failure mode.

How long should it be?

Short enough to read in a minute. If it is longer, you are describing your codebase rather than constraining behaviour — that belongs in the code.

One rules file your agent actually reads

Keep your agent's rules in one short, imperative AGENTS.md at the repo root.

EngineersVibe codersgithubanthropicopenai

An agent starts every session knowing nothing about your team's decisions. Whatever you do not write down, you will retype — and the third time you retype it you will stop bothering and start accepting the wrong output instead. A rules file is the cheapest durable memory a repository has, and it is read by every agent and every new human hire equally.

What goes wrong: The same correction given in every session until the day it stops being given, and the wrong pattern quietly becomes the codebase.

What agents change: This practice did not exist three years ago: it is entirely a response to a reader who has no memory and arrives fresh every session.

You are violating it when

You retype an instruction you have given the agent before.
Your rules file is long enough that you scroll to read it.
CLAUDE.md and AGENTS.md both exist and disagree.

The usual objection: That more rules produce better behaviour. Past roughly a page, the file is skimmed rather than followed, and the rule you most needed is the one that got averaged away.

Treat the file as the repository’s working agreement for non-human contributors. It is not a second README, a design archive, or a policy manual. It is the place for the handful of commands, conventions, boundaries, and review expectations that repeatedly affect generated changes.

The mechanism is simple: agents begin with limited local knowledge and rely heavily on the context that is loaded for the task. A small rules file gives the model a stable prior before it edits code, so recurring decisions do not have to be rediscovered through prompt-by-prompt correction. Keeping it close to the root and short also makes it more likely to be loaded, noticed, and applied.

The misconception is “more rules produce better behaviour.” Long instruction files create their own failure mode: important constraints compete with trivia, stale guidance survives because nobody wants to maintain the document, and the model averages across too much text instead of following the rule that mattered.

When an agent is writing the code, undocumented team knowledge stops being merely inconvenient and becomes invisible. The agent does not remember the last pairing session, the Slack thread, or the reviewer’s preference unless that knowledge has been turned into durable repository context.

Install it

npx klay practices add agent-rules-file

AGENTS.mdappend-block

## Ground rules

- Keep this file short. If it does not fit on one screen, it is not being read.
- Prefer the patterns already in this repo over patterns from elsewhere.
- Do not add a dependency without saying why in the pull request.
- Do not change files outside the scope you were given. Say what you skipped.
- When something here is wrong or out of date, say so instead of working around it.

The previews are the first lines of each file; the command writes them in full. Existing files are never overwritten.

How you know it stuck

npx klay practices audit reports these checks for this practice:

agent-rules-present
agent-rules-scoped

Where this comes from

AGENTS.mdAGENTS.md · Official docsDefines the cross-agent convention and expected repository placement.
Adding repository custom instructions for GitHub Copilot - GitHub DocsGitHub Docs · Official docsShows a major vendor auto-including repo instructions and constraining their size.
Effective context engineering for AI agentsAnthropic Engineering · Official docsExplains why minimal, high-signal context beats exhaustive hardcoded instruction lists.
How to write a great agents.md: Lessons from over 2,500 repositoriesGitHub Engineering · Engineering blogAdds empirical evidence about the few sections that tend to matter.

Questions

AGENTS.md or CLAUDE.md?: Write one and mirror it. AGENTS.md is the cross-tool convention; several tools read CLAUDE.md specifically. Two files with the same content cost nothing; two files with different content is the failure mode.
How long should it be?: Short enough to read in a minute. If it is longer, you are describing your codebase rather than constraining behaviour — that belongs in the code.