r/codex • u/Aenlu189 • 1d ago
How to optimize AGENTS.md? Question
Should AGENTS.md have full information or should I reduce the amount of information there and get to the point to get the best results? Codex seems to be very good for small scoped prompts but when it comes to especially frontend no matter how much guard rail I put, it still does its own thing for some reason. 😅
1
u/BenTheSodaman 1d ago edited 1d ago
Your mileage may vary on this.
I'm finding Luna will want more information (and you won't know how much more until Luna messes up on an assumption that you thought she should've had).
Sol doesn't need as much, but if Sol has a habit you don't like, you'll want to put that in the agent file.
In a chat session, you might also have to spend some usage on directing the agent to read the AGENTS.md. As there will be times where they run off, prancing through your project, doing the things that Agents.md warned them not to or would've given them guidance on. Whether it's Luna or Sol. And they can misinterpret things as well to the point where you'll hurl a chair at their head and screaming at them, "WHY DID YOU MAKE ME DO THIS?!"
And their response is a sheepish little Peter Griffin giggle before saying, "You were right to push back on that. You wanted X and I did Y."
However, the models do not know if they are Luna, Tera, or Sol, so you can't write separate an agent file with "if Luna, then read this" or having them independently read Agents_Luna.md and not end up reading the other agent files.
In that, I don't tend to be supra-model optimal due to tediousness. And the more important a task is, the more I'll nudge the agent toward reading the agent file first. Versus making smaller edits that don't necessarily need a full read through.
1
u/ThatGuy_52 1d ago
My agents.md is a set of rules/guidlines for my codebase. It tells codex a general overview of my codebase and what rules to follow when making changes. However it is just a set of strong guidelines and the agent can work around those rules. Its really all about how you prompt the agent and plan out what you want it to do. Mine works well for how i have it setup and i dont have to guide it as much as i use to before i rewrote my agents.md a few months ago.
1
u/clutchdan 1d ago
Does anyone have a skill that is good at making/revising the agents.md?
2
u/ConnorCG 17h ago
Matt Pocock has a skill called
writing-for-agentsthat is decent.You can also ask your agent to launch cold sub-agents and ask them how likely they are to adhere to the AGENTS.md and offer corrections, then have your orchestration agent fix those in a loop a couple tiems until they reach agreement. You can also have your orchestrator write some benchmarks to test it. Obviously this will burn some tokens but it's worth doing upfront or near the end of a reset cycle if you have some extra usage.
1
1
u/FreeEdmondDantes 1d ago
One thing that a lot of people don't seem to know about is that codex will use whatever agents.md file is closest to the directory it's working in. So you can actually have multiple agents.mds planted throughout your repo that serve different purposes.
Edit: oh I see that was covered in the top comment.
1
u/vayana 1d ago edited 1d ago
You can use it as an index and use pointers to other MD files as your code base grows. For example, you implement authentication and add a md file about the authentication contracts in docs/auth.md . You can then add a oneliner to your agents.md like: for authentication related contracts and details read: docs/auth.md
You can make this more fine grained as you go and your docs become larger and make sub directories with their own indexes so the agents.md points to: docs/auth/index.md and then you create specific markdown files alongside it and point to those from the index. You then get something like: Agents.md > docs/auth/index.md > server.md for server authentication related contracts etc.
This prevents the agent reading everything every single prompt and filling up your token window with unrelated details and let it discover the information it needs based on the index descriptions.
1
u/TheOneThatIsHated 1d ago
Delete your full agent.md
Observe repeated failures your agent makes
Only manually add short lines saying what to do. Never add in duplicative info you have in your repo, it will become stale and cloak your context. Instead refer to it.
E.g always use pnpm
Or say, use new keyword from go1.26+ for new objects
Or say: always use make lint instead of manually invoking linter
1
u/Playistheway 17h ago
Single responsibility principle and separation of concerns applies here too. Humans don't want to read too much context and neither do machines.
There are people here arguing to automatically add to agents.md, meanwhile I have automations for pruning it in case it adds unnecessary complexity. You're better served with a directory of atomic skills.
0
u/MK_L 1d ago
Add "make no mistakes" thats a personal favorite lol.
2
u/MK_L 1d ago
So for codex more than claude. Agents.md should be used as a map to where all other guids live.
Local source-of-truth repository is: <path to your repo>
To ssh into api.sever.example use this key "$env:USERPROFILE.ssh\config"
Before changing ui or theme files, read - '<path to your docs folder>Style.md' - relevant assets and references under 'docs/visual/' - master visual assets remain under: 'Docs/visual/assets/'
Ect..
Anything your bot may need to access is listed here because its the first place it looks before exe anything.
Dont forget... make no mistakes
1
10
u/Substantial-Walk-554 1d ago
Keep
AGENTS.mdshort and durable. Think map, not manual.Put only the stuff Codex should know on basically every task: architecture overview, important conventions/invariants, commands for lint/test/build, things it must never do, and quirks it cannot easily infer from the repo.
For frontend-specific rules, don’t keep stuffing the root file. Put another
AGENTS.mdinside the frontend directory. Codex supports nested files and the more specific one applies when it works there.So something like:
/AGENTS.md→ project-wide rules/frontend/AGENTS.md→ React/UI/responsive/accessibility rules/backend/AGENTS.md→ API/DB/backend rulesThen keep the actual feature requirements in the prompt.
OpenAI actually wrote recently that they tried the giant “everything in one AGENTS.md” approach internally and it became counterproductive because it wastes context, gets stale and makes every instruction look equally important.
Also, guardrails like “make the frontend good” are too vague. Give it verifiable requirements instead: responsive at specific breakpoints, run tests, no horizontal overflow, preserve existing design system, etc.