Antigravity でパッケージ・モジュールエラーが出るときの解決法【2026年版】

Antigravity で「AIが生成したコードをそのまま実行したらエラーになった」という経験をしたことはありませんか？なかでも厄介なのが、パッケージやモジュール関連のエラーです。Cannot find module、Module not found、Cannot use import statement——こういったメッセージを目にしたとき、何から手をつければいいか迷ってしまうことがあります。

このエラーが頻繁に起きる根本原因は「AIにプロジェクトの依存関係が伝わっていない」ことにあります。Antigravity のAIは、あなたがどのパッケージをどのバージョンで使っているかを、開いているファイルやルール設定から読み取ります。その情報が不十分だと、存在しないパッケージを使うコードや、バージョンが違う書き方のコードを生成してしまうのです。

エラーの種類と診断フロー

まず、エラーメッセージを3つのパターンに分けて考えると診断しやすくなります。

パターン1: インポートパスのエラー

Error: Cannot find module './components/Button'
Error: Module not found: Can't resolve '@/lib/utils'

パターン2: パッケージそのものが見つからない

Error: Cannot find module 'zod'
Error: Cannot find module 'react-query'

パターン3: TypeScriptの型定義エラー

Could not find a declaration file for module 'some-library'

それぞれに対応策が異なるため、まずメッセージを見てどのパターンかを確認しましょう。

パターン1：インポートパスのエラーを解決する

ファイルパスのエラーは、AIがプロジェクトのディレクトリ構造を把握できていないときに発生します。特に @/ のようなパスエイリアスを使っているプロジェクトでよく見られます。

原因の確認方法

# tsconfig.json にパスエイリアスが設定されているか確認
cat tsconfig.json | grep -A 10 '"paths"'

出力例（このような設定がある場合、AIにも認識させる必要があります）:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

tsconfig.json をエディタで開いた状態でAIに指示すると、パスエイリアスを正しく使ったコードを生成してくれます。

チャットでコンテキストを渡す方法

チャットでコードを依頼するとき、次のように現状を伝えると精度が上がります。

プロジェクトは @/ が src/ に対応するパスエイリアスを使っています。
tsconfig.json は現在開いています。このコンポーネントを作成してください。

パターン2：パッケージが見つからないエラーを解決する

このエラーは大きく2つの原因があります。「そのパッケージが package.json に存在しない」か、「インストールされていない」かです。

ステップ1: package.json を確認する

# 生成されたコードが使おうとしているパッケージが含まれているか確認
cat package.json | grep "zod"

もし含まれていなければ、インストールが必要です。

npm install zod
# または
pnpm add zod

ステップ2: node_modules を再構築する

package.json にはあるのにエラーが出る場合、node_modules が壊れていることがあります。以下のコマンドで解決するケースが意外と多くあります。

rm -rf node_modules
npm install

ステップ3: AIに使用済みパッケージリストを伝える

AIが存在しないパッケージを生成してしまう根本的な解決策は、プロジェクトのルールとして依存関係を明示することです。.antigravity/rules.md（または AGENTS.md）に次のように記載しておくと、AIが毎回 package.json を参照してコードを生成します。

## 使用パッケージ
新しいパッケージを追加する前に必ず package.json を確認すること。
既存の依存関係の範囲で実装を提案すること。新規パッケージが必要な場合は
その旨を明示し、インストールコマンドも一緒に提示すること。

ルール設定の詳細についてはAntigravity カスタムルール設定ガイドをご参照ください。

パターン3：TypeScript型定義エラーを解決する

Could not find a declaration file for module 'xxx' というエラーは、TypeScriptの型定義ファイル（@types/xxx）が不足しているときに出ます。

解決手順

# 型定義パッケージをインストール
npm install --save-dev @types/node
npm install --save-dev @types/react

多くのパッケージは現在、TypeScriptの型定義を本体に含んでいます。しかし古いパッケージや特殊なパッケージでは別途 @types/ パッケージのインストールが必要です。

型定義がない場合の応急処置

すぐに型定義が用意できないとき、プロジェクトに declarations.d.ts ファイルを作成して一時的に宣言できます。

// src/declarations.d.ts
declare module 'some-library' {
  // 必要な型定義を追加
  export function someFunction(arg: string): void;
}

この応急処置について、AIに「declarations.d.ts に型宣言を追加して一時対応したい」と伝えると、適切な型定義を生成してくれます。

バージョン競合エラーへの対処

複数のパッケージが同じ依存パッケージの異なるバージョンを要求するとき、バージョン競合が起きます。

npm error ERESOLVE unable to resolve dependency tree
npm error Could not resolve dependency:
npm error peer react@"^17.0.0" from some-package@2.0.0

診断コマンド

npm ls react
# または
npm dedupe

Antigravity に診断してもらう方法

エラーメッセージ全文を Antigravity のチャットに貼り付け、次のように依頼するのが最も効率的です。

以下のnpmエラーが出ています。package.json を見て
バージョン競合を解決する方法を教えてください。

[エラーメッセージをここに貼り付け]

package.json を開いた状態でこのように聞くと、AIが依存関係ツリー全体を考慮した解決策を提案してくれます。

よくある落とし穴：AIが古いAPIを使ってしまう

「パッケージは見つかるのにエラーになる」というケースで、もう一つよくある原因が「AIが古いバージョンのAPIを使っている」ことです。

例えば、React Query（TanStack Query）は v4→v5 でAPIが大幅に変わりました。AIがv4の書き方でコードを生成しても、v5をインストールしていれば当然エラーになります。

対策：バージョンを明示して依頼する

# 現在使っているパッケージのバージョンを確認
npm list @tanstack/react-query

確認したバージョンをAIに明示して依頼することで、正しいバージョンのAPIを使ったコードが生成されます。

@tanstack/react-query v5.0.0 を使っています。
v5のAPIで以下の処理を実装してください。

再発防止：AGENTS.md でコンテキストを固定する

個別の依頼ごとにバージョンを伝えるのは手間がかかります。プロジェクトルートに AGENTS.md を作成し、主要な依存関係とそのバージョンを記載しておくことで、AIが常に正しい情報をベースにコードを生成するようになります。

# プロジェクト技術スタック
 
## 主要パッケージ
- Next.js: 16.x（App Router使用）
- TypeScript: 5.x（strict mode有効）
- @tanstack/react-query: 5.x
- zod: 3.x
- Prisma: 5.x
 
## パスエイリアス
@/ → src/
 
## 注意事項
- 新規パッケージのインストールは必ずユーザーに確認する
- package.json に存在しないパッケージは使用しない

この設定をしておくだけで、モジュール関連のエラーが大幅に減ります。ビルドやデプロイ時に発生するエラー全般についてはAntigravity ビルド・デプロイエラーのトラブルシューティングも参考にしてみてください。

診断チェックリスト

エラーが出たとき、次の順で確認していくと素早く解決できます。

package.json にそのパッケージが記載されているか
node_modules フォルダが存在するか（なければ npm install を実行）
TypeScriptのパスエイリアス設定が tsconfig.json に正しく記載されているか
エラーに出ているパッケージのバージョンと、実際にインストールされているバージョンが一致しているか
AGENTS.md にプロジェクトの技術スタックが記載されているか

Antigravity のAIは非常に優秀ですが、プロジェクト固有の情報は人間が適切に伝える必要があります。「どのパッケージをどのバージョンで使っているか」をルールファイルに明記しておくことが、パッケージエラーを減らす最も効果的な方法です。まず AGENTS.md の整備から始めてみてください。