Write scoped instructions for Codex.
Create a concise AGENTS.md and reason about directory scope with a fictional project.
Read the descriptive transcript
Follow the complete narration and the changes shown in the video. Each example can be copied.
1. A project instruction file, not executable code.
An agents dot M D file gives Codex project guidance. Use the exact uppercase filename shown here. This example teaches the file contents; no agent is executing these instructions in the video.
Source shown
# Garden project
## Scope
Work on the project.
## Checks
Run tests.
## Boundaries
Ask before publishing.On screen
The cursor highlights the relevant source or result while the narration explains it.
2. 01 / Replace a vague scope
Work on the project is too broad. Replace it with Edit documentation only. The instruction now names what the task includes.
Source shown
# Garden project
## Scope
Edit documentation only.
## Checks
Run tests.
## Boundaries
Ask before publishing.On screen
State the permitted scope in concrete terms.
3. 02 / Name the actual check
Run tests leaves the command unclear. In this fictional project, the check is N P M test. Type the command and ask for failures to be reported. Use your own repository command in a real file.
Source shown
# Garden project
## Scope
Edit documentation only.
## Checks
Run npm test; report failures.
## Boundaries
Ask before publishing.On screen
The source is edited character by character and its parsed result updates.
4. 03 / Add an honesty requirement
Keep the publishing boundary and add Do not invent results. A written instruction is useful guidance. It does not replace tool permissions or enforce a security boundary.
Source shown
# Garden project
## Scope
Edit documentation only.
## Checks
Run npm test; report failures.
## Boundaries
Ask before publishing. Never invent results.On screen
The source is edited character by character and its parsed result updates.
5. Check which instructions apply.
Codex discovers instructions along the path from the project root to the working directory. A more specific directory can add guidance. Read the linked OpenAI documentation before using overrides.
Source shown
# Garden project
## Scope
Edit documentation only.
## Checks
Run npm test; report failures.
## Boundaries
Ask before publishing. Never invent results.On screen
Directory scope matters. Follow the host documentation.
6. Test the file in the actual host.
Use a disposable project. Ask Codex to summarize its loaded guidance, then give it a small documentation task. Check the real file changes and test output. A confident summary alone is not proof.
Source shown
# Garden project
## Scope
Edit documentation only.
## Checks
Run npm test; report failures.
## Boundaries
Ask before publishing. Never invent results.On screen
The cursor highlights the relevant source or result while the narration explains it.
7. Your turn / Define scope, checks and boundaries
Complete the three sections in the exercise. The checker recognizes the requested structure. You still need to judge whether the instructions are useful and test them in Codex.
Source shown
# Garden project
## Scope
Edit documentation only.
## Checks
Run npm test; report failures.
## Boundaries
Ask before publishing. Never invent results.On screen
The cursor highlights the relevant source or result while the narration explains it.
Project guidance has a particular filename
Codex reads AGENTS.md as project instructions. The uppercase plural name matters; an arbitrary agent.md is not automatically the same convention. Codex builds a chain of applicable instruction files from broader scope toward the working directory. Within a directory, AGENTS.override.md takes precedence over AGENTS.md. OpenAI’s AGENTS.md guide.
These files supply context. They do not change model weights, prove facts or replace the host’s actual permission controls.
Start with a small, observable contract
This is an original example for a fictional project whose package script really is npm test. Replace it with the command your project actually supports:
# Garden project
## Scope
Edit documentation only.
## Checks
Run npm test and report failures.
## Boundaries
Ask before publishing. Do not invent results.“Use good practices” is difficult to evaluate. “Report the command and its result” gives a reviewer evidence to inspect. Keep project facts separate from a one-off user request, and remove stale commands when the project changes.
Reason about a directory tree
garden-project/
AGENTS.md
docs/
AGENTS.md
planting.mdFor work launched in docs/, identify both instruction files on the route from the root. A useful docs/AGENTS.md could add “Preserve existing source links.” Do not assume the same discovery model applies to Claude Code or Gemini CLI; their lessons document their own mechanisms. Codex discovery and verification.
Test the instruction, not just its headings
In a disposable project, ask Codex to identify the instruction sources it loaded and propose a documentation-only change. Inspect whether its proposed scope matches the files you intended. Give it a small change, then compare the reported test command with the actual terminal result. A model saying “all tests passed” is not itself evidence.
Try a second request that would require publishing. The example says to ask first. Record what happened; writing the boundary is not proof that it was enforced. Use actual permissions to control tools and external effects.
Your exercise
Write the three sections below using the supplied fictional facts. The browser checks headings, nonempty sections and the named test command. It does not launch Codex or certify that your instructions will be followed. After it passes, explain which rule belongs at the root and which belongs only under docs/.
Sources checked 17 September 2026. Host behavior can change; verify it against the linked documentation when using these examples.
YOUR TURN
Make the idea your own.
Write a project title and populated Scope, Checks and Boundaries sections. Name the supplied test command and keep publication outside this task.
Readable result
Garden project
Scope
Document the garden guide.
Compare with one possible answer
# Garden project
## Scope
Edit documentation only.
## Checks
Run npm test and report failures.
## Boundaries
Ask before publishing. Do not invent results.This is one approach. Your writing can differ while meeting the same structural goal.
TAKE IT WITH YOU
Use the exact filename, inspect scope and test behavior on a small task.
Read the editor guide →Progress is stored in this browser. Your practice text is not saved.