こんにちは、makeshop事業本部開発部の鈴木(佳)です。
長く運用されたECシステムをリニューアルするとき、いちばん神経を使うのが「決済」です。私たちのチームでは旧システムから新システムへ決済処理を移行しているのですが、ここで厄介なのが、決済方式ごとに、データベースへの書き込み内容が微妙に違うことでした。
「クレジットカードは旧も新も同じ。でも後払い系は新システムだと余分なレコードが1行入る」「定期購入だとサイクル設定のカラムが片方だけ欠ける」——こういった差分が、決済方式 × 注文種別（通常／複数配送／定期購入／予約…）の組み合わせの数だけ存在します。これを人手で突き合わせるのは、現実的ではありませんでした。
本記事では、この決済DBの新旧差分チェックを、Claude Code の Skill と MCP（Model Context Protocol） を組み合わせて、ソース解析から実データ照合まで半自動で回せるようにした話を紹介します。
なぜ作ったのか
最初は「仕様書を作って机上で対比すればいい」と考えていました。が、すぐに限界に気づきます。コードを読んで作った仕様は、コードの読み間違いをそのまま引き継ぐのです。「ここはこう書き込まれるはず」という想定が、実際のDBでは違っていることが何度もありました。
そこで方針を変えました。
- 仕様（あるべき姿）は、旧・新両方のソースコードから抽出して対比表にする
- そのうえで、開発用DBの実データを直接見て、仕様どおりに書き込まれているかを裏取りする
この「実データで裏取り」までをワンセットにしたのが、今回の監査Skillです。
全体像：2フェーズのオーケストレーション
監査Skillは、それ自体が大きな処理を持つわけではなく、2つの小さなSkillを順に呼び出す「司令塔」 として設計しました。
/audit-payment-db "（決済方式名）"
│
├─ フェーズ1: ソース解析 → 新旧CRUD対比ドキュメント生成
│ （payment-db-spec スキル）
│
└─ フェーズ2: dev DB の実データ照合 → 差異レポート出力
（debug-payment-db スキル ＋ dev-db-mcp）
フェーズ1で生成した対比ドキュメントを、そのままフェーズ2の「あるべき姿（ベースライン）」として読み込ませる。この連携によって、「仕様を作る」と「実データで検証する」が一本の線でつながります。
司令塔のSkillは本体ロジックを再実装せず、オーケストレーションに徹する——これは複数Skillを組み合わせるときの大事な設計原則だと考えています。中身を持ちすぎると、サブSkill側との二重メンテで必ず破綻します。
フェーズ1：ソースから新旧CRUDを抽出する
フェーズ1では、決済方式を1つ指定すると、旧システムと新システムの両方のソースから、その決済方式が触るテーブル・カラム・書き込み値を抽出します。
このとき、旧システムの調査と新システムの調査を別々のサブエージェントに並列で走らせます。片方が旧システムの古いテンプレートやSQLを追いかけ、もう片方が新システムのプロセッサーやスキーマ定義（DDL）を追いかける。最後にその結果をテーブル/カラム単位で突き合わせ、差異の種別を分類して対比表とシーケンス図に落とし込みます。
成果物は2つです。
| 成果物 | 内容 |
|---|---|
| 旧仕様ドキュメントへの追記 | 「DB CRUD（旧システム）」セクション（注文種類の列付き） |
| 新旧対比ドキュメント | 注文種類 × 決済方式のマトリクス、共通／種類別のCRUD対比表、クエリ実行タイミングのシーケンス図 |
“途中で止めない”ための前提チェック
ここで地味ながら効いた工夫を1つ。フェーズ1のソース解析はそれなりに時間がかかります。せっかく時間をかけて解析したのに、フェーズ2に進んだ瞬間「DB接続用のMCPが繋がっていません」で止まると、徒労感が大きい。
そこで、重い処理に入る前（フェーズ1の手前）に、フェーズ2で使うDB接続が生きているかを先に確認するようにしました。未接続なら、こう選択肢を出して止まります。
フェーズ2（実データ検証）に必要なDB接続が未接続です。 途中で止まらないよう、先に方針を選んでください: [1] 先に接続を整えてから再実行（推奨・フル監査） [2] 今回はフェーズ1（ドキュメント生成）のみ実行し、フェーズ2はスキップ
「重い処理の後ではなく前に、失敗しうる前提をチェックする」。エージェントのワークフロー設計では、この順番がユーザー体験を大きく左右します。
フェーズ2：dev DBに“SELECT限定”で接続して照合する
フェーズ2では、MCP経由で開発用DBに接続し、フェーズ1の対比ドキュメントをベースラインとして、実データを照合します。
DBにエージェントを接続させる、というと身構える方も多いと思います。実際これは慎重に設計すべきポイントで、私は次のガードレールを敷きました。
- 読み取り専用：接続は SELECT 限定。書き込み系は仕組みとして弾く。
- 必ず絞り込む：ショップIDや
LIMITで対象を限定し、全件・無条件スキャンは禁止。 - クエリは事前承認：実行前にクエリ内容を提示し、承認を得てから照会する。
- 機密情報はエージェントに渡さない：DBの接続情報などの入力は、対話スクリプトをユーザーの端末側で実行させ、エージェントの文脈には載せない。
複数のDBにまたがる場合は、ベースラインのDB区分に応じて照会先を使い分けます。「設定されている接続は必ず実照会し、“未検証”のまま放置しない」ことを品質チェック項目にしました。
出力：そのままチケットに貼れるレポート
差異が見つかった場合、あるいは未調査の注文種別が残った場合に、差異レポートを生成します。レポートは新旧DB比較チケットのサブ課題本文として、そのまま登録できる標準フォーマットにしました。
- 冒頭に常時表示の「概要」表（決済方式・発生条件・新旧の注文ID・調査日）
- 続いて「差異一覧」表（対象テーブル／対象カラム／差異〔旧→新〕／発生条件／状態）
- 注文種類別の詳細やクエリは
<details>で折り畳む
再検証で解消した項目は、行を消さずに取り消し線＋状態（再検証OK / 撤回）で残します。「直したつもり」を履歴として残すことで、同じ差分の再燃に気づける構成です。
この仕組みで、最終的に18種類前後の決済方式について、注文種別を掛け合わせた網羅的な新旧対比を、実データ付きで積み上げることができました。「余分なINSERTが1行入る」「確定日時のカラムが更新されない」といった、机上では見落としがちな差分を、実データで具体的に押さえられたのが大きな収穫です。
おわりに
今回いちばん効いた発想の転換は、「仕様書はゴールではなく、DBで検証すべき仮説である」 と捉え直したことでした。AIエージェントは、ソースを読んで仕様を作るのも、DBに問い合わせて実データを突き合わせるのも得意です。その2つを1つのSkillでつなぐと、「仕様の作成」と「仕様の検証」が地続きになります。
決済に限らず、レガシー移行で「新旧でデータの作られ方が違う」場面は多いはずです。読み取り専用・絞り込み必須のガードレールを敷いたうえで、AIに実データ照合まで任せてみる——その一歩を踏み出す参考になれば嬉しいです。
参考リンク
※ 本記事は社内での取り組みを一般化して紹介しています。決済方式名・テーブル名・チケット番号は例示・抽象化しています。
