gemini-cli

Gemini CLI

在 Claude Code 工作流中，利用 Gemini 超过 100 万的上下文窗口作为 AI 编程伙伴。

本技能将教会 Claude Code 如何使用 Google 官方 Gemini CLI（gemini 命令），获取第二意见、架构建议、调试帮助和全面的代码审查。内容基于使用官方 CLI 工具进行的生产环境测试。

---

目录

1. 快速入门
2. 何时寻求 Gemini 咨询
3. 安装
4. 模型选择：Flash 与 Pro
5. 3 大使用场景
6. 集成示例
7. 3 大错误及解决方案
8. 何时加载参考资料
9. 生产环境规则

---

快速入门

前置条件：

• 已安装 Gemini CLI（bun add -g @google/gemini-cli）
• 已通过 Google 账号完成身份验证（运行一次 gemini 进行身份验证）

核心命令模式：

# Quick question (non-interactive with -p flag)
gemini -p "Should I use D1 or KV for session storage?"

# Code review with file context
cat src/auth.ts | gemini -p "Review this authentication code for security vulnerabilities"

# Architecture advice using Pro model
gemini -m gemini-2.5-pro -p "Best way to handle WebSockets in Cloudflare Workers?"

# With all files in directory
gemini --all-files -p "Review this auth implementation for security issues"

# Interactive mode for follow-up questions
gemini -i "Help me debug this authentication error"

重要：在自动化脚本中运行非交互式命令时，始终使用 -p 标志。

---

何时寻求 Gemini 咨询

必须咨询（关键场景）

在以下情况下，Claude Code 应自动调用 Gemini：

1. 重大架构决策

   • 示例：“会话存储应该使用 D1 还是 KV？”
   • 示例：“长时间运行的任务应该使用 Durable Objects 还是 Workflows？”
   • 模式：gemini -m gemini-2.5-pro -p "[architectural question]"

2. 涉及安全的代码变更

   • 身份验证系统、支付处理、PII 处理
   • API 密钥/机密管理
   • 模式：cat [security-file] | gemini -m gemini-2.5-pro -p "Security audit this code"

3. 调试陷入僵局（失败 2 次以上）

   • 经过 2 次调试尝试后，错误仍然存在
   • 堆栈跟踪不清晰或存在间歇性错误
   • 模式：gemini -p "Help debug: [error message]" < error.log

4. 大型重构（涉及 5 个以上文件）

   • 核心架构变更、数据库架构迁移
   • 模式：gemini --all-files -m gemini-2.5-pro -p "Review this refactoring plan"

5. 上下文窗口压力（已使用 70% 以上）

   • 即将达到令牌上限，需要将分析工作交给其他工具处理
   • 模式：cat large-file.ts | gemini -p "Analyze this code structure"

可选咨询

6. 不熟悉的技术 — 首次使用某个库/框架
7. 代码审查 — 提交重大变更前

---

安装

1. 安装 Gemini CLI

bun add -g @google/gemini-cli

2. 进行身份验证

gemini

按照身份验证提示关联你的 Google 账号。

3. 验证安装

gemini --version  # Should show 0.13.0+
gemini -p "What is 2+2?"  # Test connection

---

模型选择：Flash 与 Pro

gemini-2.5-flash（默认）

• 速度：约 5–25 秒
• 质量：适用于大多数任务
• 适用场景：代码审查、调试、快速提问
• 成本：较低

gemini -m gemini-2.5-flash -p "Review this function for performance issues"

gemini-2.5-pro

• 速度：约 15–30 秒
• 质量：出色，分析全面
• 适用场景：架构决策、安全审计、大型重构
• 成本：较高

gemini -m gemini-2.5-pro -p "Security audit this authentication system"

快速决策指南

Quick question? → Flash
Security/architecture? → Pro
Debugging? → Flash (try Pro if stuck)
Refactoring 5+ files? → Pro

重要发现：对于同一个问题，Flash 和 Pro 可能给出截然相反的建议（两者都合理，只是优先级不同）。Flash 优先考虑性能，Pro 优先考虑一致性/正确性。详情请加载 references/models-guide.md。

---

3 大使用场景

1. 安全审计

# Audit authentication code
cat src/middleware/auth.ts | gemini -m gemini-2.5-pro -p "
Security audit this authentication middleware. Check for:
1. Token validation vulnerabilities
2. Timing attack risks
3. Error handling leaks
4. CSRF protection
5. Rate limiting
"

2. 架构决策

# Compare technologies with context
gemini -m gemini-2.5-pro -p "
Context: Building Cloudflare Worker with user authentication.

Question: Should I use D1 or KV for storing session data?

Considerations:
1. Session reads on every request
2. TTL-based expiration
3. Cost under 10M requests/month
4. Deployment complexity
"

3. 调试根本原因

# Analyze error logs with context
tail -100 error.log | gemini -p "
These errors started after deploying auth changes. What's the likely root cause?

Context:
- Added JWT validation middleware
- Using @cloudflare/workers-jwt
- Errors only on /api/* routes
"

更多使用场景：加载 references/models-guide.md，了解性能优化、重构计划和代码审查。

---

集成示例

Claude 自动咨询 Gemini

场景：用户提出架构问题

User: "Should I use D1 or KV for storing user sessions?"

Claude (internal): This is an architectural decision. Consult Gemini for second opinion.

[Runs: gemini -m gemini-2.5-pro -p "Compare D1 vs KV for user session storage in Cloudflare Workers. Consider: read/write patterns, cost, performance, complexity."]

Claude (to user): "I've consulted Gemini for a second opinion. Here's what we both think:

My perspective: [Claude's analysis]
Gemini's perspective: [Gemini's analysis]

Key differences: [synthesis]
Recommendation: [combined recommendation]"

关键模式：综合双方观点，而不是直接转发 Gemini 的回复。

---

3 大错误及解决方案

错误 1：未通过身份验证

错误：Error: Not authenticated

解决方案：

gemini  # Follow authentication prompts

错误 2：找不到模型

错误：Error: Model not found: gemini-2.5-flash-lite

原因：模型已弃用或重命名（flash-lite 不存在）

解决方案：仅使用稳定版模型：

gemini -m gemini-2.5-flash -p "Your question"
gemini -m gemini-2.5-pro -p "Your question"

错误 3：命令卡住

原因：需要非交互式操作时却进入了交互模式

解决方案：非交互式命令始终使用 -p 标志

# ✅ Correct
gemini -p "Question"

# ❌ Wrong (will hang waiting for input)
gemini "Question"

了解更多故障排除信息：加载 references/models-guide.md，了解速率限制、大文件上下文问题和性能技巧。

---

何时加载参考资料

在以下情况下加载参考文件：

在以下情况下加载 references/models-guide.md：

• 用户询问 Flash 和 Pro 的区别
• 模型给出了相互矛盾的建议
• 需要详细的性能对比
• 为特定任务类型选择模型
• 想了解模型意见不一致的原因

在以下情况下加载 references/prompting-strategies.md：

• 为 Gemini 编写复杂提示词
• 需要 AI 对 AI 提示词格式模板
• 想提升提示词质量
• 比较新旧提示词编写方法

在以下情况下加载 references/gemini-experiments.md：

• 需要了解测试的历史背景
• 调查边缘情况
• 理解设计决策
• 排查异常行为

注意：helper-functions.md 已过时（引用了旧版 gemini-coach 封装器，而非官方的 gemini CLI）。

---

生产规则

1. 自动化时始终使用 -p

# ✅ Good for scripts
gemini -p "Question"

# ❌ Bad (interactive)
gemini

2. 根据重要程度选择模型

# Architecture/security → Pro
gemini -m gemini-2.5-pro -p "[critical question]"

# Debugging/review → Flash
gemini -m gemini-2.5-flash -p "[general question]"

3. 在提示词中提供上下文

# ✅ Good: Context + Question + Considerations
gemini -p "Context: Building Cloudflare Worker. Question: Best auth pattern? Considerations: 1) Stateless, 2) JWT, 3) <100ms overhead"

# ❌ Bad: Vague
gemini -p "Best auth?"

4. 通过管道传递文件内容进行审查

# ✅ Efficient
cat src/auth.ts | gemini -p "Review for security"

# ❌ Less efficient
gemini -p "Review src/auth.ts"

5. 综合内容，而非直接转发

❌ 错误：直接粘贴 Gemini 的回复

Claude: [runs gemini] "Gemini says: [paste]"

✅ 正确：综合双方的观点

Claude: "I've consulted Gemini for a second opinion:

My analysis: [Claude's perspective]
Gemini's analysis: [Gemini's perspective]
Key differences: [synthesis]
Recommendation: [unified answer]"

6. 妥善处理错误

if output=$(gemini -p "Question" 2>&1); then
  echo "Gemini says: $output"
else
  echo "Gemini consultation failed, proceeding with Claude's recommendation"
fi

---

版本历史

2.1.0（2025-12-15）：

• 优化至不足 500 行（从 Phase 12.5 到 13 的精简）
• 将详细内容提取到 references/
• 添加“何时加载参考资料”部分
• 精简为最重要的 3 个错误和 3 个使用场景

2.0.0（2025-11-13）：

• 为官方 Gemini CLI 完全重写（移除 gemini-coach 封装器）
• 直接 CLI 集成模式
• 更新 gemini CLI v0.13.0+ 的命令示例

1.0.0（2025-11-08）：

• 首次发布，使用 gemini-coach 封装器

---

相关技能

• google-gemini-api - 通过 SDK 集成 Gemini API
• google-gemini-embeddings - 用于 RAG 的 Gemini 嵌入
• google-gemini-file-search - 使用 Gemini 的托管式 RAG

---

许可证

MIT - 查看 LICENSE

---

支持

• 问题反馈：https://github.com/jezweb/claude-skills/issues
• 电子邮件：[email protected]
• 官方 Gemini CLI：https://github.com/google-gemini/gemini-cli