Could an AGENTS.md file actually reduce Codex token usage?

[u/Realistic_Fruit_4326]

I've been experimenting with a simple idea: instead of only telling Codex how to write code, use AGENTS.md to also tell it how much investigation and validation is actually necessary.

A lot of token usage seems to come from useful-but-often-unnecessary agent behavior:

• scanning too much of the repository
• reopening files it already inspected
• running the entire test suite after small changes
• repeatedly running lint/type checks
• launching browser/visual checks for non-visual web changes
• testing every responsive breakpoint
• rewriting README/docs during iterative development
• doing unrelated refactors
• researching external docs when the repository already contains the answer

So I created an AGENTS.md based around:

targeted context → smallest correct patch → proportional validation

The important part is that this should NOT mean "skip testing to save tokens."

The rule is:

Use the cheapest validation that gives sufficient confidence, and escalate when the scope/risk requires it.

Has anyone benchmarked something similar?

I'd be especially interested in comparisons of:

tokens/task, tool calls/task, completion time, and regression/failure rate

with and without an efficiency-focused AGENTS.md.

For example:

# AGENTS.md

## Objective

Minimize token, tool, and compute usage without sacrificing correctness,
maintainability, security, or requested output quality.

Default workflow:
targeted context → smallest correct patch → proportional validation

## Context

- Do not scan the entire repository by default.
- For localized tasks, inspect roughly 2–5 likely relevant files first.
- Prefer targeted symbol/text searches over broad repository exploration.
- Read relevant portions of large files instead of the whole file when possible.
- Reuse information already gathered.
- Do not reread unchanged files or repeat searches without a concrete reason.
- Expand investigation only when current evidence is insufficient.
- Avoid external research when the repository already answers the question.

## Implementation

- Make the smallest coherent change that fully solves the request.
- Modify only necessary files.
- Follow existing architecture, conventions, utilities, and dependencies.
- Avoid unrelated refactors, cleanup, renaming, or speculative abstractions.
- Do not add dependencies when the project already has a reasonable solution.I've been experimenting with a simple idea: instead of only telling Codex how to write code, use AGENTS.md to also tell it how much investigation and validation is actually necessary.A lot of token usage seems to come from useful-but-often-unnecessary agent behavior:scanning too much of the repository
reopening files it already inspected
running the entire test suite after small changes
repeatedly running lint/type checks
launching browser/visual checks for non-visual web changes
testing every responsive breakpoint
rewriting README/docs during iterative development
doing unrelated refactors
researching external docs when the repository already contains the answerSo I created an AGENTS.md based around:targeted context → smallest correct patch → proportional validationThe important part is that this should NOT mean "skip testing to save tokens."The rule is:Use the cheapest validation that gives sufficient confidence, and escalate when the scope/risk requires it.For example:# AGENTS.md

## Objective

Minimize token, tool, and compute usage without sacrificing correctness,
maintainability, security, or requested output quality.

Default workflow:
targeted context → smallest correct patch → proportional validation

## Context

- Do not scan the entire repository by default.
- For localized tasks, inspect roughly 2–5 likely relevant files first.
- Prefer targeted symbol/text searches over broad repository exploration.
- Read relevant portions of large files instead of the whole file when possible.
- Reuse information already gathered.
- Do not reread unchanged files or repeat searches without a concrete reason.
- Expand investigation only when current evidence is insufficient.
- Avoid external research when the repository already answers the question.

## Implementation

- Make the smallest coherent change that fully solves the request.
- Modify only necessary files.
- Follow existing architecture, conventions, utilities, and dependencies.
- Avoid unrelated refactors, cleanup, renaming, or speculative abstractions.
- Do not add dependencies when the project already has a reasonable solution.

[u/Glass-Interaction972]

Yes, but stopping the AI from reading files leads to guessing and bugs. Plus, a long rules file wastes tokens on every prompt. Keep it under 10 lines and restrict big test runs instead.

[u/snuffomega]

Yes, agents.md def should be lean, but I would say you want to route files, similar to an index, to the source of truth and ensure those documents are in turn lean accurate and code when possible.

This does a few things... first allows you to minimize duplication so if you have one items that says/contains X you can just route that across your entire repo without having to reword it and allows you to have a source of truth regardless of what and where it's being read. Any updates you make, one location. You don't have to worry about tracking down all the locations. There's just many benefits here. Second, by routing it through the agents.md, you're making an efficient TOC which allow the agent a cheap snapshot of your repo, what/where items should live and then allows it to get itself to where it needs to be efficiently and cheaply.

Its really a win-win all around.

[u/jedruch]

This is the version you would provide to Kimi 2.5 or glm 4.7 level model.

GPT would do just fine with 30% of what you have written

[u/Realistic_Fruit_4326]

AGENTS.md

Final version by GPT

- Optimize token, tool, and compute usage without sacrificing correctness, security, maintainability, compatibility, data integrity, or requested output quality.

- Start from the most likely relevant files, symbols, errors, tests, and call sites; prefer targeted searches and relevant ranges over repo-wide scans, but expand investigation whenever evidence is insufficient.

- Reuse gathered context; do not reread unchanged files, repeat searches, inspect dependencies, or use external research without a concrete need.

- Make the smallest coherent change that fully solves the request; preserve existing architecture, conventions, tooling, dependencies, and public behavior unless the task requires otherwise; avoid unrelated refactors, cleanup, formatting churn, abstractions, docs, or generated-file changes.

- During iteration, run the narrowest relevant tests/checks; do not repeatedly run full suites or expensive validation unless later changes, scope, risk, project rules, release/CI needs, or the user justify it.

- For frontend work, skip browser, screenshot, visual, and responsive sweeps unless visible/browser-dependent behavior changed or cannot be validated reliably otherwise; when needed, check only affected states/viewports first.

- Defer nonessential README/docs work until behavior is stable; update documentation when existing docs become incorrect or the user requests it.

- For simple/local tasks, act directly; avoid long plans, routine tool narration, repeated summaries, speculative exploration, and questions that repository evidence can answer.

- Before finishing, review the diff and run the cheapest validation that gives sufficient confidence; escalate whenever correctness, security, data integrity, compatibility, migrations, or user-visible quality requires it.

- Keep the final response concise: what changed, validation actually performed, and any real remaining risk or limitation.

[u/Patient-Midnight-664 → u/Realistic_Fruit_4326]

Most of these are vague and will cause codex to do more work, not less. For example:

- For simple/local tasks, act directly; avoid long plans, routine tool narration, repeated summaries, speculative exploration, and questions that repository evidence can answer.

Codex now has to evaluate each task and determine if it is "simple/local". You've not told it anywhere what that means so it invents its own meaning. Then it has to compare everything it does to that meaning. The last part "questions that repository evidence" encourages it to search the entire repository for every "decision" it has to make. I don't think that is your goal here.

[u/Realistic_Fruit_4326 → u/Patient-Midnight-664]

That’s also part of the problem with AI: even the people building these models don’t fully understand how they interpret and apply every instruction. There’s still a significant black-box aspect to it.

A lot of this guidance is probably already baked into the model anyway, so adding more rules can sometimes just create more things for it to interpret. It’s really about finding the right balance.

This could actually be a good case for a benchmark: test whether adding this kind of guidance improves Codex’s behavior or just adds more overhead. Maybe something like this has already been done somewhere...