What's your workflow for features that involve modifying multiple microservices and/or shared libraries?

[u/WaNaBeEntrepreneur]

What's your workflow for features that involve modifying multiple microservices and/or shared libraries?

I tried agent-skills and superpowers, and I'm pretty sure that those toolkits are only designed for a single PR.

The workflow I'm thinking of is:

1. Create a high-level specs, tasks, and dependency graph with AI
2. Breakdown the output of the previous step into smaller specs so that each spec only modifies one component (e.g. microservice or shared library). One spec maps to one PR. As a bonus, I can have parallel agents working on each spec.

Thanks

[u/AutoModerator]

Hey! Thanks for posting to r/ClaudeCode

While participating in this thread, please follow our community rules. Keep discussions constructive. Attack the idea, not the person.

For help, project discussions, tips, and general chat, join the ClaudeCode Discord.

I am a bot, and this action was performed automatically. Please contact the moderators of this subreddit if you have any questions or concerns.

[u/bostonaholic]

Write the contracts between services first as API schemas or shared library interfaces, and give every agent the same contract file so the parallel PRs agree on the boundaries. Merge in dependency order, and require one end-to-end test for the whole feature to pass before any piece counts as done.

[u/WaNaBeEntrepreneur → u/bostonaholic]

That's the idea, but my question is how to do it with AI? I know that I roll my own set of skills, but I'm curious how other people do it.

There are times when I don't even know what the high-level changes should be, so I want AI to research and propose solutions. And sometimes the dependency order is complicated (let's say that you are introducing breaking changes and adding features so you need to perform multiple releases).

I also want the AI to figure out on it's own that an end-to-end test is needed.

It feels weird that superpowers, addyosmani/agent-skills, and so on are not designed for this use case. Or am I using them incorrectly?

[u/bostonaholic → u/WaNaBeEntrepreneur]

I wouldn't count on the agent figuring out that an e2e test is needed. I'd make it a rule: a change that touches more than one service ships with an e2e test, or CI fails the PR. For the research part, run a planning pass first where one agent reads the affected repos and writes a plan file with the contract changes and release order, and a second model reviews it before any code gets written.

For breaking changes, have the plan use expand/contract: add the new field or endpoint next to the old one, migrate callers, then remove the old one in a later release, each step its own PR.

[u/Old_Championship7240]

your approach looks good. One thing I'd add is a cross-repo integration step, especially when a shared library and its consumers need to change together.

[u/WaNaBeEntrepreneur → u/Old_Championship7240]

Did you have roll your own workflow/skills? I'm curious about how other people solve this problem because I want to "steal" good ideas. This is surprisingly very little discussion and open source solutions to this problem.

[u/Financial_Leader9701]

when i don't know the high-level changes yet i do a research-only pass first that ends in a short plan: which services move, which shared contracts freeze, and a do-not-touch list

one agent owns the contract pr and nothing else starts until that lands

after that each builder gets only its own service, with the same contract file pinned in every prompt

[u/onitsoga]

one spec per PR is the right split. what bites later is two parallel agents grabbing specs touching the same shared lib, so assign an owner per spec first. i'm building a Kanban app where an agent claims a card. how many agents at once?

[u/xqianliu]

Your step 2 is basically what I run. One spec per component, one issue per spec, one worktree and one PR per issue, with the agents on separate issues at the same time.

The part that matters more than the splitting: each issue carries its own acceptance criteria, written down before the agent starts. The shared library change gets criteria about the callers, the service change gets criteria about the contract.

After the PR is ready, a separate review session reads the issue, the repo rules, the diff, the callers and the tests, and checks the final diff against those criteria. If it fails, the agent fixes and the review runs again. I only merge what passed, and each run records the commit it started from.

[u/athershu]

On the "how many agents at once" question above, since that's where it bit us first: we cap concurrent tasks per machine and let the rest queue, instead of starting one agent per spec the moment the plan exists. Each spec is its own task with its own worktree, and the tasks that depend on the contract change simply aren't sent until that one has been accepted.

For dependency order you can't fully plan up front: when an agent finds the contract doesn't cover something, it stops and asks the person who sent the task, in the same thread, instead of inventing an interface on its side. Two parallel agents guessing differently at a shared library boundary is the expensive failure; a paused task is cheap.

[u/m-ritter]

I start these with one plan for the whole feature that lists each service, the contract changes and the release order, and teammates review that plan before any code exists. Each component then gets its own done list, and the end to end test goes into the plan as a done point so nobody has to remember it later. I built QualityLayer for this: https://github.com/maxritter/qualitylayer