At an organization with dozens of teams sharing internal library modules, how do you keep the api/implementation split from eroding over time, and what tooling or process actually enforces that a published api module's contract doesn't silently break its consumers?

## The enforcement layers Multiple enforcement layers work together at this scale. 1. **The first is a structural convention**: dedicated api artifacts, sometimes reinforced by a custom build-tool plugin that fails the build if an implementation artifact appears as a dependency anywhere outside the module that owns it - for example, a Gradle plugin that inspects the resolved dependency graph and errors out if `foo-impl` shows up as a dependency of any module other than foo's own runtime wiring code. 2. **The second layer is automated compatibility diffing**: tools like `japicmp` or `revapi` for Java compare a previously released jar's public signatures against a candidate build and categorize each change as source-compatible, binary-compatible, or breaking, failing CI on a breaking change unless the change is accompanied by an explicit major-version acknowledgment. 3. **The third layer is semantic versioning itself**, used as the communication contract between teams: a `MAJOR.MINOR.PATCH` scheme where only a major version increment may contain a breaking API change, letting consumers safely auto-upgrade minor and patch versions through their dependency manager while a major bump becomes a deliberate, visible signal requiring active review of a migration guide. 4. **A fourth layer, architecture-boundary tests** such as ArchUnit rules or a module-boundary verification tool, runs in CI to catch code reaching into another module's internal package even inside the same monorepo, independent of whether a separate published artifact exists at all. ## Why the layering is necessary This layered approach exists because manual vigilance does not survive organizational scale. - With two teams, a Slack message and a code review are enough; with dozens of teams releasing independently, no single reviewer sees every consumer of a shared module, and per **Hyrum's Law**, informal discipline fails exactly when it matters most - once a module has enough users, undocumented behavior gets depended on regardless of anyone's intentions. - The organization needs the api/impl separation's guarantee to hold without relying on any individual engineer's memory or goodwill, which in practice means encoding the rule as an automated, CI-enforced gate rather than a policy document nobody reliably reads. ## The trade-offs of the tooling The trade-offs of this tooling are real. - **Compatibility checkers** need baseline configuration and occasionally produce false positives - a change that is technically ABI-breaking but practically harmless, such as widening a parameter type, still needs a manual override or suppression annotation reviewed by a human. - **The semver discipline** itself imposes genuine process overhead, since every breaking change now needs a deprecation cycle, migration documentation, and cross-team coordination, which slows down API evolution compared to a single-team codebase that can just change everything atomically in one commit. - **Overly strict enforcement** can also push teams toward additive-only API design that never removes anything, accumulating years of cruft, because a proper deprecate-then-remove cycle is expensive to execute across an entire organization. ## Failure modes at this scale Failure modes at this scale are distinct from the single-team case. 1. A team may ship what they believe is a minor internal cleanup, but the compatibility checker was never configured to catch a specific class of breaking change - for instance, altering a default method's runtime behavior without touching its signature, which a purely signature-based checker misses entirely - and dozens of downstream services break simultaneously in production. 2. Conversely, teams learn to **game the checker** by only ever adding and never removing or changing anything, producing API modules cluttered with numerous overlapping deprecated methods that nobody dares delete. 3. And as a monorepo grows large enough, ArchUnit-style boundary tests can become slow or flaky, tempting teams to disable them under deadline pressure, which silently reopens exactly the leakage the whole system was built to prevent. ## How this looks at platform scale This is essentially how large platform organizations manage API evolution in practice: a public/internal split enforced structurally, compatibility diffing gating every release, and a documented semantic-versioning policy that lets many independent consuming teams upgrade a shared dependency with reasonable confidence that nothing will silently break - precisely because the enforcement is automated in CI rather than trusted to any individual engineer remembering the convention. The pattern generalizes beyond Java: any ecosystem publishing a shared library to many independent internal consumers eventually needs the same three ingredients - - a structural boundary, - an automated compatibility gate, - and a versioning policy that turns 'breaking change' into a visible, deliberate signal rather than a silent surprise. The underlying principle is the same one that motivates the api/impl split at the level of a single module, just applied recursively at organizational scale: the fewer things a team promises to keep stable, and the more automatically that promise is checked, the more freedom that team retains to keep improving what's underneath it.