Run the Same Refactor Across Many Repos With One Prompt

Changing one function signature inside a single repo is a five-minute job. Changing that same signature across nine repos that all call it, when three of them are owned by other teams and deploy on their own cadence, is a week of coordination. That's the job a multi-repo refactoring prompt is built for: not the edit itself, but the sequencing, the contract versioning, and the rollout order that keeps everything green while the change is half-done.

Most published guidance on AI refactoring is monorepo-shaped. It assumes you can change a shared type and fix every caller in one atomic commit. Separate repositories break that assumption hard. The change lands at different times, in different deploy windows, often without you holding the merge button for the downstream repos. So the planning has to account for a system that's inconsistent for hours or days while the migration rolls through.

This post covers the prompt that produces that plan, and the prompt-craft patterns that keep it honest.

Why the same refactor is harder across separate repos

A multi-repo refactor is a single logical change that has to be applied independently to several repositories that share a contract but not a build. The hard part isn't the code. It's the ordering and the overlap window.

Three things make it different from the monorepo case:

1. No atomic commit. You can't change a producer and its consumers in one PR. The producer ships, then each consumer catches up on its own timeline. Between those events, both the old and new shapes have to work.
2. Shared contracts are live. If repo A publishes an API or a package that repos B and C depend on, you can't just rename the field. You version it, ship both, migrate the consumers, then remove the old one. That's three rollouts, not one.
3. Ownership is split. Some of those consumer repos belong to other teams. The plan has to produce a PR description and a deprecation note they'll actually act on, not just a diff.

The pages that currently rank for cross-repo refactoring gloss over this. Augment Code's multi-file refactoring guide mentions changes that "span multiple repositories" and a system that "makes them all at once," but its detailed walkthrough is a single Python rename inside one repo, and it gives no copyable prompt or sequencing mechanics. The Moderne and large-scale-refactoring tooling write-ups lean on platform automation that rewrites code across repos in bulk, which is great if you've bought the platform, but says nothing about how to plan the change with a model you already pay for. The gap is a copyable prompt with a locked output contract that any team can run today.

What you can do with this prompt

• Turn a one-line change ("rename userId to accountId everywhere") into an ordered, repo-by-repo migration plan.
• Decide which repo is the producer and must change first, and which are consumers that follow.
• Generate the versioning strategy for a shared API or package so nothing breaks during the overlap.
• Produce per-repo diffs plus the PR description for the teams that own each consumer.
• Get a rollback point for each step, so a failed deploy doesn't strand the system half-migrated.
• Output a verification checklist that proves each repo is consistent before the next one moves.

Anatomy of the prompt

The structure that holds up puts the inventory and the contract first, the change second, and the output contract last. Models weight the most recent tokens, so the format spec belongs at the end where it won't get buried under repo context.

Variables
  {{repo_inventory}}   → name, role (producer/consumer), language, deploy cadence per repo
  {{shared_contract}}  → the API/package/type every repo depends on
  {{target_change}}    → the refactor in one sentence
  {{constraints}}      → freeze windows, teams you can't block, must-stay-backward-compatible

Prompt
  Role: staff engineer planning a cross-repo migration.
  Task: order the repos, version the shared contract, and plan rollout.
  Context: the variables above.

Output contract (locked)
  1. Dependency graph: which repo depends on which
  2. Sequence: ordered list, producer-first, with the reason each repo is at that position
  3. Per-repo plan: the diff, the PR title/description, the rollback point
  4. Contract versioning: how the old + new shapes coexist during overlap
  5. Verification: the check that must pass before the next repo moves

1. Gather inputs

List every repo touched by the change. For each, note whether it produces the shared contract or consumes it, what language it's in, and roughly how often it deploys. The deploy cadence matters more than people expect. A consumer that ships once a sprint sets the length of your overlap window.

2. Fill the variables

Paste the inventory into {{repo_inventory}}. Name the exact thing that's shared in {{shared_contract}} (a REST field, a gRPC message, a published npm package, a shared TypeScript type). Write the change in one sentence in {{target_change}}. Be specific in {{constraints}}: "marketing-web deploys Tuesdays only" or "the billing team can't take a breaking change before Q3."

3. Run the prompt and read the sequence first

Before you look at any diff, read the ordering and the reasoning. If the model put a consumer ahead of its producer, the inventory was wrong or the roles were mislabeled. Fix the input, don't argue with the output.

4. Execute one repo at a time

Hand each per-repo plan to a coding agent or do it by hand. The point of the sequence is that you finish and verify one repo, confirm the system is still consistent, then start the next. Never open all nine PRs at once.

5. Iterate on the overlap

The contract-versioning section is where reality bites. If the plan says "ship both userId and accountId for two weeks," that's a real two weeks of dual-write or dual-read code you have to add and later remove. Budget for the cleanup pass. It's a separate, smaller refactor of its own.

Prompt-craft patterns that make it reliable

Pattern 1: producer-first sequencing as a hard rule

Tell the model the rule explicitly instead of hoping it infers ordering from the dependency graph.

Hard rule: a consumer repo NEVER changes before the producer it depends on
has shipped the new contract. If two repos both produce and consume, split
them into two steps and order each half independently.

Without this, models occasionally output an alphabetical or size-based order that looks tidy and breaks production. State the invariant.

Pattern 2: force the backward-compatible overlap into the output

For any shared contract change, the plan MUST include an overlap phase where
both the old and new shape are valid. Name the mechanism (additive field,
versioned endpoint, aliased export) and the exact step that removes the old
shape. A plan that flips the contract in one step is invalid output.

This is the pattern that separates a usable plan from a dangerous one. Claude honors a hard "this output is invalid if X" instruction more reliably than a soft "please consider backward compatibility." GPT-4o tends to need the rule restated near the end of the prompt to keep it from drifting on long repo lists.

Pattern 3: a rollback point per step, not per migration

Each step in the sequence gets its own rollback point: the commit/tag to
revert to and the one check that confirms the revert is clean. Do not output
a single rollback for the whole migration.

A migration that's only reversible as a whole isn't reversible in practice. Per-step rollback is what lets you stop safely when repo five's deploy goes sideways.

Here's the opinionated part. Don't ask one model to refactor all the repos in a single call, even with a huge context window. The plan is the durable artifact; the edits are disposable. A clean sequence with per-repo diffs that a human reviews beats a 50-file mega-diff nobody can audit. Splitting planning from execution is the whole point, and it's the thing the "make them all at once" marketing quietly skips.

Variables you'll set

Getting started

1. List every repo the change touches and tag each as producer or consumer.
2. Name the one shared contract precisely. If there are two, run the prompt twice.
3. Fill {{target_change}} in a single sentence. Vague changes produce vague plans.
4. Run the prompt and read the sequence and reasoning before any diff.
5. Execute repo one, verify consistency, then move to repo two.
6. Schedule the overlap-cleanup pass as its own task once every consumer has migrated.
7. For a recurring cross-repo cadence, reach for the Multi-Repo Orchestration Agent Pack rather than rebuilding the plan each time.

If your change is contained to one repo with internal modules instead, the Monorepo Impact Analysis Agent Pack maps the blast radius inside a single tree, and a cross-language refactor prompt handles the case where the same logic has to move between languages.

The plan is the artifact that survives the migration. A spreadsheet of "who changes when" goes stale the moment the first deploy slips. A prompt you re-run against the current repo inventory doesn't. For the wider story on scoping change before you touch code, the change blast-radius prompt and the technical-debt triage prompt both feed the same planning muscle.