Write the repo rules down once

What the move is

Put the build command, the test command, the untouchable files and the definition of a complete change in a file at the repository root. Agents read it. So do new humans.

Why it works

This is what maintainers absorbing agent-written pull requests at scale actually did: repo-specific instruction files, pull request templates that auto-close when unmet, mandatory test plans, and coverage gates.

Step by step

1. Create AGENTS.md (and/or CLAUDE.md) at the repository root.
2. State the build command and the test command exactly, as commands, not prose.
3. List the files and directories that must not be modified, and why.
4. State what a change must include: tests, a scope, a size limit.
5. Make CI enforce the parts that can be enforced, so the file is a description of the gate rather than a request.

Paste this

Read this repository and draft AGENTS.md for its root. Four things only: the build and test commands exactly as they are run, the files that must not be modified, what a change must include before it is finished, and one paragraph on the layout. If a command is not written down anywhere, say so instead of inferring one.

Make it yours

Add a short 'how this project is laid out' section. It is the single highest-value paragraph for both an agent and a new contributor.

Variations

• Add per-directory rules files where a subsystem has its own conventions.
• Keep a short 'things that look wrong but are deliberate' list to stop well-meant refactors.

Works with

• Teach the model a procedure once and reuse it
• Work through an entire repository, not a pasted file