You own a widely used shared library whose consumers each pull it in for only one of five unrelated feature areas. Walk through how you would apply the Common Reuse Principle to split it, and what new costs the split introduces.

## Step 0 — Confirm the problem is real Don't split on aesthetics. Collect three numbers: 1. **Usage matrix.** For each consumer, which public types does it actually reference? Get this from import scanning, build-graph analysis, bytecode/AST references, or published-API telemetry. The output is a consumer × class matrix. 2. **Irrelevant-release rate.** Over the last N releases, what fraction was driven by code a given consumer never uses? This is the direct cost of the CRP violation. 3. **Transitive attribution.** Which third-party dependencies exist in the tree *only* because of a particular feature area? That is the closure a split would remove for everyone else. If the matrix is dense (most consumers use most of it), you do not have a CRP problem and splitting will only add cost. ## Step 1 — Cluster by observed joint usage Group classes so that within a group, classes tend to be used by the same consumers; across groups, usage is disjoint. Practical rules: - **Keep structurally inseparable things together.** An interface with its primary implementation; a type and the types in its method signatures; a builder/factory and its product; an exception hierarchy and the API that throws it. Splitting these produces components that are useless alone — the opposite CRP failure, since a consumer must then take all the fragments anyway. - **Beware the "shared kernel".** Usually a handful of types (config, error types, core value objects) are used by all five areas. Do not duplicate them and do not let the five components depend on each other to get them. Extract them into a **core** artifact that everything depends on and that depends on nothing. It should be the most stable component in the set (Stable Dependencies Principle: depend in the direction of stability). - **Check for cycles.** If two proposed components would depend on each other, the seam is wrong; either merge them or extract the shared abstraction into core. Cycles across published artifacts violate the Acyclic Dependencies Principle and are far more painful than in-process cycles because they force lockstep releases. ## Step 2 — Choose the granularity deliberately Five feature areas does not necessarily mean five artifacts. Merge areas that are always used together or always change together (the CCP pull). Ask what an artifact-count budget can bear: every artifact carries fixed overhead — pipeline, ownership, changelog, docs, deprecation policy, security review. Prefer the smallest number of artifacts that eliminates the observed irrelevant-release traffic. ## Step 3 — Migrate without breaking anyone The safe pattern: 1. Publish the new fine-grained artifacts (`lib-core`, `lib-pdf`, `lib-events`, ...) at 1.0. 2. Republish the **original coordinates** as a thin **aggregator**: same group/name, new version, containing no code, depending on all the new artifacts and re-exporting their API. Existing consumers upgrade and keep compiling with zero source changes. 3. Mark the aggregator deprecated, publish a mapping table ("class X now lives in lib-pdf"), and give a dated end-of-life. 4. Help consumers migrate (codemods, dependency-report tooling, a migration guide). 5. Retire the aggregator. Avoid the two common mistakes: a big-bang split with no aggregator (breaks everyone at once), and an aggregator with no end-date (nothing ever migrates and you now maintain N+1 artifacts forever). Also decide the **versioning policy**: independent semantic versions per artifact (maximum CRP benefit; requires a documented compatibility matrix), versus a single train version applied to all (simpler to reason about but reintroduces lockstep and thus much of the original problem). If the seams are good, independent versioning is the right answer; if you find you must always bump all five together, your seams follow change lines that never diverge and the split bought you less than you hoped. ## Step 4 — Verify the benefit Re-measure after a quarter: irrelevant-release rate per consumer, transitive-tree size, CVE count, build/bundle size. If the numbers didn't move, the split was cosmetic. ## The new costs, stated plainly - **Release and versioning overhead** times N: changelogs, release notes, compatibility matrix, CI pipelines, publishing credentials. - **Coordination cost** for cross-cutting changes (a change touching core plus three areas now needs an ordered, multi-artifact release — the CCP penalty). - **Diamond risk:** consumers may end up with two artifacts pinning different versions of core. - **Discovery friction:** newcomers must learn which artifact holds what; mitigate with docs and a BOM/platform manifest that pins a compatible set. - **Ownership dilution:** more artifacts than the team can meaningfully own leads to unmaintained ones. - **Refactoring friction:** moving a class between artifacts is now a breaking, semver-visible change rather than an internal edit. A BOM (bill of materials) or version-catalog artifact that pins a known-good combination is the standard mitigation for the diamond and discovery costs.