AIと爆速開発！Next.js×Nest.js型定義同期の自動生成パイプライン構築術

1 初めに
2 実際に発生した問題事例：型定義の齟齬
- 2.1 環境構成
- 2.2 発生した問題
3 解決策：自動生成パイプラインの構築
4 プロジェクト構成の最適化
- 4.1 各フェーズ用のCLAUDE.mdファイル配置
- 4.2 AIに触らせないファイルの明確化
5 大規模プロジェクトでの課題と対策
6 この手法の効果
7 まとめ

初めに

AIと一緒に開発をするようになってから、フロントエンドとバックエンド両方を爆速で開発することができるようになって、検証が爆速で進むようになった龍ちゃんです。

AIが混乱しないようにプロジェクト自体を整備する方法についてお話しします。AIと一緒に開発を進める開発手法に関しては、以下の記事で解説をしています。

AIに触らせないファイルを作ることで過剰な生成を禁止したり、自動生成パイプラインを構築して人為的なミスを防ぐなど、プロジェクト構造レベルでの対策が重要です。

実際に発生した問題事例：型定義の齟齬

まず、実際に私が遭遇した問題から紹介します。

環境構成

フロントエンド: Next.js
バックエンド: Nest.js

発生した問題

フロントエンドとバックエンドで型定義の齟齬が発生していました。バックエンドで定義した型をフロントエンド側で再定義して、変更が反映されておらず参照エラーが発生する状況でした。

この問題の根本原因は、AIが各環境で独立して型定義を生成してしまい、バックエンドの型定義変更がフロントエンドに反映されないことでした。人間の開発者なら「バックエンドで型が変わったから、フロントエンドも更新しなきゃ」と気づけますが、AIは各ファイルを独立して見てしまいます。

解決策：自動生成パイプラインの構築

この問題を解決するため、以下の自動生成パイプラインを構築しました：

1. OpenAPI Spec自動生成

Nest.jsからOpenAPI Specを自動生成する仕組みを導入しました。これにより、バックエンドのAPI仕様が変更されると、自動的にスペックファイルも更新されます。

公式で提供されているので、コードレベルでOpenAPI Specを生成することができます。

2. フロントエンド側の自動生成

Orvalを使用して、Next.jsにSWR + Axiosのリクエスト・型定義を自動生成する仕組みを構築しました。OpenAPI Specから自動的にフロントエンド用のコードが生成されるため、バックエンドとフロントエンドの型定義が必ず一致します。

このシステムでは、SWRとAxiosを使ってAPIリクエストを行っており、データフェッチャーやカスタムフックが自動で提供されるため、非常に便利な仕組みになっています。

3. Claude への通知

最も重要なのは、Claudeに変更不可と明確に通知することです。自動生成されるファイルには、コメントやCLAUDE.mdファイルで「このファイルは自動生成されるため変更禁止」と明記し、Claudeが勝手に編集しないように徹底しました。

自動生成するためのコマンドと、どのファイルが変更不可なのかを明確に指定する必要があります。

プロジェクト構成の最適化

AIが迷わないよう、プロジェクト構成も工夫しています：

/
├── CLAUDE.md                    # プロジェクト全体のガイドライン
├── docs/                        # 計画・設計フェーズ
│   ├── CLAUDE.md                # 計画フェーズ専用ルール
│   └── api/                     # OpenAPI Spec
└── application/                 # 実装フェーズ
    ├── backend/
    │   └── CLAUDE.md            # バックエンド実装ルール
    └── frontend/
        └── CLAUDE.md            # フロントエンド実装ルール

各フェーズ用のCLAUDE.mdファイル配置

各ディレクトリにCLAUDE.mdファイルを配置し、そのディレクトリで作業する際の固有ルールを記載しています。例えば：

application/frontend/CLAUDE.md: 自動生成ファイルの変更禁止、使用可能なライブラリの制限など
application/backend/CLAUDE.md: API仕様変更時の手順、データベーススキーマ変更の注意点など
docs/CLAUDE.md: ドキュメント作成時のフォーマット、必須項目など

AIに触らせないファイルの明確化

過剰な生成を防ぐファイル管理戦略として、以下のような対策を実施しています：

自動生成ファイルには必ず「DO NOT EDIT – Auto Generated」のコメントを付与
パッケージファイル（package.json等）の変更制限
設定ファイル類の変更制限
各CLAUDE.mdで変更不可ファイルのリスト明記

ただし、ここまで書いていたとしても、AIは結構無視することがあります。実際に、自動生成して編集禁止にしている設定ファイルを編集しに行って動くようにしたりとか、ダイナミックな手法をやってきたりするので、いくら書いていたとしても無視をする可能性があることは念頭においた方が良いと思います。

大規模プロジェクトでの課題と対策

フロントエンド・バックエンド開発者が異なる場合の同期

大規模プロジェクトでは、フロントエンドの開発者とバックエンドの開発者が違う場合に、いかに同期を取っていくかが重要な課題となります。

開発順序の調整

現在のシステムだと、バックエンドの開発をしてからフロントエンドの開発をするという順番になるため、この順序をどう合わせていくかが必要です。

同時開発のためのアプローチ

同時に開発を進めていくためには、以下のような手法が有効です：

モックを使用した並行開発
型定義を先に作成してOpenAPI仕様書だけを先に渡す
Orvalで生成したフロントエンドコードを使ってバックエンドと協調開発

このアプローチにより、フロントエンドとバックエンドの同時進行での開発が可能になります。

この手法の効果

自動生成パイプラインとプロジェクト整備により：

型定義の齟齬が完全に解消
AIが余計なファイルを触ることによる意図しない変更の防止
人間が後から「なぜこの変更をしたのか分からない」状況の回避
コードレビュー時の確認ポイントの削減

バックエンドを定義したら、そこからフロントエンドを並行して開発できますし、バックエンドとフロントエンドで型定義が異なるという問題がほとんどなくなりました。もちろん、バックエンドの定義自体が間違っていれば動作しませんが、フロントエンド側での型の不一致はかなり抑制できたと感じています。

これまでは自動生成の仕組みを使わずに開発していたため、コードが若干汚くなる傾向があり、フロント側で型定義の再定義が行われて連携が取れていないという問題や、型ファイルが増えていくという課題がありました。この仕組みにより、プロジェクト全体がより整理されたファイル構造になり、可読性が向上したと実感しています。

特に型定義の自動同期により、フロントエンドとバックエンドの開発を並行して進められるようになりました。