TechTrainテックブログPublicationへの投稿
🏃

Claude Code と二人七脚 DB 設計

choclucy
に公開
db設計
Claude Code
tech

はじめに

弊社では開発において、コード生成・レビュー段階の9割以上を AI に一任しています。
しかし仕様設計・DB 設計においては、人間が主体です。
今回は DB 設計段階において、私が Claude Code を如何様にしてこき使っているか、一例を紹介したいと思います。

二人七脚とは

私 + Claude Code (Agent + subagent 4つ) 体制のことです。
以下の 4 step を完走した暁には DB 設計が完了している、夢の体制です。

  1. 仕様とコードベースからユースケース列挙
  2. ユースケースのブラッシュアップと起票
  3. 各問いの壁打ち
  4. subagent によるレビューループ

二人七脚で完走する 4 step

以下は例として、「ユーザーにタグを付けて管理する新機能を作る」という場合の流れです。

前提

  • 機能開発における背景や目的・要求・要件は最低限、GitHub issue 等に整理された状態
    • 「目的」と「やりたいこと」がはっきりしていれば、書き方自体は雑でも案外どうにかなります
  • エンジニア本人のプロジェクト・機能範囲に対する理解度が一定以上ある

1. 仕様とコードベースからユースケース列挙

最初のプロンプトはこれだけです。

> issue 1234 を読んで。要件を満たすように設計していくから、一緒にやろー。

この雑すぎプロンプトに対して Claude Code は以下を行います。

  • issue を読んで要件を把握する
  • 自発的に既存のコードベースを調査し、migration ファイル等から既存の table 構造を把握
  • 設計の叩き台の作成・提示

しかし Claude Code の提示する「叩き台」は 情報過多で論点が散漫 になりがちです。
まあ 1 機能全体の要件を把握させて設計をねだっているので当然ですね。次 step で整えます。

2. ユースケースのブラッシュアップと起票

step 1 の出力に対して、人間がつっこみまくるフェーズです。
ここは Agent との二人三脚であり、 人間の判断が設計の方向性を決定する 重要な step になります。

人間が担う役割は主に 2 つあります。

論点の結合・分離

たいてい、 issue やコードベースから読み取れなかった設計の論点を複数個同時に尋ねてきます。
人間の頭はそこまで頑張れないので、ここでは解決しません。
同時に考えるべき論点を統合・別で考えるべき論点を分離して、論点の整理に注力 し、論点があること自体を起票させます。
後で一個ずつ潰していけばいいのです。

ドメイン知識の注入

コードベースからは読み取れない運用実態や、ステークホルダーとの口頭確認結果を注入します。
たとえば「この table は現在使用されていない」という運用知識の取得や、漏れていた仕様の決定など、AI の預かり知らぬところを埋めてあげるのは人間の仕事です。

この時点で出来上がる issue の一例
## 概要
〇〇を目的とした要件を設計する。

## 背景・設計判断
現状は〇〇であり、運用上の課題がある。△△を実現したい。設計フェーズとして独立させ、実装 issue はこの設計を踏まえて分解する。

## ユースケース

### 管理画面
| # | 条件 | 期待する振る舞い |
|---|------|-----------------|
| 1 | 管理者が新しいユーザーを登録する | タグを設定してユーザーを作成できる |
| 2 | 管理者がユーザーのタグを後から設定・変更する | 既存ユーザーに対してタグを紐付け/変更できる |
| 3 | 管理者がタグごとのユーザー一覧を確認する | 特定のタグに紐づくユーザーを一覧できる |

### フロントエンド向け API
| # | 条件 | 期待する振る舞い |
|---|------|-----------------|
| 4 | ユーザーがタグパラメータ付きURLでサインアップする | タグが自動的に紐付く |
| 5 | タグパラメータなしでサインアップする | 従来通り、タグなしのユーザーとして登録される |
| 6 | 無効なタグパラメータでサインアップする | サインアップ失敗（エラー） |

### 既存 table との関係整理
| # | 条件 | 期待する振る舞い |
|---|------|-----------------|
| 7 | 既存テーブル ( `table_a` ) が存在する | 新しいモデルとの関係を整理する(統一 or 併存 or 段階的移行 etc) |

### 設計で答えを出すべき問い
| # | 問い |
|---|------|
| A | タグ付きユーザーモデル設計(統一テーブル or 既存3テーブルとの併存 etc.) |
| B | 1ユーザーに対するタグの多重度(1:1 or 1:N) |
| C | タグパラメータの形式と有効期限の有無 |

## データ設計
### ER 図
todo: mermaid 記法を用いた ER 図の出力

### テーブル定義
todo: SQL による table 定義の出力

3. 各問いの壁打ち

では「問い」という形で論点が明確化されたので、設計を行っていきます。

  1. Agent と議論を進める
  2. 結論が出たら「問いの答え」として issue 本文に明文化し、 ER 図やテーブル定義に起こす

Agent と二人きりでの壁打ちです。まだ二人三脚ですね。
ここで 議論が発散すると AI もだいぶ意味不明なことを言い出す ので、 step 2 の段階で論点をどれだけ切り分けできているかが、結構大切です。

この step で発生しがちな問題と対応は以下になります。

🔥 誤情報を前提とした議論になっている

ハルシネーションに騙されてしまったパターンです。
面倒なのでハルシネーション自体を抑制します。
たとえば polymorphic association の代替パターンを検討する際、こう指示します。

> polymorphic association の代替パターンについて、学習データや推論でなく、権威ある人物の blog や書籍等で提唱されるパターンの情報を収集して整理して。

私自身が代替パターンを知っていたとしても、一度ソースで提示させます。
これは私への input ではなく、 Claude Code への input なのです。
しかし銀の弾丸ではないため、「ソースにないこと言ってない？」と適宜突っ込んであげる甲斐甲斐しいお世話は稀に発生します。

🔥 議論途中で発覚する新たな問い

壁打ちを進める中で、新たに「問い」が生まれることは多々あります。
同一セッション内で深堀りし始めるとろくな議論にならないので、 一旦 issue に追記させて元の議論に戻ります。
起票させる程度の寄り道なら、もとの議論の命題を見失わずに済みます。

4. subagent によるレビューループ

設計が固まったら、複数の subagent にレビューさせます。

> AgentTeam を組んで。楽観的なエンジニア、悲観的なエンジニア、UI/UXを第一にするエンジニア、自身のこだわりが強いエンジニアの4名。
  チームの任務は以下。
  - issue 1234 とその epic issue 1230 を読み、1234 の設計方針が妥当かどうか議論する

  議論の進行については以下を遵守。
  1. リーダーでなく、全 agent が必ず自分で各 epic issue, issue 1234 にアクセスして全文を読む。これは情報伝達段階で情報漏れが発生しないようにするためである
  2. 全員の意見が出揃ったら、全員が意見を共有の上、全 agent が必ず自分で反論や同意・再思考して自身の結論を出す
  3. リーダーは再議論後の「全員の結論」をもとに意見を統合・調整し、結論を出す
  4. 上記について issue 1234 にコメントの形でアウトプットする

  では AgentTeam を組んで、議論スタート。

なぜその 4 名？

バランスが良く、 私の好みに合うからです。

  • ☀️ 楽観的: 他 subagent の過剰設計を防ぐ。また、この subagent ですら指摘する項目は重要視されやすい
  • 🛡️ 悲観的: とにかく最悪のケースを考え、セキュリティやパフォーマンスに厳しい目を向ける
  • 🎨 UI/UX 第一: 開発者目線で最適化されすぎた結果、ユーザー側に無用な不便を強いる構造にならないよう調整する
  • 🔬こだわり: 言語やクラス設計・DB 設計の教科書的パターンを規範とし、細かい指摘を入れる

ループの回し方

「レビューループ」の名の通り、 1 回レビューして終わりではありません。
以下のサイクルを回します。

  1. コンテキストクリアのため 別セッションにて、 AgentTeam が issue にコメントした設計レビュー自体の妥当性を評価させる
  2. レビューと妥当性評価の結果を人間が読み、過剰設計や仕様漏れを排除しつつ設計レビューコメントの修正を行う
  3. 1〜2 を繰り返す
  4. 設計レビューコメント内容を issue 本文に反映し、最初のプロンプトで再度設計レビューを行う
  5. 1~4 を満足するまで繰り返す

人間の役割はたいてい過剰設計のフィルタリングです。
私の組む AgentTeam はやや悲観寄りのペルソナなので、「念のためこれも考慮しよう」という指摘が増えがちです（それが好みなのですが）。
実際の開発スコープ・運用を踏まえて、取捨選択が必要になります。

まとめ

仕様設計や DB 設計において、現状の AI 性能においては判断の主体は人間であるべきだと思います。そもそも、自分が判断の主体である自覚なしに、設計や後続する開発の責任は負えないでしょう。
AI はその判断や選択肢の検証を加速させてくれます。

今回紹介したのはあくまで「今現在の私はこうしてます(私はこれが好きです)」程度のものです。
自身の思考の癖・機能追加の文脈など、状況に応じてうまく活用していきたいですねー。

TechTrainテックブログ
TechTrainテックブログPublication

TechTrainのテックブログです！ 試したことや実際の開発について書いていきます！

Discussion