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

著者: ClaudeMix Team |

AIにコーディングを任せると、型定義が各ファイルに散らばる問題が起きやすい。同じinterfaceが複数のファイルに重複し、どの型を使えばいいか判断に時間がかかる状態になった。「分析→設計→実行」という、人間が設計の主導権を握るワークフローで整理した。

① やったこと

Before: 同じインターフェースが複数の異なるコンポーネントファイルに重複して存在し、関連する型定義もデータアクセス層や自動生成ファイルなど複数の場所に点在していた。新しい機能を追加する際、どの型を使うべきか、新しい型をどこに定義すべきかの判断に時間がかかっていた。

After: 「分析(AI)→設計(人間)→実行(AI)」の3ステップワークフローで型定義を集約した。

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

循環参照のリスクはimport typeを使うことで完全に解消した。

② 設計判断

  • 【優先した価値】: 「どの型をどこに置くべきか」というドメイン境界の設計を人間が主導すること。AIは「今ある重複」しか見ないため、将来の拡張性を見据えた配置判断は人間が担う必要がある
  • 【犠牲にした価値】: AIに「整理して」と一任して即座に結果を得る速さ。分析結果を人間が確認し、設計方針を決めてから実行に移すため、AI任せより1ステップ多い

③ 技術的負債

  • 【解消した負債】: 複数ファイルに散在していた重複型定義を、単一の場所を参照する構造に集約した。型を探すために複数ファイルを調査する必要がなくなった
  • 【新たに生まれた負債】: この3ステップは自動化されておらず、新しい型が増えるたびに人間が「設計」ステップに関与し続ける必要がある。AIに全任せするより運用コストが高い

④ 経営翻訳

各部署(ファイル)が独自に同じ様式の書類(型定義)を作ってしまい、どの部署の書類が正本か分からなくなっていた状態を、「どの様式をどこで管理するか」を担当者(人間)が都度決定する運用フローに切り替えた。書類の重複は解消されたが、新しい様式が必要になるたびに担当者の判断を挟む工程が増えた。

なお、「型定義のSSoT」と同じ課題は、E2Eテストのデータ層にも存在していた。記事追加のたびにE2Eテストが壊れていた問題をspec.yamlで解決した記録も合わせて読むと、TypeScriptの型からテストデータまでを一元管理するSSOT設計の全体像が見えてくる。

このシリーズの記事