Quickstart

第一次使用 Gemini CLI，不要直接让它重构项目。官方 quickstart 会带你安装、认证、配置和发起提示词；真实项目里更稳的顺序是：先只读理解，再让它提出计划，再限定一个文件写入，最后用测试或 diff 验收。

1. 最小启动流程

npm install -g @google/gemini-cli
gemini

启动后完成认证，然后进入一个低风险 Git 仓库或练习目录。第一条提示词不要要求改文件：

请只读分析这个项目，不要修改任何文件。
输出：
1. 主要目录和入口文件。
2. 你会优先阅读的 5 个文件。
3. 这个项目最可能的测试命令。
4. 你现在还不确定的问题。

这条提示词同时验证三件事：Gemini CLI 能不能看到项目、能不能区分事实和推测、能不能遵守“不要修改文件”。

2. 第一条安全闭环

flowchart TD
    A["启动 gemini"] --> B["只读解释项目结构"]
    B --> C["指定一个小文件让它解释"]
    C --> D["让它提出修改计划"]
    D --> E["确认后只改一个文件"]
    E --> F["运行测试或检查命令"]

    style B fill:#dcfce7,stroke:#22c55e
    style D fill:#fef3c7,stroke:#f59e0b
    style E fill:#fee2e2,stroke:#ef4444

第一条闭环合格，不是看回答有多长，而是看它有没有做到：

• 没有写文件。
• 能指出真实文件和目录。
• 能说出不确定的地方。
• 能给出下一步计划，而不是直接动手。

3. 官方示例能说明什么

官方示例覆盖了几类典型任务：

• 根据图片内容重命名照片。
• clone 并解释一个远程代码仓库。
• 合并两个 CSV。
• 为登录页面写单元测试。

这些例子说明 Gemini CLI 不只会写代码。它能结合文件、命令、Web、模型能力做本地任务。但进入自己的项目时，要把范围收小。

4. 第二轮才允许小范围写入

只读任务跑通后，先用 /init 让 Gemini CLI 自动生成首份 GEMINI.md ——它会扫描你的项目结构和检查命令，写一份初稿放在项目根目录。这一步不算"修改源代码"，只是给 AI 一份长期上下文规则文件，后续你和 AI 沟通项目惯例就不用每次复述。

/init

生成后打开 GEMINI.md 检查一遍，补三件人类才知道的规则：哪些文件禁止触碰、提交时跑哪些验证命令、团队协作边界。详见 GEMINI.md 篇。

然后再选一个低风险文件做写入，例如 README、测试说明、注释或一个小 bug 的测试用例。

只修改 README.md 的安装部分，把命令整理成 npm 和 Homebrew 两种路径。
不要修改其他文件。
改完后先解释 diff，再告诉我建议运行什么检查命令。

写入后立刻检查：

git diff --stat
git diff

如果 Gemini CLI 修改了未指定文件，先停下来，不要继续加新需求。回到提示词、权限、工作目录和上下文边界排查。

5. 第一次不要做什么

• 不要让它“优化整个项目”。
• 不要让它直接处理密钥、账单、账号、生产数据。
• 不要一开始就接 MCP 写操作。
• 不要用 --approval-mode=yolo 处理真实项目。
• 不要在没看 diff 的情况下接受大范围修改。

6. 查用量

官方文档说明可以用：

/stats model

查看当前 session 的 token 用量、quota 信息和模型相关限制。

不要把 /stats model 当成永久配额真相源。不同账号、认证方式、Gemini Code Assist edition、API key、Vertex AI project 都可能影响可用额度。需要费用和 quota 决策时，回到官方 quota and pricing 页面。

第一次成功跑通后，把安装方式、认证方式和测试目录记录下来。后续教程截图如果和读者不同，最常见原因就是这三项不同。

7. 接下来去哪

官方来源

• Gemini CLI Get Started
• Gemini CLI Examples
• Gemini CLI GitHub