古い管理画面が、ルールと自動検査のレールを通ってモダンな画面に生まれ変わる概念イラスト

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は、実装計画を立てる前に必ずこれを読み込みます。 ...

2026年11月18日 · 読了時間: 1分 · 松ヶ浦健
変更した行だけを見る品質ゲート

テストが2441個あってカバレッジ9.5% ── 全体の数字を諦め、変更した行だけを見る品質ゲートに切り替えた

はじめに テストカバレッジのゲートを3つのサイトに入れた記録です。 同じドメインで連携する3つのNext.jsサイト(利用者向け / 提供者向け / 社内管理画面)を運用しています。カバレッジを測る設定は、利用者向けでは5月、社内管理画面では6月から入っていました。ただし閾値もCI連携もなく「測れるが誰も追っていない」状態でした。提供者向けでは、計測とゲートを同じ日に入れています。 半期の計画でカバレッジ向上に取り組むことが決まり、まず現状を測るところから始めました。 実測したところ、社内管理画面は テストが2441個あって、カバレッジ9.5% でした。この数字を前にして「まず全体80%を目指そう」と言っても、誰も動きません。 そこで全体の数字を目標にするのをやめ、「変更した行」だけを見るゲートに切り替えました。 この記事で得られること テスト数とカバレッジが比例しない理由と、計測対象の決め方 全体のカバレッジをゲートにすると何がうまくいかないか(未使用コードを消すと率が下がる問題) 変更した行のカバレッジをゲートにする設計と、全体の数字をこれ以上下がったら止める「下限」として使う考え方 外部のカバレッジサービスを使わず、CI内で完結させる実装 計測から外すファイルを決めないと数字が実態とずれる話 既存コードの多いリポジトリで、止めずにゲートを入れる段階の踏み方 1. 3サイトのカバレッジ実測値 まず現状を測りました。CIと同じ環境変数で、全テストが通る状態での実測値です。 Lines Statements Functions Branches テスト規模 社内管理画面 9.5% 9.5% 7.1% 8.4% 176ファイル / 2441テスト 利用者向け 26.8% 26.3% 20.0% 24.2% 70ファイル / 908テスト 提供者向け 34.3% 34.5% 28.9% 32.1% 45ファイル / 625テスト 目を引くのは社内管理画面です。テストが一番多いのに、カバレッジが一番低くなっています。 テストの数とカバレッジが比例しない理由 原因はテストの置き場所が偏っていたことでした。導入時のコミットで測り直し、テストと計測対象の行を突き合わせると、こうなっていました。 1 2 3 4 5 6 7 8 2441テストの内訳 入力チェックの定義(zodのスキーマ)のテスト 1358 自動生成されたAPIクライアントのテスト 195(自動生成コードは計測対象外) その他 888 計測対象 18981行の内訳 入力チェックの定義 143行 74.1%がテストで実行された 画面のコンポーネント 13910行 4.4%がテストで実行された テストの半分以上が入力チェックの定義に集まっていました。定義は1つが数行にまとまるので、計測対象の行数では143行、全体の1%もありません。一方、計測対象の7割以上を占める画面のコンポーネントは、ほとんどテストで実行されていませんでした。 ...

2026年11月16日 · 読了時間: 5分 · 福士宗介