Migrating a 6,000-line legacy Perl API to Go, powered by AI agents. A case study published on DeNA's engineering blog paints a vivid picture of both the promise and the limits of AI-assisted coding.
The migration succeeded, but it still took about a month. What this case study confronts us with is data-backed pushback against the optimistic assumption that "just let AI read the code and it'll handle the migration."
When AI Agents Couldn't Read Perl's Implicit Conventions
The most telling moment in DeNA's case study was when Devin, tasked with generating an OpenAPI specification from the existing Perl codebase, missed several endpoints entirely.
The cause: a delete_ suffix used to avoid collision with Perl's reserved word delete. This naming convention is common in the Perl community, but Devin failed to recognize these functions as HTTP DELETE method handlers and skipped them in the generated spec.
When the same task was given to Claude Code, it understood the Perl context and detected the endpoints correctly. What this highlights is a fundamental distinction: being able to parse code syntax and being able to read code intent are two different capabilities.
The delete_ naming has a Why behind it: "Because it collides with a Perl reserved word." But this Why is stated nowhere in the code — not in comments, not in documentation. Even an AI agent capable of reading code missed this implicit context.
Test Comparison as "Definition of Correct"
DeNA's team overcame this challenge through a rigorous testing strategy.
They built a comparison verification framework that sent identical requests to both the Perl and Go versions, verifying that responses and database updates matched exactly. With 185 test cases covering both normal and error paths, they automatically ensured that the Go version behaved identically to the Perl original.
This approach is highly practical. In migration projects, the definition of "correct behavior" is the existing system's behavior itself, making differential comparison the lifeline of quality assurance. PR approval criteria converged on a single standard: all tests pass. This dramatically reduced the human review burden.
The Gap That Tests Alone Cannot Fill
Yet if we flip this success story around, a question emerges.
Tests can verify the What (what is correct), but they cannot verify the Why (why it is that way).
For instance, when the migrated Go code needs modification in the future, what tells the developer "why this behavior must be preserved exactly as-is"? Tests tell you that something must not change, but they don't tell you why it must not change.
DeNA's own retrospective echoes this point. They cited "ambiguous initial instructions" as their biggest lesson learned, noting that "co-creating clear rules with AI — this 'meta-work' — is the key to success." This is precisely the recognition that communicating design intent beyond the implementation is fundamentally critical to AI collaboration.
Design Records Independent of Code
What sqlew advocates is an approach that separates design intent from code, structuring and persisting it independently.
Applied to DeNA's case, if information like the following had been recorded as decisions and constraints, Devin's oversight might have been prevented:
Decision: Functions whose names collide with Perl reserved words use a
_suffix by convention.delete_corresponds to the HTTP DELETE method endpoint.Constraint: When generating OpenAPI specifications, suffixed function names must be correctly mapped to their corresponding HTTP methods.
No matter how sophisticated an AI agent's code-reading ability becomes, information not written in the code cannot be extracted from the code. Tests verify output correctness, but intent transmission requires a different mechanism. By making design records independent of code, AI agents can reference "why it's done this way" regardless of whether the codebase has been rewritten in a different language.
Legacy code migration is not just repaying technical debt — it's also an opportunity to reconstruct scattered design intent. Code gets rewritten, but the Why should carry forward.
References
- DeNA Engineering Blog, "Devin AI de Idomu AI Engineer ni yoru Legacy API Ikou" — https://engineering.dena.com/blog/2025/12/legacy-code-migration-using-devin/
- "Rediscovering Architectural Decision Records: How Persistent Design Context Improves LLM Code Generation" — Shingo Kitayama (2026) — https://doi.org/10.36227/techrxiv.177205025.54351571/v2
