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.
Lesson deliverable
What you will build
Practical evidence for "Teach the repository with AGENTS.md" applied to a real or training repository.
Why it matters
The goal is to turn the lesson into a verifiable action, not just reading.
Starter repository or files
A small Git repository with Git, README, and one known validation command.
Steps
- 1. Inspect Git status before starting.
- 2. Ask Codex to work with limited scope.
- 3. Run the verification command.
- 4. Review the diff or produced evidence.
- 5. Record what is verified and what remains open.
Copy-ready Codex request
Apply the lesson "Teach the repository with AGENTS.md" in this repository. Work in small changes, cite concrete files, run one verification, and finish with evidence and risks.
Expected result
A reviewable output: map, plan, diff, test, or report depending on the lesson.
Verification command
git status --short && git diff --stat
Manual check
Check that the result matches the requested scope and Codex did not touch unrelated files.
Mini exercise
Repeat the practice in another folder of the same repository, changing only one constraint.
Show solution
Keep the same goal, add one explicit constraint, and compare whether the final evidence improves.
Evidence to save
Save the prompt, commands run, relevant output, and git diff --stat.