Architecture Governance
Architecture invariants
Record architectural boundaries and invariants in ARCHITECTURE.md so AI agents do not break them by accident.
Typical invariants include:
- Which layer owns domain logic
- Which modules may call external APIs
- Authentication boundaries
- State-management boundaries
- Databricks access boundaries
- Frontend/backend responsibilities
- Dependency direction
- Integration boundaries
Keep ARCHITECTURE.md short. It should answer one question:
What must remain true about the current architecture?
See Required Project Documentation for when ARCHITECTURE.md is required.
Architectural decision records
Record each major architectural decision in its own ADR using the shared ADR template.
An ADR covers:
- Context
- Decision
- Alternatives considered
- Reasoning
- Consequences
ADRs prevent contributors and AI agents from changing the architecture by accident. Revise them when the architectural decision needs to change.
When a user's request conflicts with an ADR:
- Understand the user's actual intent.
- Understand why the ADR exists.
- Evaluate the impact of changing the decision.
- Prefer a solution compatible with the existing architecture when reasonable.
- If the architecture genuinely needs to change, explain the impact.
- Update or supersede the ADR explicitly.
Do not silently violate an ADR.
If the user is uncertain whether the architecture should change, help analyze the consequences before making the change.