AIと共に育てるコードベース：散らばった型定義をリファクタリングした実践記録

はじめに

AIにコーディングを任せると、型定義が各ファイルに散らばる問題が起きやすいです。
interface の重複、どの型を使えばいいかわからない状態——これは「AIへの指示の問題」ではなく、設計フローが欠けている問題です。

AI開発でこんなことありませんか？

AIに任せて高速開発した結果、同じ interface が複数のファイルに重複して存在している。
型を追加するたびに「あの型どこにある？」の調査から始まる。
AIに整理を頼むと「全部一つのファイルに」と提案され、かえって見通しが悪くなった。

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

AIに設計の主導権まで委ね、人間が介在する必要性を感じていない人。
型定義の重複や混乱が、長期的な保守性に与える影響を軽視している人。
内部構造の改善よりも、目先の機能追加だけを優先したい人。

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

型定義の設計を後回しにすると

新機能を追加するたびに「この型、既存のものと合う？」の調査コストが積み上がる。
同じ型が複数箇所に存在するため、一方を変更したときにもう一方が追いつかない不整合が生まれる。
AIに修正を頼むと既存の型の存在に気づかず、さらに型を増やすという悪循環に入る。

AIとの協調リファクタリングという明るい未来

この記事を読めば、AIと対話しながら「分析→設計→実行」のフローで型定義を整理する手法が手に入る。
具体的には、AIを優秀なアシスタントとして扱い、人間が設計の主導権を握るための設計図を手に入れられる。
この方法は、本ブログ自身のリファクタリングプロセスとして実証済みであり、その効果を担保する。
この情報は、単なる整理術を超えて、AI時代のエンジニアが持つべき協調開発の一次情報である。

私も同じでした

このブログを作り始めて数週間後、型定義の散乱に直面しました。AIは「今ある重複」しか見ないため、修正を頼むたびに別の場所に同じ型が生まれる状態でした。
「分析→設計→実行」の3ステップで人間が設計の主導権を握ることで、この問題を解決しました。この記事はそのプロセスを記録したシリーズの Part 1 です。

📝 概要

AIエージェントにコーディングを任せ、高速で開発を進めていました。しかし、ある問題が発覚します。それは、型定義に関する設計指示を怠ったために、interfaceやtypeが無秩序に各ファイルへ散らばってしまったことです。

これは、AIコーディングを実践する多くの開発者が陥りがちな「見過ごされた技術的負債」ではないでしょうか。AIは指示通りにコードを生成しますが、プロジェクト全体の整合性や将来のメンテナンス性までを考慮した「設計」は、人間が主導権を握る必要があります。

この記事では、この「AI開発によって生じた型定義のカオス」という問題を、AIと協力して解決していくリファクタリングの実践記録です。

目指すのは、単なるコード整理ではありません。 AIを「全自動の魔法の杖」ではなく「極めて優秀な専門家アシスタント」として扱い、人間が設計の主導権を握りながら協調作業を進めるという、次世代の開発スタイルを実践することです。

⚠️ 問題の発見と症状

開発を進める中で、以下のような症状が顕在化してきました。

重複した型定義 : 全く同じインターフェースが、複数の異なるコンポーネントファイルに存在していた
関心の散在 : 関連する型定義が、データアクセス層や自動生成ファイルなど、複数の場所に点在していた
見通しの悪さ : 新しい機能を追加する際、どの型を使えば良いのか、あるいは新しい型をどこに定義すべきか判断するのに時間がかかる

これは、コードベースの健全性を損ない、将来の開発速度を低下させる明確なサインです。

🔍 私が設計した協調ワークフロー

この問題を解決するため、私は以下の「分析 → 設計(人間) → 実行」という、人間が主導権を握るワークフローを設計しました。

分析 : AIに重複・関連する型をリストアップさせ、現状を客観的に把握する
設計 : AIの分析結果を元に、どの型をどこに集約するか、あるいは集約しないかを人間が判断・設計する
実行 : 人間が決定した設計に基づき、具体的なコードの書き換え作業をAIに指示する

このワークフローにより、保守性の低い「神ファイル」を作ることなく、適切な粒度で型定義を整理できました。

達成した成果

改善項目	Before	After
重複した型定義	複数ファイルに散在	単一の真実の源に集約
循環参照のリスク	潜在的に存在	`import type`で完全解消
型定義の見通し	探索に時間がかかる	一箇所で全体を把握可能

その結果、「AIが生成したカオス」を「人間が設計した秩序」へ再構築することに成功しました。

AIが陥る型定義カオスの罠

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

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

「すべての型を一つのファイルにまとめましょう」
「とりあえず重複を削除しましょう」
「自動リファクタリングツールを使いましょう」

しかし、これらは対症療法です。一時的に重複は解消されますが、「どの型をどこに置くべきか」という設計原則が欠けているため、すぐに再び散らかります。

根本原因は、型定義の責務と配置の設計原則が欠けていることにありました。AIは「今ある重複」しか見ませんが、人間は「将来の拡張性」や「ドメイン境界」という、より高次の制約を満たす必要があります。

ここから先は、AIが絶対に提案しない「分析→設計→実行」という協調ワークフローの全貌と、具体的なAIへの指示文、循環参照を回避する技術的手順、そして実際の型定義の集約パターンを、すべて公開します。

このワークフローをコピーすれば、AIとの試行錯誤ループを回避し、初回から保守性の高い型定義構造を実現できます。私が実践で確立したAIとの対話パターンと、実装済みの型定義アーキテクチャを、ここで全て公開します。

実装フェーズ：具体的な手順

では、実際に私がAIと対話しながら実行した、ファイルの一括オープン手順、AIへの分析依頼の具体的な指示文、循環参照を回避するimport typeの技術的な実装パターン、そして型定義の集約先ディレクトリ構造を公開します。

このコマンドと指示文をそのままコピーすれば、「どのファイルを開くか」「AIに何を聞くか」「どこに集約するか」を毎回悩むことなく、再現可能なリファクタリングを実現できます。また、なぜドメイン分割が必要なのか、神ファイルを回避する設計判断の基準、VS Codeコマンドの実行オプションの意味も解説します。

まとめ

今回のリファクタリングを通じて、以下の重要な学びを得ました。

AIとの協調開発の本質

AIは「全自動の魔法の杖」ではなく「極めて優秀な専門家アシスタント」として扱うべきです。人間が設計の主導権を握り、AIに分析と実行を任せるというワークフローが、最も効果的でした。

「分析 → 設計 → 実行」のワークフロー

分析 : AIに現状を客観的に把握させる
設計 : 人間が集約先と構造を判断・設計する
実行 : AIに具体的なコードの書き換え作業を指示する