Google Antigravity CLI 是一个运行在终端中的 AI 编码代理。它的价值不只是生成几行代码，而是直接围绕现有项目开展工作：读取文件、梳理调用关系、发现问题，并协助完成受约束的重构。
对于 Python 项目，这种工作方式尤其自然。开发者可以把代码、测试和配置留在原来的目录中，通过明确的任务描述让代理先分析、再修改，最后用测试和静态检查验证结果。
从“解释代码”开始，而不是立即改代码
第一次让编码代理接触仓库时，适合先安排只读任务。这样既能确认它是否理解项目，也能避免在上下文不足时产生范围过大的修改。
假设已经按照当前版本的官方说明安装 Antigravity CLI，并且终端中的可执行命令是 antigravity，可以先准备一个最小 Python 项目：
mkdir -p antigravity-demo/tests
cd antigravity-demo
cat > calculator.py <<'PY'
def average(values):
total = 0
for value in values:
total += value
return total / len(values)
PY
cat > tests/test_calculator.py <<'PY'
import pytest
from calculator import average
def test_average():
assert average([2, 4, 6]) == 4
def test_empty_list():
with pytest.raises(ValueError):
average([])
PY
python -m venv .venv
. .venv/bin/activate
python -m pip install pytest
然后在项目根目录启动 CLI：
antigravity
进入交互环境后，可以给出一个严格的只读任务：
阅读 calculator.py 和 tests/test_calculator.py，不要修改任何文件。
请说明：
1. average 函数当前的行为；
2. 哪个测试会失败以及失败原因；
3. 最小修复方案；
4. 需要保留的现有行为。
这里的关键是明确写出“不要修改任何文件”。AI 编码代理通常能够同时分析多个文件，但是否执行修改，应由任务边界决定，而不是让代理自行猜测。
不同版本的 CLI 可能使用不同的启动命令、审批模式或非交互参数。上面的示例假设命令名为
antigravity；实际使用时应以本机版本的antigravity --help为准。
让代码审查产生可执行结果
“帮我看看代码”通常不是一个好任务。它没有说明重点、输出格式和风险偏好，最终容易得到泛泛的建议。
更有效的审查提示应包含四类信息：
- 审查范围，例如只看
calculator.py和对应测试。 - 关注维度，例如正确性、异常处理、类型约束和性能。
- 证据要求，例如引用文件名、函数名和触发条件。
- 修改边界，例如本轮只报告问题，不写文件。
可以这样实践：
请审查 calculator.py 和 tests/test_calculator.py，本轮不要修改代码。
重点检查：
- 空输入和非法输入；
- Python 异常类型是否清晰；
- 测试是否覆盖公开行为；
- 是否存在没有必要的复杂度。
按严重程度输出发现。每条发现必须包含：
- 文件和函数；
- 触发问题的输入；
- 实际结果与期望结果；
- 建议修复方式；
- 建议增加的测试。
如果没有发现问题，请明确说明，并列出仍然存在的测试盲区。
这种提示把“审查”变成了可验证的工程任务。尤其要警惕只有风格建议、没有复现条件的报告。真正值得优先处理的问题，通常能够对应到具体输入、错误行为或维护风险。
用约束控制重构范围
完成分析后，可以让 Antigravity CLI 执行重构，但应明确允许改哪些文件、必须保留哪些行为，以及验收命令是什么。
针对上面的示例，可以使用以下任务：
请修复 average([]) 导致 ZeroDivisionError 的问题。
约束：
- 只允许修改 calculator.py 和 tests/test_calculator.py；
- 空列表必须抛出 ValueError，消息为 "values must not be empty"；
- 非空数字列表的现有结果必须保持不变；
- 为函数增加类型标注和简短文档字符串；
- 不引入第三方运行时依赖；
- 修改完成后运行 python -m pytest -q；
- 最后总结修改过的文件、测试结果和剩余风险。
一种符合这些约束的结果可能是：
from collections.abc import Sequence
def average(values: Sequence[float]) -> float:
"""Return the arithmetic mean of a non-empty sequence."""
if not values:
raise ValueError("values must not be empty")
return sum(values) / len(values)
对应测试可以写成：
import pytest
from calculator import average
def test_average() -> None:
assert average([2, 4, 6]) == 4
def test_empty_list() -> None:
with pytest.raises(ValueError, match="values must not be empty"):
average([])
无论修改由人还是代理完成，都应在本地独立运行验收命令：
python -m pytest -q
python -m compileall -q .
git diff --check
git diff -- calculator.py tests/test_calculator.py
pytest 验证行为，compileall 捕获基础语法和导入问题，git diff --check 检查空白错误，而最后一条命令让开发者逐行确认代理实际改了什么。
把代理权限和任务风险匹配起来
终端代理可能拥有读取文件、写入代码和执行命令的能力，这也意味着它可能接触凭据、删除文件或运行具有副作用的脚本。使用时应把权限控制视为工作流的一部分。
较稳妥的做法包括：
- 在独立 Git 分支中运行代理，开始前确认
git status。 - 先要求只读分析，再批准写入操作。
- 把可修改文件写进提示，不要只说“重构项目”。
- 对数据库迁移、部署、依赖升级和批量删除采用人工审批。
- 不把
.env、云平台密钥或生产数据作为普通上下文提供给代理。 - 要求代理运行测试，但仍由开发者检查命令和测试输出。
- 修改后查看
git diff，不要因为测试通过就跳过代码审查。
还要注意，测试通过并不等于重构正确。如果测试本身遗漏了边界条件，代理可能在不触发失败的情况下改变公开行为。因此，在修改前先让它描述行为和补充测试，往往比直接要求“优化这段代码”更可靠。
一套可重复的采用流程
把 Antigravity CLI 引入日常开发时，可以从低风险任务逐步扩大范围：
- 让代理解释一个小模块及其测试，不允许写文件。
- 要求它输出带复现条件的代码审查结果。
- 选择一个边界清楚的问题，并限制可修改文件。
- 在修改前补充或确认行为测试。
- 运行项目原有的测试、格式化和静态检查命令。
- 检查
git diff，确认没有无关重构、依赖变化或敏感信息泄露。 - 只有在结果稳定后，才把任务扩大到跨模块重构。
终端 AI 编码代理最适合承担的是“边界明确、结果可验证”的工作。给 Antigravity CLI 足够的项目上下文，同时收紧权限、文件范围和验收条件，才能让它真正参与工程流程，而不是只生成看起来合理的代码。