Scenario: Platform Team
Design a harness around invariants, impact analysis, shared modules, release gates, and migration discipline.
Key takeaways
- Platform harnesses protect shared contracts across teams, with invariants, impact analysis, release gates, and ADR/changelog as the load-bearing elements.
- The loop reads invariants and runs impact analysis before implementation, then gates on contract tests and a release gate before shipping a changelog entry.
- The policy reads
docs/invariants.mdanddocs/release-gates.mdfirst and forces approval for public package API, runtime config, or shared-data migration changes. - Common failures map to specific responses: downstream breakage to impact analysis and contract tests, boundary drift to loaded invariants, hidden migration risk to a human gate.
- First 30 days: write
docs/invariants.md, require impact analysis for shared package changes, and make release notes part of the done criteria.
Platform teams fail when a local-looking change breaks a shared contract. The harness must protect invariants across teams and packages.
Problem Structure
- Shared packages are changed without understanding downstream impact.
- Architecture boundaries are implicit.
- Release gates are remembered only by maintainers.
- Migrations or config changes break consumers.
Load-Bearing Elements
| Element | Why it matters |
|---|---|
| Invariants | Prevents architecture drift |
| Impact analysis | Identifies consumers before change |
| Release gate | Keeps shared changes disciplined |
| ADR / changelog | Preserves decisions and migration notes |
Recommended Loop
Artifact Structure
architecture.md
invariants.md
release-gates.md
migration-policy.md
impact-analysis.md
release-note.md
Example Policy
platform_change:
read_first:
- "docs/invariants.md"
- "docs/release-gates.md"
require_approval_if:
- "public package API changes"
- "runtime config changes"
- "migration touches shared data"
must_update:
- "changelog"
- "migration notes"Common Failures
| Failure | Harness response |
|---|---|
| Shared API breaks downstream code | Impact analysis and contract tests |
| Architecture boundary drift | Invariants loaded before implementation |
| Release note missing | Ship gate requires it |
| Migration risk hidden | Human gate for migrations |
First 30 Days
- Write
docs/invariants.md. - Require impact analysis for shared package changes.
- Make release notes part of the done criteria.