🧹

新機能を追加するために3,000行削除した話 — AIが書いたコードの技術負債とどう向き合うか

に公開1件

はじめに — AI が書いたコードの「その先」

AI コーディングツールの普及で、非エンジニアでもシステムを構築できる時代になりました。それ自体は素晴らしいことで、実際にプロダクトとしてユーザーに使われているシステムが AI の力で生まれています。

しかし、その先に待っているのは「動いているけど設計がないコードベース」です。

場当たり的な指示で生成されたコードは、個々のファイルとしては正しく動きます。しかし全体を俯瞰すると、同じデータが複数の経路で変換され、同じ状態が異なる場所で管理され、型定義が散在している。新機能を追加しようとすると、どこに手を入れればいいのか分からない。

これは非エンジニアに限った話ではありません。ジュニアエンジニアが AI と一緒に書いたコードでも、経験豊富なエンジニアが急いで AI に書かせたコードでも、「設計を意識した人間のレビュー」が欠けていれば同じことが起きます。AI が盛んになった今、こうした技術負債は増え続けているのではないでしょうか。

この記事では、そうしたコードベースに新機能を追加するために 3,000行を削除した 実体験を共有します。そして重要なのは、この大規模リファクタリング自体も AI(Claude Code)と一緒に遂行したということです。AI が生んだ負債を、AI の力で返済する。問題は AI そのものではなく、どう指示するかにあります。

何をやろうとしたか

RAG ベースの AI チャットアプリで、参照元の表示を改善する必要がありました。同じ文献の異なるセクションが別々のカードとして表示されており、ユーザーから「参照が多すぎて見づらい」という指摘を受けていたためです。

やりたいことはシンプルです。

  • 同一ソースの複数チャンクを1つのカードにまとめる
  • 番号表示の統一
  • 詳細パネルでのチャンク一覧表示

しかし、既存コードの上にこの機能を載せようとした時点で、問題が見えてきました。

何が問題だったか

props drilling が6階層

ソース選択の状態管理が props のバケツリレーで実装されていました。

ページコンポーネント
  → リスト(onSelect, selected)
    → アイテム(onSelect, selected)
      → メッセージ(onSelect, selected, selectedNumber)
        → タブ(onSelect, selected)
          → セクション(onSelect, activeItem)

グルーピング機能を追加するには、この経路にグループID、引用IDリスト、アクティブチャンクの情報などを追加する必要がありました。6階層全てに新しい props を追加するのは現実的ではありません。

中間変換の積み重ね

グルーピングしたデータ → 個別アイテム配列(代表チャンクにグループ情報を詰め込む)→ イテレート → レンダリング、という中間変換が必要でした。元のデータを直接使えば済む話が、既存のインターフェースに合わせるために変換層が増えていく構造です。

約100行の「逆算ロジック」

選択中アイテムから引用番号を逆算する処理が約100行ありました。複数のフィールドで順番にマッチングを試みる防御的なコードです。Context で状態を管理すれば、そもそも逆算が不要になります。

判断 — 積むか、整理するか

選択肢は2つでした。

既存の上に積む 先に整理する
短期コスト 低い 高い
品質リスク props 6階層に新状態追加、バグ混入リスク大 既存機能のデグレリスク
次の変更時 また同じ苦しみ スムーズに追加可能
コード量 増える一方 減りながら機能が増える

「動いているコードを触るリスク」は確かにあります。しかし「触らずに積むリスク」の方が長期的には大きいと判断しました。このまま積めば、次の機能追加でも同じ問題に直面し、さらに複雑になったコードと向き合うことになります。

実践 — 何をどう整理したか

1. Context への統一

props drilling を全廃し、React Context で状態を一元管理しました。

// Before: 6階層の props drilling
<List onSelect={handleSelect} selected={selected}>
  <Item onSelect={onSelect} selected={selected}>
    <Message onSelect={onSelect} selectedNumber={...}>

// After: 各コンポーネントが Context を直接参照
const context = useSelection();
context.select({ item, group, messageId });

3つの props chain が全て不要になりました。

2. コンポーネントに処理を内包

クリック処理を専用フックから、バッジコンポーネント内に移動しました。Context を直接参照することで、クリック処理・選択状態の判定・表示の3つがコンポーネント内で完結します。

export const Badge = ({ id, data, ...props }) => {
  const context = useSelection();

  const handleClick = useCallback(() => {
    const item = data?.itemMapping?.get(id);
    if (!item) return;
    context.select({ item, group, messageId });
  }, [id, data, context]);

  const isSelected = context.selectionState?.item?.id === id;
  // ...
};

外部からコールバックを注入する必要がなくなり、テキスト処理関数やコンポーネント生成関数の引数が大幅に減りました。

3. グループデータを直接イテレート

セクションコンポーネントのイテレート対象を個別アイテム配列からグループ配列に変更し、中間変換を廃止しました。

// Before: グループ → 個別アイテム配列に変換 → イテレート
const items = groups.flatMap(g => ({
  ...g.chunks[0],
  _groupId: g.id,
  _groupChunks: g.chunks,
  _title: g.title,
}));

// After: グループを直接イテレート
const renderCard = (group: Group) => {
  const representative = group.chunks[0];
  return <div>{group.title}</div>;
};
filteredGroups.map(renderCard);

variant prop('cited' | 'other' | 'all')を導入し、フィルタリングもコンポーネント内で完結させました。

4. 型定義の統一

散在していた命名を統一し、不要なフィールドを削除しました。

Before After 理由
マッピング名A マッピング名B 用途を明確化
groupNumber groupId ID であることを明示
元番号リスト名 引用IDリスト名 意味を明確化
id: string id: number 型を正確に
activeIndex 削除 ID ベース判定に変更
選択状態の冗長フィールド 削除 既存フィールドで代替

結果

指標 Before After
変更ファイル数 — 98
コード増減 — +2,539 / -5,652(純減 3,113行)
props drilling 階層 6 0
選択状態のフィールド数 6 3
削除したフック — 2つ
削除したテスト — 5件(旧 props 前提で全てエラー)

機能が増えたのにコードが3,000行以上減りました。

AI でリファクタリングを遂行する — 問題は「どう指示するか」

ここで強調したいのは、この3,000行削減のリファクタリング自体を AI(Claude Code)と一緒にやったということです。

AI が生んだ技術負債を、AI で返済する。矛盾しているように聞こえますが、決定的な違いは「指示の仕方」にあります。

技術負債が生まれた時の指示は「この機能を作って」「このバグを直して」という局所的なものでした。一方、リファクタリング時の指示は違います。

  • 「この props drilling を Context に置き換えたい。影響範囲を調べて」
  • 「この中間変換を廃止して、グループデータを直接イテレートする設計に変えたい」
  • 「この型定義を統一したい。全ての使用箇所をリネームして」

つまり、設計の方向性を人間が決め、実行を AI に任せるというパターンです。AI は「98ファイルの一括リネーム」や「6階層の props 削除」のような機械的で広範囲な変更を高速かつ正確にやってくれます。人間がやったら数日かかる作業が、数時間で完了しました。

AI コーディングで技術負債が生まれるのは、AI が悪いのではなく、設計の方向性を示さずに局所的な指示を繰り返すからです。逆に、設計の判断を人間が持ち、AI に実行させれば、リファクタリングという本来面倒な作業を驚くほど効率的に進められます。

まとめ — AI 時代のコードに必要なこと

AI が書くコードは「局所的には正しい」ことが多いです。関数単位、ファイル単位では動く。しかし「全体の設計」は AI に指示した人間の責任です。

設計を意識しない AI コーディングは、技術負債を通常の何倍もの速度で生み出します。コードを書く速度が速いからこそ、一貫性のない設計が大量に生産されるからです。

しかし同時に、AI は技術負債の返済にも強力な武器になります。設計の方向性さえ示せば、広範囲のリファクタリングを高速に実行してくれる。問題は AI そのものではなく、設計を判断する人間がいるかどうかです。

「動いているから触らない」ではなく、「新機能を入れるために整理する」。その判断ができるエンジニアが、AI 時代にはますます必要になると感じています。

リファクタリングは贅沢ではなく、新機能のための投資です。そしてその投資を、AI が加速してくれます。

Discussion

mikamika

定期的にコード全体を機能を(後から追加する前提で)やや絞ってリファクタリングさせて、その後に機能を再追加させると良いです。