ローカル Gemma 4 が「期待通りに動かない」原因
Gemma 4 を Ollama 経由で Antigravity に接続したのに、コード提案が的外れだったり、日本語の指示を英語で返してきたりします。こんな経験をしたことはないでしょうか。
クラウドの Gemini API は、Google のサーバー側で暗黙のシステムプロンプトが適用されています。一方、ローカルで動かす Gemma 4 には何も設定されていない素のモデルが起動します。つまり、システムインストラクションを自分で書かない限り、モデルは「何の専門家でもない汎用アシスタント」として振る舞います。
ここが見落とされがちなポイントです。同じ質問でも、システムインストラクションの有無で回答の精度と一貫性は劇的に変わります。
システムインストラクションが効く仕組み
Gemma 4 の推論パイプラインでは、入力トークン列の先頭にシステムインストラクションが配置されます。Attention メカニズムにおいて、先頭のトークンは後続のすべてのトークン生成に影響を与えるため、ここに「何をすべきか」を明確に書くことが、出力の方向性を決定づけます。
実際に試すと、次のような差が出ます。
インストラクションなしの場合:
User: TypeScriptでAPIクライアントを書いて
Gemma 4: Sure\! Here's a simple API client...
（英語で返答、エラーハンドリングなし、型定義が曖昧）
インストラクションありの場合:
System: あなたはTypeScriptのシニアエンジニアです。
回答は日本語で行い、コードには必ず型注釈を付けてください。
エラーハンドリングを含め、本番環境で使える品質のコードを書いてください。
User: TypeScriptでAPIクライアントを書いて
Gemma 4: TypeScriptで汎用的なAPIクライアントを実装します。
（日本語で返答、Result型パターン、リトライロジック付き）
この差は、モデルサイズが小さいほど顕著になります。Gemma 4 E2B（12B）では、インストラクションの有無で体感的な品質差が非常に大きく出ます。
Antigravity でシステムインストラクションを設定する3つの方法
方法1: AGENTS.md に記述する（推奨）
プロジェクトルートに AGENTS.md を作成し、エージェント全体の振る舞いを定義します。この方法が最も管理しやすく、チームでの共有にも適しています。
# AGENTS.md
## Role
Senior full-stack engineer specializing in TypeScript and Next.js.
Always respond in the same language as the user's message.
## Code Standards
- Use strict TypeScript with explicit return types
- Handle errors with Result pattern (never throw in library code)
- Write JSDoc comments for exported functions
- Prefer composition over inheritance
## Testing
- Write unit tests alongside implementation
- Use Vitest with happy-path + edge-case coverage
- Mock external dependencies, never real APIs in testsAGENTS.md のポイントは、英語で書いても、ユーザーの入力言語に追従させるルールを明記することです。Gemma 4 はインストラクションの言語に引きずられやすいため、Always respond in the same language as the user's message の一文を入れておくと、日本語での対話が安定します。
方法2: Ollama の Modelfile でベイク（焼き込み）する
モデルレベルでシステムインストラクションを固定したい場合は、Ollama の Modelfile を使います。
# Modelfile
FROM gemma4:12b
SYSTEM """
あなたは経験豊富なソフトウェアエンジニアです。
以下のルールに従ってください：
1. ユーザーの言語で回答する
2. コードには必ずエラーハンドリングを含める
3. パフォーマンスを意識した実装を提案する
4. 不明点があれば推測せず質問する
"""
PARAMETER temperature 0.3
PARAMETER top_p 0.9
PARAMETER num_ctx 8192# カスタムモデルとしてビルド
ollama create gemma4-dev -f Modelfile
# Antigravity のローカルモデル設定でこのモデル名を指定
# Settings → AI Models → Local Model → gemma4-devこの方法は、プロジェクトを横断して同じ設定を使いたい場合に便利です。ただし、AGENTS.md と併用すると指示が二重になるため、どちらか一方に寄せることをおすすめします。
方法3: Antigravity のモデル設定画面から直接入力する
Settings → AI Models → System Instruction フィールドに直接テキストを入力する方法です。手軽ですが、バージョン管理されないため、チーム開発には向きません。個人のプロトタイピングや短期的な実験に使うのがよいでしょう。
効果的なインストラクション設計の5原則
原則1: ロールを具体的に定義する
❌ あいまい: "あなたはプログラマーです"
✅ 具体的: "あなたはTypeScriptとReactに精通したフロントエンドエンジニアです。
Cloudflare Workers上のNext.jsアプリケーション開発を担当しています"
Gemma 4 の 12B モデルでは、ロール定義が曖昧だと回答のばらつきが大きくなります。プロジェクトの技術スタックまで含めて具体的に書くことで、コード提案の的中率が目に見えて上がります。
原則2: 出力フォーマットを明示する
## Response Format
- Start with a one-line summary of the approach
- Show the complete, runnable code (no snippets)
- Explain WHY this approach, not just HOW
- End with potential edge cases to watch for「コードだけ出して」「説明も付けて」のような暗黙の期待は、ローカルモデルには伝わりにくいものです。出力の構造を明示的に書くと、回答のフォーマットが安定します。
原則3: ネガティブ制約を入れる
何をすべきかだけでなく、何をすべきでないかも書きます。
## Constraints
- Do NOT use `any` type in TypeScript
- Do NOT suggest deprecated APIs
- Do NOT skip error handling even in example code
- Do NOT add unnecessary dependenciesGemma 4 はポジティブな指示よりネガティブな制約に強く反応する傾向があります。特に any 型の抑制やエラーハンドリングの強制は、ネガティブ制約で書くと遵守率が高くなります。
原則4: コンテキストウィンドウを意識したサイズにする
Gemma 4 E2B のデフォルトコンテキストは 8,192 トークンです。システムインストラクションが長すぎると、実際のコードや会話に使えるトークン数が減ります。
私の経験では、システムインストラクションは 300〜500 トークン（日本語で 400〜700 文字程度）に収めるのが最適です。それ以上は、AGENTS.md に書いてファイル参照させる方がトークン効率がよくなります。
# インストラクションのトークン数を確認する
echo "あなたのインストラクションテキスト" | ollama run gemma4:12b --verbose 2>&1 | grep "prompt eval"原則5: タスク別にインストラクションを切り替える
すべてを1つのインストラクションに詰め込むより、タスクに応じて切り替える方が効果的です。
# AGENTS.md — タスク別セクション
## When Writing New Code
Prioritize readability and type safety. Add JSDoc for all exports.
## When Reviewing Code
Focus on: security vulnerabilities, performance bottlenecks,
missing edge cases. Be specific about line numbers.
## When Debugging
Ask for the error message first. Reproduce before fixing.
Never suggest changes without explaining the root cause.AGENTS.md にタスク別セクションを設けておくと、Gemma 4 は現在のコンテキストに合ったセクションを自動的に重視する傾向があります。
実測: インストラクション最適化前後の比較
同じプロジェクト（Next.js + TypeScript + Prisma）で、最適化前後の回答品質を10タスクで比較しました。
評価項目と結果:
- 型安全性（any 型の使用回数）: 最適化前 10タスク中6回使用 → 最適化後 0回
- エラーハンドリング: 最適化前 3/10タスクのみ含む → 最適化後 9/10タスク
- 言語一致率（日本語で質問→日本語で回答）: 最適化前 40% → 最適化後 95%
- 初回回答の採用率（修正なしで使えた割合）: 最適化前 20% → 最適化後 60%
特筆すべきは言語一致率の改善です。Always respond in the same language as the user's message の一文を加えるだけで、40%から95%まで跳ね上がりましました。
よくある落とし穴と対処法
落とし穴1: インストラクションが長すぎてコンテキスト溢れ
長いファイルを開いた状態でインライン編集を依頼すると、インストラクション + ファイル内容 + 会話履歴でコンテキストウィンドウが溢れ、回答が途切れます。num_ctx を 16384 に拡張するか、インストラクションを 200 トークン以内に短縮してください。
落とし穴2: 矛盾する指示
「簡潔に回答して」と「詳細な説明を付けて」のような矛盾する指示を入れると、Gemma 4 は回答ごとにどちらかをランダムに選択し始めます。指示の一貫性を常にチェックしてください。
落とし穴3: 日本語のみのインストラクション
Gemma 4 は英語での学習データが明確に多いため、インストラクション自体は英語で書き、「回答言語はユーザーに合わせる」と指定する方が安定します。日本語のみのインストラクションだと、コード内コメントも日本語になるなど、意図しない副作用が出ることがあります。
プロジェクト別テンプレート集
Web アプリ開発用
# AGENTS.md
## Role
Full-stack TypeScript engineer. Tech stack: Next.js 16,
Prisma ORM, Cloudflare Workers, Tailwind CSS.
## Rules
- Respond in the user's language
- Use server components by default, client components only when needed
- All database queries through Prisma with explicit select
- CSS via Tailwind utility classes, no custom CSS files
## Do NOT
- Use `any` or `as` type assertions without justification
- Import from barrel files (use direct path imports)
- Create API routes for data that can be fetched in server componentsモバイルアプリ開発用
# AGENTS.md
## Role
iOS/Android engineer using Swift and Kotlin.
Focus on performance and battery efficiency.
## Rules
- Respond in the user's language
- SwiftUI for iOS, Jetpack Compose for Android
- Follow platform HIG/Material Design guidelines
- Handle offline scenarios in every network call
## Do NOT
- Block the main thread with synchronous operations
- Store sensitive data in UserDefaults/SharedPreferences
- Use force unwrap (\!) in Swift production codeデータ分析・スクリプト用
# AGENTS.md
## Role
Data engineer proficient in Python and SQL.
## Rules
- Respond in the user's language
- Use pandas for tabular data, polars for large datasets
- Type hints on all function signatures
- Include data validation before processing
## Do NOT
- Use mutable global state
- Ignore encoding issues (always specify utf-8)
- Skip null/NaN handling全体を振り返って: 小さな設定で大きな品質差
Gemma 4 をローカルで使う場合、システムインストラクションは「あったらいいもの」ではなく必須の設定です。300〜500 トークンの投資で、回答品質が目に見えて変わります。
最初の一歩は、プロジェクトルートに AGENTS.md を作り、ロール・技術スタック・禁止事項の3つを書くこと。それだけで、ローカル Gemma 4 は「汎用アシスタント」から「プロジェクト専属のシニアエンジニア」に変わります。
Gemma 4 と Antigravity のローカル環境構築がまだの方は、Antigravity × Gemma 4 完全統合ガイドを参考にセットアップしてから、本記事のテンプレートを適用してみてください。