Monorepo Package Instructions
Places shared and package specific rules at the directory levels where they apply.
Scenario
You maintain a pnpm monorepo with applications and shared packages.
Different packages have different responsibilities:
apps/web → product application
packages/ui → reusable UI
packages/db → database access
packages/config → shared configuration
Repository-wide instructions belong at the root.
Packages with meaningful specialized constraints have their own AGENTS.md.
Repository Structure
platform/
├── AGENTS.md
├── apps/
│ └── web/
│ └── src/
├── packages/
│ ├── ui/
│ │ ├── AGENTS.md
│ │ └── src/
│ ├── db/
│ │ ├── AGENTS.md
│ │ └── src/
│ └── config/
│ └── src/
├── pnpm-workspace.yaml
└── package.json
AGENTS.md
Root AGENTS.md:
# Monorepo Instructions
## Workspace
- Use `pnpm`.
- Run workspace dependency installation from the repository root.
- Applications live under `apps/`.
- Shared packages live under `packages/`.
## Dependencies
- Declare a dependency in the workspace that directly uses it.
- Do not add dependencies to the root solely to make them available to packages.
- Reuse an existing workspace package when it already owns the required functionality.
## Validation
- Validate every workspace affected by a change.
- When a shared package changes, validate important consumers.
packages/ui/AGENTS.md:
# UI Package Instructions
## Responsibility
- Keep this package application-agnostic.
- Do not import code from `apps/`.
- Do not add product-specific business logic.
## Components
- Follow existing component APIs and variant patterns.
- Preserve accessibility behavior when modifying existing components.
## Validation
Run:
- `pnpm --filter @platform/ui lint`
- `pnpm --filter @platform/ui typecheck`
- `pnpm --filter @platform/ui test`
Validate affected application consumers when public component behavior changes.
packages/db/AGENTS.md:
# Database Package Instructions
## Responsibility
- Keep shared database access in this package.
- Follow the existing repository/data-access patterns.
- Do not expose database implementation details unnecessarily to consumers.
## Schema Changes
- Create a new migration for schema changes.
- Do not rewrite already-applied migrations to change production schema history.
## Validation
Run:
- `pnpm --filter @platform/db typecheck`
- `pnpm --filter @platform/db test`
Validate affected consumers when public database APIs change.
What This Does
This treats packages as architectural boundaries rather than simply directories.
The root file establishes workspace behavior.
The UI package then adds rules that make sense specifically for a reusable component library.
The database package adds rules around persistence and migrations.
Notice that:
packages/config/
does not have an AGENTS.md.
That is intentional.
Not every workspace needs one.
What This Does NOT Do
The repository does not create:
AGENTS.md
inside every package merely for consistency.
If packages/config has no meaningful additional instructions, the root guidance may be enough.
The files also do not repeat workspace-wide dependency rules unless a package needs a specialized extension.
Why These Instructions Matter
Monorepos create a temptation to treat every directory as equally accessible.
An agent working inside:
packages/ui/
might import:
import { currentUser } from "../../../apps/web/src/auth";
The code could compile under some configurations.
Architecturally, however, the shared UI package now depends on one application.
The scoped instruction:
- Do not import code from `apps/`.
makes the package responsibility explicit.
Shared packages also have larger blast radiuses.
Changing:
packages/ui
may affect:
apps/web
apps/admin
apps/docs
That is why consumer validation matters.
Key Decisions
Scope by responsibility
A package deserves specialized instructions when it has meaningful responsibilities or constraints.
Don't create files mechanically
Package count should not determine AGENTS.md count.
Instruction differences should.
Shared packages need consumer awareness
A package can pass its own tests while breaking an application that consumes it.
Validation should account for this.
Keep dependency ownership clear
Dependencies should be declared where they are actually used.
This helps agents avoid using the workspace root as a dependency dumping ground.
When to Use This Pattern
Use this pattern when:
- the repository uses workspaces;
- packages have distinct architectural responsibilities;
- shared packages have multiple consumers;
- package-level validation differs;
- some packages need specialized modification rules.
The goal is not one AGENTS.md per package.
The goal is useful guidance at the scopes where behavior actually differs.