Summary

Progressive disclosure: root for overview + cross-package conventions; per-package AGENTS.md for scoped detail. Precedence: narrowest wins (packages/api/AGENTS.md overrides root AGENTS.md for api package). Root file stays tight (~150 lines), per-package files focus on package-specific commands, testing, and boundaries. Avoid duplication: per-package files reference root, then add package-specific content. Optional: per-package CLAUDE.md for Claude-specific overrides in specific packages.

Root: Overview + cross-package commands (~150 lines)
├── packages/api/AGENTS.md: API-specific (~100 lines)
├── packages/web/AGENTS.md: Web-specific (~100 lines)
└── Precedence: packages/*/AGENTS.md overrides root

Monorepos (pnpm workspaces, Yarn workspaces, Lerna, Turbo) need per-package context files. A single root AGENTS.md is insufficient because each package has different commands, conventions, and boundaries.

The pattern is progressive disclosure: root AGENTS.md provides overview and cross-package conventions; per-package AGENTS.md files provide scoped detail.

Structure

.
├── AGENTS.md                      # Root: overview, cross-package commands
├── CLAUDE.md                      # Claude Code overlay (optional; applies to all packages)
├── .cursor/rules/                 # Cursor rules (can be scoped per-package)
└── packages/
    ├── api/
    │   ├── AGENTS.md              # API-specific commands, testing, boundaries
    │   └── CLAUDE.md              # (optional) API-specific Claude hints
    ├── web/
    │   └── AGENTS.md              # Web-specific commands
    ├── shared/
    │   └── AGENTS.md              # Shared package commands
    └── cli/
        └── AGENTS.md              # CLI package commands

Root AGENTS.md

Provides overview and cross-package commands. Tight (~100–150 lines).

# AGENTS.md

Monorepo for SaaS platform: API (Fastify), Web (Next.js), Shared types, CLI.

## Monorepo Layout

packages/api: Backend server (Node/Fastify)
packages/web: Frontend (Next.js 16)
packages/shared: Shared type definitions
packages/cli: Command-line tool

## Quick Start

Development:
pnpm dev # Both API + Web (http://localhost:3000)
pnpm test # All packages
pnpm lint # Lint all

Build:
pnpm build # All packages in dependency order (~3m)

Package-specific:
pnpm --filter=@app/api dev
pnpm --filter=@app/web dev
pnpm --filter=@app/shared type-check

Release:
changeset add # Stage version bump
pnpm release # Publish all packages

## Tech Stack

See packages/\*/AGENTS.md for package-specific tech.

Shared tools: TypeScript, ESLint, Prettier, Vitest, Turbo.

## Conventions

Filenames: kebab-case
Functions: camelCase
Types: PascalCase
API routes: /api/v1/...
Imports: absolute paths (src/...)

## Testing

Unit: Vitest (pnpm test)
Turbo parallel: pnpm test -- --parallel

pnpm test must pass before merge.

## Boundaries

Always:

- Read files, run tests, lint
- Open draft PRs

Ask first:

- Install dependencies
- Run migrations

Never:

- Deploy to production
- Rotate credentials

## More

See packages/\*/AGENTS.md for package-specific details.
Architecture: docs/ARCHITECTURE.md
Contributing: CONTRIBUTING.md

Per-Package AGENTS.md

Detailed commands, testing, and conventions specific to each package.

packages/api/AGENTS.md

# API Server (packages/api)

Backend server: HTTP API, database operations, authentication.
Framework: Fastify + TypeScript
Database: PostgreSQL + Prisma

## Quick Start

Dev:
pnpm --filter=@app/api dev # http://localhost:3001
pnpm --filter=@app/api test
pnpm --filter=@app/api test:watch

Build:
pnpm --filter=@app/api build # Compile TS
pnpm --filter=@app/api start # Run production server

## Directory Map

src/routes/ API route handlers (/api/v1/...)
src/db/ Prisma schema, migrations
src/middleware/ Authentication, logging, error handling
src/types/ TypeScript type definitions (see ../shared/)
test/ Integration tests (Supertest)

## Testing

Integration tests with real database (test container):
pnpm --filter=@app/api test

Watch mode:
pnpm --filter=@app/api test:watch

## Database

Migrations (apply pending changes):
pnpm --filter=@app/api db:migrate # Ask first

Seeding (populate test data):
pnpm --filter=@app/api db:seed

Rollback (dev only):
pnpm --filter=@app/api db:rollback

## Conventions

Routes: /api/v1/[resource]/[id]?
Error response: { error: { code, message, details } }
All endpoints require authentication (except /auth/\*)

## Boundaries

Always:

- Read files, run tests
- Run db:seed

Ask first:

- db:migrate (non-dev)
- External API calls

Never:

- Production deploys
- Drop databases

## More

See ../AGENTS.md for cross-package info.
Schema: src/db/schema.prisma
Routes: src/routes/

packages/web/AGENTS.md

# Web (packages/web)

Frontend: Next.js 16 + React 19
Framework: Next.js App Router
Styling: TailwindCSS + shadcn/ui

## Quick Start

Dev:
pnpm --filter=@app/web dev # http://localhost:3000
pnpm --filter=@app/web test
pnpm --filter=@app/web test:watch

Build:
pnpm --filter=@app/web build # Next.js build
pnpm --filter=@app/web start # Serve built app

Preview:
pnpm --filter=@app/web build:preview # Local build preview

## Directory Map

src/app/ Page routes, layouts
src/components/ Reusable React components
src/lib/ Utilities, helpers
src/hooks/ Custom React hooks
test/ Unit tests (Vitest), E2E tests (Playwright)

## Testing

Unit:
pnpm --filter=@app/web test

E2E (Playwright):
pnpm --filter=@app/web test:e2e

Watch:
pnpm --filter=@app/web test:watch

## Conventions

Components: PascalCase (src/components/Button.tsx)
Hooks: camelCase starting with 'use' (useAuth, useRouter)
Routes: lowercase + kebab-case (/api/users, /user/settings)
Styling: TailwindCSS utility classes, no inline styles

## Dependencies

Keep light! Check bundle size before adding packages.

## Boundaries

Always:

- Read files, run tests
- Run build and preview

Ask first:

- Add new dependencies

Never:

- Deploy to production
- Modify next.config.js for performance (discuss first)

## More

See ../AGENTS.md for cross-package info.
Components: src/components/

packages/shared/AGENTS.md

# Shared Types (packages/shared)

Shared TypeScript types and Zod schemas used across API and Web.

## Quick Start

Type check:
pnpm --filter=@app/shared type-check

Build:
pnpm --filter=@app/shared build # Emits TS + ESM

Test:
pnpm --filter=@app/shared test

## Directory Map

src/types/ TypeScript type definitions
src/schemas/ Zod validation schemas (used by API + Web)
src/utils/ Shared utilities (parsing, formatting)

## Publishing

This package is published to npm @app/shared.

Releases require:

- changeset add (document breaking changes)
- pnpm release (run once all changesets merged)

See ../AGENTS.md > Release for full flow.

## Conventions

Exports: named (export const, export type)
No default exports (explicit is better)
Schemas: one per file (userSchema.ts, invoiceSchema.ts)

## Boundaries

Always:

- Type changes
- Schema additions

Ask first:

- Breaking changes to exported APIs
- New dependencies

## More

See ../AGENTS.md for cross-package info.

Precedence Rules

There is no single cross-tool precedence ladder - each tool resolves its own files independently, and the rules don't merge:

AGENTS.md itself: nested files win over the root. packages/api/AGENTS.md overrides AGENTS.md (root) for anything under packages/api/.
Claude Code (v2.1.277+): reads AGENTS.md directly when no CLAUDE.md exists anywhere from the working directory up to the repo root; if one does exist, Claude Code reads that instead unless it starts with a literal @AGENTS.md import - see CLAUDE.md for the exact rule.
Cursor: reads AGENTS.md natively (nested wins) and layers .cursor/rules/*.mdc on top for glob-scoped detail - see Cursor and Copilot.
GitHub Copilot: reads AGENTS.md directly (coding agent, code review) and separately reads .github/copilot-instructions.md plus path-scoped .github/instructions/*.instructions.md.

Example: For server conventions, a package-scoped packages/api/AGENTS.md is what every tool prefers over the root file for that package - that part is shared. What differs is whether a given tool also reads a tool-specific file (CLAUDE.md, .cursor/rules/, .github/instructions/) alongside it, and each tool's own docs are the source of truth for that.

Cross-Package Tool Filters

Use Turbo filters to limit tool execution to specific packages:

## Running Tests for Specific Packages

All tests:
pnpm test

API only:
pnpm --filter=@app/api test

Web only:
pnpm --filter=@app/web test

Multiple packages:
pnpm --filter=@app/api --filter=@app/web test

Depending packages (changes in shared affect web + api):
pnpm --filter=@app/shared... test

Document these in root AGENTS.md and reference in per-package files.

Monorepo Boundaries

Root AGENTS.md can define boundaries that apply globally; per-package files can override for local scope.

Root AGENTS.md:

## Boundaries (Cross-Package)

Always:

- Read files
- Run tests
- Open draft PRs

Ask first:

- Install dependencies
- Run migrations
- Deploy to staging

Never:

- Production deploys

packages/api/AGENTS.md (override):

## Boundaries (API-Specific)

(Inherit from root)

Additional for this package:

- Ask before: External API calls to production services
- Never: Run db:migrate without reviewing migration script

Monorepo-Specific Commands in Root

Include common multi-package commands in root AGENTS.md:

## Common Tasks

Format all files:
pnpm lint --fix

Build all packages (dependency order):
turbo run build

Run test in all packages:
turbo run test -- --coverage

Build only changed packages:
turbo run build --changed

Check types all:
pnpm type-check

Watch mode (specific package):
pnpm --filter=@app/web dev

Tool Scoping in Cursor Rules

Cursor rules can be scoped per-package:

.cursor/rules/
├── global.mdc                       # All files
├── api-routes.mdc                   # packages/api/src/routes/**
├── web-components.mdc               # packages/web/src/components/**
├── shared-schemas.mdc               # packages/shared/src/schemas/**
└── tests.mdc                        # All *.test.ts files

Each file uses globs to target its scope:

api-routes.mdc:

---
globs: "packages/api/src/routes/**/*.ts"
---

# API Route Rules

Routes follow RESTful conventions: /api/v1/[resource]/[id]?

web-components.mdc:

---
globs: "packages/web/src/components/**/*.tsx"
---

# Web Component Rules

Components are PascalCase and exported as named exports.

Monorepos