Most of the attention on GenAI in software development has focused on generating new code. Yet there is as much or more value in understanding existing code, particularly in large, complex legacy systems where documentation is scarce and experts are hard to find.
Our experience across multiple projects shows that GenAI-assisted understanding of legacy systems is now a practical standard rather than an experiment. The productivity impact is consistent and substantial.
The legacy code challenge
The scale of the problem
According to Stack Overflow's 2024 developer survey, 62% of developers cite technical debt as their main frustration. An IDC study reveals that nearly half of companies overspend on digital infrastructure due to legacy system maintenance.
The numbers are stark:
- $2.9 million per year per company in legacy maintenance costs (SnapLogic)
- 63% of developers spend 30-120+ minutes a day searching for answers about their codebase (Stack Overflow, 65,000 respondents)
- 60% of development time is spent trying to understand code, not writing it
Why GenAI for legacy code
Legacy systems frequently lack adequate documentation, or the existing documentation is outdated or misleading. The subject-matter experts (SMEs) who understand these systems are scarce and often overloaded.
The tooling ecosystem
AI IDEs and code assistants
The market has matured fast. These are the most relevant tools for code understanding:
| Tool | Main strength | Context |
|---|---|---|
| Cursor | VS Code fork with native AI. Reads the whole project, import trees, variables | Claude 4 Sonnet/Opus |
| Claude Code | Terminal CLI. Maps structure, triages issues, generates PRs, runs tests | 200k tokens |
| Windsurf | AI-first IDE with Cascade mode. Local embeddings for natural-language search | Full codebase |
| GitHub Copilot | Market leader. 46% of code completed with ~30% acceptance | IDE integration |
| Aider | Open-source CLI for pair programming. Supports multiple models | Direct editing |
Platforms specialized in code understanding
Beyond IDEs, there are platforms designed specifically to understand large codebases:
- Sourcegraph Cody: Indexes the entire repository graph. Chat spanning packages and symbol references. Context up to 100,000 lines. Recognized by Gartner as a Cool Vendor 2024.
- Swimm: Application Understanding platform with static analysis. Creates a living inventory of programs, modules and dependencies. Auto-syncs documentation with code changes.
- Unblocked: Contextual code intelligence. Integrates with GitHub, Slack, Jira, Confluence. Raised $20M in 2025 to help developers understand the "why" behind the code.
- PocketFlow Codebase Knowledge: 100-line open-source framework. Generates structured tutorials from repositories with Mermaid diagrams.
GraphRAG: the advanced approach
What GraphRAG for code is
A particularly promising technique is the Retrieval-Augmented Generation (RAG) approach over a knowledge graph of the code. The graph can preserve structural information about the codebase beyond what an LLM could derive from text alone.
Key GraphRAG components
- Codebase parsing: Systematic analysis using Abstract Syntax Trees (AST) to extract semantic structure
- LLM enrichment: Generation of descriptions, functional summaries and metadata for each entity
- Knowledge Graph construction: Storage in a graph database (Neo4j) with relationships like
calls,inherits,depends_on - Intelligent querying: RAG that retrieves relevant nodes and lets the LLM traverse neighboring nodes for additional context
GraphRAG tools
- Code-Graph-RAG: RAG system that analyzes multi-language codebases using Tree-sitter. MCP Server integration for Claude Code.
- GitLab Knowledge Graph: Structured, queryable representations of repositories to power GitLab Duo.
- FalkorDB Code Graph: Interactive visualization of how classes, methods and modules are interconnected.
- GraphGen4Code: IBM/WALA toolkit for building knowledge graphs with integrated StackOverflow data.
Case study: Thoughtworks' CodeConcise
Project context
One of the major automakers spent three decades developing a system to support sales business processes. The system:
- Runs on mainframe
- Comprises approximately 15 million lines of COBOL code
- Uses IDMS — a technology stack for which qualified engineers are scarce
The goal was to migrate to microservices architecture before the end of 2025 to avoid licensing problems. However, rewriting 15 million lines is a significant task, and the program was behind schedule. The main bottleneck: the reverse-engineering process.
The solution: CodeConcise
CodeConcise is an internal Thoughtworks accelerator inspired by the Code-as-Data concept, where code is treated and analyzed in ways traditionally reserved for data:
- Ingestion Pipeline: Parses code into forests of ASTs, stores them in a graph database (Neo4j), and establishes edges between nodes
- Comprehension Pipeline: Traverses the graph using algorithms like DFS with backtracking to enrich it with LLM-generated explanations
- Noise Reduction: Granular analysis that reduces unnecessary context, keeps the LLM focused and uses the context window efficiently
- Chatbot Interface: RAG over the enriched Knowledge Graph to answer questions that would typically require an SME
Measurable results
"Before the PoC, reverse-engineering 10,000 lines of code typically took 6 weeks. With CodeConcise, we estimate a two-thirds reduction: from 6 weeks to 2 weeks per module."
This translates into potential savings of 240 person-years for the entire mainframe modernization program.
GenAI for mainframe modernization
The COBOL challenge
According to Gartner, by 2027, GenAI tools will be used to explain legacy business applications and create appropriate replacements, reducing modernization costs by 70%.
Decades of business logic encoded in COBOL make it hard to extract, document and translate to modern languages. GenAI offers specific capabilities:
- Business rule extraction: GenAI can automatically extract rules, logic and system behavior by analyzing legacy code
- Code translation: Scales translation and refactoring from COBOL or PL/I to modern languages like Java, C++ or Python
- Documentation generation: Creates up-to-date technical documentation describing the functionality of each component
- Dependency analysis: Maps dependencies within the system for greater confidence when making changes
- Cutover validation: Supports dual-run or shadow-traffic methods to verify that modernized systems behave as expected
Productivity impact: the evidence
Studies and benchmarks show consistent improvements:
| Activity | Improvement | Source |
|---|---|---|
| Code documentation | 50% faster | McKinsey 2023 |
| Writing new code | 50% faster | McKinsey 2023 |
| Code refactoring | 33% faster | McKinsey 2023 |
| Migration to modern languages | 73% faster | Slalom 2024 |
| Reverse engineering (COBOL) | 66% faster | Thoughtworks 2024 |
| Modernization costs | 70% reduction | Gartner 2024 (projection) |
According to McKinsey, developers who use AI tools are twice as likely to report feeling happier, fulfilled and regularly entering a state of "flow".
Best practices for implementation
Tool selection criteria
- Context size: For large codebases (>100K lines), prioritize tools with wide context windows (200K+ tokens) or robust RAG capabilities
- Ecosystem integration: Evaluate compatibility with existing IDEs, version control systems and documentation tools
- Enterprise security: Verify SOC 2 certifications, on-premise deployment options and data retention policies
- Multi-language support: Especially critical for legacy environments with COBOL, PL/I, or less common languages
Recommended adoption strategy
- Initial assessment: Identify the highest business-value legacy systems for modernization. Prioritize areas where GenAI can deliver the greatest ROI.
- Proof of Concept: Start with a representative module (5,000-10,000 lines) to validate effectiveness before scaling.
- Knowledge Graph construction: For codebases >50K lines, invest in GraphRAG. The setup effort scales with complexity but the return is substantial.
- Workflow integration: Connect understanding tools with existing documentation, testing and CI/CD pipelines.
- Continuous iteration: Refine prompts, enrich context and update knowledge graphs as the code evolves.
Extracting specifications from legacy code
One of the most valuable applications of GenAI for legacy code is automated specification extraction. This transforms "black box" systems into structured documentation that can guide modernization projects with precision.
What can be extracted
- Low-level requirements: Structured documentation that Business Analysts can use directly to derive specs. The CodeConcise case processed 1,500 COBOL modules, generating documentation consumable by non-technical people.
- Business rules: Automatic extraction of conditions, validations and decision flows. Frameworks like BREX combined with LLMs can represent rules in a structured, executable format.
- Implicit contracts: What each function expects as input, what it returns, what side effects it has, what exceptions it can throw.
- Capability maps: Discover what the system does at a functional (not technical) level. Useful for defining modernization scope and prioritizing by business value.
- Dependencies and data flows: How components connect, what data flows between them, and which are the critical integration points.
The spec-extraction flow
The extraction process follows a structured sequence that combines automated analysis with human validation:
1. LEGACY CODE INGESTION
- Parsing via AST
- Knowledge Graph construction with relationships between entities
2. GENAI ENRICHMENT
- Generation of semantic descriptions
- Identification of business patterns
- Rule extraction
3. STRUCTURED SPEC GENERATION
- Transformation into consumable formats
- User stories, acceptance criteria
- Abstract flow diagrams
4. VALIDATION WITH SMEs
- Review by domain experts
- Confirmation of accuracy and completeness
- The CodeConcise chatbot reduces this dependency
5. FINAL SPECS
- Validated documentation ready to guide development
- Basis for testing and equivalence validation
Connection with Spec-Driven Development (SDD)
This extraction capability opens a natural connection with Spec-Driven Development methodologies, creating a complete cycle for modernization projects.
Reverse SDD: Legacy to Specs
- Analyze existing code to extract implicit specifications
- Document current behavior without relying exclusively on SMEs
- Identify which functionalities to preserve, which to discard, which to improve
- Create a documented baseline to validate functional equivalence
Forward SDD: Specs to New System
- Use validated specs as a contract for the new development
- Generate automated tests from the specifications
- Guide code generation with full requirements context
- Validate that the new system meets the extracted requirements
"The classic modernization problem is: 'we can't rewrite because we don't know exactly what the current system does.' GenAI combined with SDD resolves precisely this blocker, transforming tacit knowledge into explicit, actionable specifications."
Where onext can add value for you
This capability can be structured as a "Spec Extraction from Legacy Code" consulting service with the following components:
- Initial assessment: Codebase evaluation, complexity identification, effort estimation for extraction
- Infrastructure setup: Knowledge Graph setup, ingestion pipelines, integration with GenAI tools
- Extraction and documentation: Execution of the extraction process, generation of specs in standard formats
- Validation workshops: Sessions with SMEs to validate and refine the extracted specifications
- Modernization roadmap: Prioritized plan based on the validated specs, with effort estimates
- Knowledge transfer: Training the client team in tool usage and Knowledge Graph maintenance
Special relevance: This service is especially valuable for organizations with critical legacy systems where knowledge is concentrated in a few experts, creating business risk. Systematic spec extraction democratizes that knowledge and enables modernization with confidence.
Conclusions
GenAI has become an essential part of how we explore and understand legacy systems. The transition from "experiment" to "practical standard" reflects the maturity of the tooling ecosystem and the accumulated evidence of positive productivity impact.
Organizations adopting these technologies are seeing tangible benefits:
- Significant reduction in onboarding times
- Lower dependency on scarce SMEs
- Ability to make informed modernization decisions based on real understanding of the existing code
The key message: it's not just about generating new code faster, but about finally being able to understand and evolve the code we already have. For organizations with decades of critical legacy systems, this represents a transformational opportunity.
References and resources
- Thoughtworks Technology Radar: "Using GenAI to understand legacy codebases" (2024-2025)
- Martin Fowler: "Legacy Modernization meets GenAI" (September 2024)
- McKinsey: "Unleashing developer productivity with generative AI" (2023)
- McKinsey: "The economic potential of generative AI" (2024)
- Gartner: "Top Strategic Predictions for 2024 and Beyond"
- Google Cloud Blog: "Accelerate mainframe modernization with Google Cloud AI" (2025)
- AWS: "Mainframe Modernization with GenAI" (re:Invent 2025)
- Microsoft DevBlogs: "AI Agents for COBOL Migration" (2025)
- TechCrunch: "Unblocked raises $20M for AI to help devs understand codebases" (2025)
- Neo4j Blog: "Codebase Knowledge Graph: Code Analysis with Graphs"
- Sourcegraph: Cody Enterprise Documentation
- Swimm: Application Understanding Platform Documentation
Frequently asked questions
Can AI understand legacy code nobody documented?
Yes, and it is one of its highest-return uses. AI reads the code, reconstructs what it does and generates documentation and specifications from it. It does not replace the judgement of whoever decides what to modernise, but it removes the slowest phase: working out what is there.
How much does AI actually speed up legacy work?
The benchmarks cited in the article point to 50% faster documentation and new code and 33% faster refactoring (McKinsey 2023), 73% faster migration to modern languages (Slalom 2024) and 66% faster COBOL reverse engineering (Thoughtworks 2024).
Why are legacy systems so expensive to maintain?
Because the cost is not only infrastructure. 62% of developers cite technical debt as their main frustration (Stack Overflow 2024), and 63% spend between 30 and 120+ minutes a day looking for answers about their own codebase.
How does this relate to Spec-Driven Development?
Directly: extracting specifications from existing code is the bridge. Once you have a specification of what the system actually does, you can modernise with SDD instead of rewriting blind.
Jordi García is Tech Lead at onext. He works on bringing AI into governed production across development and product teams —with Spec-Driven Development, context engineering and human verification at every step— and authors onext's technical insights on the method, quality and cost of applied AI.
LinkedIn →