結論から書くと、Laravel の保守で Claude Code を使うときは、調査レポート → 計画 → 小さな差分とテスト → 別の視点でのレビュー の順に進め、工程ごとに人が確認する成果物を置きます。AI の作業を速くすることより、各工程の終わりで「人が何を見て次に進むか」を決めておくことが、保守では大切です。
どの工程を AI に任せ、どこを人が判断するかという線引きの考え方は「Claude Code を受託開発で使って分かった、任せられる工程と任せられない工程」で説明しました。この記事では、既存の Laravel のシステムで不具合を直す、小さな改修を入れるといった保守の作業に絞って、具体的な手順を扱います。
| 工程 | Claude Code | 人 | 成果物 |
|---|---|---|---|
| 準備 | — | 指示ファイルと権限の設定 | CLAUDE.md、設定ファイル |
| 調査 | 関係するコードを読み、レポートを書く | 根拠の確認、業務の担当者への確認 | 調査レポート |
| 計画 | 変更の計画を出す | 方針の承認 | 計画 |
| 修正 | 再現するテストを書き、直す | 差分の確認 | 差分とテスト |
| レビュー | 新しい文脈で差分を見直す | 指摘の採否、最終の判断 | レビューの結果 |
| 反映 | 手順書の下書き | 本番への反映 | 作業の記録 |
準備: 指示ファイルと権限を整える
最初に、プロジェクトの CLAUDE.md に、コードを読んでも分からないことを書きます。公式のベストプラクティスでは、CLAUDE.md に向いている内容として、作業を確かめるための正確なコマンド、コードが誤解を招く箇所、リポジトリに無い決定事項が挙げられています。Laravel の保守なら、たとえば次のような内容です。
# 確認のコマンド
- テスト: php artisan test
- ルートの一覧: php artisan route:list
# 前提
- Laravel と PHP のバージョンは composer.lock のとおり。
それより新しいバージョンにしか無い機能は使わない
- app/Legacy/ は今も使われている。書き方を新しいコードに真似しない
# 決まっていること
- 本番への反映は人が行う。マイグレーションは人の承認の後に実行するバージョンを明記するのは、古い Laravel のシステムに、新しいバージョンの書き方が混ざるのを防ぐためです。指示ファイルに書く項目と書かない項目の考え方は「AI 駆動開発で最初に作る AGENTS.md、受託現場での書き方」にまとめています。
ただし、CLAUDE.md は守らせる仕組みではありません。公式のメモリの説明では、CLAUDE.md は強制される設定ではなく文脈として扱われるとされています。絶対に避けたい操作は、権限の設定で止めます。Laravel では .env にアプリケーションのキーやデータベースの接続情報が入っているので、読み取りを拒否しておきます。
{
"permissions": {
"deny": [
"Read(./.env)",
"Read(./.env.*)"
]
}
}そもそも、本番の接続情報は手元の開発環境に置かないのが前提です。テストは、テスト用のデータベースにだけつながる環境で動かします。
調査: 根拠付きのレポートを書かせる
不具合の報告を受けたら、いきなり直させずに、まず調査のレポートを書かせます。依頼の例です。
「請求書の金額が、月末に登録した注文だけずれる」という報告があった。
関係するルート、コントローラ、モデル、ジョブ、定期処理を調べて、
docs/investigation/ にレポートを書いて。コードは変更しない。
- 各記述に、根拠のファイルパスと行番号を付ける
- 「確定」「推定」「不明」に分ける
- 原因の候補が複数あれば、すべて挙げる
- 業務の担当者に確認すべきことを最後にまとめる入口を探すには、Laravel の php artisan route:list（ルートの一覧）や php artisan schedule:list（定期処理の一覧）が役立ちます。どちらも、コードを読むより先に全体を見渡せます。
レポートをファイルに残すのは、会話が長くなっても、セッションを変えても、調査の結果を失わないためです。人は、レポートのうち影響の大きい記述について、根拠の行を開いて確かめます。「推定」の記述は、確かめるまで事実として扱いません。
調査に本番のログやデータを使いたくなることがありますが、そのまま渡すのは避けます。必要な行だけを取り出し、個人情報や取引先の名前を伏せてから渡します。お客様のシステムであれば、秘密保持の契約で外部のサービスの利用が制限されていないかも、作業の前に確かめておきます。
レポートの最後にまとめた確認事項は、人が業務の担当者に聞きに行きます。「月末の注文は翌月の請求に回す決まりがある」といった業務の取り決めは、コードからは分からないからです。答えが分かったら、レポートに追記してから次の工程に進みます。
計画と修正: 計画を確かめてから、小さな差分にする
調査の結果に納得したら、修正の計画を出させます。公式の よく使うワークフローの説明にある計画モードでは、Claude はファイルを読んで計画を出し、承認されるまで編集しません。計画では、変更するファイル、影響する範囲、追加するテストを確かめます。
修正は、次の順にさせます。
- 不具合を再現するテストを先に書く。 直す前にテストが失敗することを確かめます。
- 直す。 1つの不具合に1つの変更とし、「ついでの整理」はさせません。差分が大きくなると、確認しきれなくなるからです。
- テストを実行し、出力を見せてもらう。
公式のベストプラクティスでは、合否が返る確認の手段（テスト、ビルドの終了コード、リンター、出力を期待値と比べるスクリプトなど）を Claude に渡すよう勧めています。確認の手段があれば、Claude は失敗の出力を読んで自分で直しを繰り返せます。また、完了の報告には、実行したコマンドとその出力という証拠を求めるよう書かれています。「テストは通りました」という文章だけでは、確認したことになりません。
テストの無いシステムでは、修正する箇所の周りだけでも、今の動きを固定するテストを先に入れます。
レビュー: 書いた文脈から離れて見直す
差分ができたら、書いたときの会話を引きずらない形でレビューします。公式のベストプラクティスによると、ターミナルの /code-review は、会話を見ていない新しいサブエージェントで差分をレビューするため、コードを書いたときの理由づけに引きずられません。計画どおりかを確かめたい場合は、計画や仕様のファイルと差分を照らし合わせるよう、レビューの依頼を自分で書く方法も紹介されています。
同じ箇所に、問題を探すよう頼まれたレビュアーは必ず何かを見つける、という注意もあります。指摘をすべて直すと、不要な抽象化や起こり得ないケースのテストが増えます。指摘を採るかどうかは人が決めます。保守の差分で人が特に見るのは、次の箇所です。
- データを書き換える処理と、その条件
- 権限の確認（誰がその操作をできるか）
- 入力の検証と、一括代入で書き換えられる項目
- マイグレーションの有無と、戻し方
最後に、検証環境の画面で動きを確かめ、本番への反映は人が行います。
h-system でできること
h-system の AI 導入・活用コンサルティングでは、Claude Code などの AI を既存システムの保守や開発にどう組み込むかのご相談を承ります。指示ファイルや権限の設定の整え方、調査やレビューの工程の組み立て方、人が確認すべき箇所の決め方まで、実際のリポジトリの状況に合わせてご説明します。Laravel のシステムの保守そのもののご依頼も可能です。初回相談（オンライン30分程度）は無料で、代表が直接対応します。