Day 08 of 21
The AGENTS.md file - give Codex permanent project rules
Goal: Every Codex session starts fresh with no memory of your project. Today you create one file that fixes this — AGENTS.md. It sits in your project folder and tells Codex exactly how to behave before it touches a single file. You will create it, paste a starter template, and confirm Codex actually reads it.
What to do
Understand what AGENTS.md does
AGENTS.md is a plain text file you put in your project folder. Every time Codex opens in that folder, it reads AGENTS.md first and follows the rules inside it — automatically, without you needing to repeat yourself. Think of it as a permanent sticky note on your project that says "here is how I want you to work."
Find your project root folder
The project root is the main folder that contains all your project files. AGENTS.md must go in this exact location — not in a subfolder. Open your project in File Explorer (Windows) or Finder (Mac) and confirm you are looking at the top-level folder of your project. You should see files like index.html, package.json, or your main project files directly inside.
Create the AGENTS.md file
The .md extension stands for "Markdown" — it is just a plain text file with a special name. You do not need to know what Markdown is. Think of it as a normal text file that Codex knows how to read. Open Notepad (Windows) or TextEdit (Mac — go to Format > Make Plain Text first). Create a new empty file. Before typing anything, save it into your project root folder and name it exactly: AGENTS.md — capital letters, no spaces, .md extension. The most common mistake here is saving it as AGENTS.md.txt instead of AGENTS.md. See the help below if that happens.
Paste the starter template into AGENTS.md
Open AGENTS.md in your text editor. Select all the text in the code block below and paste it into the file. Replace [YOUR PROJECT NAME] with your actual project name. Save the file when done.
# AGENTS.md — Project Rules for Codex
## About this project
Project: [YOUR PROJECT NAME]
Owner: Non-technical founder. I am not a developer.
## How to communicate with me
- Explain everything in plain English. No jargon.
- If you need to use a technical term, explain it in one sentence.
- Always tell me what you are about to do before you do it.
## Before touching any file
- Write a plan first. List every file you will change and what you will do to each one.
- Wait for me to say "go ahead" before making any edits.
- If the task is risky or unclear, ask me a question instead of guessing.
## What not to change
- Do not change files I did not mention.
- Do not change design tokens, color values, or font settings unless I specifically ask.
- Do not remove or rename reusable components without asking first.
- Do not change routing or navigation structure without asking first.
## After you finish
- Show me a diff of every file you changed.
- Tell me in plain English what changed and what I should check in the browser.
- If anything could break, warn me before I approve.Test whether Codex reads the file
Open a terminal in your project folder and start Codex. Then ask it to confirm it read your AGENTS.md rules. Do not ask it to do any work yet — just confirm it loaded the file.
Read my AGENTS.md file and confirm you loaded it. Tell me: what is my project name, what must you do before touching any file, and what must you never change without asking?Confirm the file in your project browser
Open your project folder in File Explorer (Windows) or Finder (Mac). Look for AGENTS.md in the top-level folder. Then open it in your text editor to confirm all the rules are still there. This is your final check before the lesson is complete.
Expected result
AGENTS.md exists in your project root. It contains your project name and six sections of rules. Codex can accurately repeat those rules back to you from a fresh session without you saying anything.
Key takeaway
- AGENTS.md is your permanent sticky note on every Codex session. Write your rules once — Codex reads them every time it opens in your project. Never start a Codex session without one.