Can AI Help You Understand Undocumented Legacy Code?

You’re facing a modernization project and you’ve got 400,000 lines of undocumented Python code written between 2008-2015. Your architectural decision relies on understanding what this code actually does. A team member suggests: “Let’s feed it to ChatGPT and see what AI says.”

It’s a reasonable instinct. AI has gotten genuinely good at reading code. But there’s a gap between “AI can help” and “AI can solve this”—and crossing into that gap is where modernization projects start burning time.

What AI Can Actually Do Well (The Honest Assessment)

Generating annotations and documentation. Give AI a function, it can produce reasonable documentation. A 50-line function that calculates some business metric? AI can usually generate a pretty good docstring. Not perfect, but good enough to orient a human reader. This is genuinely useful and saves time.

Identifying patterns and potential refactors. When you have blocks of duplicated logic scattered across a codebase, AI can find them and suggest consolidation. It can identify “this pattern shows up in 7 places, maybe extract it to a utility function.” That’s valuable architectural insight.

Explaining individual functions or small modules. If you ask “what does this 200-line class do?” and show it the code, AI can usually give you a reasonable summary. Not exhaustive, but useful as a starting point for further investigation.

Finding likely bugs or security issues. AI is pretty good at spotting obvious problems—uninitialized variables, SQL injection vulnerabilities, missing error handling. It won’t find everything, but it catches low-hanging fruit.

A financial services company we worked with ran their legacy codebase through Claude’s analysis. It identified 47 potential SQL injection vulnerabilities in their data access layer. They investigated all 47. Twenty-three were actual issues. The other 24 were false positives (the code handled the risk differently than AI expected). Still a 50% accuracy rate on critical security issues is worth the time to investigate.

What AI Struggles With (The Hard Limits)

Inferring business intent from code. This is the critical limitation. AI can tell you what the code does syntactically. It struggles with why it does it that way. Why does this calculation use a specific rounding mode? Is it intentional for financial accuracy or a historical quirk? Why does this service retry logic back off exponentially? AI can see the code but not the business decision behind it.

Understanding context across a large codebase. You can feed AI a file or a function, but understanding how it relates to 50 other files, how the database schema evolved, how business requirements changed—that requires context that’s usually only in people’s heads. AI works best with bounded, self-contained problems.

Identifying intentional design decisions that look weird. Legacy code often has decisions that look wrong but are actually intentional. A cache that never gets invalidated might be intentional (the data is effectively immutable). A loop that looks inefficient might be processing in a specific order for a reason. AI will suggest “optimization” without understanding the constraint.

Validating correctness against unstated requirements. This is maybe the biggest risk. AI can tell you what the code does. But if the code is subtly wrong in ways that the business has learned to work around, AI won’t know that. We’ve seen situations where AI suggested “fixing” code that was actually implementing a complex business rule that had never been explicitly documented.

The Hybrid Approach That Actually Works

Here’s how we use AI effectively in legacy code analysis:

Phase 1: Surface-level mapping. Use AI to generate documentation for major functions. This creates an initial mental model of what the system does. Don’t trust it blindly—treat it as a starting hypothesis that needs validation.

Phase 2: Pattern identification and questions. Ask AI to identify suspicious patterns: “Show me all database queries that don’t use parameterized statements.” “Find places where the same calculation happens in multiple files.” “Show me error handling patterns that look incomplete.” Let AI highlight areas that need human investigation.

Phase 3: Targeted deep dives. For specific areas you need to understand (like “how does payment processing work?”), have an AI analyze the relevant code paths and produce a summary. Then have a senior engineer read the summary, validate it against what they know, and fill in the gaps.

Phase 4: Implementation assistance. Once you understand what the code does, use AI to help with modernization. “Show me how to refactor this payment processing logic into a service that takes these inputs and produces these outputs.” AI can generate reasonable refactoring suggestions because now you’ve constrained the problem.

A retail company we worked with used this approach on a 200K-line inventory system. It took three months:

• Month 1: AI-assisted documentation of major modules (2 engineers, 20 hours)
• Month 2: Investigation and validation of AI findings (3 engineers, 120 hours)
• Month 3: Using AI-generated insights to design the new inventory service (2 architects, 80 hours)

Total: 200 hours of work. Without AI, the same deep understanding would have taken 400+ hours. AI didn’t solve the problem—it accelerated it by 50%.

Where Most Teams Go Wrong (The Failure Modes)

Trusting AI output without validation. Someone runs the entire codebase through Claude, gets a 50-page summary, and starts planning modernization based on it. That summary is probably 70% correct, and the 30% errors are in critical areas. This inevitably causes rework.

Using AI as a substitute for human knowledge. When the person who built the system is still available, asking AI first and the engineer second is backwards. Ask the engineer first. Use AI to prepare follow-up questions and validate their answers.

Over-investing in “perfect” documentation. You can spend weeks using AI to generate exhaustive documentation of legacy code. But if the code is being rewritten, that documentation becomes outdated waste. Generate just enough documentation to make good architectural decisions.

Feeding AI incomplete or misleading context. Legacy code often has external dependencies—configuration files, environment variables, database behavior—that aren’t visible in the source code. If you don’t tell AI about those, its analysis will be wrong.

A healthcare company fed their billing system code to Claude without mentioning that the system relied on specific database views that contained business logic. Claude analyzed the code as if all the logic was visible, missed critical calculations that lived in the database layer, and produced a summary that was misleading enough to cause architectural mistakes.

The Real Use Case That AI Actually Nails

The single most valuable use of AI in legacy code modernization is this: You have a specific behavior you need to preserve in the new system. You don’t fully understand why the legacy system does it that way. Ask AI to help you find and explain it.

“Our reports show customer discounts sometimes calculate differently. Find where discount calculations happen in this codebase and explain the different code paths.”

AI will find the relevant code sections, show you the differences, and help you understand the business rules. Then a human validates it. This is bounded, specific, and AI is genuinely better than humans at the “find all relevant code” part.

Another strong use case: Security and performance analysis. “Find all SQL queries in this codebase and show me which ones might be vulnerable to injection attacks” or “Show me all database connections and identify places where we’re not using connection pooling.” AI is systematic in ways humans aren’t—it won’t miss scattered instances of a pattern.

The Numbers That Matter

If you’re using AI to understand legacy code for modernization:

• 40-50% acceleration on pure code understanding and documentation phases
• 25-30% reduction in missed bugs or edge cases during refactoring (because you’ve documented what you found)
• 0% reduction in time spent understanding business intent (AI can’t shortcut this)
• 35-45% increase in time spent validating AI output and reconciling it with reality

The last point is critical. You don’t save 50% of your analysis time by using AI. You save maybe 40%, because you spend 30% of the saved time validating the analysis.

When You Should Invest in This (And When You Shouldn’t)

Use AI-assisted legacy code analysis if:

• Your codebase is large (>100K lines) and you don’t have the original architects available
• You need to understand specific behaviors in detail but don’t have time for archaeology
• You’re trying to identify security or performance issues across a large surface area
• You’re planning a significant refactor and need to be confident you understand all the code paths

Don’t invest if:

• You’ve got the original engineers available and they have time to explain things
• The code is small enough that one person can understand it in a few weeks
• You’re planning a ground-up rewrite anyway (pure documentation isn’t worth it)
• The code is in a domain you’re abandoning entirely (legacy payment processor going away)

The Honest Truth About AI and Legacy Code

AI is useful for modernization work. It accelerates analysis, finds patterns humans miss, and helps you ask better questions. But it’s a tool that amplifies human understanding, not a replacement for it.

You still need senior engineers who understand both the business domain and software architecture. You still need time for investigation and validation. You still need to make judgment calls about what’s intentional and what’s accidental.

What AI does is make those judgment calls better informed. It finds the code sections you need to care about. It flags edge cases you should consider. It generates draft documentation that a human can validate and refine.

That’s genuinely valuable in modernization, where time and expertise are both scarce. But it’s not magic. Use it to amplify your team’s capability, not to avoid hiring senior architects.

The companies we see succeed with legacy code modernization aren’t the ones asking “Can AI understand this?” They’re the ones asking “How can AI help my experienced team understand this faster?”

That’s the right question.