Monorepo example
AGENTS.md Template for a Monorepo
Copy a monorepo AGENTS.md example with workspace discovery, dependency boundaries, affected-package commands, ownership, nested instructions, and integration checks.
Use this at a monorepo root to define shared workflow and package boundaries, then place shorter nested files only where a workspace needs different instructions.
Full version
Copy the AGENTS.md template
Replace every bracketed value and delete any rule you cannot verify in the repository.
# Monorepo Instructions
## Scope
These root instructions apply across the repository. A deeper AGENTS.md may add or override rules for its directory tree.
## Workspace Map
- `apps/web/`: [purpose and owner]
- `apps/api/`: [purpose and owner]
- `packages/ui/`: [public API and consumers]
- `packages/config/`: [shared configuration]
- `tooling/`: [build and repository tooling]
## Root Commands
- Install all workspaces: `[exact command]`
- List/graph affected workspaces: `[exact command]`
- Test one workspace: `[exact filtered command]`
- Lint affected workspaces: `[exact command]`
- Build affected workspaces: `[exact command]`
- Full CI-equivalent validation: `[exact command]`
## Dependency Boundaries
- Apps may depend on packages; packages must not import from apps.
- Import packages through their declared public entry points, not internal source paths.
- Update package manifests and lockfiles through the workspace package manager only.
- Treat shared package API changes as changes to every consumer.
- Do not create circular workspace dependencies.
## Change Workflow
- Identify the owning workspace and downstream consumers before editing.
- Read the nearest AGENTS.md and package README in the affected subtree.
- Keep package-specific behavior and commands in a nested AGENTS.md.
- Run focused checks first, then integration or build checks for affected consumers.
- If shared configuration changes, run the full CI-equivalent validation.
## Ownership and Safety
- `[path]`: requires review from `[team/codeowner]`.
- Migrations, releases, publishing, and deployment require explicit authorization.
- Never modify generated artifacts directly.
- Preserve versioning and release-note conventions used by the repository.Do not copy blindly: Do not duplicate every package README or place package-specific commands in the root when they can be scoped closer to the code.
Minimal version
Start smaller when the repository is simple
# Monorepo Instructions
## Workspaces
- `apps/[name]`: [owner and purpose]
- `packages/[name]`: [owner and purpose]
## Commands
- Install from root: `[exact command]`
- Test affected workspace: `[exact filtered command]`
- Full validation: `[exact command]`
## Rules
- Identify affected workspaces before editing.
- Respect dependency direction and package public APIs.
- Run focused checks for changed packages plus integration checks for their consumers.
- Follow a deeper AGENTS.md when working in its subtree.Customize each field
Workspace Map
List boundaries, public responsibilities, and ownership—not every directory.
Affected commands
Use the repository's real pnpm, npm, Nx, Turborepo, Bazel, Pants, or other filters.
Nested instructions
Put framework-specific rules close to the workspace so they do not pollute unrelated tasks.
Consumers
Document how to find downstream dependants and which integration checks protect them.
Validate the instructions
- Start the agent from the repository root and confirm root instructions load.
- Start from a package directory and confirm both root and applicable nested instructions load.
- Run the documented affected-workspace command on a known small change.
- Verify a shared-package change triggers checks for at least one downstream consumer.
- Check that nested files do not contradict root safety or release rules.
Common mistakes
Copying all package instructions into the root
Keep the root as a map and shared contract; scope details in nested files.
Testing only the edited package
Test direct consumers when a public package interface changes.
Using an unverified affected-workspace filter
Run it on a known change and compare the reported dependency graph.
Interactive tool
Generate a repository-specific starting file.
Choose your framework, real commands, paths, and approval boundaries, then copy or download the result.
Open AGENTS.md GeneratorRelated templates
Choose the closest repository shape.
Official sources
Instruction discovery and scope behavior were checked on August 13, 2026. Recheck product documentation when standardizing these files across a team.