設計書を機能ドメイン別に分割した話 — 33ファイル＋5目次の大規模リファクタリング
Mark445,212行の設計書が開発効率のボトルネックになっていた
45,212行の設計書が抱えていた問題
wagahiアプリの設計書は、累計で45,212行に達していました。バックエンド詳細設計書だけで1万行超、内部設計書も数千行。設計書の品質には自信がありましたが、物理的なファイルサイズが開発効率のボトルネックになっていたのです。
問題1: Claude Codeのコンテキスト管理
AI駆動開発でClaude Codeを使う場合、設計書をコンテキストとして読み込ませる必要があります。しかし、1万行の設計書全体をコンテキストに含めると、トークン消費が膨大になり、実質的に使いものになりません。
毎回「この部分だけ読んで」と範囲指定するのも手間ですし、必要な箇所を人間が特定する作業自体が非効率です。
問題2: 検索と参照の困難さ
「このAPIの仕様はどこに書いてあるか」「この画面の状態管理はどの節か」。1つの巨大ファイル内での検索は時間がかかり、関連する情報が離れた場所に散在していることもありました。
問題3: 並行作業の制約
複数の機能を同時に改修する場合、同じ設計書ファイルの異なるセクションを編集する必要が生じます。Gitでのマージコンフリクトが頻発し、設計書の更新作業が開発のボトルネックになっていました。
分割の設計方針
分割にあたり、以下の方針を定めました。
機能ドメイン別に分割する
単純にファイルサイズで分割するのではなく、機能ドメイン（認証、キャラクター管理、チャット、トークン管理等）を基準に分割しました。これにより、「トークン関連の変更」をするときは「トークン管理」のファイルだけを見ればよい、という直感的な構造になります。
各ファイルは2,000行以内
Claude Codeのコンテキストウィンドウを考慮し、各分割ファイルは2,000行以内に収めるルールとしました。これなら、設計書全体を読み込むことなく、必要な機能ドメインのファイルだけを効率的に参照できます。
目次ファイル（_index.md）の整備
各設計書に目次ファイルを用意し、以下の情報を含めました。
- 分割ファイルの一覧と概要
- 逆引き表: API-ID、画面ID、コンポーネントID等から該当ファイルを特定
- 用途ガイド: 「何を調べたいときにどのファイルを見るか」の案内
分割結果
| 設計書 | 分割数 | 目次ファイル |
|---|---|---|
| バックエンド詳細設計書 | 10ファイル | _index.md |
| フロントエンド詳細設計書 | 10ファイル | _index.md |
| DB詳細設計書 | 2ファイル | _index_DB.md |
| 外部設計書 | 5ファイル | _index.md |
| 内部設計書 | 6ファイル | _index.md |
合計33ファイル＋5目次ファイル。原本はorg/ディレクトリに保存し、万が一の際にも復元可能にしています。
逆引き表の威力
目次ファイルに設けた逆引き表が、想像以上に強力でした。
たとえばバックエンド詳細設計書の逆引き表は、以下のような構成です。
- API-ID（API-AUTH-001等）→ 該当ファイル名
- テーブル名 → 該当ファイル名
- クラス名 → 該当ファイル名
Claude Codeに「API-CHAR-003の仕様を確認して」と指示すれば、目次ファイルの逆引き表から該当ファイルを特定し、そのファイルだけを読み込んで回答できます。45,212行全体を読み込む必要はありません。
GPS位置情報会話統合の開始
設計書のリファクタリングと並行して、Ver2_01の最初の機能であるGPS位置情報会話統合にも着手しました。
これは、ユーザーの現在位置情報をAI会話に統合する機能です。位置情報に基づいてキャラクターの会話内容が変化し、「今いる場所」に応じた応答を返す。wagahiアプリの位置情報ゲームとしての核心機能の一つです。
設計書分割が完了した直後にこの実装に取り組んだことで、分割された設計書の使い勝手を即座に検証できました。結果は上々。必要な設計書ファイルだけをピンポイントで参照でき、開発効率は明らかに向上しました。
まとめ — 設計書もリファクタリングが必要
コードのリファクタリングは当たり前に行われますが、設計書のリファクタリングはあまり語られません。しかし、AI駆動開発では設計書がAIへの入力として日常的に使われるため、設計書の構造最適化は開発効率に直結します。
45,212行を33ファイルに分割するのは大きな作業でしたが、その後の開発効率の向上を考えれば、十分に投資対効果のある取り組みでした。
本記事は2026年2月時点の開発状況に基づいています。
著者: 株式会社シーテン — インフラ系から宇宙関連システムまで20年以上の開発経験を持つ技術者集団。2025年より生成AI・AIエージェントを活用したAI駆動開発に本格参入し、自社プロダクト「wagahi」の開発を通じて実践知見を蓄積中。
関連記事:
投稿者プロフィール
