[News] AWS releases tool to generate specifications from existing code

IT

AWS Japan has released “Reverse Spec Flow,” a tool that automatically generates specifications for AI agents from existing code. This development comes against a backdrop of legacy systems becoming “black boxes” and a growing need for AI-driven reconstruction.

Overview of Reverse Spec Flow, released in November 2026

On November 21, 2026, Amazon Web Services Japan unveiled Reverse Spec Flow, a new AI-driven modernization tool, on its official blog. This tool follows the AI Modernization Flow announced on October 6, 2026, and serves as a specification creation workflow that acts as the gateway to “Reimagine”—rebuilding the entire system—as opposed to “Refactor,” which focuses on refreshing the technology stack. In the legacy systems used by many companies, design documents have often become missing or obsolete due to years of modifications, creating a “black box” challenge where developers are forced to decipher source code directly just to understand system behavior. Reverse Spec Flow has been released as an open-source workflow in a sample repository on GitHub, allowing anyone to verify it in their own local environment. After setting up the environment, developers can run a simple script and provide instructions to AI agents such as Kiro or Claude Code to automatically generate high-quality specifications from the target code. Please refer to the following configuration image for a conceptual diagram to understand the overall system architecture.

Figure 1

The introduction of this tool is expected to significantly streamline the investigation of current systems, a task that previously required substantial man-hours and human resources.

Traditional Challenges in Legacy System Migration and the Risks of Leveraging AI

In traditional migration projects, assigned engineers manually traced code to create specifications, meaning that the analysis phase alone incurred enormous time and costs. With the rise of generative AI, attempts have been made to input code directly into AI agents and request the generation of specification documents, but this approach carried serious risks. Primary challenges include the introduction of hallucinations—where baseless information is generated—the omission of critical processing, and an over-reliance on specific technologies, such as existing frameworks or data structures. Additionally, there were frequent omissions of elements that are difficult to discern from code alone, such as input validation for web screens or the sequence of batch processing. Even more alarming are “silent failures,” where functionality disappears without triggering any errors or exceptions. For example, during a version upgrade of the Struts web framework, a phenomenon occurred where default security settings caused screen outputs to be empty; because unit tests and HTTP statuses remained normal, the issue could not be discovered until manual E2E testing was performed. Since AI-generated documents present verified facts and unverified conjectures in the same format, it has been pointed out that there is a risk of incorrect specifications propagating directly into subsequent development phases.

The Mechanism and Five-Step Process of Reverse Spec Flow

Five phases and validation mechanisms supporting high accuracy

Reverse Spec Flow does not rely on AI intuition or gut feelings; instead, it proceeds through a workflow consisting of five strictly defined phases. In Phase 0 (Ingestion), the target code commit is fixed, and in Phase 1, a code graph representing the connectivity of the entire system is created to establish the denominator for analysis. In the subsequent Phase 2, multidimensional analysis is performed; in Phase 3, specifications compliant with the international standard ISO/IEC/IEEE 29148 are authored; and in Phase 4, an independent audit is conducted. Within this process, the file path and line number of the supporting source code are explicitly provided for every description, eliminating baseless assertions. A double-check structure is integrated into the system, where a separate AI—distinct from the one responsible for creating the specifications—acts as a verifier to cross-reference the code with the written content. The completion of each phase is not determined by AI self-reporting, but is instead performed mechanically based on whether the audit script gates.sh returns a passing code. Furthermore, the system features a gate function that pauses processing at critical boundaries where the cost of backtracking is high, allowing for human judgment. Please refer to the following diagram for an overview of the workflow and the transitions between each phase.

Figure 2

A two-layer structure that separates implementation reality from essential specifications

One of the groundbreaking aspects of this workflow is the organization of the generated specifications into two distinct layers. The first is the “Implementation Facts Layer,” which records concrete details of the current code and design information that depends on specific programming languages or frameworks. The second is the “Technology-Independent Essence Layer,” which extracts essential specifications that would remain unchanged even if the system were rebuilt with a different technology stack in the future, such as business rules, state transitions, logical data models, validation conditions, and external integration specifications. For items that cannot be objectively determined from the code, the system strictly prohibits the AI from guessing and filling in the blanks; instead, a mechanism is enforced to explicitly mark these as pending with an “UNKNOWN” label. Each specification item is assigned a unique identifier (such as REQ-F-01), and the system automatically generates both an index for searching files by ID and a reverse index for tracing specifications back from the source code. This allows subsequent AI agents to pinpoint and reference only the necessary specifications without having to read the entire dataset, and it can also be utilized for impact analysis during the maintenance of existing systems.

Verification Results and Key Points to Watch for Future Commercialization

Empirical data from an open-source platform on the scale of 150,000 lines

An announcement from AWS Japan presents the results of a proof-of-concept (PoC) using Apache Roller 6.1.5, an open-source CMS for blogs. This system is an application written in Java consisting of approximately 150,000 lines of code and features a complex configuration that includes batch processing and external integrations. When Reverse Spec Flow was applied using the most detailed verification settings, the specification process was completed in approximately 38 hours, including time spent waiting for human review. After randomly extracting 200 descriptions from the generated specifications and cross-referencing them with the original source code, it was found that while approximately 5% contained minor flaws—such as some missing conditions or overstatements—there were zero instances of hallucinations, which are considered critical errors. Furthermore, by executing the AI-DLC workflow using the extracted specifications as input, the project successfully achieved a zero-base reconstruction into a new architecture using TypeScript and Next.js. This method has also been applied to Apache Fineract, a financial system platform consisting of approximately 840,000 lines of code, demonstrating that even large-scale codebases can be handled through parallel processing via sub-agents.

Preparations for Implementation and the Outlook for Future Modernization

When companies consider implementing Reverse Spec Flow, they set up the development environment with compatible AI tools such as bash, git, Kiro, and Claude Code, and then initialize the workspace using the provided init.sh script. Depending on the objective of the analysis, users can choose from three modes: “maintenance,” “evaluation,” and “rebuild.” Additionally, “Playbooks”—knowledge bases supporting 10 different programming languages, including Java, .NET, COBOL, VB6, PHP, and PL/SQL—are available.

However, AWS Japan emphasizes that this tool is not a “magic wand” that automatically produces an optimal system. Human engineers and business stakeholders must make the final determination as to whether the extracted specifications align with the company’s business requirements and whether the system can be sustainably maintained after migration. Moving forward, the key to successful legacy modernization will be establishing a framework that appropriately combines automated drafting with human decision-making, while proceeding with migration in parallel with test automation.

Reference page

  • [AWS Official Blog] [AI-Driven Modernization] Announcing “Reverse Spec Flow” to Generate Specifications for AI Agents from Existing Code

  • 【AWS Official Blog】[AI-Driven Modernization] Introducing “AI Modernization Flow” to Enable Disciplined Migration Tasks by AI Agents

AIDM: Introducing AI Modernization Flow

The utilization of AI has become a critical management strategy that determines a company’s competitiveness, going beyond mere technical updates.

However, many companies face challenges such as, “We want to introduce AI, but we don’t know where to start,” or “We cannot determine whether our existing systems and data are suitable for AI utilization.”

To solve these challenges and help companies take smooth steps toward AI adoption, we have launched an initiative called “AIDM (AI Digital Modernization).” The core process of this initiative is the “AI Modernization Flow” that we are introducing today.

What is AIDM?

AIDM is an initiative designed to support companies in their journey toward digital transformation (DX) through the integration of AI. Instead of just introducing individual AI tools, AIDM focuses on modernizing the entire business processes and data foundations to realize the full potential of AI.

Overview of AI Modernization Flow

The AI Modernization Flow is a structured methodology provided as part of AIDM to guide companies through the complexities of AI introduction. It consists of three main stages: Assessment, Design, and Implementation.

The Three Steps of AI Modernization Flow

1. AI Readiness Assessment

In this first step, we evaluate the current state of your organization’s data, infrastructure, and human resources.
* Data Assessment: Is the data organized and accessible? Is the quality sufficient for AI training and inference?
* Infrastructure Assessment: Are the existing cloud environments and computing resources capable of supporting AI workloads?
* Skill Assessment: Does the organization have the necessary expertise to operate and maintain AI systems?

2. AI Application Design

Based on the assessment results, we design the specific AI applications and the architecture required to support them.
* Use Case Identification: Identifying which business processes will benefit most from AI.
* Architecture Design: Designing a scalable and secure architecture using AWS services (e.g., Amazon Bedrock, Amazon SageMaker).
* Data Pipeline Design: Designing how data will be collected, processed, and fed into AI models.

3. AI Implementation & Operation

The final step involves the actual development, deployment, and continuous monitoring of the AI solutions.
* Development & Deployment: Building the AI models and integrating them into business workflows.
* Continuous Monitoring: Monitoring model performance and data drift to ensure accuracy and reliability.
* Iterative Improvement: Continuously updating the models and processes based on feedback and new data.

Summary

Introducing AI is not a one-time project but a continuous journey of modernization. The AI Modernization Flow within the AIDM framework provides a clear roadmap for companies to navigate this journey, moving from assessment to implementation and ensuring long-term success in the AI era.
– [GitHub Repository] aws-samples/sample-reverse-spec-flow
https://github.com/aws-samples/sample-reverse-spec-flow
– [GitHub Repository] apache/roller (v6.1.5)
https://github.com/apache/roller/tree/roller-6.1.5

【#AWS #GenerativeAI #LegacyModernization #AutomatedSpecificationGeneration #ReverseSpecFlow】

コメント

Copied title and URL