1.4 KiB
1.4 KiB
Monorepo Harness Notes
Use this reference when the repository contains multiple apps, packages, crates, or services.
What to map clearly
- workspace root vs package roots
- shared libraries vs deployable apps
- root-level commands vs package-level commands
- ownership or responsibility boundaries between packages
- which decisions are global vs package-local
Common risks
- root-level commands may not validate a specific package well
- agents may edit shared packages when a package-local change is safer
- build, lint, and test commands may vary by package manager, workspace tool, or package type
- one package may require a spec, ADR, or risk note even when the rest of the repo does not
- status can become ambiguous when several packages move in parallel
Good harness patterns
- include a short workspace map
- show how to run commands for one package or crate
- define allowed scope for a task
- prefer targeted validation for the touched package first
- record cross-package rules in a durable place
- use specs or status docs for multi-package migrations or coordinated refactors
Artifact guidance
In monorepos, keep the top-level working guide short. Push detail into focused supporting artifacts when needed:
- project map for workspace layout and boundaries
- task contracts for per-package scope
- ADRs for cross-cutting decisions
- status docs for migrations spanning several packages
Do not duplicate every package's README into the harness.