はじめに

こんにちは。and factory でサーバーエンジニアをしている松ヶ浦です。

弊社では、自社アプリの広告関連の売上やKPIを管理する社内システムを内製しています。この管理画面はPHP(CodeIgniter 3)で作られていて、いわゆるレガシーな構成のまま運用されていました。PHPのバージョンは2022年11月にサポートが終わった7.4のままで、本来はバックエンドで守るべき権限の制御も画面側のコードで守っているような状態でした。それでも社内専用ということもあって、対応はずっと先送りにされていました。なお、今回のリプレイスでPHPの画面は停止して撤去し、権限の制御もバックエンド側で守るようにしています。

ただ、ここ最近でAIが十分に賢くなり、ハーネスエンジニアリングやソフトウェアファクトリーといった考え方も出てきました。そこで、今ならほぼ全自動でリプレイスできるのではないかと考え、React(Next.js)で作り直すことにしました。

僕はサーバーエンジニアで、フロントエンドを本格的に書いた経験はほとんどありません。そのため、実装はほぼすべてClaude Codeに任せると決めて、進め方の決まりと自動検査の仕組みを「ハーネス」として構築しました。

結果として、予定していた9画面の移植は、実装上のバグを出さずに終えられました。この記事では、作ったハーネスの構成と、実際に運用してみて見えてきた課題を紹介します。

プロジェクトの前提条件と技術スタック

対象は、エンドユーザーが触れない社内専用の管理画面です。売上の集計、KPIのダッシュボード、各種マスタ、管理ユーザーの管理などがあります。ほとんどがシンプルなCRUDで、バックエンドからフロントエンドまで、サーバーエンジニア1〜2名で開発、運用しています。

元のPHP版は、PHP 7.4とCodeIgniter 3.1でサーバー側がHTMLを組み立てる構成で、画面はjQuery、Bootstrap、DataTablesで作られていました。もともとPHPの画面がGoのバックエンドをgRPCで呼ぶ、PHPとGoのハイブリッド構成です。リプレイスに備えて、PHP側にあった集計などの処理はあらかじめGoに移植してありました。そのため、今回はREST APIを使うフロントエンドだけを、次の構成で作り直しています。

用途採用技術
フレームワークNext.js 16(App Router)、React 19、TypeScript
データ取得TanStack Query v5
フォーム周りreact-hook-form、Zod
UIスタイリングTailwind CSS v4、shadcn/ui
APIクライアントorval(OpenAPIからhooks・型・Zodスキーマを自動生成)
テストVitest、Testing Library、Playwright、MSW
CIGitHub Actions
実行環境Node.js 24、pnpm

なぜ「ハーネス」が必要だったのか

チームにはフロントエンドの専任者がいないので、AIが生成したコードを人間が1行ずつ読んでレビューするのは難しいと考えました。かといって、チャット感覚でその都度AIに指示を出すと、出来上がりにブレが出そうです。既存のPHP版と挙動が変わったり、UIの崩れに気づけなかったりすることも心配でした。

そこで、人間がやることを次の3つに絞る仕組み(ハーネス)を作りました。

  1. AIへ指示を出す(skillの実行)
  2. AIが作った実装計画のレビュー
  3. 最終的な画面の確認とマージ

コードの実装、テストの追加、画面キャプチャの撮影までは、Claude Codeと自動検査(CI)に任せます。その代わり、任せた部分が勝手に崩れないよう、いくつかルールを決めました。

決めたことは、設計判断(ADR)や仕様書としてリポジトリに残し、口頭やチャットでの合意は仕様として扱いません。品質の合否は、コマンドで再現できる自動検査だけで判断し、手で埋めたチェックリストは根拠にしません。仕様も、実装しながら固めるのではなく、実装を始める前に画面仕様書で決めておきます。

さらに、Claude Code自身にも次のルールを守らせています。

  • 実行していないテストを「合格」と書かない
  • 失敗したテストをskipやリトライで無理やり通さない
  • 承認された実装計画から勝手に外れない
  • CIが落ちたときは専用のサブエージェントが直し、2往復しても直らなければ人間に戻す

ハーネスの構成(3つのリポジトリとCI)

ここで紹介するのは、運用しながら直したあとの形です。ハーネスは、役割ごとに3つのリポジトリに分けています。

1. リポジトリの役割分担

リポジトリ役割・置いているもの
docs設計判断(ADR)、画面ごとの仕様、承認済みの実装計画、不変条件
skillClaude Codeを動かすためのskill(計画用skill、実装用skill)
フロントエンドアプリケーションのコード、E2Eテスト、CIの定義

docs にある不変条件は、システムとして壊してはいけない性質をまとめたもので、全部で8件あります。たとえば「未ログインでは画面を見られない」「アクセス権のないデータは画面とCSVのどちらにも出さない」「自分自身は削除できず、権限の昇格もできない」といったものです。Claude Codeは、実装計画を立てる前に必ずこれを読み込みます。

2. 自動検査(CI)

GitHub ActionsのCIジョブは、次の4つに分けています。

1
2
3
4
5
jobs:
  quality:   # pnpm lint → tsc → test → build
  e2e:       # E2E用にビルドしPlaywrightを実行(qualityと並列)
  visual:    # E2Eで撮影したキャプチャをPRコメントに自動で貼る
  contract:  # ルート・仕様・E2E・実装計画の整合性チェック

特に力を入れたのが contract ジョブです。ここでは、ドキュメントと実装が一致しているかを確かめます。

  1. 作成されたルートの一覧が、コミット済みのものと一致するか
  2. ルートごとに、画面仕様書と対応するE2Eテストがあるか
  3. 仕様書に書いた「受け入れ条件のID」が、すべてE2Eのテスト名に含まれているか

たとえば、仕様書に | AC-01 | 見出しと件数が出る | という受け入れ条件を書いたとします。このとき、E2Eテスト側にも test('AC-01 見出しと件数が出る', ...) がなければCIが落ちます。これで、仕様を足したのにテストを書き忘れる、というミスを防いでいます。

また、実装PRの本文には、元になった実装計画(Markdown)へのパスを必ず書かせています。その計画が docs リポジトリでマージ済みでなければ、CIを通しません。

1画面あたりの開発フロー

1つの画面は、次の流れで開発を進めます。

flowchart LR
    SPEC["画面仕様・不変条件・ADR<br/>(docs)"] --> PLAN["計画を書く<br/>(計画 skill)"]
    PLAN --> A{"人間が<br/>計画をレビュー"}
    A --> IMPL["実装・E2E・画面撮影<br/>(実装 skill)"]
    IMPL --> CI["自動検査"]
    CI --> B{"人間が画面を確認して<br/>マージ"}
  1. 計画の作成(AI):人間が計画skillを実行する。AIが仕様を読み込み、実装計画をPRとして出す。
  2. 計画のレビュー(人・AI):サブエージェント(AI)による事前のレビューを経て、人間が内容を確認してマージする。
  3. 実装とテスト(AI):人間が実装skillを実行する。AIがコードとE2Eテストを書き、画面キャプチャを撮ってPRを出す。
  4. 自動検査(CI):前の節の4つのジョブが走る。
  5. 最終確認(人):CIが通り、PR上のキャプチャに問題がなければ、人間がマージする。

実際にやってみてどうだったか

このハーネスで、予定していた9画面の移植を、実装上のバグを出さずに終えられました。

完成した画面は、まずエンジニアが動作を確認し、そのあと実際に使うマーケティング担当者にも触ってもらいました。指摘はデザインの微調整だけでした。9画面を通して、コードの構成や命名もそろっていて、未使用のコードもありませんでした。

実装はかなり速く進みました。実装skillを実行してから実装PRが自動検査を通るまでは20〜40分ほどで、CI修復用のサブエージェントが動いたのも1回だけです。ほとんどのPRが一発で通っていました。

運用して見えた課題

実装がスムーズだった一方で、実装前の計画づくりにはかなり時間がかかりました。AIが計画を書き、別のAIがレビューして直す、というやり取りだけで、1画面あたり1〜2時間ほどです。人が関わるのは、そのあと計画を読んでマージするところだけです。ここからは、運用中に直面した課題と、それに対して変えたことを紹介します。

1. AI同士のレビューが終わらない

計画の精度を上げるため、AIが書いた計画を別のAIにレビューさせる仕組みを入れました。ところが、これがなかなか終わりませんでした。

指摘を直すたびにAIが「新しい決めごと」を書き足し、それが別の文書と食い違って、また指摘される、というループに入っていました。レビューと修正の往復を1巡と数えると、1画面の計画に11巡かかったこともあります。

対策として、次のルールを決めました。

  • レビューで必ず直す指摘は「事実の誤り」「要件の漏れ」「文書どうしの矛盾」の3つに限る
  • 巡回は最大4巡までにする
  • レビューの途中で新しい決めごとを足さない

2. バックエンドの実装や仕様と食い違う

フロントエンドの実装計画を立てるとき、AIがバックエンドの実装を確認せずに、想像で書いてしまうことがありました。また、旧PHP版では画面側で守っていた権限の制御(本来はバックエンドの役割)が仕様書に混ざっていました。これはフロントエンドのE2Eテストでは確かめられないので、受け入れ条件のIDに対応するE2Eが書けず、contract ジョブが落ちてしまいます。

対策として、次のようにしました。

  • 計画skillに、バックエンドの実装とPHP版の挙動を読んで突き合わせる手順を足す
  • バックエンド側の要件は、専用のIDで不変条件に書き分け、フロントエンドのE2Eの対象から外す
  • 仕様書を変えたときは、PR本文に変更点を必ず書き、履歴を追えるようにする

3. AIの「確認しました」が信用できない

あるPRの本文に、AIが「別システムのバックエンドが値を更新していることを確認済み」と書いていました。根拠を聞いてみると、そこで初めてコードを検索し始めました。その結果、値を更新する処理はそのシステムにはなく、「確認済み」は誤りだったことが分かりました。この画面は、移植の進め方を見直しました。

対策として、次のようにしました。

  • 「確認した」と書くときは、何をどうやって確認したかまで書かせる
  • IssueやPRの状態は、AIの記憶に頼らず、gh コマンドで最新の状態を取ってから前提にさせる

4. 直列進行による待ち時間の発生

最初は「前の画面の実装が終わるまで、次の画面の計画は作らない」というルールにしていました。ただ、これでは実装を待っている間の時間がもったいないと感じていました。

対策として、次のようにしました。

  • 計画は並行して作れるように、ルールを変える
  • 実装PRでは、docs リポジトリ(submodule)の参照先を「自分の計画がマージされた時点のコミット」に固定し、ほかの画面のまだ実装していない仕様が混ざらないようにする

5. Claude Codeの利用枠が足りない

1画面あたり、計画で3〜4回、実装で2回、AIのレビューが走ります。そのため、Claude Codeの5時間ごとの利用枠には何度も引っかかりました。体感では、1.5画面くらいで枠を使い切っていた気がします。

対策として、レビューなどのサブエージェントはSonnetで動かすようにして、消費を抑えました。もっと軽いモデルも考えたのですが、レビューの質は落としたくなかったので、Sonnetにしています。

まとめ

今回、AIに任せてリプレイスをしてみて、コードを書くこと以上に、何を作るかを決めて、それが正しいかを確かめる仕組みづくりが大事なのだと実感しました。

実装skillの実行から自動検査を通るまでは20〜40分なのに、AIどうしの計画のすり合わせに1〜2時間かかったのは予想外でした。ただ、コマンドで品質を確かめられるCIを用意したことで、計画を通さずに実装を始めたり、テストを書き忘れたりすることは起きませんでした。

今回はリプレイス案件だったので、既存の画面をもとに要件があらかじめ決まっている状態でした。こういう場面では、もうほとんど人間が手を入れなくても実装できてしまうことを、ニュースや技術ブログで聞いてはいました。実際にやってみて、そのことを肌で実感しました。

皆さんも、社内に眠っているレガシーなシステムを、モダンな構成に更新してみてはいかがでしょうか。

※記載されている会社名、製品名、サービス名は、各社の商標または登録商標です。