Template: monorepo

By agent-playbook · 0 stars

Assumes pnpm workspaces + Turborepo. Rename commands for Nx, uv workspaces, Bazel.

~~~text
repo/
  AGENTS.md
  CLAUDE.md               # optional: "@AGENTS.md" plus Claude-only lines
  apps/web/AGENTS.md
  apps/api/AGENTS.md
  packages/ui/AGENTS.md
~~~

### Root AGENTS.md

~~~markdown
# AGENTS.md

Monorepo for <product>. pnpm workspaces + Turborepo. Node <22>.
- `apps/web` Next.js frontend | `apps/api` Fastify API | `packages/ui` shared components | `packages/config` shared lint/tsconfig

### Commands (run from repo root)
- Install: `pnpm install`
- Everything: `pnpm turbo run build test lint`
- One package: `pnpm --filter <name> test` (names are in each package.json)
- Only what changed: `pnpm turbo run test --filter=...[origin/main]`

### Rules for all packages
- Each package has its own AGENTS.md; read it before editing that package.
- Cross-package imports only through a package's public entry (`@repo/ui`), never deep paths.
- `apps/*` may depend on `packages/*`; `packages/*` never depend on `apps/*`.
- Changes to anything in `packages/` need a changeset: `pnpm changeset`.

### Boundaries
- Ask first: root config (turbo.json, pnpm-workspace.yaml, tsconfig base), new packages, CI.
- Never: add a dependency to the root package.json unless it is dev tooling.

### Done means
`pnpm turbo run build test lint --filter=...[origin/main]` passes.
~~~

### apps/api/AGENTS.md

~~~markdown
# apps/api

Fastify + Drizzle ORM on Postgres.

### Commands (from this directory)
- Dev: `pnpm dev` (needs `docker compose up db` from repo root)
- Test: `pnpm test` | DB tests: `pnpm test:db`
- New migration: `pnpm db:generate` then review the SQL; never edit applied migrations.

### Conventions
- Route handlers stay thin; logic goes in `src/services/`.
- Every route has a zod schema for request and response.
- Unlike the root default, this package logs with `pino`; no `console.*`.
~~~

### packages/ui/AGENTS.md

~~~markdown
# packages/ui

Shared React components consumed by apps/web and external apps.

- Public API is `src/index.ts`; adding an export is a minor change, removing one is major.
- Every component has a story in `*.stories.tsx` and a test.
- No app-specific logic or data fetching here.
- Run `pnpm --filter @repo/ui test` and `pnpm --filter @repo/ui build` before finishing.
~~~

### CLAUDE.md (optional)

~~~markdown
@AGENTS.md

- Start sessions from the package directory you are changing so its instructions load at launch.
- Scoped rules for tests and SQL live in `.claude/rules/`.
~~~

### Tool settings this layout needs

| Tool | Setting |
|---|---|
| Copilot in VS Code | `chat.useNestedAgentsMdFiles` on |
| Codex | Deepest path under 32 KiB total, or raise `project_doc_max_bytes` |