Multi-Project & Monorepo Configs

Monorepos and multi-project setups need a layered AGENTS.md strategy. The root AGENTS.md covers shared infrastructure — the monorepo tool (Nx, Turborepo, pnpm workspaces), shared conventions, and cross-cutting rules. Each package or app directory gets its own AGENTS.md with framework-specific rules, test commands, and local conventions that apply only when Codex is working in that directory.

The directory-scoping system handles this naturally. When you run Codex in apps/web/, it loads the root AGENTS.md first, then apps/AGENTS.md (if it exists), then apps/web/AGENTS.md. Each layer refines the context. The root says "this is a pnpm monorepo." The apps/web layer says "this app uses Next.js 15 with app router." The specificity increases as you go deeper, exactly like CSS cascading.

# Monorepo AGENTS.md structure

./AGENTS.md                          # Monorepo: pnpm, shared conventions
./packages/shared/AGENTS.md          # Shared lib: Zod schemas, utils
./apps/web/AGENTS.md                 # Next.js 15, app router, Tailwind
./apps/api/AGENTS.md                 # Express, Prisma, PostgreSQL
./apps/mobile/AGENTS.md              # React Native, Expo
./infrastructure/AGENTS.md           # Terraform, Docker, CI scripts

# Each file only contains rules specific to that scope.
# Root rules cascade to all packages automatically.

1. Map your scopes List every directory that has distinct conventions, frameworks, or rules. Each one is a candidate for its own AGENTS.md.
2. Extract shared rules to root Anything that applies everywhere (code formatting, commit conventions, CI commands) goes in the root AGENTS.md. Do not repeat it in subdirectories.
3. Test the cascade Run Codex in each major directory and verify with /status that the correct rules are active. Check for conflicts and unintended overrides.