Skip to content

skillBackend and APIs

Microservice Boundaries

Finds real seams in a monolith, assigns data ownership, and proposes a migration order that extracts one service at a time with a clear reason.

npx workspacetemplates add microservice-boundaries --tool claude-code

Writes 1 file to .claude/skills/microservice-boundaries/

.claude/skills/microservice-boundaries/SKILL.md28 lines · 1.9 KBFile
---
name: microservice-boundaries
description: Finds real seams in a monolith, assigns data ownership, and proposes a migration order that extracts one service at a time with a clear reason.
---

# Microservice boundaries

Find seams in the evidence. Do not draw them on a whiteboard.

## Steps

1. Map the modules: directories or packages, and for each one the tables it reads and writes (grep for table names, ORM models and raw SQL), the modules it imports, and who commits to it (`git shortlog -sn -- <path>`).
2. Build the dependency picture: count imports between modules in both directions and count cross-module joins and shared tables. Two modules that write the same table are one service until proven otherwise.
3. Score candidates. A good seam has few inbound calls, a table set nobody else writes, a distinct rate of change or scaling need, and one owning team. Rank candidates by this score.
4. For the top candidate, list every call that would become a network call, with its frequency and whether it is in a user-facing request path. More than a few synchronous calls per request means the seam is wrong.
5. Define data ownership: the service owns its tables; others read through an API or a replicated read model fed by events. Name the events.
6. Plan the extraction: first isolate behind an interface inside the monolith, then move the tables to a separate schema, then run the new service in parallel, then switch the traffic, then delete the old code.
7. Estimate cost honestly: deployment, monitoring, tracing, local development and distributed failure handling.

## Rules

- Never propose shared databases between services as the end state.
- Never propose more than one extraction at a time.
- If no seam scores well, recommend a modular monolith and list the boundaries to enforce with lint rules.

## Report

The map, ranked candidates with evidence, the recommended first extraction with its steps, and the risks.

What it does

Most failed service splits cut along technical layers or along the org chart instead of along the data. The result is services that must change together and call each other on every request. This skill has the agent look at coupling in the code and the database first.

It produces a short, evidence-based proposal: which module could move out, who owns which tables, what calls would become network calls, and in what order to extract. It also says when to stay a monolith.

Example

you › Should we split billing out of our Rails monolith?

agent › Billing owns 6 tables and no other module writes them; 4 inbound calls, none in the checkout path after a change of the invoice preview to a local read model. Two teams commit to it. Recommended first extraction: billing, in 5 steps starting with a Billing::Gateway interface. Not recommended: splitting notifications; it joins 3 shared tables.

Questions

Will it tell me to stay a monolith?
Yes, if the evidence does not support a split. A modular monolith with enforced boundaries is a legitimate result.
Does it change any code?
Analysis only by default. It edits code only for the first isolation step, and only after you approve the plan.
  • API Error Responses

    SkillBackend and APIs

    Free
  • API Pagination Design

    SkillBackend and APIs

    Free
  • API Versioning Strategy

    SkillBackend and APIs

    Free
  • Background Job Design

    SkillBackend and APIs

    Free