Write the page the agent reads first.
A coding agent is a new hire on day one, every day — and it does not ask in Slack. Whatever it cannot find in the repository, it guesses. Nine questions here become an AGENTS.md: one page, links to files, no novels.
9 questions · 5 minutes · Nothing stored
“Link to files instead of describing them. The agent would rather read the Makefile than a paragraph about the Makefile.”
The repository
Write for someone who has never seen the repository. That is exactly what the agent is.
Commands
Exactly as typed in the terminal. Empty fields are left out of the file.
The checks
If CI is the only place the truth lives, the agent will learn by pushing.
The road to production
Branches, environments, who presses the button. The agent should know what a merge actually does.
What “everyone knows”
One line per item. This is the section that replaces the Slack question.
Path, dash, why. One per line. Link rather than explain.
The things that make a senior sigh in code review. One per line.
Decisions a human should make. One per line.
What the agent may do without asking
Anything not allowed lands automatically under “Ask before you”.
Your file
# AGENTS.md
Read this before touching anything. Everything below is the short version — the files linked are the source of truth.
## Before you push
Run the same checks CI runs before you push. If they fail locally they will fail in CI.
## Branches and commits
Trunk-based: small changes straight to the main branch, never long-lived branches.
## Ask before you
- Add a dependency.
- Change the CI configuration.
## Allowed without asking
- Run tests and lint.
## When something is unclear
Stop and ask instead of guessing. Say which file you read and what you could not find.
<!-- Generated with paperphyte.com/agents-md-generatorn — keep it short, keep it true. -->
≈ 27 lines — that fits on one page.
Next step
Put the file in the repository root and commit it. Then ask an agent to do something small for real — and note every guess it still makes. Every guess is a missing line. Why the file matters is in Your next platform user is an agent (in Swedish), and the AI readiness check measures whether the codebase holds up to what the agent now knows how to do. If you want help building the whole path, Developer Experience is the engagement.
Generated locally in your browser — nothing is sent anywhere.