レガシーJava APIをClaude CodeでTypeScript+Honoに移行する手順(教材zip付き)

この記事でわかること:

• レガシーJava(Java 8スタイル)のAPIを Claude Code で TypeScript + Hono に移し替える具体的な手順
• 移行を安全に進める順序 —— 仕様書化 → テストの安全網 → 移行 → 突き合わせレビュー
• AIが高確率で取りこぼす仕様(大文字小文字・空文字・404)と、その見つけ方

前提

• Windows 11 / Node.js 20 LTS / JDK 17以上(Temurin) / Claude Code(2026年8月時点の最新版)/ Hono v4
• 題材は教材用のレガシー風Javaプロジェクト legacy-orders(注文管理。raw型・Calendar・長いメソッドを意図的に残した約500行。MIT)
• 業務コードは使わない。教材zipは ハンズオン教材サイト から取得できる(Maven不要・JUnitランチャー同梱)

# 教材のセットアップ(zip展開後)
cd legacy-orders
run-tests.cmd        # 既存テスト2件がグリーンになればOK
claude               # Claude Code起動

Step 1: 現行仕様を読ませ、人間が突き合わせる

移行の最初の作業はコーディングではなく現行仕様の固定だ。Claude Code に次を指示する。

src/main/java/com/example/orders/OrderService.java の現行仕様を読み解き、
公開メソッドごとの入力・出力・例外、バリデーションのルール、
注文ステータスの遷移がわかる仕様書を docs/order-service-spec.md に作成してください

数分で仕様書が出てくるが、そのまま信用してはいけない。コードと突き合わせると、私の場合は 「キャンセル時に在庫を戻す」仕様が抜けていた。「◯◯が抜けている。追記して」と指摘すれば直る。この突き合わせをやるかどうかが移行の品質を決める。

Step 2: テストで現行の挙動を固定する

移行後の同値性を機械的に確認できるよう、先に移行元へテストを張る。境界値を明示的に指定するのがポイントだ。

PriceCalculator.java に JUnit 5 のユニットテストを作成してください。
送料無料になる5000円の境界、クーポン適用の3000円の境界、
まとめ買い割引の10個の境界、会員ランクごとの割引を必ず含める。
作成後、run-tests.cmd を実行して全テストが通ることを確認してください

生成されたテストは1本ずつ読む。「5000円ちょうどは送料無料か」を自分で答えられない状態でグリーンを喜んではいけない。

Step 3: Honoへ移行させる

OrderService の注文検索(顧客IDの前方一致)と1件取得と同等のREST APIを、
TypeScript + Hono で新規フォルダ hono-orders に実装してください。
- データはメモリ上のサンプル配列でよい
- GET /orders?customer=xx で検索、GET /orders/:id で1件取得
- 元のJava実装とAPI仕様の対応表を hono-orders/SPEC.md に作成
- npmで起動し、curlでの動作確認まで行ってください

生成される実装の骨格はおおむねこうなる。

import { Hono } from "hono";

const app = new Hono();

app.get("/orders", (c) => {
  const prefix = (c.req.query("customer") ?? "").toLowerCase();
  if (!prefix.trim()) return c.json([]);
  return c.json(
    orders.filter((o) => o.customerId.toLowerCase().startsWith(prefix))
  );
});

app.get("/orders/:id", (c) => {
  const found = orders.find((o) => o.id === c.req.param("id"));
  return found ? c.json(found) : c.json({ error: "not found" }, 404);
});

export default app;

cd hono-orders && npm install && npm run dev
curl "http://localhost:3000/orders?customer=ta"
curl "http://localhost:3000/orders/ORD-00001"

Step 4: SPEC.md の対応表を突き合わせる(ここが本番)

AIは動くコードを速く書くが、元実装の暗黙仕様を高確率で取りこぼす。SPEC.md の対応表を元のJavaコードと突き合わせ、差分を指摘して直させる。

ハマりどころ

1. 大文字小文字の扱い
Java側の検索は toLowerCase() で大文字小文字を無視していたが、初回生成のHono側は区別していた。?customer=TA で結果が変わってしまう。対応表に「case-insensitive」と書かれているかを必ず確認する。

2. 空文字・null の挙動
Java側は空文字・nullで「空リストを返す」仕様。Hono側は未指定時に全件を返す実装になりがちで、これは情報漏えい相当の仕様差になる。

3. 存在しないIDのレスポンス
Java側は null を返すだけだが、REST APIとしては404を返すべきだ。ここは「仕様差を直す」のではなく「移行を機に仕様を明文化する」判断ポイントになる。判断はAIではなく人間がやる。

実測のすすめ

「従来なら何分かかったか」を先に見積もってから各Stepの実時間を測ると、自分の環境での短縮率が手に入る。他人のベンチマークを引用するより、自分の実測値で語るほうが社内の説得力は圧倒的に高い。

まとめ

• 移行は「仕様書化 → テスト → 移行 → 突き合わせ」の順序でやれば小さく安全に試せる
• AIは書くのが速いが、大文字小文字・空文字・404 といった暗黙仕様を落とす。見つけて直させるのが人間の仕事
• レガシーを読める人ほど、この分業の恩恵は大きい

---

この記事は Shimanto AIブログの元記事 を Qiita 向けに再編集したものです。手順を全3回・約8時間で体験できる無料ハンズオン教材(サンプルコードzip付き)も公開しています。