https://www.m3tech.blog/entry/2025/11/06/110000

システムを運用していると時折直面するのが「移行作業」です。

新しい技術に触れられるのは楽しいです。一方、大量のコードの書き換えはちょっと辛いですよね。単純な置換で済めばよいのですが、そううまくはいかないことがほとんどです。

今回はこの書き換えを Claude Code を活用して楽に、精度良く実施したお話です。

データ基盤チーム/Unit9（エビデンス創出プロダクトチーム）エンジニアの坂元です。このブログはデータ基盤チーム/Unit9 ブログリレー 1 日目の記事です。

背景

エムスリーのデータ基盤（BigQuery）上では数多のデータパイプラインが稼働しています。今回はそのうちの一部を dbt (data build tool: SQL ベースのデータ変換ツール) 化することにしました*1。移行対象の SQL はおよそ 50 本。これらの SQL には様々なパターンがあります。

例えばある SQL は毎日更新対象のテーブルを洗い替えています。別の SQL は日々新しいシャーディングテーブルを作成しています。UDF を使用している SQL もあります。

パターンに応じて書き換え、dbt 版のコードを作成していく必要があります。

また、各カラムには description を設定しています。中には not null 制約を設定しているカラムもあります。この辺りも全て dbt で再現しなければなりません。

個々を見れば単純な作業です。しかし、手作業でやると工数がかかりそうですし、ミスも起こりそうです。何より腱鞘炎のリスクに怯えることになりそうです。

そこで、Claude Code に頼ることにしました。ここからはどのように Claude Code と共に歩んだかをお伝えします。

はじめの一歩

最初は素朴に、こんなお願いをしました。

「xxx.sql を dbt 化してください」

するとあっという間に dbt 化された（と思われる）ファイルが出来上がりました。さすが Claude Code だ。これならすぐ dbt に移行できる。そう思いました。

ただ、中身をよくよく見ると出来上がったファイルには以下のような問題がありました。

コメントが消されている。
修正しなくてよいロジック部分まで書き換えられている
not null 制約が外れている

やはりこれだけ簡素なプロンプトだと厳しいようです。ここは根気強く「コメントは消さないで」「ここは変えないで」と細かく修正を重ね、なんとか dbt 化しました。

ただ、毎回この進め方を繰り返すのであれば、自分で実装した方が早そうです。

そこで、 Claude Code に以下のようにお願いしました。

「今回の作業で得た知見を活かして次回以降の作業に役立つ手順書を作ってください」

作りたてほやほやの手順書は以下のような構成でした。

# dbt モデル移行手順書

## 1. 移行元の SQL ファイルを確認する
## 2. 参照先となる外部スキーマのテーブルの sources 定義を作成する
## 3. dbt モデルの SQL ファイルを作成する（日次洗い替えテーブル版）
## 4. モデルファイル作成時の注意事項
## 5. dbt モデルのスキーマファイルを作成する
## 6. 全体共通の注意事項

独り立ち

2 本目以降は手順書を元に実装を進めてもらいました。Claude Code には以下のようにお願いをしています。

yyy.sql を dbt 化してください。
対応方法は手順書.md を参照してください。

これで対応したことがあるパターンの SQL については概ね適切な実装ができるようになりました。

細かいミスをすることもあります。その場合はどういった記載があればミスを繰り返さないかを考えてもらい、手順書を更新してもらいました。

ミスの一例としては以下のようなものがありました。

outer join と inner join を変えてしまう
ref() で参照するべきところを source() で参照してしまう
sources 定義が不足している
移行前後でカラム名が変わってしまう（これは元の SQL の CREATE TABLE 部分と SELECT 部分でカラム名が一致していなかったために生じていました）

新しいパターンの SQL についてはどのように対応するのが最適なのか一緒に考えました。そして実装後、得られた知見を手順書に反映していきました。

これを複数回繰り返します。するとみるみる Claude Code は成長し、一発で求めていたコードを出力できるようになっていきました。

この頃にはもう数分で実装を終えられるようになっていました。仮に自分で対応していたら 20 分から 30 分はかかりそうなものです。

コードの品質が安定してきた頃の手順書は以下のような構成です。

# dbt モデル移行手順書

## 1. 移行元の SQL ファイルを確認する
## 2. 参照先となる外部スキーマのテーブルの sources 定義を作成する
## 3. sources 定義への追加漏れチェック
## 4. sources 定義追加時の注意事項・トラブルシュート方法
## 5-a. dbt モデルの SQL ファイルを作成する（日次洗い替えテーブル版）
## 5-b. dbt モデルの SQL ファイルを作成する（パーティションテーブル版）
## 5-c. dbt モデルの SQL ファイルを作成する（シャーディングテーブル版）
## 6. モデルファイル作成時の注意事項
## 7. dbt モデルのスキーマファイルを作成する
## 8. dbt 実行環境の更新（必要な場合）
## 9. セルフレビュー
## 10. 全体共通の注意事項

初期にはなかった sources 定義追加時の注意事項や、パーティションテーブルやシャーディングテーブルの対応方法などが増えています。また、上記の構成からは読み取れませんが、「全体共通の注意事項」の文量は初期に比べて数倍になっていました。

そして検証も…

この取り組みを始めた当初は実装だけ任せられれば御の字と考えていました。しかし、実装を任せられるようになると、動作検証もお願いしたくなります。動作検証まで任せられれば Claude Code が自走できる時間が長くなり、その間に自分も別の作業を進められます。

そこで動作検証のために行なっていた一連の作業を洗い出し、コマンドベースで再現できるように整理しました。試行錯誤を重ねながら手順書に反映し、最終的な手順書は以下のような構成になりました。

# dbt モデル移行手順書

## 1. 移行元の SQL ファイルを確認する
## 2. 参照先となる外部スキーマのテーブルの sources 定義を作成する
## 3. sources 定義への追加漏れチェック
## 4. sources 定義追加時の注意事項・トラブルシュート方法
## 5-a. dbt モデルの SQL ファイルを作成する（日次洗い替えテーブル版）
## 5-b. dbt モデルの SQL ファイルを作成する（パーティションテーブル版）
## 5-c. dbt モデルの SQL ファイルを作成する（シャーディングテーブル版）
## 6. モデルファイル作成時の注意事項
## 7. dbt モデルのスキーマファイルを作成する
## 8. dbt 実行環境の更新（必要な場合）
## 9. セルフレビュー
## 10. QA 環境へのデプロイ
## 11. 動作検証を行う
## 12. 動作検証時の注意事項・トラブルシュート方法
## 13. 全体共通の注意事項

できたこと

今回行っていた動作検証は「既存の処理と差分がないことを確認する」というものです。差分がない場合の検証作業については安定して完遂できるようになりました。QA 環境へのデプロイから処理の起動、テーブルの正当性確認まで一連の流れを任せられるようになったため、並行して別の作業を進められるようになりました。

残った課題

一方で、差分があった場合の原因特定はうまくいきませんでした。

差分が生じる原因パターンをいくつか手順書に明記することも試しましたが、調査時にうまく活用できていないようでした。そもそも今回移行した SQL は冪等な作りになっており、差分が生じたケースが少なかったという事情もありますが、今回試行錯誤した範囲では解決することができませんでした。この点は今後の取り組みで解決したいところです。

細かい工夫

全文読んでから対応すること

手順書が長くなってくると、Claude Code が手順書の最初の方だけ読み込み、中途半端な知識を持った状態で対応する場面が見られました。そうなった時は手順書に記載されている様々な注意点を拾い切れず、以前と同じミスを繰り返していました。

これを避けるために、手順書の最初に以下の文言を記載しています（ちょっと圧が強い気がしますが、これは Claude Code が自分で記載した文言です）。

## 注意！！！

- 当ファイルを読む際は必ず全文読み込んでください。断片的に読んでも良い作業はできません。

セルフレビューしてもらう

前述の通りミスがあった時は同じミスを繰り返さないように手順書を更新していました。しかし、それでも稀に手順書に記載があるにも関わらずミスをしていることがありました。

Claude Code も注意事項を見落としてしまうことがあるのだと思います。ミスを防げない以上、早く気がつく方向で対策を考えたいところです。

そこで、手順書の後半にセルフレビューの章を設け、そこにチェックリストを作成してもらいました。

これが意外と有効で、自分でセルフレビューをした結果ミスに気がつき、追加で対応するという場面を時折目にしました。

まとめ

この取り組みを始めた直後はうまくいくのか不安でした。しかし最終的に 50 本中半分以上の書き換えを Claude Code におまかせでき、不具合もなくスムーズに dbt 化を実現できました。

別のデータパイプラインを dbt 化する際にも、今回作成した手順書をもとに Claude Code に活躍してもらえると思っています。また、この手順書は Git リポジトリ上で管理しているため、他のメンバーが dbt 移行対応する際にも活用できます。このように知見を資産化できた点も、手順書を作成してよかった点かと思います。

今回の記事がこれから何かの移行対応をされる方の一助となれば幸いです。

We are hiring!

エムスリーでは Claude Code に限らず様々な最新技術を活用しながらエンジニアリングを行っています。そんな刺激的な環境に少しでもご興味を持っていただける方は以下のリンクからカジュアル面談にご応募ください！

jobs.m3.com

*1:今後データ品質向上や運用効率化への取り組みを強化していくため、まずは基盤となる dbt の導入を進めることにしました。