What I tried

On November 21, 2026, AWS Japan published Reverse Spec Flow (RSF) on AWS Samples. It is a workflow that reads an existing code base and writes specifications for AI agents to use. The target is code with no specs, outdated specs, or code nobody understands anymore.

I wanted to see the whole loop on something small, so I did three things:

  • Ran RSF on a 300-line PHP + MySQL app I wrote for this test
  • Gave only the generated specs to another AI agent and had it rebuild the app in TypeScript
  • Deployed the rebuild to AWS with the AWS CDK and checked it against the old logic

Announcement (Japanese): https://aws.amazon.com/jp/blogs/news/aidm-introducing-reverse-spec-flow/
Repository: https://github.com/aws-samples/sample-reverse-spec-flow

How RSF works in five phases

RSF splits the work into five phases. Phase 0 pins the commit and decides the scope. Phase 1 builds a code graph, a list of modules, entry points, and external connections. That list becomes the denominator for coverage: the work is not done until every node has a spec. Phase 2 analyzes the code, Phase 3 writes the specs, and Phase 4 audits them.

Every statement in a spec carries a path:line citation, and anything the code cannot prove stays as UNKNOWN. The workflow is also not "done" when the agent says so. It is done when the gate script gates.sh exits with 0.

Between phases, the agent stops and asks a human to confirm (a HITL gate).

The test app

The app is a tiny shop called legacy-shop: 7 files, about 300 lines, procedural PHP with MySQL.

  • index.php lists active products
  • order.php takes a member ID and a quantity and places an order
  • orders.php lists orders and lets you ship or cancel them
  • batch/low_stock_report.php runs from cron at 7:00 and writes products with stock under 5 to a CSV

The business rules sit in lib/functions.php. Here is the price calculation:

// returns array(subtotal, discount, shipping, tax, total) function calc_price($price, $qty, $rank_code) { $subtotal = $price * $qty; $discount = (int)floor($subtotal * discount_rate($rank_code)); $after = $subtotal - $discount; $shipping = ($after >= FREE_SHIPPING_LINE) ? 0 : SHIPPING_FEE; $tax = (int)floor(($after + $shipping) * TAX_RATE); $total = $after + $shipping + $tax; return array($subtotal, $discount, $shipping, $tax, $total); } 

Gold members get 10% off and silver members 5%. Shipping is free at 10,000 yen or more after the discount, otherwise 500 yen. Tax is 10%, rounded down. An order can only move from NEW to SHIPPED or from NEW to CANCELLED, and cancelling puts the stock back.

I used RSF v2.2.1 (commit caa0a9d) and Claude Code 2.1.323 on Amazon Bedrock in us-east-1. The model was Claude Opus 4.6, and later Claude Opus 4.5 (more on that below). The rebuild went to the Tokyo region.

Step 1: Put the target under git

RSF pins a commit, so the target has to be a git repository.

cd legacy-shop git init git add -A git commit -m "legacy-shop initial" 

Step 2: Create the spec repository with init.sh

Clone RSF next to the target and run init.sh.

cd .. git clone https://github.com/aws-samples/sample-reverse-spec-flow.git ./sample-reverse-spec-flow/init.sh ./legacy-shop legacy-shop rebuild --playbook php-procedural-mysql 

The third argument, rebuild, asks for specs deep enough to rebuild the app. Use maintenance if you only want to understand the current system. The Playbook holds counting rules for procedural PHP, and RSF also works without one.

This creates legacy-shop-spec/ next to the target. The specs go there, and the target code is never modified.

Step 3: Run Phase 0 to 4 with Claude Code

The README says to open legacy-shop-spec/ in a new session and give an instruction like this:

Read spec-extraction/AGENTS.md. The source to analyze is in /path/to/legacy-shop (read-only; do not modify it). Fill in the <PLACEHOLDER> values in spec-extraction/AGENTS.md, then start from Phase 0. 

I pointed Claude Code at Bedrock with environment variables:

export CLAUDE_CODE_USE_BEDROCK=1 export AWS_REGION=us-east-1 export ANTHROPIC_MODEL=us.anthropic.claude-opus-4-6-v1 cd legacy-shop-spec claude 

In this test I ran it one turn at a time with claude -p and --continue. When the agent reached a gate, it wrote its questions and stopped, and the answer went in as the next turn. The gate answers were written by another Claude (Claude Code) session that was driving the whole test.

One thing to check first: your Claude Code version. RSF isolates its verifier agent (spec-verifier) so it cannot read the specs it is checking. According to HOST.md, the setting that makes this work (omitClaudeMd) needs Claude Code 2.1.271 or later. My global claude was 2.1.220, so I installed a newer one inside the work folder.

What the gates asked

There were three gates. Each one listed decisions the agent had made on its own and asked me to approve them.

  • Phase 0 to 1: Are the four code comments the only reference material (yes, since I wrote the app)? Is a "medium" risk that the cron line differs from production acceptable?
  • Phase 1 to 2: Is the code graph (10 nodes, 21 edges) right, and is it fine to treat the whole app as one business capability?
  • Phase 3 to 4: Are the nine spec files right, and is it fine to narrow cross-cutting concerns to five?

All three were approved. Phases 2 and 3 finished in a single turn without a gate in between.

A 429 in the middle of Phase 4

Phase 4 starts many verifier agents in parallel. Partway through, Claude Opus 4.6 on Bedrock hit the daily token limit and the calls started coming back with a 429:

API Error: Request rejected (429) · Too many tokens per day, please wait before trying again. 

I stopped the process, switched to Claude Opus 4.5, and resumed. In the resume prompt I told the agent to throw away results from verifiers that ended in a 429, verify those blocks again, and run at most four verifiers at a time. RSF keeps its progress in files and git, so it picked up where it left off.

The specs it produced

gates.sh phase4 exited with 0:

✅ 全ゲート通過(WARN 2)。結果を spec-extraction/03-audit/gate-results.md に記録した。 

(The gate output is in Japanese. It says all gates passed with two warnings.)

The specs/ folder ended up like this:

specs/ ├── AGENTS.md <- rules for agents that use the specs ├── overview.md ├── cross-cutting.md <- transactions, XSS handling, and so on ├── source-index.md <- reverse index from source files to specs ├── api/legacy-shop.md <- the four entry points ├── behavior/order-processing.md ├── data/ <- members / products / orders / stock report CSV ├── modules/legacy-shop.md └── rebuild/legacy-shop.md <- technology-independent spec for the rebuild 

The specs are written in Japanese. The business rules in rebuild/legacy-shop.md carry line citations, for example "free shipping at 10,000 yen or more after discount (./lib/functions.php:44, ./config.php:9-10)". The spec also called out that the app has no authentication and that anyone can see everyone's orders, and marked both as decisions to make in the rebuild. Things outside the code, such as how members get registered, stayed as UNKNOWN.

The verifiers found 10 errors

In Phase 4 the specs were split into 20 blocks, and isolated verifiers checked each block against the source. They found 10 errors across 7 blocks: an incomplete SQL WHERE clause, wrong line numbers, and miscounts. All of them were fixed, and the work only finished after a second round found zero. A separate adversarial audit then found 4 more issues, such as wrong numbers, which were also fixed.

This was a 300-line app, and an independent check still found errors in the specs.

Time and cost

The cost comes from the total_cost_usd estimate that Claude Code printed. All five runs continued the same session with --continue, so that value is cumulative, and the numbers below are the differences between runs. I did not check the actual Bedrock bill.

  • Phase 0: about 2 minutes, about $2.0
  • Phase 1: about 5 minutes, about $3.5
  • Phase 2 and 3: about 11 minutes, about $4.7
  • Phase 4: about 19 minutes and $19.0 until the 429, then about 21 minutes and $18.0 after resuming

In total that is about one hour and roughly $47, and about $37 of it went to Phase 4. The announcement recommends specifying a small code base under 10,000 steps (lines of code) first to measure consumption, then widening the scope.

Step 4: Rebuild from the specs only

Next, I gave only specs/ to a separate AI agent (Claude Code) and asked it to rebuild the app in TypeScript. It never saw the PHP code.

I fixed the target architecture up front:

  • Amazon API Gateway (HTTP API) and AWS Lambda serve the three pages
  • Amazon DynamoDB holds three tables
  • Amazon EventBridge Scheduler runs a Lambda function at 7:00 JST that writes the CSV to Amazon S3

Placing an order uses a DynamoDB transaction: decrement the stock only if there is enough, and create the order in the same transaction. That matches what the MySQL transaction did.

The price calculation came out like this:

export function calcPrice(unitPrice: number, qty: number, rankCode: string): Price { const subtotal = unitPrice * qty; // 整数のまま計算して切り捨てる(小数の誤差で1円ずれないように) const discount = Math.floor((subtotal * discountPercent(rankCode)) / 100); const afterDiscount = subtotal - discount; const shipping = afterDiscount >= FREE_SHIPPING_THRESHOLD ? 0 : SHIPPING_FEE; const tax = Math.floor(((afterDiscount + shipping) * TAX_RATE_PERCENT) / 100); const total = afterDiscount + shipping + tax; return { subtotal, discount, shipping, tax, total }; } 

(The comment says: calculate in integers and round down, so floating point errors cannot shift the result by 1 yen.)

I asked the agent to write down everything the specs did not settle in SPEC-GAPS.md. It listed 23 items. Three examples:

  • The old code multiplies by a float. The rebuild uses integer math, and the specs cannot tell whether any input makes the two differ by 1 yen
  • The specs do not say what discount applies to ranks other than N, S, and G, so the rebuild uses 0%
  • No authentication, same as today, with the decision left open

specs/AGENTS.md has a rule that an agent without the original source must not claim it "verified" anything. The agent declared "no-source mode" at the top of SPEC-GAPS.md.

To save time, I started the rebuild before the Phase 4 audit had finished. After the audit, I had another agent compare the audited specs with the rebuilt code on seven points: pricing, order validation, stock updates, status changes, both list pages, and the stock report. It found no mismatch. If you follow the intended order, wait until gates.sh phase4 passes before rebuilding.

All 36 unit tests passed:

npx vitest run # Test Files 5 passed (5) # Tests 36 passed (36) 

Step 5: Deploy and compare

npm install npx cdk deploy npm run seed # 3 members and 6 products 

The deploy took about 65 seconds. I sent orders with curl:

URL=https://xxxxxxxx.execute-api.ap-northeast-1.amazonaws.com # Gold member (ID 3) orders 3 desk lamps at 4,800 yen curl -s -X POST $URL/order -d product_id=3 -d member_id=3 -d qty=3 

Then I compared the results with values I worked out by hand from the PHP formula.

  • Gold member, 3 lamps: 14,400 minus 1,440 is 12,960 (free shipping), plus 1,296 tax, so 14,256 yen expected. The app returned 14,256 yen
  • Silver member, 2 lamps: 9,600 minus 480 is 9,120, plus 500 shipping and 962 tax, so 10,582 yen expected. The app returned 10,582 yen
  • Cancelling the silver order brought the lamp stock from 3 back to 5, and cancelling an already shipped order was rejected with "This order cannot be changed"

The error cases matched as well: quantity 11 gave "Quantity must be 1 to 10", 4 pens with 3 in stock gave "Not enough stock", and an inactive product gave "Product is not available".

I ran the stock report Lambda function by hand and read the CSV from S3:

aws lambda invoke --function-name <LowStockReportFunction name> /dev/stdout aws s3 cp s3://<ReportBucketName>/low_stock_20261122.csv - 
id,name,stock 5,Stapler,0 4,Office Chair,2 2,Ballpoint Pen,3 

Active products with stock under 5, lowest first. The inactive product with a stock of 1 is not in the list, which is what the spec says.

Clean up

cd rebuild-shop npx cdk destroy 

The DynamoDB tables and the S3 bucket are set to be deleted with the stack.

What I would tell someone trying this

The specs covered more than formulas. They flagged the missing authentication and the fact that anyone can see all orders, which are exactly the things you need to decide before a rebuild. The rebuild agent then listed 23 open points on its own, including the float versus integer difference in pricing.

Plan for Phase 4. On a 300-line app it took the most time and most of the cost, and it is also where the 10 errors were caught. If you run it on Bedrock, keep an eye on the per-model daily token limit, because the parallel verifiers are what pushed me over it.