1Password — What We Learned Using AI Agents to Refactor a Monolith

1Password's B5 is a multi-million-line Go monolith. The team is breaking it into services and used AI agents through the work. The post is an honest split between what worked easily and what didn't.

What worked: agents building deterministic tools

The team's first move was not "agents write the refactor" but "agents build the analyzers we need to plan the refactor." A toolchain combining Go SSA analysis, SQL parsing, and DataDog MCP integration produced a domain ownership map and an extraction order — Vault → Billing → AuthN/AuthZ → Identity core. From that point, teams argued over stable artifacts instead of model interpretations. This is the core of agent-built-deterministic-tools.

A side effect of building the tooling: the DataDog instrumentation needed for the coupling map gave the company end-to-end transaction visibility it didn't previously have. Unrelated benefit, real.

The MustBegin migration: the productivity sweet spot

MustBegin is the team's panic-on-database-failure transaction starter. There were over 3,000 call sites. The migration:

1. SSA-generated manifest of every call site
2. Classify sites into repeatable patterns
3. Per-pattern transformation templates
4. Playbooks with failure modes and escalation rules
5. Parallel agents on git worktrees

Execution ran in hours. Most of the calendar time went into tooling and specs. The line: "When the work is fully specified and bounded, agents are both fast and accurate." This is the same shape as acceptance-criteria-ids and specsmaxxing — turn judgment into a navigable artifact before letting the agents loose.

Where it broke: service extraction

Service extraction showed only 20–30% productivity gains. Three failure modes:

• Sequencing errors. Agents backfilled UUID columns before updating the insertion code, causing silent data loss. The kind of mistake that's obvious post-hoc and invisible during code review.
• Ownership confusion. Shared tables treated as independently owned by each service, creating deployment conflicts.
• Speculation. When context was insufficient, agents filled gaps with locally-reasonable assumptions (e.g., guessing the identifier format was ULID).

The throughline: model variability is fine when the problem is bounded. It's expensive when consequences are sequencing-dependent or hard to reverse.

The four lessons

The post crystallizes the experience into four:

1. Code generation isn't the bottleneck. Sequencing constraints, schema evolution, deployment order, and shared-state boundaries are.
2. Contain non-determinism. Use agents to build deterministic analyzers and manifests, then constrain subsequent work to those outputs.
3. Explicit specifications prevent implicit ones. If you don't supply invariants, ordering constraints, and escalation paths, the agent will invent them — locally reasonable, globally wrong.
4. Parallelism requires solved isolation. Concurrent agents only work when changes are structurally independent. Worktrees solve the file-system half; the design problem of conflict-free decomposition is on you.

Lessons 2 and 3 are the actionable ones. Lesson 1 is the orientation; lesson 4 is the warning.

Broader implications

The team flags two adjacent patterns:

• Bigger-slower for plans, smaller-faster for execution. Tido Carriero (Cursor VP Eng) is quoted: large model proposes a concrete plan, human edits it, smaller model executes. Same separation that ai-assisted-workflow argues for, framed by where you spend the tokens.
• Agents as a new class of actor. Implications for access control, audit, and trust — the same problem space agent-principal-agent-problem is in, from the access-management side instead of the code-review side.

How this fits in the wiki

The piece is a counterweight to the tropes on both sides. Against the "agents will replace engineers" reading: 20–30% on the hard work, and the value comes from the tools the agents build, not the code they write. Against agentic-coding-is-a-trap and agentic-coding-fatigue: a concrete recipe for where agents do pay off, with worked examples that aren't toys. The pattern lines up with no-silver-bullet-llms — agents don't make the essential difficulty (sequencing, schema, ownership) easier, only the accidental difficulty (mechanically rewriting 3,000 call sites).

The deterministic-tools pattern also rhymes with clean-code-coding-agents (agents waste tokens orienting in messy code) and context-engineering (assemble the right prior state before invoking).

Related: average-is-all-you-need for the agent-driven walkthrough framing, building-syntaqlite-ai for the personal version of the same arc (vibe-coding fails, disciplined spec-first works).