Astro + React Islands Architectureのコード品質改善：AIに4軸分析させて1日でリファクタリング

Astro + React Islands Architectureで構築したECサイトのコード品質を、AIの4軸分析（品質・セキュリティ・パフォーマンス・アーキテクチャ）で1日かけて改善した記録です。約87回のAI対話を通じて、型エラー修正からアーキテクチャ再設計まで一気に進めました。

本記事では分析ワークフローの具体的な手順と、AIが得意だった改善・人間の判断が必要だった改善を正直に切り分けます。

背景：技術的負債が溜まったSSG + Reactプロジェクト

AstroのIslands Architectureを使ったECサイトを運用していました。SSGで静的ページを生成し、インタラクティブな部分だけReactコンポーネントをハイドレーションする構成です。

機能追加を優先した結果、以下の負債が蓄積していました。

TypeScriptの any 型が散在
1ファイル500行超の巨大コンポーネント
未解決のTODOコメント
console.log の残存
レイヤー分離が曖昧な状態

手動で1つずつ潰すのは現実的ではありません。そこでAIに体系的な分析を依頼しました。

4軸分析アプローチ

Claude Codeの sc:analyze コマンドを、4つのフォーカスエリアで順番に実行しました。

1
sc:analyze --focus quality       # 品質分析
2
sc:analyze --focus security      # セキュリティ分析
3
sc:analyze --focus performance   # パフォーマンス分析
4
sc:analyze --focus architecture  # アーキテクチャ分析

各分析で検出された問題を優先度別にリスト化し、sc:improve で改善を適用します。この「分析→文書化→改善→検証」のサイクルを4軸分回しました。

軸1：品質改善

AIが検出・修正した5カテゴリです。

型エラー修正（高優先度）

TypeScriptのstrict modeで検出されるべきエラーが放置されていました。AIは型定義の不整合を一括で検出し、修正パッチを生成します。これは機械的な作業なのでAIの精度が高いです。

巨大コンポーネントの分割（高優先度）

500行を超えるReactコンポーネントが複数ありました。AIに「1コンポーネント200行以下、単一責務」の制約で分割を依頼しました。Container/Presentationパターンで、ロジックとUIを分離しました。

1
// Before: 1ファイルに全てが混在
2
// ProductPage.tsx（500行超）
3

4
// After: 責務で分割
5
// ProductPageContainer.tsx — データ取得・状態管理
6
// ProductPagePresentation.tsx — UIレンダリング
7
// useProductData.ts — カスタムフック

`any` 型の排除（中優先度）

any を使っている箇所をAIが列挙し、適切な型定義に置き換えました。APIレスポンスの型定義が不足しているケースが多く、interfaceの追加で解決しました。

TODO解決・console.log削除（低〜中優先度）

TODOコメントの棚卸しとconsole.logの削除です。AIは機械的に列挙できますが、TODOの「本当に不要かどうか」は人間が判断する必要がありました。

軸2：セキュリティ改善

AIによるセキュリティ分析では、依存パッケージの脆弱性チェック、環境変数の取り扱い、入力値のバリデーション漏れなどが検出されました。

ECサイト特有の注意点として、フォーム入力のサニタイズやCSRF対策の確認が含まれます。AIはチェックリストの網羅性が高く、人間が見落としがちな箇所を拾ってくれます。

軸3：パフォーマンス改善

React.memoの追加

Islands Architectureでは、ハイドレーションされるReactコンポーネントの再レンダリングコストが重要になります。AIが不要な再レンダリングが発生しているコンポーネントを特定し、React.memo でラップしました。

1
// Before
2
const ProductCard = ({ product, onSelect }) => {
3
  return <div>{/* ... */}</div>;
4
};
5

6
// After
7
const ProductCard = React.memo(({ product, onSelect }) => {
8
  return <div>{/* ... */}</div>;
9
});

Virtual Scrollの検討

商品一覧ページで大量のアイテムを描画する箇所があり、Virtual Scrollの導入をAIが提案しました。ただし、SSGで静的に生成するページではSEOへの影響を考慮する必要があり、最終的な導入判断は人間が行いました。

Lazy Loading

Islands Architecture の利点を活かし、client:visible ディレクティブでビューポートに入ったタイミングでコンポーネントをロードする設定を追加しました。

軸4：アーキテクチャ改善

最も改善効果が大きかったのがアーキテクチャ分析です。

ディレクトリ構造の再編成

機能ベースのディレクトリ構造に再編成しました。

1
src/
2
  features/
3
    product/
4
      components/
5
      hooks/
6
      types/
7
    cart/
8
      components/
9
      hooks/
10
      types/
11
  shared/
12
    components/
13
    hooks/
14
    utils/

設計パターンの適用

AIの分析で以下のパターンが提案・適用されました。

パターン	適用箇所	効果
Context/Provider	グローバル状態管理	Props drillingの解消
Container/Presentation	コンポーネント分割	テスタビリティ向上
Custom Hooks	ロジック共通化	コード重複削減
Guard	認証チェック	条件分岐の整理
Reducer	複雑な状態遷移	状態管理の予測可能性

Islands Architecture最適化

Astro特有の改善として、不要な client:load を client:visible や client:idle に変更し、初期バンドルサイズを削減しました。AIはコンポーネントの使用パターンを分析して、最適なハイドレーション戦略を提案できます。

ミドルウェアの改善

認証チェックやリダイレクト処理がページコンポーネントに散在していたのを、Astroのミドルウェアに集約しました。

ワークフロー：analyze → improve → verify

1日の作業フローは以下の通りです。

1
1. sc:analyze --focus {axis}     # 問題検出・優先度付け
2
2. 検出結果をレビュー              # 人間が優先度を確認
3
3. sc:improve                    # AIが改善パッチ生成・適用
4
4. テスト実行                     # 回帰テストで動作確認
5
5. 次の軸へ                       # 1-4を4回繰り返す

約87回の対話でこのサイクルを回し、4軸すべての改善を1日で完了しました。

結果

軸	主な改善
品質	型エラー修正、巨大コンポーネント分割、`any` 排除、TODO解決
セキュリティ	入力バリデーション強化、依存パッケージ確認
パフォーマンス	React.memo追加、ハイドレーション戦略最適化
アーキテクチャ	ディレクトリ再編成、5パターン適用、レイヤー分離

[要確認] 具体的なビルドサイズの変化、Lighthouseスコアの変化などの定量データ。

正直な評価：AIが得意だったこと・人間が必要だったこと

AIが高精度だった改善

型エラーの検出と修正: 機械的な作業。人間より速く正確です
any 型の排除: 型推論の候補を提案する能力が高いです
console.log/TODOの列挙: 漏れなく検出できます
React.memoの追加: 再レンダリングパターンの分析が正確です
ディレクトリ構造の提案: ベストプラクティスに基づく整理が得意です

人間の判断が必要だった改善

Virtual Scrollの導入判断: SSGとの相性やSEO影響は文脈依存です。AIは「導入できる」と言いますが、「すべきかどうか」はビジネス判断です
TODOの要否判断: 「このTODOはまだ必要か？」はプロジェクトの方向性を知らないと判断できません
設計パターンの選択: AIは複数のパターンを提案しますが、プロジェクトの規模や今後の拡張方針に合うかは人間が決めます
ハイドレーション戦略: client:load vs client:visible vs client:idle の選択は、ユーザーの実際の操作パターンに依存します

AIは「何が問題か」の検出と「どう直すか」の実装が得意です。一方で「やるべきか」「どこまでやるか」のスコープ判断は人間が握る必要があります。

まとめ

4軸分析（品質・セキュリティ・パフォーマンス・アーキテクチャ）を sc:analyze → sc:improve のサイクルで回すことで、1日でプロジェクト全体の品質改善を完了できました。

重要なのは以下の3点です。

分析を構造化する: 4軸に分けることで漏れなく問題を検出できます
AIに任せる範囲を決める: 機械的な修正はAI、スコープ判断は人間という分担です
テストで安全網を張る: 改善のたびに回帰テストを実行し、動作の不変性を保証します

Astro + React Islands Architectureは、SSG部分とインタラクティブ部分が明確に分かれているため、AIによる分析と改善の対象を絞りやすい構成です。技術的負債の返済に腰が重い場合、まず sc:analyze で全体像を把握するところから始めると良いでしょう。