Codex is good at following instructions and bad at guessing taste. Give it a spec and it executes. Give it "make the dashboard look nice" and you get a competent interface from a different product.
The split that works: AGENTS.md tells it how to build, DESIGN.md tells it what the result should look like.
Why two files
AGENTS.md is the open convention for agent instructions in a repository. Codex reads it from the project root. It is where testing commands, folder conventions, and code style belong.
Design is a different kind of rule. It changes on a different schedule, it is owned by different people, and it needs to be readable by Cursor and Claude Code too. Keeping it in its own file means one design contract feeds every tool you use.
The setup
Put both files in your repository root. Then add a design section to AGENTS.md:
# AGENTS.md
## Build and test
- Install: `npm install`
- Dev server: `npm run dev`
- Tests must pass before you report a task complete: `npm test`
## Design
All visual work follows DESIGN.md in this directory. Read it before you create
or modify any component, page, layout, or stylesheet.
Hard rules:
- Colors, spacing, radius, and type come only from DESIGN.md tokens.
- Component behavior and states follow the component rules in DESIGN.md.
- No new font family, shadow, or gradient without asking first.
- If DESIGN.md does not cover a case, stop and ask rather than inventing.Codex reads AGENTS.md automatically, so the pointer is enough. You do not need to paste the design system inline.
Make the instruction checkable
This part is easy and it changes the output quality more than the wording does.
Vague: "follow our design system."
Checkable: "every color you write must appear in the colors block of DESIGN.md."
The second version gives the model a test it can run against its own output before it hands the work back. I have found that phrasing rules as verifiable conditions cuts the number of review comments noticeably.
Verify it worked
Ask for something small and inspect the values:
Create a card component with a title, body text, and a secondary action.
Use only tokens defined in DESIGN.md and list which token each style came from.The list is the tell. If Codex can name the token for every value, it read the file. If it hand-waves, the pointer is not landing and you should check the filename and location.
Common mistakes
- Duplicating design rules into AGENTS.md. Now you have two versions and one of them is stale. Point, do not copy.
- Burying the design section at the bottom of a 300 line AGENTS.md. Put it near the top. Position matters more than it should.
- Skipping the "ask, do not invent" rule. Without it, missing tokens get filled in silently and you find out later.
What this means for you
Codex does not need more prompting. It needs a source of truth that is short, specific, and always present.
Two files, one job each. AGENTS.md for how the repo works, DESIGN.md for how the product looks. Grab a documented system from the library and you have the second file already written.