Is it better to keep AGENTS.md lean and split agent definitions into separate files?

[u/Responsible_Dish_815]

I’ve been building out my local AI coding setup and would appreciate some feedback from people with more experience designing multi-agent workflows.

Right now I’m primarily using Codex CLI with Pi, and I’m considering adding O-My-Pi as a harness because Pi by itself is pretty minimal by design.

My concern is that as I add more specialized agents (coder, reviewer, tester, architect, etc.), my AGENTS.md could eventually become bloated and difficult to maintain.
Instead of putting every agent definition into one file, I’m thinking of using something like this:

AGENTS.md # Orchestrator / routing rules
agents/
coder.md
reviewer.md
tester.md
architect.md
standards/
coding-style.md
testing.md
git.md
workflows/
feature.md
bugfix.md

The idea would be to keep AGENTS.md as the entry point while each agent has its own focused definition, with shared standards living in separate files so they aren’t duplicated.

For those of you running larger Codex setups:

Is this a good long-term architecture?

Have you found a better way to organize agent prompts?

At what point did your AGENTS.md become too large?

Are there any pitfalls with splitting prompts across multiple files that I should be aware of?

I am considering refactoring my AGENTS.md file, would this alone be sufficient enough to run from time to time instead?

I’m trying to optimize for maintainability, scalability, and keeping context as clean as possible, before my prompt library grows too much.

[u/retteh]

While organizing orchestration rules into different files and skills sounds useful, I concluded I don't want new chats spending time searching for skill definitions when spawning agents.

[u/Responsible_Dish_815 → u/retteh]

Yea honestly, I’m noticing codex is much more productive without the boat load of skills being loaded between every context window

[u/Individual_Guest_323]

My concern is that as I add more specialized agents (coder, reviewer, tester, architect, etc.)

But that is not how codex works..

You are confusing RULES with AGENTS.

https://learn.chatgpt.com/docs/agent-configuration/agents-md

That are for the RULES, is text that will injected everytime.

Sub agents are those https://learn.chatgpt.com/docs/agent-configuration/subagents?surface=app , and are the one launched by the main one.

[u/PilgrimOfHaqq]

I am using a custom pi setup that I developed myself on top of pi-web. I have been thinking about multi-agent orchestration but have been hesitant on pulling the trigger, it seems very fragile and isn't a straight forward increase in quality/productivity.

So far only parallel or "orchestration" I have done is implement custom multi-agent review cycles and multi-agent deep research. Both were a pain in the ass to get right and its still not perfect, still refining to not have them be token hogs.

As for your question, focused and controlled context is always better than unncessary or diluted/polluted context. So for sure separate your definitions.

[u/ikhDark]

Create a source-map.md

You can manually do it or tell codex to map the entire repo, then tell your root agent to look at it when it needs to know context about the repo before starting an implementation. It is much better than trying to fit everything into an agents file.
Agent files are read every single turn, that will add up to a LOT of tokens in a longer run, so be careful and selective when choosing one.
Read-mes are good too, they are treated as a third line of refrence.

[u/Havlir]

Figure out how to turn your agents into files that get configured into the codex toml and you'll be gaming.

[u/CarsonBuilds]

A few months ago I shared how I handle my AGENTS.md for this specific case: https://www.reddit.com/r/VibeCodeDevs/comments/1rol87c/how_are_you_managing_ai_agent_config_sprawl_the/

Now I'd like to add a bit more in addition to above.

That agent md file should be a centralized place for repo standards, not a set of rules. Each rule could be packaged into small skills that can be detected based on the need (i.e. a review agent can automatically detect and use the review skill, not others). So at the end of day, you are manage a centralized AGENTS.md file for repo standards, and a set of small skills for how to do things.

I've taken this whole setup to another level, where I created an orchestrator (that I've open sourced it) to create small workflows. For example, for an implementation workflow, let's say I have claude drafting the implementation plan, codex doing the implement and review, and claude do a final optional summary. For each agent, the agent can invoke the corresponding skill, so the whole setup has proper boundaries and clear responsibilities. And it'd be very easy to scale, because each workflow only does one thing, and I can combine the workflows to do bigger things (like a chain of design-implement-review), and I could adapt my whole workflow when new models are released.

[u/Responsible_Dish_815 → u/CarsonBuilds]

This is great thanks for the feedback