---
url: /antigravity/cli-best-practices.md
description: 掌握工作流、提示词架构和本地配置选择，在保持强大控制力的同时最大化 Agent 速度。
---

# Antigravity CLI 最佳实践 (Best practices for Antigravity CLI)

掌握工作流、提示词架构和本地配置选择，在保持强大控制力的同时最大化 Agent 速度。

## 建立验证循环 (Establish verification loops)

确保自主 Agent 进行可靠、正确修改的最有效单一方法，是向 Agent 提供本地验证机制（例如单元测试、构建命令或格式化脚本）。

在要求 Agent 执行代码更改之前：

1. 确保您的工作空间目录准备好测试套件。
2. 如果测试不存在，请先指示 Agent 编写标准测试块。
3. 一旦 Agent 提议代码，指示它运行本地测试命令以验证其工作。
4. 观看 Agent 执行命令并自动根据测试输出进行迭代。

```text
> 在 main.py 中实现功能 X。之后运行 npm test 以验证构建。
```

## 探索、规划，然后执行 (Explore, plan, then execute)

当复杂的更改被划分为不同的探索、规划和执行阶段时，自主本地 Agent 的运行准确率最高。

* **探索**：在编写任何修改之前，要求 Agent 解释目标代码库如何解决特定问题，或者接口在何处定义。
* **规划**：请求实施计划。Agent 将在实施计划产物中列出目标文件、所需的依赖项和逻辑重写。
* **执行**：一旦您批准了结构化计划，指示 Agent 应用这些修改。

```text
> 探索我们的路由器如何解析 `/docs/:page`。写下添加 `/docs/best-practices` 的实施计划。
```

## 丰富您的提示词上下文 (Enrich your prompting context)

为本地 Agent 提供高保真度的指示，以缩小推理边界并尽量减少 Token 开销。

### 目标文件自动补全

在提示框内输入 `@` 以触发交互式路径建议浮层。高亮显示并选择路径会直接将绝对工作空间文件路径导入到您的提示词中。这有助于 Agent 锁定其代码搜索。

### 附加视觉证据

如果调试视觉 UI 问题、渲染错误或前端布局不一致，请捕获屏幕截图或视频录屏，复制并在提示框内按 `ctrl+v` 粘贴以进行附加。Agent 将咨询该媒体文件以诊断问题。

## 配置您的工作空间环境 (Configure your workspace environment)

优化您的本地工作站规则和安全边界，以匹配您的工程流。

### 编写代码库规则文件

在工作空间根目录下创建一个 `GEMINI.md` 或 `AGENTS.md` 文件，以概述特定的目录标准、样式规范、测试命令参数和废弃警告。Agent 会在启动时自动解析这些规则，并在建议更改之前查阅它们。

### 建立结构化权限

根据您的项目风险级别调整 `~/.gemini/antigravity-cli/settings.json` 中的安全屏障：

* **request-review** (默认)：在执行任何写入操作、Bash 命令或远程网络调用之前向您提示。
* **proceed-in-sandbox**：将所有终端执行限制在安全沙箱隔离环中。安全命令将自主执行，而有风险的命令将提示审核。
* **strict**：始终对所有非读取操作进行提示，提供完整的逐行透明度。

```json
{
  "toolPermission": "proceed-in-sandbox",
  "enableTerminalSandbox": true
}
```

## 主动管理 TUI 会话 (Manage TUI sessions proactively)

使用活动的会话导航工具，从工程死胡同中恢复或纠正中间 Agent 循环。

### 尽早纠正方向 (`esc`)

如果您看到 Agent 执行了错误的搜索模式，或编写了偏离您意图的代码，请立即按全局安全出口键 `esc` 中断轮次并重新获得干净的提示框。

### 使用 `/rewind` 回滚历史

如果 Agent 进行了几次连续更改并引入了构建错误，您无需放弃该会话。输入 `/rewind`（或 `/undo`）可将您的对话线程回滚到先前的稳定状态。

### 使用 `/fork` 进行分支实验

如果您不确定最佳实施路径：

1. 达到一个稳定的基线线程。
2. 输入 `/fork` 以启动一个复制的并行会话。
3. 在分支会话中测试您的投机性代码修改。
4. 如果该方法失败，运行 `/resume` 切换回您的稳定主分支。

## 自动化与脚本编写 (Automate and script)

Antigravity CLI 旨在与标准 Shell 管道工具无缝配合运行。

### 运行非交互式命令 (`-p`)

要自动执行快速查询或将 Agent 集成到 Git 钩子中，请使用单次提示标志 `-p`：

```bash
agy -p "审核此 git diff 并起草符合约定的 commit 消息" --cwd $(pwd)
```

### 使用并行子 Agent 进行扇出

对于大规模的扫描或多文件重构，指示主 Agent 生成并发的后台子 Agent。在您继续在主屏幕上工作的同时，Agent 管理器会自动处理后台线程。

## 相关资源 (Related resources)

了解如何配置设置和自定义视觉布局：

* **设置、渲染与键绑定**：自定义键盘快捷键和缓冲区。
* **权限与沙箱**：强制执行文件系统隔离。
* **插件与技能**：创建您自己的自定义斜杠命令。