← All articles

    What does an LLM actually need to know about a codebase?

    The biggest mistake you can make when using an LLM on a large codebase is giving it too much code. An LLM doesn't need the entire codebase in its context window. It needs the right parts of the codebase, the right system context, and a clear task objective.

    The AI Architecture Series

    The 6 Components to Build a Deterministic Codebase Knowledge Graph

    From code to context to code generation — with structure, not guesswork.

    1. Software decomposition

      • src/, app/, core/, services/
      • pom.xml, build.gradle, README.md
      • Python, JavaScript, Java, TypeScript

      Parse multiple languages and frameworks

    2. Deterministic codebase KG

      • App
      • Service, Function
      • Database, File, Class

      Build a deterministic codebase knowledge graph

    3. Context retrieval

      • Relevant files
      • Connected functions
      • Dependencies
      • Parameters & data flow
      • Architecture constraints

      Retrieve the right context for the task

    4. LLM code generation

      Generate, validate and deliver

    The 6 components of codebase decomposition

    • Abstract syntax trees

      The structure

    • Control flow graphs

      The logic

    • Symbol tables

      The definitions

    • Call graphs

      The relationships

    • Unit tests

      The verification

    • Test coverage

      The confidence

    The biggest mistake you can make when using an LLM on a large codebase is giving it too much code.

    An LLM doesn’t need the entire codebase in its context window.

    It needs the right parts of the codebase, the right system context, and a clear task objective.

    That’s difficult when you’re dealing with an unfamiliar enterprise system:

    • incomplete or outdated documentation
    • multiple languages and frameworks
    • decades of accumulated code
    • complex dependencies
    • business logic that isn’t obvious from individual files

    In my previous article, I proposed using language-specific parsers to build a deterministic Codebase Knowledge Graph (KG) as the foundation for managing the context window for an unfamiliar codebase.

    This article takes the next step:

    What does that decomposition actually look like?

    flowchart TD
        A(Codebase)
        B(&#x2460 AST)
        subgraph Graph Components
            C(&#x2461 Control Flow Graph)
            D(&#x2462 Symbol Table)
            E(&#x2463 Call Graph)
        end
        subgraph Test Specification    
            F(&#x2464 Unit Tests)
            G(&#x2465 Coverage)
        end
        H(System behaviour)
        A-->|Syntax Parsing|B
        B-->C
        B-->D
        D-->E
        A-->|Lexical search|E
        C-->F
        D-->F
        E-->F
        F<-->G
        G-->H
    
    

    Six components underpin the decomposition of a codebase

    The key idea is that we’re not asking the LLM to discover everything about the codebase from raw source code.

    Instead, we can deterministically extract different views of the codebase first, then use those views to provide the LLM with the context it needs.

    The first four describe the structure of the code. The final two help us understand its observed behaviour.

    The key point is this decomposition is done with pre-existing software engineering tools and libraries.

    To illustrate this, I’ll use the same simple shopping-cart function throughout.

    1. Start with the Abstract Syntax Tree (AST)

    Language parsers generate an Abstract Syntax Tree (AST) that allows us to analyse the structure of source code.

    Consider:

    def calculate_total(cart):
        subtotal = sum(
            item.price * item.quantity
            for item in cart.items
        )
    
        if subtotal > 100:
            discount = calculate_discount(subtotal)
        else:
            discount = 0
    
        tax = calculate_tax(subtotal - discount)
    
        return subtotal - discount + tax

    From the AST, we can identify constructs such as:

    ConstructExtract
    Function:calculate_total
    Parameter:cart
    Local variables:subtotal, discount, tax
    Conditional statement
    Function calls:sum(), calculate_discount(), calculate_tax()
    Attribute accesses:cart.items, item.price, item.quantity
    Return statement

    The AST answers:

    What is the structure of this code?

    But structure alone isn’t enough. We also need to understand how execution can move through that structure.

    2. Enter the Control Flow Graph (CFG)

    A Control Flow Graph (CFG) represents the possible paths that execution can take through a function.

    For our calculate_total() function, the important decision is:

    flowchart TD
        A(Start)
        B(Calculate subtotal)
        C(subtotal > 100?)
        D(Yes)
        E(No)
        F(calculate_discount)
        G(discount = 0)
        H(Calculate tax)
        I(Calculate total)
        J(End)
        A-->B
        B-->C
        C-->D
        C-->E
        D-->F
        E-->G
        F-->H
        G-->H
        H-->I
        I-->J
    

    The CFG answers:

    What execution paths are possible?

    This becomes particularly useful when we start thinking about testing.

    The function has different behaviour depending on whether the subtotal is greater than $100.

    A CFG gives us a map of those possible execution paths.

    3. Then there is the Symbol Table

    A symbol table helps us understand the names used within a program and the scopes in which they exist.

    For the same function, symbol analysis might identify:

    NameRoleScope
    calculate_totalFunctionModule
    cartParametercalculate_total
    subtotalLocal variablecalculate_total
    itemComprehension variableComprehension
    discountLocal variablecalculate_total
    calculate_discountFunction / dependencyModule or imported
    taxLocal variablecalculate_total
    calculate_taxFunction / dependencyModule or imported

    This allows us to understand relationships such as:

    calculate_total
          |
          ├── uses → cart
          ├── creates → subtotal
          ├── calls → calculate_discount
          ├── creates → discount
          ├── calls → calculate_tax
          └── creates → tax

    The symbol table helps answer:

    What do the identifiers in this program represent, and where are they defined?

    This becomes important when trying to understand dependencies, scopes and relationships between components.


    4. Finally, we have the Call Graph

    A call graph describes the relationships between functions or methods — specifically, which functions call other functions.

    For our example:

    calculate_total
          |
          +----> sum
          |
          +----> calculate_discount
          |
          +----> calculate_tax

    And if we look further into those dependencies:

    calculate_total
          |
          +----> calculate_discount
          |           |
          |           +----> ...
          |
          +----> calculate_tax
                      |
                      +----> ...
    

    There is an important distinction:

    A CFG describes control flow within a function.

    A call graph describes relationships between functions.

    We can now move from:

    code structure → execution paths → names and dependencies → relationships between functions

    At this point, we have a reasonably rich static picture of the code. But there’s still a fundamental question:

    Does the code actually behave the way we think it does?

    5. Validate behaviour with Given–When–Then tests

    Static analysis tells us what the code contains and what paths could exist.

    It doesn’t tell us whether the system actually behaves as expected.

    For that, we need to execute the code.

    One way of expressing expected behaviour is through Given–When–Then tests.

    For example, for our shopping cart:

    Given

    A cart containing items with a subtotal of $150.

    When

    calculate_total(cart) is called.

    Then

    The discount branch should be executed, tax should be calculated on the discounted subtotal, and the final total should be returned.

    The test captures the behavioural specification:

    • Given — the preconditions and application state
    • When — the function or operation is executed
    • Then — the expected result and state changes

    This is where I think LLMs can become particularly useful.

    We can use queries against the Codebase KG to populate a prompt template with the relevant context:

    “Given [this function], its [dependencies], [inputs], [outputs] and [control-flow paths], generate candidate Given–When–Then tests.”

    The LLM isn’t being asked to understand the entire codebase.

    It’s being given targeted context derived from the graph.

    6. Did we exercise every relevant execution path?

    Now we have another problem.

    How do we know whether our tests actually exercise the behaviour we’ve identified?

    This is where test coverage becomes useful.

    All the major languages come with testing tools that tell us can tell us which statements and branches were exercised by our tests.

    Our CFG identifies two important paths:

    flowchart TD
        A(sub_total > $100)
        B(Yes)
        C(No)
        A-->B
        A-->C
    

    Our first test might only exercise the Yes branch.

    Test coverage can tell us that the No branch hasn’t been tested.

    That information can feed back into test generation.

    We can ask the LLM to generate additional scenarios around:

    • boundary conditions
    • alternative branches
    • exceptions
    • invalid inputs
    • missing values

    Coverage doesn’t prove that we’ve tested every possible behaviour.

    It tells us which parts of the implementation our tests have exercised, making it a useful feedback mechanism for identifying gaps.

    So why the graph perspective?

    Coming from a knowledge graph background, I find this part particularly interesting.

    • A CFG is already a graph.
    • A call graph is a graph.
    • Symbol relationships can be represented as a graph.
    • Data flows can be represented as a graph.
    • Test execution and coverage can also be associated with the graph.

    This gives us the possibility of representing a codebase as interconnected layers:

    Rather than storing source code as isolated files, the Codebase KG becomes a model of how the application is constructed and how it behaves.

    The bigger idea

    I’m beginning to think that reverse engineering legacy software doesn’t have to be a completely manual process.

    A combination of:

    • AST analysis
    • Control Flow Graphs
    • Symbol and scope analysis
    • Call graphs
    • Data-flow analysis
    • Test execution
    • Test coverage
    • Graph analysis
    • LLMs

    could create a systematic pipeline for progressively converting an unfamiliar codebase into something much more understandable.

    Not just: “Here is the source code.”

    But:

    “Here is its structure.”

    “Here are its possible execution paths.”

    “Here are its dependencies.” “Here are the relationships between its components.” “Here is the behaviour we’ve observed.” “Here are the tests that describe that behaviour.”

    And ultimately:

    “Here is a behavioural specification that can be used to understand, maintain, refactor — or potentially reimplement — the application.”

    The role of the LLM changes as well.

    Instead of asking:

    “Here is my entire codebase. What can you tell me about it?”

    we can ask:

    “Here is the specific context relevant to the task. What can you reason about from it?”

    That’s a much more interesting proposition.

    The goal isn’t to put more code into the LLM’s context window. The goal is to put the right knowledge into it.

    What do you think?

    Could static analysis, test coverage, knowledge graphs and LLMs together provide a better way to reverse engineer legacy applications?

    Discussion

    Get started

    Want this applied to your codebase?

    Request a discovery call. We’ll talk through your system, where it hurts, and whether a Codebase Knowledge Graph is the right fit.