
2年目サーバーエンジニアがPHP製の社内管理画面をほぼ全自動でReactにリプレイスした
はじめに こんにちは。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 CI GitHub Actions 実行環境 Node.js 24、pnpm なぜ「ハーネス」が必要だったのか チームにはフロントエンドの専任者がいないので、AIが生成したコードを人間が1行ずつ読んでレビューするのは難しいと考えました。かといって、チャット感覚でその都度AIに指示を出すと、出来上がりにブレが出そうです。既存のPHP版と挙動が変わったり、UIの崩れに気づけなかったりすることも心配でした。 そこで、人間がやることを次の3つに絞る仕組み(ハーネス)を作りました。 AIへ指示を出す(skillの実行) AIが作った実装計画のレビュー 最終的な画面の確認とマージ コードの実装、テストの追加、画面キャプチャの撮影までは、Claude Codeと自動検査(CI)に任せます。その代わり、任せた部分が勝手に崩れないよう、いくつかルールを決めました。 決めたことは、設計判断(ADR)や仕様書としてリポジトリに残し、口頭やチャットでの合意は仕様として扱いません。品質の合否は、コマンドで再現できる自動検査だけで判断し、手で埋めたチェックリストは根拠にしません。仕様も、実装しながら固めるのではなく、実装を始める前に画面仕様書で決めておきます。 さらに、Claude Code自身にも次のルールを守らせています。 実行していないテストを「合格」と書かない 失敗したテストをskipやリトライで無理やり通さない 承認された実装計画から勝手に外れない CIが落ちたときは専用のサブエージェントが直し、2往復しても直らなければ人間に戻す ハーネスの構成(3つのリポジトリとCI) ここで紹介するのは、運用しながら直したあとの形です。ハーネスは、役割ごとに3つのリポジトリに分けています。 1. リポジトリの役割分担 リポジトリ 役割・置いているもの docs 設計判断(ADR)、画面ごとの仕様、承認済みの実装計画、不変条件 skill Claude Codeを動かすためのskill(計画用skill、実装用skill) フロントエンド アプリケーションのコード、E2Eテスト、CIの定義 docs にある不変条件は、システムとして壊してはいけない性質をまとめたもので、全部で8件あります。たとえば「未ログインでは画面を見られない」「アクセス権のないデータは画面とCSVのどちらにも出さない」「自分自身は削除できず、権限の昇格もできない」といったものです。Claude Codeは、実装計画を立てる前に必ずこれを読み込みます。 ...
