How We Implemented AGENTS.md in a Production TypeScript Monorepo

FAQ

What is AGENTS.md and why use it instead of tool-specific rule files?

AGENTS.md is a plain markdown file that gives AI coding agents project context and instructions, readable by multiple tools instead of one. Tool-specific formats like .cursor/rules work fine in isolation, but the moment more than one tool touches the repo, duplicating the same instructions across formats guarantees drift.

How do you avoid duplicating instructions across Cursor, Claude Code, and Codex?

Give every instruction exactly one canonical location and stop copying it anywhere else. Universal rules go in a root AGENTS.md, package-specific rules go in that package's own AGENTS.md, and only genuinely cross-cutting edge cases get a mirrored pair with a strict requirement-text contract.

Should AGENTS.md be one file or nested per package in a monorepo?

Nested, scoped to package boundaries rather than every directory. A single root file loses locality once apps diverge in stack or convention, and a file per directory creates too many places to look with no clear ownership. Package boundaries were the smallest unit that kept guidance close to the code without turning the repo into a maze.

Does Codex actually load nested AGENTS.md files reliably?

We didn't assume it would. We tested it directly: root and nested guides deliberately set to disagree, then Codex run from the repo root and from a package directory, across single-file and multi-file edits, checking what actually loaded. Codex does support hierarchical discovery by design, walking from the project root down to your working directory and concatenating files in order, but it's capped at 32 KiB by default and silently stops adding files past that limit, so verify in your own setup before building an architecture on top of it.

What's the precedence order when instructions from different tools conflict?

In order: system and developer instructions, then root AGENTS.md, then the nearest nested AGENTS.md, then tool-scoped rules (.cursor/rules or .claude/rules matching the task), then local task or PR notes. Root sits above nested on purpose, so a package-level index can't quietly override a universal invariant just because it happens to load later in the instruction chain.

How many AGENTS.md files is too many in a monorepo?

More than one full rule body per package is usually a sign you're duplicating rather than scoping — index files that point elsewhere are cheap, duplicated rule bodies aren't. We went from 36 Cursor rule files down to one root AGENTS.md, six package-level indexes, one heavy domain guide for billing and webhooks, and two mirrored pairs for the two scopes that couldn't nest cleanly. The roughly 20 remaining path-scoped Cursor rules stayed exactly where they were; they hold detail specific enough that promoting them to AGENTS.md would have meant re-fighting the locality problem all over again.

Is AGENTS.md an official standard or just a convention OpenAI started?

It started as a practical Codex mechanism, but it's since moved past single-vendor ownership. In December 2025 it was donated to the Agentic AI Foundation, a directed fund under the Linux Foundation, alongside Anthropic's Model Context Protocol and Block's Goose framework, with governance and Platinum membership spanning AWS, Google, Microsoft, and Cloudflare.