Skip to content

Cross-Team Interface Contract

Interface protocol — instantiates Organization–Artifact Topology Alignment

Turns a boundary between two teams into an explicit, versioned contract — the promised interface and handoff terms — so the teams can evolve independently without renegotiating every change.

Some seams between teams should persist — the answer isn't always to redraw them. Cross-Team Interface Contract is what you reach for when a boundary is worth keeping: it freezes the interface across that seam into an explicit, versioned agreement — the schema, the semantics, the handoff terms, the deprecation policy — so each side can change its internals freely as long as the contract holds. Its defining move is to convert an ongoing, ad-hoc coordination cost into a managed, stable interface: the point is decoupling two teams' work rhythms, not mapping the boundary (the reviews do that), deciding whether it should exist (the domain review and refactors do that), or recording the decision (the register does that).

Example

In a car manufacturer, the infotainment team ships quarterly while the powertrain team moves slowly under safety certification — and both touch the vehicle's internal bus. Every infotainment change used to trigger a powertrain review, coupling two teams that should have been able to work on their own clocks. They write a Cross-Team Interface Contract: a versioned set of bus messages — IDs, units, ranges, update rates — that powertrain promises to emit and infotainment promises to consume, with a stated deprecation window for any change. Now infotainment ships without waiting, and powertrain reworks its internals freely, so long as the contracted messages stay stable. The seam didn't move; it became something both teams can rely on and evolve against.

How it works

What distinguishes it from an informal "we agreed on the API" is that the agreement is made binding and testable:

  • Freeze the interface — schema plus semantics plus handoff SLAs — into a single versioned artifact both teams own.
  • Route change through versioning, not renegotiation: a deprecation policy governs how the contract evolves, so neither side is surprised.
  • Verify automatically where possible — ideally consumer-driven contract tests in CI, so a breach fails a build rather than production.
  • Scope it to a seam worth keeping — it manages an existing boundary; it does not judge whether that boundary should exist.

Tuning parameters

  • Contract strictness — schema-only versus schema-plus-semantics-plus-SLA. Stricter buys more independence but costs more to write and maintain.
  • Versioning policy — how many versions are supported at once and how long the deprecation window runs. Longer windows smooth evolution but add maintenance.
  • Verification — handshake documentation versus consumer-driven tests in CI. Automated verification catches breaches early but needs upfront investment.
  • Ownership of the contract — one side versus joint. Joint ownership is fairer but slower to change.
  • Scope — a single message set versus the whole boundary between two teams.

When it helps, and when it misleads

Its strength is decoupling release cadences and localizing change: a stable contract is frequently far cheaper than restructuring the teams or the artifact, and it lets a fast team and a slow team coexist across a boundary.

Its failure mode is the mirror image of that strength — a contract can ossify a seam that should not exist, dressing coupling that ought to be removed in enough ceremony that nobody questions it. The classic misuse is writing ever-thicker contracts to defend an organizational boundary that is actually the wrong place for a seam. The discipline that guards against it is to treat contracts as instruments for stable boundaries: if a seam needs constant renegotiation and its contract keeps churning, that is a signal to restructure — hand the boundary to an artifact refactor or a team redesign — rather than to write more contract.[1]

How it implements the components

Cross-Team Interface Contract fills exactly one part of the archetype's machinery — the interface artifact at a seam:

  • interface_and_handoff_contract_set — the versioned set of interface and handoff terms it defines, verifies, and maintains across a team boundary.

That single component is deliberate. It does not model ownership_and_decision_rights_model — who owns the decision is recorded by Architecture Decision Record with Ownership — and it is not the boundary_spanning_role_or_forum: the human channel across teams is the Liaison or Architecture Forum. It manages a seam; it does not decide whether the seam should exist, which belongs to the Bounded Context or Domain Boundary Review and the refactors.

Notes

A contract is a bet that a seam is stable and worth keeping. So the number of contracts at a boundary is itself a diagnostic: when they multiply and keep needing new versions, that is evidence the boundary is in the wrong place — a prompt to restructure, not to keep contracting.

References

[1] In the consumer-driven contracts pattern (described by Ian Robinson and others), the consumers of an interface express their expectations as tests the provider runs, so a breaking change is caught in the provider's build. It is the right tool for a stable, worth-keeping seam; it is a poor substitute for removing a seam that shouldn't be there. ↩