40 lines
1.4 KiB
Markdown
40 lines
1.4 KiB
Markdown
# 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.
|