Multi-file refactors with Goatfied: case studies from real codebases

Single-file edits are where most AI coding tools live. Multi-file refactors are where they fall apart — and where real engineering time actually goes. Renaming a core type, extracting a module, or changing a function signature used in forty places is exactly the kind of tedious, error-prone work you'd love to automate, and exactly the kind that punishes a tool that can't hold the whole change in its head. Here's how Goatfied approaches it, illustrated with the patterns we see most often.

Why multi-file refactors are hard for AI

A refactor spanning many files has three failure modes:

1. **Partial application** — the tool updates ten call sites and misses the eleventh, so the build breaks in a way that only shows up in CI.

2. **Architecture drift** — given too much context, the model "improves" things you didn't ask it to, and now your small refactor is a 900-line diff nobody wants to review.

3. **Silent behavior change** — the signature changes but a default shifts, and a test that should have failed doesn't because it wasn't in scope.

Goatfied's design targets all three directly.

The approach: plan the whole change, apply it in reviewable slices

The agent loop plans the _entire_ refactor first — every file, every call site — then applies it as a coherent, reviewable change set. Crucially:

• It scopes retrieval to the touched files plus their direct dependents, so it sees every call site that matters without dragging in unrelated code.
• It keeps the diff tight to the plan. No opportunistic rewrites.
• It runs compile, lint, and targeted tests as a gate, so a partially-applied refactor never counts as "done."

If validation fails on a missed call site, the loop narrows to that file, fixes it, and re-validates — rather than handing you a half-finished change.

Case study 1: renaming a core domain type

**The task:** rename `Account` to `Workspace` across a backend used by a web app and a CLI.

The naive approach — find-and-replace — breaks on the cases that matter: a serialized field name that must stay `account` for backward compatibility, a database column, and a public API response.

Goatfied's plan separates these explicitly: rename the type and its internal usages, but _preserve_ the wire-format field and the column name via mapping. The gate catches the one integration test that asserts the old JSON shape, and the loop keeps that field name intact. You review a diff that's large but mechanical, with the one interesting decision — "we kept the wire field name" — called out.

Case study 2: extracting a module

**The task:** pull authentication logic out of a 2,000-line `server.ts` into an `auth/` module.

The risk here is circular imports and broken relative paths. The plan moves the functions, rewrites the imports at every call site, and adds the new module's barrel export. The compile gate is unforgiving about import cycles, so any mistake surfaces immediately and gets fixed inside the loop before you see it. The result is a diff you can actually review: a move plus a set of import updates, not a mysterious rewrite.

Case study 3: changing a signature across dozens of call sites

**The task:** add a required `context` parameter to a logging function called in ~40 places.

This is the classic "boring but dangerous" refactor. Miss one call site and the build breaks; pass a wrong default and you get silent behavior change. Goatfied enumerates every call site in the plan, threads the parameter through with a safe, explicit value at each, and the targeted tests confirm the logging behavior didn't drift. The failure notes from any missed site feed the retry, so the second pass is clean.

What makes it work

Across all three, the same principles carry the weight:

• **Plan the full change before editing.** Multi-file refactors fail when they're applied incrementally without a map. The plan _is_ the map.
• **Keep diffs reviewable and reversible.** A refactor you can't roll back in minutes is a refactor you can't safely delegate.
• **Gate on compile, lint, and targeted tests.** Partial application is the number-one refactor failure mode, and the gate is what catches it.
• **Precise context, not maximal context.** Seeing the call sites that matter — and not the ones that don't — is what prevents architecture drift.

Using Goatfied for your own refactors

• Describe the refactor as an outcome plus the invariants that must hold ("rename the type, but the JSON field stays `account`").
• Point it at the repos involved — Goatfied supports cross-repo, long-running tasks.
• Let the gate do its job: review the green diff, not the model's stream of consciousness.

Multi-file refactoring is where an AI tool proves whether it understands your code or just autocompletes it. Goatfied is built to treat the whole change as one reviewable, validated unit — which is the only way this kind of work is safe to hand off.

Related reading

• [The Goatfied agent loop: how we ship code that compiles first try](/blog/goatfied-agent-loop-compiles-first-try)
• [Goatfied vs Cursor vs GitHub Copilot: how to benchmark them on real PR tasks](/blog/goatfied-vs-cursor-vs-github-copilot-benchmark-50-pr-tasks)