はじめに
LLM とペアで設計書レビューを回すようになって、生産性が劇的に上がった一方で、こんな"あるある"に何度もぶつかりました。
「あの重要な指摘、確か3時間前のチャットに書いてあったんだけど…どこだっけ？」
「LLMに再質問したら、要約版しか返ってこない。元の鋭い指摘が消えてる」
そして、設計書側でも別の事故が起きます。
「移行対象が一部変更になったので設計書を直したよ」
→ 数日後のレビューで「移行フロー図が古いままです」「検証対象リストに消えたはずのテーブルが残っています」
LLM のコンテキスト消失と、設計書の整合性崩れ。一見別問題ですが、両方を一気に潰す運用ワークフローが作れたので共有します。大規模な移行案件で実戦投入し、レビュー指摘の手戻りが激減した方法です。
Part 1: 移行設計書の整合性を守る「4つの連動箇所」
問題発見: 1箇所だけ直して残り3箇所を忘れる
数十テーブル・複数バケットにまたがる大規模移行設計書を運用していると、こんな指摘が頻発します。
- 「3章で移行対象から外したはずのテーブルが、5章の検証対象リストに残っています」
- 「移行先バケットが減ったのに、移行フロー図のバケット数は古いままです」
- 「セクション番号が3.3の次に3.5になっています（3.4はどこに行きました？）」
これらは別々の事象に見えますが、根は同じです。移行対象を1箇所で変更すると、設計書の複数セクションに連動して影響が及ぶのに、その連動範囲がチームの暗黙知になっていたのです。
実際に体験した最悪パターンは、こんな流れでした。
[Day 1] アプリサーバAは移行不要と決定
→ 「3.1 移行対象一覧」を更新（テーブル削除）
→ ここで満足してしまう
[Day 5] レビューで指摘
- 「5章の検証対象に削除済みテーブルが残っています」
- 「移行フロー図に旧バケットが残っています」
- 「3.4節が欠番になっています」
[Day 8] 修正版を再提出
→ 「今度は移行先バケット一覧に旧バケットが…」
直すべき場所が散在しており、しかも章をまたいで参照しあっているため、1箇所修正の影響が3〜4箇所に波及することを毎回見落としていました。
解決: 「4つの連動箇所」チェックリスト
整合性事故を分析した結果、移行対象が変わる時に必ず連動して見直すべき箇所は4つに集約されました。
| # | 箇所 | 典型的な漏れ |
|---|---|---|
| 1 | 移行不要テーブル／対象一覧 | 移行対象から外したのに、別表に名前が残る |
| 2 | 移行先バケット／スキーマ一覧 | 廃止したバケットの記載が残る |
| 3 | 移行フロー図（手順） | 図中の登場人物（バケット名・サーバ名）が古い |
| 4 | 検証対象リスト | 移行しないものに対する検証手順が残る |
これをチームのチェックリストに固定化しました。設計書の差分PRを出すときも、レビュアもこの4観点を機械的に確認します。
Before / After（整合性事故率）
| 運用 | 1リリースあたりの整合性指摘件数 |
|---|---|
| チェックリスト導入前 | 平均5〜8件（章をまたぐ漏れが頻発） |
| 4観点チェックリスト導入後 | 平均1件以下（残るのは新規記述の typo 系のみ） |
数値はチーム内の体感ベースですが、レビュー会の所要時間が体感で半分近くまで縮みました。「機械的に潰せる指摘」が事前に潰せるからです。
なぜ4箇所なのか
ここはあえて細かく分解しすぎていません。人間が一度に把握できる粒度を意識しています。
たとえば「移行スクリプト内の参照テーブル名」「IAMポリシー上のバケット名」まで分解し始めると、チェック項目が10を超えてリスト自体が形骸化します。あくまで設計書本体の整合性に絞った4観点で、スクリプトやIAMは別レイヤのチェックリスト（コードレビュー観点）に切り分けています。
Part 2: AIレビュー知見の「Markdown即時永続化」ワークフロー
問題発見: LLM のコンテキスト圧縮で重要指摘が要約されてしまう
設計書レビューを LLM と進めると、1セッションが数時間に及びます。途中でLLM側のコンテキスト圧縮が走ると、序盤の鋭い指摘や、苦労して組み立てた検証コードが、
「データ移行検証として件数比較・PK比較・サンプリング比較を実施することを推奨」
くらいの抽象的な要約に丸まってしまうことがあります。元の文脈には「TIMESTAMP WITH TIME ZONE と Spanner TIMESTAMP の精度差」みたいな具体的な含みがあったのに、要約後はただの一般論になっている、というやつです。
これでは翌日同じ会話を続けられないし、組織のナレッジとしても残りません。
試行錯誤: 何で残すか問題
最初は色々試しました。
- スクリーンショット: 大量に溜まるだけで検索性ゼロ
- チャット履歴のエクスポート: ノイズが多すぎて再利用しにくい
- Confluence に都度貼る: 重い、整形コストがかかる、編集権限の手間も発生
落ち着いたのは「会話の区切りごとに、LLM自身に構造化Markdownでまとめさせて、即ファイル保存」というシンプルな運用でした。
解決: 4セクション構造のMarkdownテンプレ
レビューの節目ごとに、LLMに以下のテンプレで出力させます。
# レビュー記録 YYYY-MM-DD: <対象設計書名>
## 1. 指摘事項
- [ ] 検証方法の拡充: 件数一致だけでは弱い。データ型変換検証と業務操作検証を追加
- [ ] 制約事項・依頼事項の明文化: メンテナンスモード、データ静止点
- [ ] 役割分担・想定時間の明記
## 2. 対応案
- 検証章を5層構成に拡張（件数/PK/型変換/業務操作/性能）
- 制約事項は表形式で工程ごとに記載
- 役割分担はベンダー/顧客の列を分けた表に整理
## 3. 検証手順（実コマンド）
```bash
# オンプレ側
find /mnt/contents -type f -printf '%P\t%s\n' | sort > onprem.tsv
# Cloud Storage 側
gcloud storage ls -lR gs://bucket/contents/** | awk '...' | sort > gcs.tsv
# 突合
md5sum onprem.tsv gcs.tsv
4. 保留事項
- データ型変換の代表値サンプリングルール（次回レビューで詰める）
- 業務操作検証のシナリオ本数の合意
ポイントは4セクションの役割を明確に分けたことです。
| セクション | 性質 | なぜ分けるか |
|---|---|---|
| 1. 指摘事項 | 事実（誰が何を指摘したか） | 後でレビュー対応漏れがないか辿れる |
| 2. 対応案 | 設計判断（どう直すか） | 案 vs 確定の区別が必要 |
| 3. 検証手順 | 再現可能なコマンド | 同じ手順を別案件でも流用できる |
| 4. 保留事項 | 次回への申し送り | 圧縮で消えると致命的な「未決」を別建てに |
特に3. 検証手順は、文章で書かずに動くコマンドそのものを貼ります。「find -printf '%P\t%s\n' でルートを除いた相対パスとサイズを出すと Cloud Storage 側のオブジェクト名と直接突合できる」のような選択理由は、コメントとしてコマンド近くに残します。
なぜ「即時保存」が効くのか
LLMに長文を出力させた直後にファイル保存しないと、次の数往復で内容が要約されたり、別の話題に流れたりします。生成された瞬間が最も具体性が高いので、その場でMarkdownファイルに固定する。これだけです。
Part 3: 2つを組み合わせる ― 「4箇所チェック → 即Markdown化」ループ
ここまでのPart 1（整合性チェック）とPart 2（Markdown永続化）を、運用としてループ化します。
[設計変更PR起票時]
└─ 4箇所連動チェックリスト（Part 1）を観点として明記
[AIレビュー実施]
└─ 指摘・対応案・検証手順・保留事項をMarkdown化（Part 2）
└─ 設計書側にも反映（4箇所連動チェック付き）
[次回レビュー]
└─ 前回のMarkdownをLLMプロンプトに添付
└─ 「圧縮前の状態」から会話再開
└─ 新たな指摘を同じテンプレで追記
このループの肝は、前回のMarkdownを次回プロンプトに添付することです。LLMは前回の文脈を「ゼロから読み直せる」ので、
「前回の保留事項4-1（型変換サンプリングルール）から続けて検討します」
のように、抽象化される前の具体性で会話を継続できます。レビューが1回ごとの会話から、積み上がるドキュメントに変わる感覚です。
副次効果: チーム内で再利用できる
Markdown化したレビュー記録は、git で版管理してチームの設計書リポジトリに置いています。すると次のような副次効果が出ました。
- 別案件で同種の移行設計を始めるとき、過去レビューMarkdownを参考に論点を先回りできる
- 新メンバーのオンボーディング時、「過去にどんな指摘で詰められたか」が読める
- LLMに「過去レビュー記録一式」を読ませると、新規設計書のドラフトレビューで過去と同じ観点を再現できる
つまり、Markdown化したレビュー記録自体がプロンプト資産になっていきます。
おわりに
LLM の能力は今後も上がり続けます。ただ、その能力を残せる形に切り出す運用がないと、毎回ゼロから組み立て直すことになります。
今回紹介したのは、難しい技術ではなく、
- 4箇所連動チェックリスト: 設計書の整合性事故を機械的に潰す
- 4セクションMarkdown永続化: AIの鋭い指摘を圧縮前に固定化する
- 両者をループ化: チェック → 記録 → 次回参照 → さらにチェック
の3点だけです。地味ですが、レビューが「会話」から「資産」に変わる感触があります。
LLM を設計レビューに本格活用しているチームの参考になれば幸いです。