Day 09 of 21
What to put in AGENTS.md so Codex follows your rules every session
Goal: Learn the six essential sections of a strong AGENTS.md, study a complete working example, customise at least one rule for your project, and confirm Codex reads it accurately.
What to do
Understand the six sections every AGENTS.md needs
An AGENTS.md that says only "be careful" is not useful — Codex cannot act on vague instructions. A good AGENTS.md has six sections, each protecting a different part of your workflow. The six sections are: About the project (who you are and what you are building), How to communicate (plain English rules), Before touching any file (plan-first rules), What not to change (safety guardrails), After you finish (reporting rules), and Reusable skills (added in Day 15, optional now). Every rule should be a specific instruction Codex can follow — not a general principle.
Study the complete example AGENTS.md and compare it to yours
Read this complete example before editing your own file. Notice that every rule is a short, specific instruction — not a general wish. After reading, open your own AGENTS.md and check each section: does it exist, Is each rule specific enough to act on, or is it still a vague placeholder?
# AGENTS.md — Project Rules for Codex
## About this project
Project: My Restaurant Website
Owner: Non-technical founder — I am not a developer. Treat me as a non-developer at all times.
Stack: HTML, CSS, basic JavaScript. No frameworks. (Stack means the tools your project uses — for most learners this is simply "HTML and CSS".)
Current goal: Add a simple contact section to the homepage.
## How to communicate with me
- Use plain English. Define any term you use that a non-developer might not know.
- Tell me what you are about to do before you do it, in one sentence.
- If you are unsure about anything, ask me a question instead of guessing.
- Keep summaries short — three to five bullet points maximum.
## Before touching any file
- Write a numbered plan listing every file you will change and what you will do.
- Wait for me to say "go ahead" before making any edits.
- If the task will change more than two files, ask if I want to split it into phases.
- Never install new packages or dependencies without telling me what they are first.
## What not to change
- Do not change any font, color, or spacing unless I specifically ask.
- Do not touch the navigation menu or footer.
- Do not change any file that is not in the approved plan.
- Do not delete any content without asking first — even if it looks like a duplicate.
- Do not touch src/styles/globals.css — this file controls the whole site look and feel.
## After you finish
- Show me a diff of every file that changed.
- Summarise what changed in three bullet points or fewer, in plain English.
- Flag anything I should check manually in the browser.
- Tell me if anything you changed could affect the live site.
## Emergency rules
- If you encounter an error you cannot explain, stop and tell me. Do not try a fix.
- If a fix requires changing a file not in the plan, stop and ask first.Add a current-goal line and one specific do-not-touch rule
Two changes make the biggest immediate difference to every Codex session. First: add a "Current goal" line at the top of the About section — one sentence describing what you are building right now. Second: add one specific do-not-touch rule that names an actual file or feature in your project. Use the examples below as a guide. Generic rules like "do not break things" are useless. Specific rules like "do not touch src/styles/globals.css" are followed.
Add this to your About section:
Current goal: [YOUR CURRENT GOAL IN ONE SENTENCE]
Add this to your What not to change section
(replace with your real file or feature):
Do not touch [YOUR FILE OR FEATURE] — [ONE SENTENCE EXPLAINING WHY].
Examples of specific do-not-touch rules:
Do not touch src/styles/globals.css — this file controls the whole site look.
Do not change the navigation menu in Nav.js — it took a long time to get right.
Do not edit anything inside the /admin folder — that is backend logic I do not want changed.
Do not modify the checkout flow in checkout.js — it handles real payments.Add an emergency-rules section
The most important moments in any Codex session are the moments when something goes wrong. An emergency-rules section tells Codex exactly what to do when it hits an error or an unexpected situation — instead of guessing. Add this section at the bottom of your AGENTS.md. You can customise the rules to match your project, but keep the first two rules exactly as written.
## Emergency rules
- If you encounter an error you cannot explain in plain English, stop and tell me the error. Do not try a fix.
- If completing a task would require changing a file that is not in the approved plan, stop and ask me first.
- If you are about to delete any content — even a comment or a blank line — ask before doing it.
- If the task starts involving more than three files, stop and ask if I want to split it into phases.Ask Codex to read the file and answer four questions from it
Start a new Codex session in your project folder. Do not give it any task yet. Ask it to read your AGENTS.md and prove it understood the key rules by answering four specific questions. If Codex cannot answer accurately, you know exactly which section needs to be rewritten more specifically.
Read my AGENTS.md file. Then answer these four questions using only what is in that file:
1. What is my project about and what is the current goal?
2. What must you do before touching any file?
3. Name one specific file or feature you must never change without asking.
4. What must you do if you encounter an error you cannot explain?
Do not start any work. This is a reading-and-recall test only.Expected result
Your AGENTS.md has all six sections, a current-goal line, at least one project-specific do-not-touch rule naming a real file or feature, an emergency-rules section, and has been successfully read and recalled accurately by Codex from a fresh session.
Key takeaway
- Generic rules are ignored. Specific rules are followed. Every rule in AGENTS.md should be something you can check — either Codex did it or it did not. If you cannot check whether a rule was followed, the rule is too vague. Rewrite it until you can.