Gemini 4 Argon Codebase Refactoring: A Workflow That Ships

Gemini 4 Argon codebase refactoring works best as a three-part setup: a rulebook in .agents/skills that tells the model how your repository wants to be changed, a one-paragraph goal that says what "done" means, and a run in Google Antigravity that's allowed to produce several small, independent changes instead of one giant diff. That's the pattern Google describes for both the Chrome architecture split and the Agent Development Kit (ADK) performance pass, and it transfers to an ordinary-sized codebase without much adaptation.

The rest of this piece walks through each part in order: what goes in the rulebook, how to write the goal so an overnight run doesn't wander, how to record a baseline so a performance pass produces real numbers, and the mistakes that turn an autonomous refactor into an unmergeable branch.

What Google's own Argon refactors tell you#

Two examples from the launch announcement are worth reading closely, because they describe a workflow and not just a result.

The Chrome team used Argon to separate core webpage handling from a legacy folder of browser features. The folder was about 6 million lines inside Chromium's 40 million-line codebase. The refactor touched hundreds of files, and the model worked by "piping multiple clean code changes at a time" rather than producing one enormous patch. Months of planned work finished in weeks.

The ADK team ran a performance pass on a production Python codebase. They gave Argon their .agents/skills rulebook plus a one-paragraph goal: eliminate framework overhead without breaking existing apps. The model worked autonomously overnight in Antigravity and surfaced optimizations that are now live in google/adk-python. The published results were in-memory session prep time cut by 40% in long sessions and cold imports sped up by 21%.

Across Google more broadly, Argon in Antigravity increased agentic code submissions by more than 35% while reducing rollbacks by nearly a third. The rollback figure matters more than the submission figure. It means the small-changes approach wasn't just faster, it was also safer to merge.

Four things are common to both stories, and they're the skeleton of everything below:

• A written rulebook the model reads before touching code.
• A short goal with a constraint built in ("without breaking existing apps").
• Many small changes instead of one branch.
• A measurable definition of success, either tests passing or a number moving.

Step 1: write the skills rulebook before the goal#

The ADK team's rulebook lived in .agents/skills. The announcement names the directory but doesn't publish a file schema, so treat the layout as Antigravity's concern and focus on content. My recommendation is one short markdown file per topic, each one answering a question the model will otherwise guess at.

For a refactor or performance pass, the rulebook needs to cover:

• How to run the tests, including the exact command and which suites are slow enough to skip during iteration.
• How to measure, meaning the benchmark script, where the baseline lives, and what counts as a regression.
• Forbidden zones, such as public API signatures, generated code, vendored directories, and database migrations.
• Change size, for example one logical change per commit, each one passing tests on its own.
• Reporting, meaning what to write down when a change was attempted and abandoned.

A minimal performance skill looks like this:

# Performance pass rules

- Baseline numbers are in bench/baseline.json. Run `python bench/run.py` before and after every change.
- A change ships only if the median improves and no other metric gets worse by more than noise.
- Never change a public function signature in src/framework/api/.
- One optimization per commit. Commit message states the metric and the before/after numbers.
- If a change needs a migration or a config flag, stop and write it up instead of doing it.

The last line is the most important one. Argon was trained to pause for human confirmation before irreversible steps and to report negative findings honestly, and on coding benchmarks shortcut attempts dropped to 2%. A rulebook that spells out the stop conditions gives that training something concrete to act on.

Step 2: write the one-paragraph goal#

The ADK goal was one paragraph. That's a feature, not a shortcut. A long design document invites the model to pick its own favorite section and run with it. A paragraph with four parts leaves no room for that.

The four parts I'd always include are the outcome, the scope, the proof, and the hard stop. Here's a small script that assembles the paragraph and checks nothing was left blank:

# Build a one-paragraph goal and check it has the parts an autonomous run needs.
goal = {
    "outcome": "cut framework overhead in the request path",
    "scope": "src/framework/ only; do not touch public API signatures",
    "proof": "pytest passes and bench/baseline.json numbers do not regress",
    "stop": "stop and report if a change needs a schema migration or a new config flag",
}
paragraph = (
    f"Goal: {goal['outcome']}. Scope: {goal['scope']}. "
    f"Done means: {goal['proof']}. Hard stop: {goal['stop']}."
)
print(paragraph)
print()
missing = [k for k, v in goal.items() if not v.strip()]
print(f"words: {len(paragraph.split())}, missing parts: {missing or 'none'}")

For an architectural refactor rather than a performance pass, the outcome changes but the shape doesn't. Something like: move everything under browser/features/ that doesn't depend on tab state into core/, keep every existing test green, don't change behavior, and stop if a move requires editing more than one public header.

In Antigravity the goal goes in through the /goal slash command, which the announcement mentions alongside multi-agent loops with custom skills. The paragraph you just wrote is the argument.

Step 3: record a baseline so "faster" means something#

The ADK results were reported as percentages against a measured baseline. Without that baseline the model can only claim a change looks faster, and you can't tell a real win from noise.

Record the baseline before the run, commit it, and point the rulebook at it. Here's a minimal harness in plain Node.js that produces a JSON file the model can diff against. The function being measured is a stand-in; replace it with your real session setup or import path:

// Record a baseline so a performance pass has a number to beat.
const { performance } = require("perf_hooks");

function prepSession(n) {
  const s = {};
  for (let i = 0; i < n; i++) s["k" + i] = { id: i, tags: [] };
  return Object.keys(s).length;
}

function bench(fn, runs) {
  const t = [];
  for (let i = 0; i < runs; i++) {
    const a = performance.now();
    fn();
    t.push(performance.now() - a);
  }
  t.sort((x, y) => x - y);
  return { median_ms: +t[Math.floor(runs / 2)].toFixed(3), min_ms: +t[0].toFixed(3), runs };
}

const baseline = { prep_session_20k: bench(() => prepSession(20000), 15) };
console.log(JSON.stringify(baseline, null, 2));

A few habits make the baseline useful rather than decorative:

• Use the median, not the mean, so one slow run doesn't skew the target.
• Measure the things the goal names. If the goal says "cold imports", have a cold-import benchmark.
• Keep the benchmark runnable with one command, because the model will run it dozens of times.

Step 4: let Argon ship multiple clean changes#

The Chrome refactor landed as many clean changes in parallel. You can set that up deliberately by planning the batches before the run, instead of hoping the model slices a large branch well afterward.

For a module-moving refactor, the batches fall out of the dependency graph: a file can move once everything it depends on has moved. This script groups files into batches that can be refactored, tested, and reviewed independently:

# Group files into batches that can be refactored and reviewed independently.
# A file is ready once everything it imports has already moved.
deps = {
    "browser/tab.py": ["core/page.py"],
    "browser/panel.py": ["core/page.py", "browser/tab.py"],
    "browser/window.py": ["browser/tab.py"],
    "core/page.py": [],
    "core/nav.py": [],
    "browser/history.py": ["core/nav.py"],
}
done, batch = set(), 1
while len(done) < len(deps):
    ready = sorted(
        f for f, d in deps.items() if f not in done and all(x in done for x in d)
    )
    if not ready:
        raise SystemExit("cycle detected, break it by hand before the run")
    print(f"batch {batch}: {', '.join(ready)}")
    done.update(ready)
    batch += 1

Feed the batch list to the model as part of the goal or as a skill, and ask for one pull request per batch. Each one should pass the full test suite on its own. Reviewing five 200-line changes is a normal afternoon. Reviewing one 1,000-line change that touches six subsystems is where rollbacks come from.

For a performance pass the batching is simpler: one optimization per commit, each with the before and after numbers in the message, as the rulebook example above requires.

Antigravity or the Gemini API for a large refactor#

Both Google examples ran in Antigravity, which is where the skills rulebook and the /goal command live. Argon in Antigravity is available to Google AI Ultra subscribers and to enterprises.

If you'd rather build your own loop, Argon is available through the Gemini API paid tier in AI Studio and Android Studio. The model has a 1M unified input-output token limit via the API, and the announcement points developers to the documentation for a new continuation protocol that long-running tasks need. Read the Gemini API documentation before wiring up an overnight job, because a refactor across hundreds of files is exactly the kind of task that runs past a single turn.

Pricing at launch is $2 per million input tokens and $10 per million output tokens, with cached input tokens at 95% off. After the introductory period expires on November 30, 2026, the price of $4 per 1M input tokens and $20 per 1M output tokens will apply. A long refactor re-reads the same rulebook and the same files repeatedly, so caching is where the cost of an overnight run actually gets decided.

Common mistakes when refactoring with Gemini 4 Argon#

Pasting a design doc as the goal. The model will pick the most tractable section and optimize that. Keep the goal to one paragraph and move the detail into skills, where it's reference material rather than instruction.

No baseline for a performance pass. You'll get commits that claim speedups you can't verify. Record the numbers first and make the rulebook require re-running the benchmark after every change.

One branch for the whole refactor. This is the single biggest cause of wasted runs. Plan batches up front, require one PR per batch, and make each one independently green.

A rulebook that only says what to do. The forbidden zones and the stop conditions are the lines that keep the run merge-safe. Argon is trained to pause before irreversible steps, but it has to know which steps you consider irreversible in your repository.

Treating code comments and README files as trusted. A legacy codebase is full of text the model will read. Argon leads the Gray Swan Indirect Prompt Injection benchmark, cutting attack success across 15 adaptive attempts to 0.7%, which is good, but still review any change whose justification traces back to a comment rather than to a test or a number.

Skipping the negative findings. The ADK run surfaced optimizations; a run on your code will also surface dead ends. Ask for them in the report. A note saying "tried caching the schema loader, no measurable gain" saves the next person a day.

Running the full test suite on every micro-step. If the suite takes 40 minutes, the model spends the night waiting. Put a fast subset in the rulebook for iteration and the full suite as the gate before a batch is declared done.

Quick reference checklist#

Before the run:

• [ ] .agents/skills has a test skill, a measurement skill, and a forbidden-zones skill.
• [ ] Baseline numbers are committed and reproducible with one command.
• [ ] Batches are planned from the dependency graph, with no cycles.
• [ ] The goal is one paragraph with outcome, scope, proof, and hard stop.

During the run:

• [ ] One logical change per commit, metric and numbers in the message.
• [ ] One PR per batch, full suite green on each.
• [ ] Stop conditions trigger a write-up, not a workaround.

After the run:

• [ ] Review each PR against the baseline, not against the model's description.
• [ ] Read the negative findings and record them in the repository.
• [ ] Fold whatever rule you had to explain in review back into the skills, so the next run starts from there.

Quick answers