AGENTS.md — Project Rules
The per-project rules file the agent reads on every turn — what belongs in it, and why you write it rather than the agent.
What is AGENTS.md?
`AGENTS.md` is a plain markdown file at the root of your project's sources. It holds the rules the agent must follow in this project: your design system, naming and code style, architecture decisions, domain vocabulary.
The agent reads it at the start of every chat turn and places it in its instructions under a heading that marks it authoritative for the project. A fresh conversation therefore starts knowing your conventions instead of inferring them from the code each time.
You own the file
AGENTS.md is yours to write. The agent will not create it for you and will not offer to — it reads the file, it does not maintain it.
Because it is a normal file in the repository, a change to your rules is a change to the code: it shows up in a diff, goes through the same review as everything else, and is versioned with the release it belongs to. Months later the history still shows which rules were in force when a feature was built.
What goes in
- Design tokens and the visual system — palette, typography, radii, spacing
- Naming and code style conventions
- Architecture decisions, and the reason behind them
- Domain vocabulary — what a "session" or a "tenant" means in this product
- External systems the project depends on
What stays out
- Secrets and API keys — use environment variables
- Anything that changes every week; rules are for what stays true
- Long explanations. The file is read on every turn, so keep it tight
Rules for a whole organisation
`AGENTS.md` covers one project. On the Platform Builder plan an organisation can set rules once for **all** of its projects — stored on the organisation, not in any repository, so no project can quietly opt out of them. See Shared Context & Standards.