Mapping a legacy codebase: what goes into an Atlas

Before any agent edits a line of code, we want a map. We call it the Atlas: a structured description of a codebase that tells engineers, and the agents working for them, what exists, how it connects and where the risk is. This note describes what we think belongs in it.

Inventory

The first layer is plain inventory. For a COBOL estate that means programs, copybooks, JCL jobs and procedures, CICS transactions, DB2 tables and VSAM files. For Java it means modules, packages, build files and the libraries they pull in, including the ones that stopped receiving updates years ago.

Inventory sounds trivial until you try it. Copybooks are included under names that differ from their file names. JCL references datasets created by other jobs. Java projects load classes by name through reflection or configuration. A good inventory resolves these indirections instead of listing files.

Dependencies

The second layer is a dependency graph: which program calls which, which job writes the file another job reads, which table is updated by whom. This graph drives the migration order. Modules with few inbound dependencies and clear interfaces are good first candidates. Modules that everything depends on are usually migrated last, behind a stable interface.

Dead code

Every long-lived system carries code that never runs. Migrating it is wasted effort and wasted review time. Static analysis finds unreachable paragraphs and unused classes. Job schedules and production logs, where available, find programs that exist but have not been executed for a long time. We mark these as candidates, not as deletions. A person decides.

Business rules

This is where agents add the most value. Rules such as “waive the fee if the account is older than five years and the customer is over sixty” are buried in nested conditions, often spread across several programs. An agent can read the code, extract the rule, express it in plain language and point to the exact lines it came from.

Extracted rules are treated as hypotheses. Each one links back to source and, where possible, to golden-master cases that exercise it. Subject-matter experts confirm or correct them. The confirmed rules become documentation the organization did not have before, which is valuable even if the migration never happens.

Risk ranking

Finally, the Atlas ranks modules by migration risk. The signals we plan to use include:

• size and complexity of the module;
• number of inbound dependencies;
• use of hard-to-translate features such as REDEFINES, ALTER or pointer arithmetic;
• how much of the module the golden-master inputs can actually reach;
• how many extracted business rules are still unconfirmed.

The output is a proposed migration order that an engineering lead can adjust. The Atlas does not decide; it makes the decision informed.

Why the Atlas comes first

An agent working on a module needs context: what this module is for, what calls it, which rules it implements and which tests prove it still works. The Atlas is that context, written down once and reused for every agent session. It is also the first thing we plan to deliver to design partners, because it is useful on its own.