A small code change can lead to a lot of extra work when a project has broad instructions. You ask Codex to fix a button label, but AGENTS.md tells it to read the database guide, study the deployment process, and run every check three times.
Those steps may follow the file exactly. They may also have little to do with the requested change.
OpenAI’s guide to skills and prompts for GPT-6 Astra suggests reviewing instructions written for earlier models. In this article, I will focus on one part of that work: finding rules in AGENTS.md that are unclear, too broad, or no longer useful.
The examples below describe a sample project. They are a way to review your own rules, not measured results from a performance test.
What belongs in AGENTS.md
AGENTS.md gives Codex standing instructions for a project. It is a useful place for facts that matter across many tasks:
Where source files live.
Which files are generated.
Which commands check the project.
Which documents explain important parts of the system.
Which actions need approval.
A filename for today’s report or the wording of a new button usually belongs in the current task prompt.
Skills serve another purpose. A SKILL.md file describes a reusable job, such as preparing an invoice or reviewing a migration. The task prompt, project instructions, and selected skills can all affect the same run. A review should consider how they fit together.
Start with the instructions Codex actually reads
Before editing a rule, check its source.
OpenAI’s AGENTS.md documentation explains how Codex combines global and project instructions. It looks for guidance along the path from the project root to the current working directory. More local guidance can override earlier guidance. An AGENTS.override.md file can take priority over AGENTS.md in the same directory.
This means the file at the repository root may not be the only source of a repeated pause or an extra check.
Ask Codex:
List the instruction files that apply to this task. For each file, give its path and the rules that affect reading documents, running checks, and asking for approval. Report conflicts or missing files. Do not change anything yet.
In the CLI, start a fresh session after changing project instructions. Then check which sources were loaded. This helps avoid testing an edit against an older set of instructions.
Find rules that apply too widely
Suppose a project has this rule:
Before every edit, read: - docs/ui.md - docs/database.md - docs/deployment.md - docs/architecture.md
The documents may all be useful. The phrase “before every edit” is the part to examine.
A database change needs the database guide. A deployment needs the deployment guide. A spelling correction may need neither.
A more focused version is:
## Project documents - Read docs/ui.md for interface changes. - Read docs/database.md for schema or data-storage changes. - Read docs/deployment.md when preparing a deployment. - Read docs/architecture.md when changing service boundaries. Read every guide that applies when a task crosses these areas. Keep the relevant documents current when behavior changes.
Use paths that exist in your project. If a document contains rules that apply to every task, keep that requirement. You could also move its short, general rules into AGENTS.md and leave the detailed workflow in the document.
The aim is to make the scope clear. Deleting a required guide because it is long does not solve that problem.
Separate required checks from repeated checks
Another rule worth reviewing is:
Run the full test suite three times after every edit.
Repeated runs can help investigate a test that sometimes fails. They can also be part of a release process. But the rule above does not explain why every edit needs three runs.
Start with the checks your project requires. Then describe what should happen when something fails:
## Verification Run the checks required for the affected part of the project. Keep the full release checks when preparing a release. Fix failures caused by the requested change and rerun the affected checks. Report unrelated failures separately. Repeat or broaden checks when a new change, a failure, or an unresolved concern gives you a reason to do so.
If the team requires a full build for a source change, keep it. Removing duplicate work should not remove an agreed requirement.
Also name the evidence you need. A successful build shows that the app can build. It does not prove that clearing a search field restores the full list. That behavior needs its own check.
Explain what the agent may finish on its own
“Ask before making changes” can mean several things. Does it cover a local source edit, a test run, a database update, or a production deployment?
Name the actions:
You may edit files in this project and fix problems caused by the requested change. Run local checks that use the project's confirmed disposable test data. Ask before changing production data or deploying.
Only describe test data as disposable after checking that this is true. A command run on your laptop may still connect to a shared service.
These instructions explain your intent. They do not change Codex’s technical permissions. The sandbox still controls which files and network resources commands can access.
Give the task a clear stopping point
An instruction file can also cause Codex to stop earlier than you expect. For example, “return the first version for review” may conflict with a request to implement and check the whole change.
For a small bug fix, a task prompt could say:
Fix the search filter so clearing the input restores all items. Keep the current layout. Complete the edit and the required project checks. Verify searching, no results, and clearing the input in a local preview if browser access is available. Fix problems caused by this change. Finish with the result, the checks performed, and any verification you could not complete.
If you do want a plan or a draft before implementation, say so. The stopping point should match the decision you need to make.
Ask for proposed edits, not a shorter file
An instruction review needs a clear purpose. “Make this file shorter” may remove a rule that protects a real requirement.
Try this prompt:
Review the applicable AGENTS.md files using this guide: https://developers.openai.com/blog/rethinking-skills-and-prompts-for-gpt-6-astra Look for broad reading rules, unclear approval boundaries, repeated checks, stale paths, and conflicting stopping rules. For each useful change, show: - The file and current wording. - A task where the wording could cause a problem. - A proposed replacement. - The requirement that the replacement keeps. - A task we can use to check the new rule. Keep required checks and approval boundaries. Flag unclear requirements for review. Do not edit files yet.
The result should help you make a small decision. “Read the deployment guide only for deployment work” is specific enough to review. “There is too much context” needs more explanation.
Check the change with familiar tasks
Save the old file, approve one edit, and try tasks whose expected results you understand.
For example, use a text correction, a small interface fix, and a data-storage change. Check whether Codex reads the right documents and still runs the required checks for each one.
Keep the model and task inputs the same when comparing versions. Review the output and the visible work, including file reads, checks, and approval requests. One successful run gives limited evidence, so try more than one kind of task before changing shared guidance.
If teammates use other models, include those models in the review. OpenAI notes that instructions useful for Sol or Luna may constrain Astra differently.
Start with a rule that has caused a clear problem. Keep the edit if it improves that task while preserving the project’s requirements.
Video and sources
I cover this topic alongside prompts and skills in my seven-tip video tutorial. The full guide on my website includes more examples and an instruction-audit prompt.
