How to Write a Build System Migration Prompt for a Messy Monorepo

Most monorepos don't start unified. They accrete. One team wired Webpack, another added a Makefile, a third dropped in Gulp for a legacy package, and now a single npm run build fans out into six toolchains that nobody fully understands. A build system migration prompt turns that mess into a sequenced plan instead of a six-week spike.

The problem isn't picking a tool. That part's easy to read about. The problem is the migration: which package moves first, what breaks when it does, and how to keep CI green while half the repo runs on the old system and half on the new one.

Search "Nx vs Turborepo vs Bazel" and you'll drown in comparison posts. They're useful for a first read and useless the morning you actually have to move. This post is about the prompt that does the moving.

Why comparison articles leave you stuck

The ranking pages for monorepo tooling are almost all the same shape. Sourcegraph's monorepo build tools guide (updated May 2026, ~3,500 words) runs a clean evaluation matrix and a "choose by stack and team size" section, then closes with a demo CTA. It's a strong selection guide. It has no migration plan. A widely-shared DEV Community piece (May 2026, ~2,000 words) does better and includes a four-step polyrepo-to-Turborepo path, but it's generic: create the structure, move packages, fix dependencies, add shared configs. None of it knows your repo.

That's the gap. These articles answer "which tool," and you already suspect the answer. What you don't have is the ordering for your dependency graph and your CI. That's exactly what a prompt with your inputs can produce.

What you can do with this prompt

• Audit every build tool, script, and config across the repo into one table
• Justify a single unified system against your language mix and team size
• Sequence package migrations so leaf packages move before their dependents
• Design a remote caching setup so CI doesn't recompute unchanged packages
• Draft the CI pipeline changes each migration step needs
• Hand a reviewer a plan they can veto step by step, not a black box

Anatomy of the prompt pack

The structure that holds up here is an audit prompt feeding a decision prompt feeding a sequencer. Each stage takes the prior stage's output as a variable, so you're never re-explaining context.

Variables → Prompt → Output

{{repo_build_profile}}      # languages, package count, current tools
{{repo_constraints}}        # team size, CI provider, deploy cadence
        │
        ▼
Current-State Build Audit  → {{build_audit_table}}
        │
        ▼
Tool Fit Analysis          → {{chosen_tool}} + rationale
        │
        ▼
Migration Sequencing       → ordered package list
        │
        ▼
Caching and CI Plan        → {{ci_setup}} changes

The {{build_audit_table}} from stage one becomes an input to stage two. That handoff is the whole trick. When each prompt restates the audit in its own words, the plan drifts; when the table is passed verbatim, the sequencer reasons against real package names.

Step-by-step usage

1. Build the inventory

Don't describe your build setup in prose. List it. For {{repo_build_profile}}, dump the package names, each package's current build command, and the language. A find . -name "package.json" plus your CI config is usually enough raw material.

2. Set the constraints

{{repo_constraints}} is where you make the prompt honest. Team size changes the answer. A four-person team shouldn't adopt Bazel because a Google engineer blogged about it. State your CI provider, your deploy cadence, and any hard limits (a package that must stay on its own toolchain, a compliance rule).

3. Run the audit and read it before moving on

The audit stage produces {{build_audit_table}}. Read it. If it missed a package or mislabeled a toolchain, fix the input and rerun. Everything downstream inherits this table, so a wrong cell here poisons the sequence.

4. Let the fit analysis argue

Feed the table into the fit analysis. A good output names {{chosen_tool}} and the two runners-up it rejected, with reasons tied to your constraints. If it just says "use Turborepo" with no rejected alternatives, the reasoning's too thin to defend in a design review.

5. Sequence, then stage the CI

The sequencer orders packages leaf-first. Then the caching plan produces the {{ci_setup}} changes each step needs. You migrate one slice, watch CI, migrate the next.

Prompt-craft patterns that matter here

Pass the artifact, not a summary. The single biggest reliability win is feeding {{build_audit_table}} into the next stage as-is. Claude holds a pasted table across a long prompt more faithfully than it holds a paraphrase it generated three turns ago. Restated context is where migration plans invent packages that don't exist.

Force the rejected options. A one-line role plus a hard output contract beats a long persona. Tell the model to output the chosen tool, the rejected tools, and one sentence of rationale each. Here's the shape:

Role: You are a build engineer planning a monorepo unification.
Task: From the audit table, recommend one build system.
Output contract:
- Chosen system + 2-sentence rationale tied to the constraints
- Two rejected systems, one sentence each on why not
- Confidence: high | medium | low
No preamble.

That "two rejected systems" line does real work. It stops the model from rubber-stamping the trendiest tool and makes the recommendation reviewable.

Sequence leaf-first, explicitly. Tell the sequencer to order packages by ascending dependent-count so the first migrations touch the fewest consumers. A big-bang cutover is the failure mode; incremental keeps CI green. That's the opinionated take here: unify incrementally or don't bother. A migration that turns the build red for a week gets reverted, and the mess wins.

Variables you'll set

Getting started

1. Export your package list and CI config as raw text.
2. Fill {{repo_build_profile}} and {{repo_constraints}}.
3. Run the audit; verify {{build_audit_table}} matches reality.
4. Run the fit analysis; confirm it rejected the alternatives with reasons.
5. Generate the sequence; sanity-check that leaf packages come first.
6. Stage the {{ci_setup}} changes one migration slice at a time.
7. Pair it with a blast-radius check before each slice ships.

Before you touch any package, it's worth knowing what a change actually breaks. The monorepo impact analysis prompt covers that check, and it pairs naturally with a staged build migration. If your migration also drags a framework version forward, the framework migration prompt handles that half.

One caveat worth stating: any recommendation a model makes about your build is a starting hypothesis, not gospel. Pin your tool versions, run the first migration slice on a low-traffic package, and keep the old build path until the new one's proven. For repos spanning several services, the monorepo impact analysis pack and the framework migration playbook extend the same staged discipline past the build layer.