AGENTS.md and project context: teach Codex how this project works
Write useful Codex project instructions, keep context focused and create handoffs that let a long project continue without starting over.
Keep the facts the next conversation will need.
You should not have to explain the same project conventions at the beginning of every task. A concise instruction file and a current handoff can preserve the things that repeatedly matter while keeping each new request focused.
Separate durable rules from today’s task
An instruction file is for recurring expectations: how to run the project, where important code lives, which generated files should not be edited directly, and which behaviors must stay true. Today’s bug reproduction belongs in the task. A temporary hypothesis belongs in a work note. Mixing all three creates instructions that become stale quickly.
OpenAI documents AGENTS.md as a source of Codex project guidance, with global and project scopes and more specific instructions along the working path. Check the official discovery rules when you use nested folders. Keep the file short enough that a future collaborator can understand its priorities.
Write rules with a reason and an observable result
“Write good code” adds little. “Reports must retain the original source filename so a reviewer can trace a number” explains a property that can be checked. “Preserve unrelated working-tree changes” makes the collaboration boundary clear. Use exact launch or test commands only after checking they exist.
The template below is a starting document to adapt to your repository. Replace its placeholders. Ask the agent to inspect the project before filling in commands; otherwise an authoritative-looking README can contain a test command the project has never supported.
A request you can adapt
Project working agreements
Purpose: [what this project does and for whom]. Start here: [current README and key entry point]. Run locally: [verified command]. Validate changes: [verified relevant checks]. Preserve: [important behavior and unrelated work]. Data: keep source provenance and mark unavailable inputs explicitly. Generated files: [which source or generator to edit instead]. Finish: explain the changed behavior, checks run and remaining limitations. Publishing: prepare a reviewable result; publish only when requested.
Give it the context that changes the answer
A complete repository can contain far more material than any task needs. Point to the relevant module, a known example, the failing behavior and any contract it must preserve. Ask Codex to inspect those first, then follow dependencies as needed. Uploading or attaching more material is useful when it changes the answer, not simply because more is available.
For a design task, context may be a screenshot, a style guide and two pages you want to feel consistent. For a data task, it may be a schema and three representative records. Tell the agent which source is authoritative when an old note disagrees with current code.
Write a handoff that makes restarting cheap
At a natural stopping point, capture what works, what changed, what remains and how to verify the state. Include the working location and launch instructions. Keep unresolved questions separate from decisions. A handoff is most useful when the next session can test its claims quickly.
Review the document after major changes. A stale instruction can be worse than an absent one because it gives a future agent confidence in the wrong plan. Ask for updates to the affected sections instead of repeatedly appending new exceptions at the bottom.
A request you can adapt
Write a concise project handoff with the current working state, files that matter, decisions and their reasons, verified launch/check commands, known limitations and the next concrete task. Mark uncertain information. Make it useful to a new collaborator who has not seen this chat.
Take this into your next task
Keep durable expectations in project instructions and changing state in a current handoff. Both should contain facts another session can verify.
Questions people ask
Is AGENTS.md a security boundary?
No. It is guidance for the agent. Enforced file, network and tool permissions belong to the environment. Use both appropriate access controls and clear project instructions.
Sources and editorial notes
Reviewed September 6, 2026. Product capabilities depend on the app, plan, region and workspace settings. Workflows and prompts are authored teaching material, not recorded model results or measured time-saving claims.
Keep going
- Getting Started with Codex: Your First Project
- Codex Skills and Repeatable Workflows
- Continue the guide
Related Power of AI pages
Keep reading with Start here, everyday uses, the tool guide, the writing workshop, and sources and standards.