Using AI Agents for Codebase Refactoring and Monolith Decomposition

1password · Tech · 2026 · source Agentic: yes · promotional bias: low · source-backed · extracted with prompt 0.5.6 (schema v2)

Generated from extraction.json — do not edit by hand. Every claim cites verbatim source evidence; stated means the quote directly asserts the claim, implied means it supports it indirectly.

Problem

Domain: Production engineering and monolith decomposition

1Password needed to decompose and refactor a multi-million-line Go monolith while learning where AI agents could safely accelerate high-stakes engineering work without violating sequencing, schema, deployment, or data-boundary constraints.

Constraints:

Architecture

1Password built an agentic refactoring toolchain around deterministic artifacts. Go SSA analysis, SQL parsing, and DataDog MCP runtime data produced domain ownership maps, coupling graphs, and extraction order. Agents helped build analyzers and execute well-specified migrations from manifests and playbooks, while humans constrained scope, reviewed sequencing, and stopped complex service extraction where schema and deployment invariants were too interdependent for safe autonomous execution.

Diagram confidence: explicit (topology described by the source).

flowchart LR
  b5-go-monolith["B5 Go monolith"] --> go-ssa-analyzer["Go SSA analyzer"]
  b5-go-monolith --> sql-dependency-parser["SQL dependency parser"]
  go-ssa-analyzer --> deterministic-artifacts["Deterministic artifacts"]
  sql-dependency-parser --> deterministic-artifacts
  datadog-mcp-integration["DataDog MCP integration"] --> deterministic-artifacts
  deterministic-artifacts --> human-engineering-reviewers["Human engineering reviewers"]
  deterministic-artifacts --> agent-execution-worktrees["Agent execution worktrees"]
  human-engineering-reviewers --> agent-execution-worktrees
  agent-execution-worktrees --> b5-go-monolith
Drag to pan · scroll or use +/− to zoom · reconstructed from the source's described component topology

Components

Component Role Interacts with
B5 Go monolith The multi-million-line production codebase being analyzed and refactored. Go SSA analyzer, SQL dependency parser, Agent execution worktrees
Go SSA analyzer Provides static code-structure and call-site analysis. B5 Go monolith, Deterministic artifacts
SQL dependency parser Identifies database schema and access-pattern coupling. B5 Go monolith, Deterministic artifacts
DataDog MCP integration Supplies runtime coupling and transaction visibility. Deterministic artifacts
Deterministic artifacts Represent domain ownership maps, coupling graphs, call-site manifests, and extraction-order plans. Go SSA analyzer, SQL dependency parser, DataDog MCP integration, Human engineering reviewers, Agent execution worktrees
Human engineering reviewers Define boundaries, invariants, sequencing, and escalation decisions. Deterministic artifacts, Agent execution worktrees
Agent execution worktrees Isolated workspaces where agents execute independent, specified changes in parallel. B5 Go monolith, Deterministic artifacts, Human engineering reviewers

Data flow

Static code, SQL schemas, and DataDog runtime traces feed analyzers that generate deterministic ownership maps, coupling graphs, manifests, and extraction-order recommendations. Engineers turn those artifacts into playbooks with invariants and escalation rules. Multiple isolated agents operate in git worktrees on independent tasks, apply templates or draft changes, and hand ambiguous or sequencing-sensitive work back to humans for review.

3 supporting quotes
“The team built a sophisticated agentic toolchain that combined multiple data sources to create a comprehensive understanding of their system.”summary, stated
“The execution strategy for this migration demonstrated the operational patterns that proved most effective.”summary, stated
“They then wrote a detailed playbook describing exactly how agents should execute the migration, including a comprehensive list of common failure modes and clear instructions on when to stop and escalate to humans”summary, stated

Why this architecture

1Password constrained agents with deterministic artifacts because unconstrained model judgment was too risky for irreversible production migrations. Agents were valuable at reading, classifying, and applying repetitive patterns, but engineers kept authority over system boundaries, deployment order, and data invariants.

3 supporting quotes
“An important architectural decision was using agents to build deterministic tooling rather than relying on them for ongoing interpretation.”summary, stated
“The successful pattern involved using agents to build deterministic tools (analyzers, manifests, specifications) and then constraining subsequent work to those outputs”summary, stated
“Engineers remain responsible for defining system boundaries, modeling dependencies, and ensuring correct sequencing”summary, stated

Models used: AI coding agents · Cursor planning/execution model mix

Scale

Alternatives considered (roads not taken)

Let agents interpret the codebase continuously

Rejected because: 1Password preferred deterministic analyzers and manifests that engineers could reason about reproducibly.

“this analyzer produced reproducible outputs that engineers could reason about as stable artifacts rather than debating what the model believed about the system.”summary, stated

Parallelize all agent refactoring work

Rejected because: Parallelism only worked when changes were independent and structurally isolated.

“parallelism only works effectively when changes are truly independent and isolation has been structurally guaranteed.”summary, stated

Ask agents to handle complex service extraction autonomously

Rejected because: Service extraction involved ordering and invariants across schema evolution, deployment sequencing, and shared data contracts.

“Even for relatively small services, extraction requires coordinated changes across schema evolution, read and write paths, deployment sequencing, and shared data contracts”summary, stated

Automate comprehensively

Rejected because: 1Password found it safer to define explicit automation boundaries and escalation paths.

“Coverage should be intentional, not comprehensive.”summary, stated
“teams should focus on clearly defining where automation stops and human judgment takes over.”summary, stated

Patterns

multi-agent-orchestration (agent execution)

1Password used multiple isolated agents in git worktrees for parallel codebase changes where independence was guaranteed.

“1Password employed a parallel multi-agent approach using git worktrees to maintain isolation between concurrent agent operations.”summary, stated
“This architectural pattern allowed multiple agents to work simultaneously on different parts of the codebase without creating conflicts”summary, stated

tool-use-orchestration (agent tooling)

Agents and engineers combined SSA, SQL parsing, DataDog runtime data, manifests, and playbooks to guide refactoring.

“At the core of their analysis layer were three primary components working in concert. First, they employed Go SSA (Static Single Assignment) analysis to understand code structure at a deep level, providing visibility into how different parts of the codebase related to each other.”summary, stated
“First, they employed Go SSA (Static Single Assignment) analysis to understand code structure at a deep level, providing visibility into how different parts of the codebase related to each other.”summary, stated

observability-tracing (runtime context)

DataDog runtime coupling data informed extraction sequencing and improved transaction visibility.

“they integrated with DataDog through an MCP (Model Context Protocol) integration to incorporate runtime coupling data”summary, stated
“A valuable side benefit of this instrumentation work was improved end-to-end transaction visibility in DataDog”summary, stated

structured-output-contract (agent safety)

Agents worked from deterministic manifests, explicit templates, playbooks, invariants, and escalation rules rather than open-ended judgment.

“The team generated a deterministic manifest of every call site using SSA, classified those sites into a small number of distinct patterns, and defined explicit templates for each pattern.”summary, stated
“The only reliable mitigation is making specifications explicit, including invariants, ordering constraints, and clear escalation paths for anything outside defined patterns.”summary, stated

human-in-the-loop-gate (safety)

Humans retained responsibility for sequencing, boundaries, and ambiguous service-extraction decisions.

“The agents provided value but did not eliminate the need for careful human coordination and review, particularly around correctness constraints and sequencing dependencies.”summary, stated
“Engineers remain responsible for defining system boundaries, modeling dependencies, and ensuring correct sequencing”summary, stated

Tradeoffs

Agents build deterministic tools

Chose Use agents to create analyzers and manifests, then constrain execution to those artifacts over Use agents as ongoing interpreters of system boundaries.

Rationale: Deterministic outputs gave engineers stable artifacts to review and reason about.

“The agents helped write parts of the SSA analyzer, but once built, this analyzer produced reproducible outputs that engineers could reason about as stable artifacts”summary, stated

Heavy specification before rapid execution

Chose Build tooling, classify patterns, and write a playbook before running agents over Send agents directly through thousands of call sites.

Rationale: Upfront deterministic preparation made the repetitive migration safe enough to execute quickly.

“This ratio – heavy upfront investment in specification and tooling, followed by rapid automated execution – emerged as a key success pattern.”summary, stated

Human-controlled service extraction

Chose Keep humans in charge of schema/deployment sequencing over Let agents autonomously extract services.

Rationale: Current agents could not reliably manage dependency chains and invariants.

“For this class of complex, coordinated work, the productivity gains were real but modest – approximately 20-30% improvement.”summary, stated
“For this class of complex, coordinated work, the productivity gains were real but modest – approximately 20-30% improvement. The agents provided value but did not eliminate the need for careful human coordination and review, particularly around correctness constraints and sequencing dependencies.”summary, stated

Intentional coverage boundaries

Chose Define where automation stops and escalation begins over Chase complete automation with more prompting.

Rationale: Graceful escalation was safer than letting agents improvise on ambiguous edge cases.

“The goal is not to have agents handle every possible case, but to have them execute confidently on well-understood patterns and escalate quickly when encountering ambiguity.”summary, stated

Gotchas (what bit them)

Agents mishandled migration sequencing despite explicit instructions.

Root cause: Complex service extraction requires interdependent schema, write-path, read-path, deployment, and data-contract decisions.

Resolution: 1Password restricted agents to well-specified patterns and kept humans responsible for sequencing-sensitive work.

“The agents consistently struggled with sequencing and invariants, making errors that would introduce subtle but critical failures.”summary, stated
“These patterns persisted even when the team provided explicit instructions about ordering and constraints, suggesting fundamental limitations in how current language models handle complex dependency chains.”summary, stated

An agent attempted an unsafe UUID-column backfill order.

Root cause: The agent optimized local code changes without preserving insertion-path invariants.

Resolution: Humans needed to enforce correct migration sequencing and stop unsafe plans.

“an agent attempted to backfill UUID columns before updating the code responsible for inserting new rows, a sequence that would introduce silent data loss”summary, stated

Agents speculated when context was incomplete.

Root cause: Language models fill gaps with plausible but unverified assumptions.

Resolution: Specifications must name invariants, boundaries, ordering constraints, and escalation conditions.

“when agents lacked sufficient context, they filled gaps with assumptions that appeared locally reasonable but were not verified.”summary, stated
“Incomplete specifications lead to implicit ones. When agents lack sufficient context, they inevitably fill gaps in ways that may be locally reasonable but globally incorrect.”summary, stated

Parallel agents can amplify inconsistency without structural isolation.

Root cause: Concurrent edits collide unless work units are independent.

Resolution: Use worktrees and only parallelize when independence has been guaranteed.

“Without proper isolation, attempting to parallelize agent work merely increases the surface area for inconsistency rather than reducing execution time.”summary, stated

Generated code was not the hard part.

Root cause: Correctness depended on sequences of irreversible or hard-to-reverse engineering decisions.

Resolution: Invest in deterministic analysis, explicit specs, and human coordination before automated execution.

“The bottleneck is not code generation. Agents proved highly effective at reading code, analyzing structure, and drafting changes.”summary, stated
“The difficulty emerged in managing sequences of decisions with ordering constraints or changes that are difficult to reverse”summary, stated

Evaluation

1Password evaluated agents pragmatically through migration outcomes, alignment with experienced engineers' extraction order, productivity gains, and observed failure modes in real refactoring work.

Metrics: 3,000+ call-site migration in hours · 20-30% productivity improvement on complex coordinated tasks · Extraction order aligned with experienced engineers · Observed sequencing and speculation failure cases

3 supporting quotes
“The extraction order produced by this analysis aligned well with what experienced engineers would likely recommend”summary, stated
“The most successful application of their agentic approach was a database transaction handling migration that required updating over 3,000 call sites.”summary, stated
“For this class of complex, coordinated work, the productivity gains were real but modest – approximately 20-30% improvement.”summary, stated

Outcomes

The work targeted a multi-million-line Go monolith and a 3,000+ call-site migration, with complex service extraction still requiring human-led sequencing.

3 supporting quotes
“The agents successfully automated a 3,000+ call site migration in hours and provided useful extraction sequencing”summary, stated
“The case study is notable for its candor about limitations alongside successes. The team explicitly acknowledges that they are working on problems – decomposing production systems under live traffic, structuring multi-agent execution – that lack well-established playbooks.”summary, stated
“This approach leverages agent capabilities for analysis and code generation while avoiding the risks of unconstrained agent decision-making in production contexts.”summary, stated