No Spec? Build a Current-State Spec from Code with AI
Summary: When a running system has no specification left, AI such as Claude Code can read the source code and draft a current-state spec (現行仕様書). The draft shows what the system does today, not why. So every item must be confirmed by business users before the spec becomes the basis for a new system.
Contents
- Can AI build a current-state spec from source code?
- What does a code-derived spec tell you, and what doesn't it?
- What are the steps to build a current-state spec?
- How do you confirm each item with business users?
- Where does this fit in VAON's Spec Lock Phase?
- When should you not do it this way?
- FAQ
1. Can AI build a current-state spec from source code?
AI can produce a draft, but the draft is not yet a spec. Claude Code, according to Anthropic's public documentation, is a coding tool that can read an entire codebase, so it handles quickly what tires a human reader: hundreds of screens, data tables, nested conditionals.
But a system that has run for ten years holds ten years of decisions by many people, edited again and again. Code records the outcome of those decisions, not the reasons. So VAON treats AI output as a list of hypotheses about system behavior. The real work is checking each hypothesis with the people who use the system.
We have done this on real projects. We do not have measurements yet (how much faster, what percentage correct), so this article gives no numbers and names no clients.
2. What does a code-derived spec tell you, and what doesn't it?
A spec derived from source code tells you what the system does at the level of behavior, and says almost nothing about why, whether a rule is still alive, or what lives outside the code. This table lists the limits worth knowing before you start.
| Question | Can a code-derived spec answer it? | How to handle it |
|---|---|---|
| What does the system do (screens, APIs, batch jobs, calculations)? | Mostly | Compare against the running screens |
| Why does this rule exist? | No | Ask business owners and long-time staff |
| Is this rule still used, or dead? | Not reliably: code that exists may never run | Check logs and real data, ask users |
| Logic outside the code (master data, real environment settings, manual steps)? | No | Interview operations, inspect the real environment |
| How does a third-party system behave? | Only the call, not the inside | Vendor documentation, ask the owner |
| Is this behavior a spec or a long-standing bug? | Cannot tell | Business users decide keep or fix |
The last row is the dangerous one. A defect that has existed for years, if AI records it as "spec," gets copied straight into the new system. Staff may even have learned to work around it and consider it normal.
3. What are the steps to build a current-state spec?
VAON's procedure has seven steps. AI takes part only in steps 2 to 4, and people own the rest.
- Agree on permission and scope. Ask whether the client allows the source code to go into an AI tool, and which parts. Sign an NDA, agree which data may be used and who may see it. If not allowed, no code goes into AI; people read the code instead, slower but still doable.
- Inventory the system. List the entry points: screens, APIs, batch jobs, data tables, external integrations. This is the skeleton of the spec, and the list that tells you later what is missing.
- Draft in small units. Let AI read one feature at a time, not the whole system in one pass. Every draft line records its source (file and function) so a reviewer can open it and check.
- Label each item. Each is one of: appears to run, suspected dead, or unclear. Where AI interprets intent ("probably to avoid duplicate orders"), separate it out, because that is a guess, not behavior.
- Write questions for business users. Separate "what the system does" (already from code) from "why, is it still needed, is it right" (only people can answer).
- Hold item-by-item review sessions. See section 4. This step takes the most time and cannot be skipped.
- Finalize and sign off. The confirmed current-state spec, plus a keep, fix, or drop decision for each item, becomes the input for the new system's spec.
In parallel with steps 3 to 6, we observe the system running for real: logs, actual data, real environment configuration. That is the measurement layer the source code does not provide.
4. How do you confirm each item with business users?
Confirming item by item means a business person looks at each behavior in the draft and gives one of four verdicts. An item without a verdict is not yet part of the spec.
| Verdict | Meaning | Next step |
|---|---|---|
| Correct, keep | Behavior is right and needed | Goes into the new spec |
| Wrong, fix | Code differs from how the business really works | Record the correct behavior in the new spec |
| Dead, drop | Nobody uses it | Remove from scope, less work to do |
| Bug, decide | Code differs from original intent | Business owner decides to fix or keep |
Each row should have six columns: item ID, behavior per code, source in code, question for the business user, verdict, confirmer and date. The last column matters. When a dispute comes later, you know who said what and when.
Run sessions by feature group, not by file order. Business people remember workflows, not function names. And bring actual users, not only managers: managers often do not know the detours staff take.
5. Where does this fit in VAON's Spec Lock Phase?
Building the current-state spec is the core of entrance A in VAON's Spec Lock Phase (仕様確定フェーズ), for clients who already have a system. Entrance A means reading the code, interviewing operations, and measuring, led by a BrSE (Bridge System Engineer) and a Tech Lead.
The phase takes 1 to 2 weeks, or 2 to 4 for large projects. The price is fixed, quoted up front, with no add-ons. The output is a requirements document, wireframes for each screen, database design, system architecture, and a fixed-price quote for the build phase. You are free to stop after this phase.
On how we work: our engineers use Claude Code and GitHub Copilot every day, and a person always checks before release. The final result is a document a person signs, not raw machine output.
For how long a requirements phase takes and what it costs in general, read Requirements definition: how long it takes and what it costs. If the people who understood the system have left, see taking over a system after the engineer leaves. For quality control when AI is involved, see the 12-point checklist for outsourcing AI-driven development. Replacing an old system without downtime is covered in legacy CMS modernization with zero downtime.
6. When should you not do it this way?
This approach is not a fit when no business person has time to confirm. Without step 6, you hold a smooth-looking draft no one can verify, which is worse than having no spec.
It also does not work when there is no source code (only a packaged product), when the client has not allowed code into AI tools but still expects AI-level speed, or when most of the system's behavior lives in manual steps and tacit rules the code does not reflect. In that last case, interviews with operations lead and the code plays a supporting role.
And a current-state spec is not a test. It describes what the system does, and does not prove the new system does the same. That proof needs its own test scenarios.
7. FAQ
Our system has no spec and its author has left. Will VAON take it on? Possibly. First we ask whether source code exists and whether business users can take part in confirmation. Those two things decide whether it can be done. The first 60-minute session includes our CEO and needs no documents.
Can AI read code in an old language? It depends on the language and size, and we do not promise before seeing the code. We try one small feature, compare with users, then decide whether to expand. That trial shows real reliability.
Is a spec built by AI correct? It cannot be called correct until business users confirm it. A draft can be wrong where it interprets intent, where a rule is dead, or where a bug is recorded as spec. That is why every item carries a source in the code and a confirmer's verdict.
Do I have to hand over my source code to VAON? Code can stay in your own repository, and we put code or data into AI tools only when you allow it. If not allowed, people read the code, which takes longer.
What comes after the current-state spec? The Spec Lock Phase: requirements document, wireframes, database design, architecture, and a fixed-price quote for the build phase. You can stop after that phase if you want.
Running a system nobody has a spec for? Tell us the situation, even if you do not have the code in hand. Book a free 60-minute consultation
Author: Đoàn Minh Hoàng, Co-Founder & CTO, VAON.
References
- Anthropic, Claude Code overview: https://code.claude.com/docs/en/overview (opened Oct 17, 2026)