What belongs in it
AGENTS.md stores stable repository conventions: architecture, commands, style, boundaries, and verification. Do not turn it into an encyclopedia or store secrets in it.
# AGENTS.md ## Architecture - app/ contains routes; lib/ contains shared data. ## Commands - npm run lint - npm test - npm run build ## Conventions - Follow existing components. - Do not add dependencies without justification. ## Verification - Check mobile and desktop for UI changes.
Folder hierarchy
Instructions closest to a file take precedence. A root AGENTS.md defines general rules, while one inside a module can refine commands or conventions for that scope.
Create and audit it
The /init command can create a starting point. Review it like code: remove vague statements, verify commands, and keep the document concise.
/init Read every applicable AGENTS.md and summarize the rules that govern this task before editing.
Quality signal
A new teammate should be able to run the project and validate a change from this file. If a rule applies to one task only, keep it in the prompt instead of making it permanent.