300行を超える注文処理のアクションを、Claude Code に「Service Object に分けて」と一括で頼んだことがあります。出てきた分割は一見きれいでしたが、在庫の引き当てと決済の境界が誤っていて、決済失敗時に在庫だけ減ったまま残る構造になっていました。
そこからは、一度に分けさせるのをやめて1責務ずつ、毎回テストで固定してから次へ進めるやり方に切り替えました。この記事は、その手順とAIへの指示の粒度、レビューで見ている点をまとめたものです。題材は Rails の注文アクションですが、Laravel でも考え方は同じです。
前提と書いてあること / ないこと
- 題材: 在庫チェック・決済・メール送信・ポイント付与が1つのアクションに混在している注文処理（実案件を一般化したもの）
- 環境: Rails（Laravel 側は別案件の経験）、Claude Code、既存のリクエストテストあり、またはこれから書く
- この記事のコードは説明用の骨格で、そのままでは動きません（コード検証状態は末尾に記載）。実行結果は載せていません
なぜ一括で分割させると失敗するのか
注文アクションが300行を超えていた案件では、在庫チェック・決済・メール送信・ポイント付与のロジックが1本に混ざっていました。最終的には Service Object に分離してコントローラは20行ほどに収まり、各サービスのユニットテストも書きやすくなりました。結果だけ見れば順当ですが、最初の一括依頼は失敗しています。
原因は、AIがコードの見た目の塊で境界を引くことだと私は考えています。トランザクションの範囲や「どこまで失敗したら巻き戻すか」は、コードの字面からは読み取りにくい。そのため、塊としてきれいに分かれても、業務上の不変条件（決済に失敗したら在庫を戻す）が分割線をまたいでしまいます。
進め方：1責務ずつ切る5ステップ
Step 1: まず分割せず、責務の地図だけ作らせる
最初の指示は「リファクタリングして」ではなく、読み取り専用の分析にします。
このアクションを変更せず、次を表にして。
- 各ブロックの責務（在庫/決済/通知/ポイント/その他）
- 各ブロックが読む・書くDBテーブル
- トランザクションの開始・終了位置
- 失敗したときに巻き戻すべきもの / 巻き戻せない外部副作用（メール送信など）
古い PHP コードを段階的に直したときも、最初に構造分析をさせて依存関係マップを作らせました。変更前に地図を出させる工程は、言語が違っても効きます。この表で、巻き戻せない副作用（メール、外部決済API）をどこに置くかを人間が先に決めます。
Step 2: 現状の挙動をテストで固定する
分割の前に、既存の挙動を拾うリクエストテストを書かせます。正常系だけでなく「在庫不足」「決済失敗」の2本は必須にしています。
# 説明用の骨格（未実行）。実プロジェクトの factory 名・パス・エラー表現に置き換える
RSpec.describe "POST /orders", type: :request do
it "決済失敗なら在庫が減らない" do
# 在庫10の商品を用意し、決済ゲートウェイをスタブして失敗させる
post orders_path, params: valid_params
expect(product.reload.stock).to eq 10
expect(Order.count).to eq 0
end
end
このテストが「今のコードで通る」ことを先に確認します。通らないなら、それは既存バグであり、分割と混ぜてはいけません。
Step 3: 最初に切るのは在庫（副作用が最も戻しやすい）
切り出す順番は 在庫 → 決済 → 通知 にしました。理由は、巻き戻せる処理（DB更新）から先に出し、巻き戻せない処理（外部決済・メール）を最後まで元の位置に残せるからです。
指示は1責務に絞ります。
在庫チェックと引き当てのブロックだけを OrderStock::Reserve に切り出して。
- 触るのは対象ブロックとコントローラの呼び出し箇所のみ
- トランザクション境界・他のブロックの順序は変えない
- 戻り値は Result 風（成功/在庫不足）にして、例外で制御しない
- 終わったら既存テストを実行して結果を貼る
# 説明用の骨格（未実行）
class OrderStock::Reserve
Result = Struct.new(:ok, :error, keyword_init: true)
def initialize(cart:)
@cart = cart
end
def call
# 各明細の在庫を確認し、足りなければ Result.new(ok: false, error: :out_of_stock)
# 足りれば引き当てて Result.new(ok: true)
end
end
Step 4: 決済を切る。ここがいちばん境界を誤りやすい
決済は在庫と同じトランザクションに入るのか、外に出すのかで設計が変わります。Step 1 の表で決めた方針をそのまま指示に書き、**「トランザクションをまたぐ場合は切り出さず、私に確認して」**と明示します。AIが勝手に transaction の範囲を動かすのを止めるためです。
Rails の公式ガイドでは、保存・削除のコールバックの連鎖が1つのトランザクションに包まれ、通常の例外はロールバックされたうえで再送出される、と説明されています。ただし ActiveRecord::Rollback と ActiveRecord::RecordInvalid は、この再送出の一般則から除外されています。また throw :abort で止めた場合、create や destroy などの非bang版は例外ではなく false を返します（Active Record Callbacks の Halting Execution 節。2026-10-31 確認）。通常の例外についてはこの性質を前提にすると、サービス内で例外を握りつぶす実装は、巻き戻しを黙って無効にしかねません。レビューではここを必ず見ます。
Step 5: 通知を切る。ここで「サービスか、イベントか」を分ける
この案件では、メール送信とポイント付与を、注文成立後の後処理として定義しました（ポイント付与が注文の成否と独立してよいかは業務要件しだいで、DB更新なら通常はロールバック可能です）。そう定義した部分は、Service Object で呼び出し順を書くより、イベントにしたほうが素直でした。
別案件の Laravel で、注文完了時の処理（メール・在庫更新・ポイント付与・ログ）が400行を超える1メソッドに詰め込まれ、直すたびに他が壊れていたことがあります。OrderCompleted イベントに4つのリスナーを紐づけて直したところ、各リスナーを独立してテストでき、後処理の追加もリスナー1つで済むようになりました。
ただし、イベント化には落とし穴があります。Laravel の公式ドキュメントによれば、キュー対象のリスナーをデータベーストランザクション内でディスパッチすると、トランザクションのコミット前にキューで処理されうるため、リスナーが依存するレコードがまだ存在しないことがあります。対処として、リスナーに ShouldQueueAfterCommit を実装する方法が示されています（Laravel 12.x Events。2026-10-31 確認）。
Rails 側で同じ目的を満たす手段としては、コミット後には after_commit、ロールバック後には after_rollback が実行される、と公式ガイドに書かれています（Active Record Callbacks の after_commit / after_rollback 節。2026-10-31 確認）。同節には、after_commit の中で例外が起きても、保存済みのデータは巻き戻せないという趣旨の記述もあります。通知の失敗でデータを戻したいのか、戻したくないのかを、先に決めておく必要があります。
サービスとイベントの使い分け（私の基準）
以下は公式の規定ではなく、私の案件での判断基準です。
| 観点 | Service Object | イベント＋リスナー |
|---|---|---|
| 失敗したら注文自体を失敗にしたい | ○ 呼び出し側で結果を見る | △ キュー化してコミット後に実行し、失敗を注文処理へ伝播させない設計なら、注文は成立する（同期リスナーは例外が呼び出し元へ伝播し、同一トランザクション内ならロールバック要因にもなる） |
| 実行順序に意味がある（在庫→決済） | ○ 順序がコードに残る | × 順序保証を別途考える必要がある |
| 後処理が今後増えそう（通知・連携） | △ 呼び出し箇所が増える | ○ リスナー追加で足せる |
| 処理の流れを1ファイルで追いたい | ○ | △ 発火元と受け手が離れる |
在庫と決済は順序と成否が注文に直結するので Service Object、通知とポイント付与は後処理なのでイベント、と分けました。
AIへの指示の粒度とレビューポイント
| 指示でやること | 理由 |
|---|---|
| 1回の依頼で触る責務は1つ | 境界の誤りを、差分が小さいうちに見つけられる |
| 「変えないもの」を明示する（トランザクション、順序、公開API） | 暗黙に動かされやすいのがここ |
| 終了条件にテスト実行結果の貼り付けを入れる | 通ったと言うだけの報告を防ぐ |
| 判断が要る箇所は「切らずに質問」と指示する | 勝手に境界を決めさせない |
レビューで私が見ている点は4つです。
- 例外を握りつぶして、巻き戻しが効かなくなっていないか
- トランザクションの開始・終了位置が分割前と同じか
- 巻き戻せない副作用（メール、外部API）が、確定前に走っていないか
- サービスの引数に、リクエスト（
params）やセッションがそのまま渡っていないか
別の案件でコントローラに ActiveRecord の where チェーンが複雑に書かれ、同じ条件があちこちにコピペされていたときも、名前付きスコープとクエリオブジェクトに分けることで重複が減りました。サービス分離とは別の話ですが、「条件に名前を付ける」ことが、AIに指示を出すときの共通語彙になる点は同じでした。
ハマったところ
- 一括依頼で、決済失敗時に在庫だけ減る分割案が出た（冒頭の件）。テストが先にあったので、マージ前に気づけた
- 「ついでにリネームもして」を許したら、差分が大きくなりレビューが追いつかなくなった。以降は1依頼1責務で、リネームは別の依頼にしている
- 通知をイベント化したとき、トランザクション内でのディスパッチを意識しておらず、ステージングでレコード未存在の例外を踏んだ（上のStep 5の注意点）
まとめ
- 先に責務の地図とテストを作り、分割はその後
- 切る順は、巻き戻せる処理（在庫）から、巻き戻せない処理（決済・通知）へ
- 注文の成否に関わるものは Service Object、後処理はイベント。ただしコミット前ディスパッチに注意
- AIには1回1責務、「変えないもの」を明記し、テスト結果の提示を終了条件にする
結局のところ、AIに任せたのは「切る作業」で、「どこで切るか」の判断は人間に残しました。分割そのものは速くなりましたが、時間がかかったのは境界の判断とテストの用意のほうで、そこを省いた一括依頼がいちばん高くつきました。
正直、ここに辿り着くまでに「一括で頼んで境界を誤る」ところで何度かやり直しました。同じところでハマっている人が遠回りせずに済めば、この記事を書いた意味があります。似た経験や「うちはこう回避した」があれば、ぜひコメントで共有してください。