A useful instruction file prevents mistakes. An oversized instruction file can also repeat information or mix procedures from unrelated areas. The goal is to improve the instruction set without removing the rules that make the result correct.
First, check which instructions Codex loads
OpenAI documents a global instruction layer and project instructions along the path to the working directory.
An AGENTS.override.md file can take precedence over AGENTS.md at the same level.
See the official discovery rules.
Before an audit, record the launch directory and applicable files. Do not assume a file is active merely because it exists somewhere in the repository.
For example:
repository/
AGENTS.md
services/
payments/
AGENTS.mdLaunching from services/payments gives discovery a different path from launching at the repository root.
Verify the active instructions after changing the layout.
Moving a required rule into an undiscovered file can make the instruction set smaller and less useful.
Bytes, tokens, and cost are different measurements
Use file size to identify unusually large instruction files. Use the relevant tokenizer or request telemetry to measure tokens. Use the provider’s accounting to measure cost.
OpenAI’s project_doc_max_bytes setting controls a byte limit, not a token budget.
Do not convert that limit directly into a token count.
Repeated input can also receive different treatment under prompt caching. OpenAI explains matching prefix reuse in its prompt caching guide. An instruction reduction therefore does not imply an identical percentage reduction in money spent.
Keep, shorten, move, or remove
| Instruction type | Recommended action | Reason |
|---|---|---|
| Required test commands | Keep | The agent needs a completion check |
| Constraints on existing work | Keep | The agent must preserve unrelated changes |
| Security and data rules | Keep | Token reduction does not justify weaker controls |
| Repeated explanation | Shorten | One precise rule can replace several restatements |
| Specialist procedure | Scope carefully | Only relevant tasks need the full procedure |
| Obsolete command | Correct or remove | A short incorrect rule still wastes work |
| Historical discussion | Move to documentation | Most tasks need the decision, not its full history |
Example: shorten a rule without changing its meaning
This example shows an editorial reduction, not measured token savings.
Before:
Please remember that when you make a change to authentication,
you should always make sure that you run the session tests.
The session tests are important because authentication changes
can affect session expiry and refresh behavior.After:
After authentication changes, run the session tests.
Check session expiry and refresh behavior.The shorter version keeps the trigger and required behavior. In a real repository, include the exact test command if the agent cannot reliably discover it.
Give each rule one job
A compact root file can identify the package manager, main checks, and shared constraints. Specialist files can describe local procedures when the agent’s workflow loads them. Reference longer documentation when the task needs its detail.
Do not hide critical requirements behind vague instructions such as “follow the documentation.” Name the relevant file and the condition that requires reading it. The agent still needs enough information to choose the correct procedure.
Verify the shorter file
- Save the original instruction set and repository revision.
- Select tasks that exercise its important rules.
- Record the loaded instruction files for each launch directory.
- Run the baseline with fixed model and tool settings.
- Repeat with the shortened instructions in an equivalent checkout.
- Compare total usage and required behavior.
Include tests, preserved files, and task acceptance in the comparison. Count repeated investigation and repair work. A file reduction that causes missed requirements fails the audit, even if its initial context is smaller.
Halv supports this workflow with code navigation, command filtering, and context compression. Download Halv and evaluate a task with your existing project rules.
What to report in a measured result
Report the instruction diff, active discovery paths, model, client version, and tokenizer when known. Separate instruction tokens from complete task tokens. Include cached usage, attempts, and test outcomes.
Do not claim that a shorter AGENTS.md explains every difference between two stochastic runs.
Repeat tasks and preserve evidence before attributing an improvement to the edit.
For related context decisions, read Codex compact versus new. For tool instructions, read MCP context usage.
Sources and scope
Official documentation checked on September 28, 2026. The example demonstrates writing technique. It does not establish measured token or cost savings.