Shared Rules & Cross-Cutting Concerns

Shared rules are the backbone of monorepo consistency. They live in the root AGENTS.md and apply everywhere unless explicitly overridden. The challenge is deciding what belongs at the root level versus the workspace level. The litmus test: if violating a rule in ANY workspace would cause a problem (broken CI, security vulnerability, inconsistent API contract), it is a root-level rule. If it only matters within one workspace, it belongs there.

Cross-cutting concerns like commit message format, PR template requirements, branch naming conventions, and security policies are always root-level. Framework-specific patterns like "use server components for data fetching" are always workspace-level. The gray area — shared type conventions, error handling patterns, logging standards — requires judgment. When in doubt, start at the root and push down if it causes friction.

# Acme Monorepo

## Tooling
- pnpm 9 workspaces, Turborepo for orchestration
- Node 22 LTS, TypeScript 5.7 strict

## Shared Commands
- `pnpm build` — build all packages (topological order)
- `pnpm test` — test all packages
- `pnpm lint` — ESLint + Prettier across all packages
- `pnpm typecheck` — TypeScript strict check, all packages

## Cross-Cutting Rules
- All packages export types from a single index.ts barrel
- Shared types live in packages/shared — never duplicate
- Error classes extend BaseAppError from packages/shared
- All API responses use the ResponseEnvelope<T> type
- Never import from another app — only from packages/*
- Commit messages follow Conventional Commits

## Security (mandatory, all packages)
- No secrets in source — use environment variables
- All user input validated with Zod schemas from packages/shared
- SQL queries use parameterized Prisma queries, never raw SQL

1. Audit import boundaries Run a dependency graph tool (Nx graph, Turborepo visualize) to identify cross-app imports. Each violation is a rule you need in root AGENTS.md.
2. Categorize rules Sort every rule into "root" (cross-cutting) or "workspace" (local). Move misplaced rules to the correct level.
3. Test enforcement Ask Codex to make a change that would violate a root rule. Verify it refuses or flags the violation. If it does not, the rule needs stronger language.