Skip to content

Service Boundaries

Principle · service-boundaries

Loads automatically whenever the agent touches code this principle governs. Install the skills · View source

Almost every painful microservice system is painful for the same reason: the boundaries were drawn around technical nouns or team convenience rather than around units of business change. A wrong boundary is the most expensive mistake in this library — it is not refactorable inside one repository, and it shows up as chatty calls, shared databases, and lockstep releases.

The default answer to "should this be a new service?" is no, not yet. Make the case.

Config Resolution

  1. Read .msskills/config.yaml in the repo root; look up paths.boundaries.
  2. A custom document exists at that path → read its frontmatter mode:
  3. override → use it alone; ignore the defaults below.
  4. overlay (default, or no mode key) → read defaults first, then apply the custom document's sections on top, matched by exact heading; new sections append.
  5. A path is configured but no file exists there → say which path is missing, then use the defaults.
  6. No config file or no paths.boundaries key → use defaults.
  7. .msskills/context-map.md exists → treat it as the current record of contexts and their relationships. Any change to a boundary updates that file.

Self-Validation Checklist

STOP before proposing any boundary — a new service, a split, a merge, or a module. Verify every check. Fix failures before presenting.

  1. BUSINESS CAPABILITY: Can you name the boundary as a capability the business would recognise — pricing, fulfilment, identity? If the name is technical (api-service, db-writer, orchestrator) → you have drawn a layer, not a boundary. Redraw around the capability.
  2. UBIQUITOUS LANGUAGE: Inside this boundary, does each term have exactly one meaning? If "order" means two different things in two places → those are two contexts, and the boundary runs between them.
  3. DATA OWNERSHIP: Does exactly one service write each piece of data? Two writers to one table, or a shared database → the boundary is wrong or the split is incomplete. Fix before proceeding.
  4. AUTONOMY: Can this service serve its primary use case when every other service is down? If not, list which hops break it and justify each one — every synchronous dependency multiplies into the availability budget (see resilience-patterns).
  5. CHANGE COUPLING: Do the last several changes to this area touch this boundary alone? If a typical feature edits three services → the boundary cuts through a single unit of change. Merge or redraw.
  6. CHATTINESS: Does one user-facing operation cross this boundary more than once or twice? A loop of remote calls, or fetching data only to send it straight back → the data or the logic is on the wrong side.
  7. TRANSACTION FIT: Does any single invariant need to hold across this boundary atomically? If yes → either it belongs in one service, or the invariant becomes a saga with compensation, which is a decision the user must make (see cqrs-and-consistency).
  8. TEAM FIT: Can one team own this end to end? A boundary that needs two teams to agree on every release is a distributed monolith with extra latency.
  9. JUSTIFIED SPLIT: For a new service specifically — which concrete force requires separate deployment: independent release cadence, divergent scaling, isolation of failure, regulatory separation, or team ownership? "Cleaner" and "more scalable" are not forces. If none applies → propose a module inside the existing service instead.

All checks pass → state "Boundary holds: , owns , autonomous except ."

Active Anti-Pattern Scan

Any box you can check is a defect. Fix it before presenting.

  • [ ] Distributed Monolith: services that must deploy together, share a database, or break when a sibling is down → merge them, or make the coupling asynchronous.
  • [ ] Entity Service: a service per database table (CustomerService, AddressService) with no behaviour of its own → collapse into the capability that owns the behaviour.
  • [ ] Nano-Service: a service whose entire job is two endpoints wrapping one table → the operational cost exceeds its value; fold it in.
  • [ ] Shared Database: two services reading or writing the same schema → publish an API or events instead; the schema is an implementation detail, not a contract.
  • [ ] God Service: one service everything depends on, changed by every feature → split along the capabilities that change independently.
  • [ ] Chatty Boundary: N+1 remote calls, or a call in a loop → move the query, batch it, or move the data.
  • [ ] Layer as Boundary: services named for tiers (api, business-logic, data-access) → that is clean-architecture inside one service, not a decomposition.
  • [ ] Leaked Language: another context's terms and identifiers used raw in this one → add an anti-corruption layer and translate at the edge.
  • [ ] Conway Mismatch: a boundary no single team owns → align to team, or accept and document the coordination cost.
  • [ ] Premature Extraction: a service split out of a system whose domain is still moving → keep it a module until the seam has stopped shifting.

Ambiguity Signals

Route these through collaborative-judgment. Each has two defensible answers.

  • Module or service. Both give the same logical boundary; only one gives independent deploy and independent failure — at the cost of a network hop, a contract, and an operational surface. Present the forces, and lean toward the module until one of them clearly applies.
  • Duplicate the data or call for it. Owning a replica removes a runtime dependency and adds staleness plus a second source of truth. Neither answer is free.
  • Where an ambiguous entity lives. A concept that appears in two contexts (a "product" in catalogue and in fulfilment) may be one shared entity or two models with a translation between them. Two models is usually right and always more work.
  • Splitting for scale. Real when one part's load profile genuinely diverges; a rationalisation when the whole system is comfortably within one instance. Ask for the numbers.
  • Extraction order. Which seam to cut first in a monolith trades risk against value — the safest extraction is rarely the one that relieves the most pain.