/gemini-prompting

name: gemini-prompting
description: Internal guidance for composing Gemini 2.5 Pro/Flash prompts for coding, review, diagnosis, and research tasks inside the Gemini Claude Code plugin
user-invocable: false

Gemini 2.5 Prompting Guide for Coding Tasks

Reference document for writing effective prompts when delegating to Gemini 2.5 Pro or Flash. Covers model selection, thinking mode, context window use, structured output, tool use, and antipatterns.

---

Model Selection

Choose based on task complexity and cost tolerance:

| Model | Use when | Context | Thinking | |---|---|---|---| | `gemini-2.5-pro` | Complex architecture, cross-file refactors, SWE-bench-style tasks, novel algorithm design | 1M tokens | Always on (128–32,768 tokens, default dynamic) | | `gemini-2.5-flash` | Production tasks with good cost/quality balance: reviews, summaries, data extraction, chat | 1M tokens | Dynamic by default (0–24,576 tokens, can disable) | | `gemini-2.5-flash-lite` | High-volume, low-cost: classification, routing, simple translation, triage | 1M tokens | Off by default (512–24,576 tokens) |

**Decision rule:** Default to Flash for most coding assistance. Switch to Pro only when Flash produces shallow or incorrect reasoning on complex multi-step problems. Use Flash-Lite only when cost is the primary constraint and quality requirements are low.

**SWE-bench data point:** Gemini 2.5 Pro scores ~63.8% on SWE-bench Verified with a custom agent setup — comparable to frontier models for real-world GitHub issue resolution.

---

Thinking Mode (Budget Tokens)

Gemini 2.5 models have an internal reasoning phase ("thinking") before responding. You control how many tokens it can spend reasoning.

How to configure (Gemini API)

# Python SDK
from google import genai
from google.genai import types

client = genai.Client()
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Refactor this authentication module...",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(
            thinking_budget=8192  # or -1 for dynamic, or 0 to disable
        )
    )
)

Token budget ranges

| Model | Min | Max | Default | |---|---|---|---| | gemini-2.5-pro | 128 | 32,768 | Dynamic (cannot disable) | | gemini-2.5-flash | 0 | 24,576 | Dynamic (-1) | | gemini-2.5-flash-lite | 512 | 24,576 | 0 (disabled) |

When to use each level

**Disable (budget=0) or minimal:**

• Simple lookups: "What does this function return?"
• Mechanical transforms: format conversion, renaming, boilerplate
• Single-file edits with clear instructions
• When latency is critical

**Medium (512–4096 tokens):**

• Standard code review requests
• "Explain why this is slow"
• Bug diagnosis with provided stack trace
• Multi-file but clearly scoped changes

**High (8192–32,768 tokens) or dynamic (-1):**

• Complex algorithm design or optimization
• Architectural planning across a full codebase
• Debugging non-obvious failures with multiple possible causes
• Code migration or refactoring with implicit constraints
• Writing Python web apps with auth ("verified code generation")

**Cost warning:** High thinking budgets cost significantly more. One practitioner reported auto-mode costing ~37x more than flash-only mode for identical workloads ($6k vs $163/month at scale). Match thinking budget to actual task complexity.

---

Prompt Structure for Coding Tasks

The canonical structure

[Role/persona — optional but effective]

[Context: what exists, what matters]

[Task: specific, scoped, explicit]

[Constraints: what NOT to do, style rules]

[Output format: how to structure the response]

Role setting works well with Gemini

Gemini responds well to role framing. Set it in the system prompt or at the start:

You are a senior Go engineer specializing in performance-critical systems.
You follow idiomatic Go, prefer composition over inheritance, and always
handle errors explicitly rather than panicking.

Task decomposition

Break large tasks into sequential prompts. Do not cram multi-phase work into one prompt.

**Bad:**

Refactor the authentication module, add rate limiting, write tests,
and update the API documentation.

**Good (4 separate prompts):** 1. "Refactor the auth module. Preserve the existing interface exactly." 2. "Add rate limiting middleware. Wire it after the auth middleware." 3. "Write unit tests for the rate limiter. Cover the burst and sustained rate cases." 4. "Update the API docs for the two new rate-limiting headers."

Explicit negation — critical for Gemini

Gemini's most common failure mode: "I Know Better" syndrome — it fixes unrelated code you didn't ask it to touch. Always state what NOT to do:

**Bad:**

Refactor this function to be more efficient.

**Good:**

Refactor this function for efficiency. 
DO NOT change the function signature.
DO NOT modify the input validation logic.
DO NOT add or remove comments.
DO NOT change error return types.

Architecture-first, then implementation

For complex features, establish the design before writing code:

Before writing any code, describe the architecture for adding webhook
support to this service. Cover: data model changes, handler design,
retry strategy, and failure modes. I'll confirm the approach before
you implement.

Incremental generation for large features

For anything generating hundreds of lines, do it in stages:

Generate the HTML structure for the dashboard component first.
Stop after the HTML. I'll review it before we proceed to CSS and JS.

---

Context Window Strategy (1M tokens)

What to include

• All files directly relevant to the task (source, not compiled output)
• Configuration files that affect behavior (tsconfig, pyproject, etc.)
• Interface/type definitions that the code must satisfy
• Existing tests that encode the expected behavior
• The specific error message, stack trace, or failing test out