How to write requirements for a rewrite when the old system is the only spec

Why the old system makes a poor spec on its own

When a rewrite starts, the old system is usually the only complete description of how the business works. The original authors have moved on, the documentation is out of date or was never written, and the people who use the screens every day know what the system does but not why. So the code becomes the spec by default.

That default is risky. Code records everything the system does, including behavior nobody chose on purpose. If you copy all of it, you rebuild every workaround and old mistake. If you copy only what people remember, you lose rules that nobody has thought about in years. Writing requirements from legacy code means sorting between those two failures, and it needs a method.

This page covers how to turn recovered rules, screens and data flows into requirements a development team can build against, and how to separate the behavior you must keep from the accidents of history.

Start by recovering three things, not one

Teams that reverse engineer requirements from a legacy system often collect only rules. A usable requirements set needs three inputs, each tied back to the code it came from.

  • Business rules. Calculations, validations, eligibility checks and state changes. For example, a rule that derives a net payment from an amount and a fee.
  • Screens and workflows. What a user sees, in what order, and which triggers fire when they act. In an Oracle Forms application this includes forms, triggers and the sequence of steps between them.
  • Data flows. Where each field originates, how it is transformed, and which tables, reports and downstream records it reaches.

Rules without workflows tell you what is calculated but not when. Workflows without data flows hide the side effects, such as a ledger entry or audit record written as a consequence of one field changing. If you need help getting these out of the code, see our guides on extracting business rules from COBOL and tracing a field from screen to table.

Write each requirement as behavior, with evidence attached

A requirement a development team can build against states what the system must do in terms a tester can check, without prescribing how the old code did it. The structure that works well has four parts.

  1. The behavior. Write it in plain language: given this input, the system produces this result. Describe the business outcome rather than the COBOL paragraph or the PL/SQL trigger.
  2. The source reference. Point to the program, form or table where the behavior lives. This lets a developer or auditor check your reading of the code.
  3. The affected data. List the fields read and written, including secondary records like audit trails.
  4. The acceptance check. Describe how you would show the new system matches. Real inputs and outputs from the old system make the best test cases. See our piece on proving a migrated system behaves like the old one.

Keep the source reference even when the requirement is clear. Six months into the project, someone will ask why a rule exists, and the answer should be one link away rather than a search through old code.

Separate must-keep behavior from historical accident

This is the step that decides whether the rewrite improves on the old system or just reproduces it. Every recovered behavior should land in one of four buckets, ideally reviewed with someone from the business side.

  • Must keep. Behavior tied to a regulation, contract, financial calculation or audit obligation. Changing it needs a deliberate decision and sign-off.
  • Keep for now. Behavior users depend on, even if it looks odd. Carry it over, flag it, and revisit after cutover rather than during it.
  • Historical accident. Workarounds for hardware or software limits that no longer exist, field lengths chosen because of old storage costs, and screens shaped around a terminal. These are candidates to drop.
  • Dead code. Logic that no input can reach. Confirm it is unused before excluding it. Our guide to finding unused code in a legacy system covers how.

A useful test for borderline cases: ask who would notice if the behavior vanished. If the answer is a regulator, a customer or a finance team, it belongs in the first two buckets. If nobody can name a person, it is a candidate for removal, but record the decision so it can be traced later.

Where tooling helps and where people decide

Reading a large legacy codebase by hand is slow, and it is where requirements work most often stalls. Replai reads existing code in languages such as COBOL, PL/I and Oracle Forms and builds a structured map of the business rules, workflows and dependencies, with each item linked to its source. That gives a team a starting inventory to review instead of a blank page. For background on how that analysis works, see how AI agents read legacy code.

The sorting is still human work. A tool can show what the code does and what it connects to. It cannot tell you whether a rounding rule is a regulatory requirement or an old shortcut. Treat the recovered map as evidence, and have the people who own the business process make the keep-or-drop calls.

Once the requirements exist, they also help you choose an approach. A clear list of must-keep behavior makes it easier to compare options in rehost, refactor, rewrite or replace and to plan a staged replacement such as the strangler fig pattern.

Frequently asked questions

Can legacy code serve as the requirements document for a rewrite?

It can be the main source, but not the whole spec. Code shows what the system does, including behavior nobody chose on purpose, so it needs review by people who own the business process before it becomes a requirement.

What should I recover from a legacy system before writing requirements?

Three things: business rules, screens and workflows, and data flows. Rules alone miss timing and side effects, such as audit or ledger records written when a field changes.

How do I decide which legacy behavior to keep?

Sort each behavior into must keep, keep for now, historical accident, or dead code. Ask who would notice if it disappeared: a regulator, customer or finance team means keep it.

Why attach a source reference to every requirement?

It lets developers and auditors verify your reading of the code and answer later questions about why a rule exists without searching the old system again.

Can AI tools write requirements from legacy code?

They can recover and map rules, workflows and dependencies from code, giving the team an inventory to review. Deciding which behaviors are essential still needs people who understand the business.

How do I show that the new system matches the old one?

Define an acceptance check for each requirement, using real inputs and outputs from the old system as test cases wherever possible.