AIと育てる型定義：シリーズ総集編〜生きた仕様書への道〜

はじめに

AIに任せてコードを高速生成すると、型定義が各ファイルに散らばります。場当たり的に整理しても再び散らかります。
「分析→設計→実行」の5ステップで人間が設計の主導権を握ることで、型定義をプロジェクトの「生きた仕様書」にできます。このシリーズの総集編です。

AI開発のスピード感に、設計が置いてけぼりになっていませんか？

高速にコードを生成できるAIを使い始めたが、気づけばプロジェクト全体の型定義が無秩序に散らばってしまった。
重複や不整合を解消しようとしても、場当たり的な修正ばかりで根本的な「秩序」が取り戻せない。
AIをどう指示すれば、長期的に保守可能なコードベースを維持できるのか、その正解が見えず悩んでいる。

この記事をお勧めしない人

AIが出したコードをそのまま動かすだけで満足し、その裏にある設計思想には興味がない人。
型定義の整理は単なる「見た目の問題」であり、プロジェクトの保守性には無関係だと考える人。
AIを単なる下請けとして使い、設計パートナーとしての可能性を信じていない人。

もし一つでも当てはまらないなら、読み進める価値があるかもしれません。

体系的な戦略なしに整理を続けると

AIに「型を整理して」と頼むたびに部分最適な提案が返り、整理したそばから新しい散らかりが生まれる。
重複削除→再散在→重複削除のサイクルが繰り返され、コードベースの全体像が誰にも把握できなくなる。
新機能を追加するたびに「この型はどこにある？」から始まる調査が必要になり、開発速度が落ちる。

生きた仕様書への昇華という明るい未来

この記事を読めば、AIを設計パートナーとして活用し、混沌とした型定義を「生きた仕様書」へと変える体系的戦略が手に入る。
具体的には、5つのステップで進めるリファクタリングの全貌と、AI時代のエンジニアが持つべき「構造の主導権」の設計図を手に入れられる。
この方法は、全5回のシリーズを通じて本ブログで実証された集大成である。

私も同じでした

このブログで5回のシリーズを通じて実践しました。Part 1 で重複を排除し、Part 2 で YAML からの型生成、Part 3 で Intersection Types による責務分離、Part 4 でドメイン知識の集約、Part 5 で全層の型統合——この順序で進めたことで、型定義がコードベースの仕様書として機能するようになりました。

🗺️ リファクタリングの旅路：5つのステップ

私たちのリファクタリングは、単純な作業から始め、徐々に抽象度を上げながら、以下の5つのステップで進められました。

Part 1: 単純な重複の排除

目的 : 最も分かりやすい問題から着手する

プロジェクト内に散らばる、完全に同一の型定義を洗い出し、共通の型定義ファイルに集約しました。これは、リファクタリングのウォーミングアップであり、コードベースの現状を把握する第一歩でした。

Part 2: 『唯一の真実の源』の確立

目的 : データモデルの中心を定義する

完全なデータ構造を持つ基底型を「唯一の真実の源」として定義。派生的な型は、基底型から型システムを使って生成するように変更しました。これにより、データモデルの変更が派生型にも自動的に反映される、堅牢な構造が生まれました。

Part 3: 『関心の分離』の実践

目的 : 型の責務を明確にする

複数の責務が混在していた型を、それぞれの責務を持つ独立した型に分割。そして、型システムを使って結合することで、責務の明確化と再利用性の向上を両立させました。

Part 4: ドメイン知識の集約

目的 : アプリケーションの「仕様」をコードで表現する

特定のレイヤーに属さない「ドメイン知識」を表す型を共通の場所に集約。これにより、型定義ファイルは単なる型置き場から、プロジェクトの仕様を定義する場所へと進化し始めました。

Part 5: UIとデータ層を繋ぐ『生きた仕様書』の完成

目的 : データフロー全体を型で保証する

UIコンポーネントが期待するデータの形状や、サーバーで変換された後のデータモデルまでも共通の型定義で管理。これにより、データフロー全体が型で繋がれ、型定義ファイルは名実ともにプロジェクトの「生きた仕様書」として完成しました。

✨ 結果：『生きた仕様書』がもたらす価値

このリファクタリングを経て、型定義ファイルは以下のすべてを定義する、プロジェクトの中核となりました。

データモデル : アプリケーションが扱うデータの基本構造
ビジネスロジックの契約 : 関数の入力と出力の仕様
ドメイン知識 : アプリケーション固有の概念
UIのデータ要件 : コンポーネントが表示に必要なデータの形状

これにより、「コードが仕様を語り、仕様がコードを制約する」という理想的な状態が実現しました。新しい機能を追加する際は、まずこの仕様書を更新することから始めます。それだけで、影響範囲や実装すべき内容が明確になり、開発プロセス全体がスムーズになります。

AIが陥る場当たり的リファクタリングの罠

ここで重要な警告があります。

AIに「型定義を整理して」と頼むと、高確率で以下のような提案が返ってきます：

「重複を見つけて削除しましょう」
「各ファイルの型を適切な場所に移動しましょう」
「型の命名を統一しましょう」

しかし、これらは場当たり的な修正です。一時的に整理されますが、「なぜそこに配置するのか」という設計思想が欠けているため、すぐに再び混沌が訪れます。

根本原因は、体系的なリファクタリング戦略が設計されていないことにありました。AIは「今ある問題」しか見ませんが、人間は「設計原則に基づいた段階的な改善」や「最終的に到達すべき理想の状態」という、より高次の制約を満たす必要があります。

ここから先は、AIが絶対に提案しない「5段階の体系的リファクタリング戦略」の全貌と、各段階で適用する設計原則、型定義を「生きた仕様書」へ昇華させる具体的な手順、そしてAIを設計パートナーとして活用する対話パターンを、すべて公開します。

この戦略をコピーすれば、場当たり的な修正ループを回避し、初回から設計思想に基づいた体系的なリファクタリングを実現できます。私が実践で確立した5段階のリファクタリング戦略と、AIとの協調開発パターンを、ここで全て公開します。

体系的リファクタリング戦略の全貌

では、実際に私が設計した5段階のリファクタリング戦略、各段階で適用する設計原則、型定義を「生きた仕様書」へ段階的に昇華させる具体的な手順、そしてAIを設計パートナーとして活用する対話パターンを公開します。

この戦略と対話パターンをそのままコピーすれば、「どの順序でリファクタリングするか」「各段階で何を達成するか」「AIにどう指示するか」を毎回悩むことなく、再現可能な体系的リファクタリングを実現できます。また、なぜ段階的なアプローチが重要なのか、設計原則の適用順序、AIとの効果的な対話方法も解説します。

🤖 AIとの協調：設計パートナーとしてのAI

この旅を通じて、AIは単なるコード生成器ではありませんでした。

設計の壁打ち相手 : AIの指摘が、より良い設計への気づきを与えてくれました
設計原則の適用支援 : 適切なタイミングで設計原則を提示し、リファクタリングの指針を示してくれました
体系的な計画の立案 : 目の前の問題だけでなく、全体を見通したリファクタリング計画を共に策定しました

AIを「設計パートナー」として活用することで、一人では見落としがちな視点を得ながら、一貫した思想に基づいた高品質なリファクタリングを推進できたのです。

🚀 まとめ

良質な型定義は、現代的なWebアプリケーション開発における最も価値ある資産の一つです。今回のシリーズで実証したように、AIとの協調を通じて体系的なリファクタリングを行うことで、コードベースは単なるプログラムから、チーム全体の共通理解を促進し、未来の変更を容易にする「生きた仕様書」へと進化させることができます。

この一連の記録が、皆さんのプロジェクトにおけるコード品質向上のヒントとなれば幸いです。

型定義のSSOTを確立した後、同じ「一箇所を変えれば全体に波及する」思想をYAMLレイヤーにも適用しました。3段階の階層型マージにより、UIラベルやバリデーションまで含めて一元管理するアーキテクチャがその記録です。また、E2Eテストのデータもspec.yaml一本で管理し、記事追加でテストが壊れなくなった実践記として残しています。型・設定・テストの3層がすべて同一の情報源を参照する状態が、AI時代の保守性の基盤となっています。