AGENTS.md and CLAUDE.md: one folder, two AI tools, one rulebook

The setup exists because the two tools do not look for the same file. Codex starts with AGENTS.md in its home directory (default ~/.codex) and then walks from the project root down to the current working folder, joining files from the root side and stopping once the total reaches a default cap of 32 KiB. Claude Code, by contrast, reads CLAUDE.md from the working folder and each folder above it, and a line starting with @path inside CLAUDE.md pulls in another file, following those references up to four levels deep.

The catch is the default condition for AGENTS.md in Claude Code. When any CLAUDE.md exists in the working folder or above it, the default skips AGENTS.md. In nested working folders, where an upper folder often holds a CLAUDE.md, a lower folder's AGENTS.md would stop being read. The fix the author uses is a CLAUDE.md in the company folder that contains the single import line, which restores AGENTS.md regardless of what CLAUDE.md files are added above.

To keep the entry file short, AGENTS.md itself is 13 lines and holds only the workflow and pointers, with the actual rules living in rules/ files and per-role files under team/. The author notes AGENTS.md is read on every task, so a longer entry file leaves less of what the AI can read at once for actual work, and points to the 32 KiB Codex cap and Claude Code's documented 200-line guideline for CLAUDE.md. The same shape applies to skills: both tools use a SKILL.md file but look in different locations, and the author verified on October 12, 2026 that Codex read skills placed under ~/.codex/skills in their environment. To confirm the entry is actually read, the author uses a Codex command that asks it to summarize the current instructions, and a Claude Code command that returns the numbered steps from AGENTS.md.