You ask OpenAI Codex (Codex CLI or the cloud agent) to “add a user settings page.” The code runs, but the file lands at src/UserSettings.tsx instead of src/pages/settings/index.tsx where every other page lives; it’s named UserSettings instead of your consistent SettingsPage; it reaches for useState even though the project standardizes on Zustand. Codex defaults to “generic best-practice React” and does not automatically infer your repo’s existing conventions.
Fastest fix: add an AGENTS.md at your repo root that spells out paths, naming, and stack, then point every prompt at one concrete sibling file to copy from. As of June 2026, Codex reads AGENTS.md automatically on every run, so this alone fixes most cases. The rest of this page covers the diagnosis, the full setup, and how to confirm it stuck.
Which bucket are you in?
| Symptom | Likely cause | Go to |
|---|---|---|
No AGENTS.md / CLAUDE.md / rules file in repo | Codex has no spec to follow | Cause 1 / Step 1 |
| Guide exists but Codex still uses generic patterns | Prompt never pointed at a sample file | Cause 2 / Step 2 |
Wrong library (axios, bare useState) | Prompt didn’t pin the stack | Cause 3 / Step 1 |
| Output is right half the time | Repo itself is inconsistent | Cause 4 |
Files land at repo root, not apps/web | Codex picked the wrong workspace root | Cause 5 / Step 5 |
Common causes
Ordered by hit rate, highest first.
1. No AGENTS.md (or equivalent) in the repo
Codex reads AGENTS.md for project instructions. Claude Code reads CLAUDE.md; Cursor reads .cursor/rules/*.mdc (the single-file .cursorrules is deprecated as of Cursor 0.43 but still loads). Without any of these, Codex scans a few recently edited files and guesses.
You: add a user settings page
Codex: (no AGENTS.md, README says nothing about directory layout)
-> creates src/UserSettings.tsx
Your project: every page lives at src/pages/<feature>/index.tsxHow to spot it: check the repo root. If none of AGENTS.md, CLAUDE.md, or .cursor/rules/ exist, this is it.
2. Codex never read a sibling file
Even with a guide present, if the prompt doesn’t point at a concrete reference sample, Codex falls back to “standard React project” patterns from its training set instead of your local conventions.
How to spot it: check whether Codex actually read a sibling file before generating. Every session is logged as JSONL under ~/.codex/sessions/YYYY/MM/DD/rollout-<session-id>.jsonl; filter the tool calls:
# Latest session, show only tool calls (needs jq)
ls -t ~/.codex/sessions/**/rollout-*.jsonl | head -1 | \
xargs cat | jq 'select(.type == "tool_call")'If there’s no read on a sibling file before the write, that’s the cause. (For live tracing, RUST_LOG=debug codex 2>&1 | grep file: works too.)
3. The prompt didn’t pin the stack
A default prompt like “implement feature X” gives Codex full freedom. It uses generic React + axios + useState and ignores your Zustand / SWR / TanStack Query / shadcn-ui choices.
How to spot it: compare the libraries imported in the generated code to package.json. If it imports something you don’t have installed (or ignores a state library you do have), the prompt was too loose.
4. The project itself is internally inconsistent
If half the files are kebab-case and half PascalCase, half live in pages/ and half in routes/, Codex randomly mimics one and looks wrong about half the time.
How to spot it: run find src -name '*.tsx' | sort. If naming or location is mixed, the project itself is the underlying problem and no prompt will fully fix it.
5. In a monorepo, Codex picked the wrong workspace root
In monorepos, Codex anchors on the directory it was launched from. Start it at the repo root and it sees the root package.json, assumes that’s the entry point, and writes files to the root instead of apps/web or packages/ui.
How to spot it: generated files land at the root or in the wrong workspace instead of next to similar code.
Shortest path to fix
Ordered by ROI. Steps 1 and 2 usually get Codex on-style on the first try.
Step 1: Write AGENTS.md with paths, naming, and stack spelled out
Place it at the repo root. Codex reads it on every run. If you’d rather start from a scaffold, run /init inside a Codex session to generate a first draft from your detected dependencies and layout, then trim it to the rules that actually matter:
# AGENTS.md
## Project structure
- Pages: src/pages/<feature>/index.tsx
- Shared components: src/components/<PascalName>.tsx
- API calls: src/lib/api/<resource>.ts
- Types: src/types/<resource>.ts
- Monorepo entry is apps/web. Do NOT write to repo root.
## Naming
- Component files: PascalCase (SettingsPage.tsx)
- Hook files: useXxx.ts
- Route segments: kebab-case (user-settings)
## Stack (do NOT introduce substitutes)
- State: Zustand (no Redux / Recoil / bare useState for global)
- Data fetching: TanStack Query (no raw axios)
- Forms: react-hook-form + zod
- Styling: Tailwind + shadcn-ui
## Workflow
- After edits run `pnpm typecheck && pnpm lint && pnpm test`
- Ask before adding any new dependencyKeep it under the default 32 KiB cap (project_doc_max_bytes in ~/.codex/config.toml); past that, Codex truncates. Aim for tight rules, not prose.
Step 2: Reference a concrete sibling file in the prompt
Have Codex read a similar existing file before writing:
Add a "Notifications Settings" page.
First, read these two files and copy their structure and style:
- src/pages/account-settings/index.tsx (sibling page)
- src/components/SettingsCard.tsx (card component usage)
Then generate the new page following AGENTS.md's naming and directory rules.
Do not add new dependencies; reuse Zustand + TanStack Query.Telling it to read a specific file is far more effective than a vague “follow existing style,” because it grounds the output in your actual code rather than its training prior.
Step 3: Demand plan-first, confirm structure before any code
Make Codex output a plan first; you approve, then it edits:
Before writing any code, output a plan with:
1. List of file paths to create or modify
2. One-line purpose for each
3. Any new dependencies (if any)
4. Which existing modules this touches
Wait for me to say "go" before starting any edits.If a path is wrong, the plan stage catches it with no rollback needed.
Step 4: Self-check with tree plus a naming validator
Add a self-verify instruction near the end of AGENTS.md:
# After creating new files, run:
tree src/pages -L 2
# Confirm the new page path matches src/pages/<feature>/index.tsxOr provide a validator script and have AGENTS.md require it:
node scripts/verify-structure.mjs
# Outputs OK or lists violating filesStep 5: In a monorepo, pin the working directory and drop a nested AGENTS.md
Two fixes that stack. First, launch Codex from (or pointed at) the right workspace so the root is correct:
# Set the working root with --cd (alias -C). This is the current flag;
# the older --working-dir name has been replaced.
codex --cd apps/web "add a user settings page"
# Coordinating across workspaces? Grant extra writable roots:
codex --cd apps/web --add-dir ../packages/ui
# Or be explicit at the top of the prompt:
"Working directory is apps/web. All new files must live under apps/web/src.
Do not touch the repo root or any other workspace."Second, take advantage of nested instruction files. Codex merges every AGENTS.md from the git root down to your current directory, so an apps/web/AGENTS.md with web-specific rules overrides the root one when you work there (a per-dir AGENTS.override.md wins if both exist). Put workspace-specific paths in the workspace’s own file.
How to confirm it’s fixed
Run the request again, then check:
- Path: the new file sits where AGENTS.md says (e.g.
src/pages/<feature>/index.tsx), not at the root. - Naming: the component/file name matches your convention (
SettingsPage, notUserSettings). - Stack: imports match
package.json— Zustand/TanStack Query in, axios/bare globaluseStateout. - Reads: the session JSONL shows a read on your sibling file before the write.
If all four pass on a fresh run, AGENTS.md is loading and the prompt is grounded.
FAQ
Does AGENTS.md replace CLAUDE.md and .cursor/rules?
No. Each tool reads its own file: Codex reads AGENTS.md, Claude Code reads CLAUDE.md, Cursor reads .cursor/rules/*.mdc. Keep all three at the repo root and sync them so an agent never follows stale rules. Codex also merges a global ~/.codex/AGENTS.md if you keep personal defaults there.
Codex still ignores AGENTS.md. Why?
Most often the file is too large (over the 32 KiB project_doc_max_bytes cap, so the tail gets truncated), or you launched Codex from a directory above the git root so it never found the file. Confirm the file is at the root and Codex is started inside the repo. As of June 2026 Codex rebuilds the instruction chain on every run, so there’s no cache to clear.
How do I see exactly which files Codex read?
Inspect the session log at ~/.codex/sessions/YYYY/MM/DD/rollout-<id>.jsonl and filter for tool_call entries, or run with RUST_LOG=debug codex and grep for file:. If there’s no read on a relevant sibling before the write, your prompt needs an explicit “read this file first” instruction.
The project structure itself is inconsistent. What now? No prompt fixes a repo that contradicts itself. Pick one convention, document it in AGENTS.md as the single source of truth, and migrate stragglers (or note the legacy area as off-limits). Until then, Codex will mirror whichever pattern it happened to read.
What’s the flag to set the working directory?
--cd (alias -C), e.g. codex --cd apps/web. The older --working-dir name has been replaced. Use --add-dir to grant additional writable directories.
Prevention
- Keep
AGENTS.md(Codex),CLAUDE.md(Claude Code), and.cursor/rules/*.mdc(Cursor) at the repo root; sync them so they stay aligned. - When introducing a new file type, update AGENTS.md first, write the first sample, then let the AI mimic it.
- Bake “read a sibling sample first, then write” into your prompt template.
- Add a
scripts/verify-structure.mjsand run it in CI; block PRs that violate naming or path rules. - In monorepos, launch Codex with
--cd <workspace>and add a nested per-workspaceAGENTS.md, never relying on the repo root alone. - Quarterly, review AGENTS.md and codify the mistakes the AI keeps making (e.g. “always picks
useState”) as explicit bans.
Related
- Codex vs Claude Code
- AI pre-commit review workflow
- Claude Code SEO audit
- AI dependency upgrade workflow
- Cursor missed project context
External references: OpenAI Codex AGENTS.md guide, Codex CLI command-line reference.