You are asked to update an existing system or add new features. Before making architecture decisions, you need to understand what the system actually does today.
There is documentation, which should make your job easier.
But as you start reading it, you find problems.
A context diagram exists, but as you investigate further, you discover dependencies between systems that are missing. The document lists SQL scripts and Python jobs but does not explain what they do or which business rules they apply. It is unclear which processes write to which database tables.
So you start looking elsewhere.
You inspect parts of the code and database schema. You talk to developers and the operations team. Each source gives you another piece of the picture, but the pieces do not always agree.
This creates a difficult situation. Your manager expects you to move toward the new design, but you are still trying to understand the existing system. Moving ahead without this understanding creates a bigger risk.
The problem is not simply that the documentation is old.
You have several sources that describe parts of the system, and you need to find out what is correct, what conflicts, and what is still unknown.
How an LLM Can Help
An LLM can’t tell you how your system really works. It wasn’t there when the system was built, and it doesn’t know which document is correct.
But it can help you organize and compare the information you already have.
Start by identifying the information that can help you understand the system. This may include parts of architecture documents, selected code or SQL, parts of the database schema, operational notes, and information collected from people who know the system.
Do not assume that you can share complete documents, source files, or schemas with an AI tool.
Use only the information you need. Make sure both the AI tool and the information are approved for this use. Remove sensitive details when needed.
Configuration files require extra care because they may contain security-sensitive information. In many cases, you should not provide the complete configuration file.
Once you have selected the information you can use, work in two passes.
Pass 1: Understand the Current System
First, ask the LLM to describe the system using only the information you provided.
The important part is to tell it not to fill gaps with assumptions. If something can’t be determined from the available information, it should say so.
Try This Prompt
I am trying to understand how this system works today.
Using only the information I provided, describe the main components, data flows, processing steps, and data stores.
For important statements, tell me which source supports them.
If the information is missing or unclear, say that it is unknown. Do not guess based on how similar systems normally work.
Review the result before moving to the next pass. Look for anything that does not match what you already know. Your goal is not to create perfect documentation. It is to create a first description that you can review.
Pass 2: Look for Conflicts and Missing Information
The second pass is more interesting.
Ask the LLM to compare the same sources and look for places where they disagree.
For example, the architecture document may say that a validation happens before data is stored, while the code suggests that part of the validation happens later. A SQL script may write to a table that is never mentioned in the documentation.
You also want the LLM to identify information that can’t be confirmed.
Try This Prompt
Compare all the information I provided about this system.
Find places where two or more sources disagree.
Identify information that appears in only one source or cannot be confirmed from the available sources.
Do not decide which source is correct when there is a conflict.
Organize the findings into:
- What we know
- Conflicts between sources
- What still needs to be confirmed
- Questions I should ask the developers, operations team, or system owner
The last part is important.
Instead of giving you only another document to read, the LLM can help turn the gaps into questions you can investigate:
- In what order are the validation steps executed?
- Is this SQL process still running in production?
- Which process writes to this table?
- Are there processing steps or exceptions missing from the current documentation?
These questions can become the agenda for your next discussion with the people who know the system.
Building a Clear Picture of an Existing System from Different Sources –
AI Helps with the Investigation, Not the Final Answer
There is an important limitation. A clear AI answer is not proof that it is correct.
The LLM only sees the information you give it. Important knowledge may exist only in someone’s memory. Two documents may contain the same wrong information. Code may show what the system does, but not why it does it.
The LLM can also miss conflicts or connect information incorrectly.
That is why the architect remains responsible for checking key findings and deciding which sources to trust.
Use AI to help you investigate the system, not to decide what is true.
A Question for You
When you inherit an existing system, how do you decide that you understand it well enough to start changing it?
I am collecting real problems that software architects face when using AI in their daily work. If outdated or incomplete documentation is one of them, I would like to hear how you deal with it.