CDX-301a · Module 1

Workspace Configuration Strategies

4 min read

Monorepos demand a layered AGENTS.md strategy that mirrors the dependency graph. The root AGENTS.md defines the monorepo tooling (pnpm workspaces, Nx, Turborepo), cross-cutting conventions, and the shared command vocabulary. Each workspace — whether it is an app, a library, or an infrastructure package — gets its own AGENTS.md that refines context for that scope. The key insight is that Codex resolves these files at session start, merging them in directory order. A poorly structured hierarchy forces Codex to reconcile conflicting rules, wasting context tokens and producing inconsistent output.

The workspace config should declare its framework, its build command, its test runner, and any conventions that differ from the root. If the root says "use Vitest" but one workspace uses Jest, the workspace-level AGENTS.md must override that explicitly. Implicit overrides — where a workspace silently ignores a root rule — create drift that compounds over time. Be explicit about every deviation.

# Monorepo workspace config hierarchy

./AGENTS.md                              # Root: pnpm, shared lint, commit rules
├── apps/web/AGENTS.md                   # Next.js 15, app router, Tailwind
├── apps/api/AGENTS.md                   # Express, Prisma, PostgreSQL
├── apps/mobile/AGENTS.md                # React Native, Expo SDK 52
├── packages/shared/AGENTS.md            # Zod schemas, shared types
├── packages/ui/AGENTS.md                # Component library, Storybook
└── infrastructure/AGENTS.md             # Terraform, Docker, CI scripts

# Workspace-level overrides
apps/web/AGENTS.override.md              # Dev's personal Next.js prefs
apps/api/AGENTS.override.md              # Dev's personal API prefs
  1. Inventory workspaces List every workspace in your monorepo. For each, note its framework, test runner, build tool, and any conventions that differ from the root.
  2. Create per-workspace configs Write an AGENTS.md for each workspace that declares its specific context. Keep it under 50 lines — details belong in code comments, not config files.
  3. Validate the cascade Start Codex in each workspace directory and run /status. Verify the merged rules match your expectations. Fix conflicts immediately.