Google Antigravity CLI 是一个运行在终端中的 AI 编码代理，适合读取、审查和重构 Python 代码。真正值得关注的并不是“让 AI 写出更多代码”，而是如何把代理放进现有工程流程：先限定任务，再检查改动，最后用测试验证结果。
由于来源摘要没有给出具体版本的安装方式和子命令，下面不会假定某个固定 CLI 接口。实际使用前应先执行 antigravity --help，再根据本机版本启动交互会话或提交任务。
从一个有问题的 Python 函数开始
可以先创建一个足够小、能够运行和测试的示例项目。下面的函数混合了数据过滤、折扣计算和结果格式化，正适合用来观察 AI 代理如何阅读与重构代码。
mkdir -p antigravity-python-demo/tests
cd antigravity-python-demo
cat > pricing.py <<'PY'
def calculate_total(items, discount=0):
total = 0
for item in items:
if item["price"] > 0 and item["quantity"] > 0:
total = total + item["price"] * item["quantity"]
if discount > 0:
total = total - total * discount
return round(total, 2)
PY
cat > tests/test_pricing.py <<'PY'
from pricing import calculate_total
def test_calculates_discounted_total():
items = [
{"price": 10.0, "quantity": 2},
{"price": 5.0, "quantity": 1},
]
assert calculate_total(items, discount=0.1) == 22.5
def test_ignores_non_positive_lines():
items = [
{"price": -10.0, "quantity": 2},
{"price": 8.0, "quantity": 1},
]
assert calculate_total(items) == 8.0
PY
python -m pip install pytest
python -m pytest -q
这组测试定义了当前行为，但没有覆盖所有输入边界。例如，discount=2 会产生负数，缺少字段会触发 KeyError，字符串价格也可能导致异常。代码审查的价值就在这里：代理不仅要描述代码“做了什么”，还应指出接口没有明确表达的约束。
把任务拆成读取、审查、重构三轮
先确认本机 Antigravity CLI 暴露了哪些命令：
antigravity --help
随后按帮助信息启动代理，并让它在项目根目录工作。下面是可以直接改造后提交给代理的三组提示词；具体提交方式取决于已安装版本。
第一轮：只读取，不修改
Read pricing.py and tests/test_pricing.py.
Explain the current behavior of calculate_total, including assumptions,
exception paths, and inputs that are not covered by tests.
Do not modify any files.
这一轮的关键约束是 Do not modify any files。先验证代理是否正确理解现有行为，可以避免它在误读接口后直接大规模改写代码。
第二轮：做风险导向的审查
Review pricing.py as production Python code.
Prioritize correctness bugs, ambiguous input contracts, and missing tests.
Report findings with file and line references.
Do not refactor yet.
有效的审查结果应当具体到输入和后果，而不是只给出“提高可读性”之类的泛化建议。例如，它可以追问折扣是否必须位于 0 到 1 之间，以及无效商品行究竟应该忽略还是拒绝。
第三轮：限定范围地重构
Refactor calculate_total to improve type clarity and input validation.
Preserve the behavior covered by existing tests.
Add focused tests for every newly enforced rule.
Keep the public function name unchanged, avoid unrelated edits,
and run the complete test suite after making changes.
Summarize changed files and any compatibility risks.
这个提示词同时规定了行为兼容性、修改范围和验收方式。相比“重构这个文件”，它更容易产生可检查的小型补丁。
不要把代理的总结当成验证结果
代理完成修改后，仍应由开发者检查工作区。Git diff 能揭示它是否改动了任务之外的文件，测试则确认代码至少满足已编码的契约。
git diff -- pricing.py tests/test_pricing.py
python -m pytest -q
python -m compileall -q pricing.py tests
如果项目已经使用 Ruff、Mypy 或其他工具，也应执行仓库原有命令，而不是临时发明另一套规则。例如：
ruff check pricing.py tests/
mypy pricing.py
是否运行后两条命令取决于项目是否已经安装并配置对应工具。AI 代理可能生成看似合理的类型标注，但静态检查器才能判断这些标注是否与项目配置一致。
审阅 diff 时重点检查四件事：公开函数签名是否意外改变，异常类型是否改变，浮点舍入规则是否改变，以及新增测试是否只是在迎合当前实现。对于金额计算，生产系统通常还要评估是否应使用 Decimal；这属于业务决策，不能仅凭代理建议自动替换。
三道自测题
- 为什么读取代码和修改代码最好分成两轮？答案要点：先确认代理理解了现有行为，降低基于错误假设重构的风险。
- 为什么“测试通过”仍不足以证明重构正确？答案要点：测试只覆盖已经编码的场景，未覆盖的兼容性、异常和业务规则仍可能改变。
- 哪一种提示更可执行：“优化这段代码”，还是“保持公开函数名和已有测试行为，补充输入验证及对应测试”？后者，因为它定义了范围、约束和验收标准。
采用时的检查清单
把 Antigravity CLI 当作能够读取和编辑工作区的协作者，而不是可信执行源。首次在仓库中使用时，建议从小模块开始，并坚持以下边界：
- 先运行
antigravity --help，以当前版本的帮助信息为准。 - 在提示词中明确允许读取和修改的文件。
- 审查阶段禁止修改，重构阶段要求小型、聚焦的补丁。
- 修改前后运行同一套测试、静态检查和格式化命令。
- 使用
git diff人工检查接口、异常、依赖和无关改动。 - 不向提示词或工作区暴露密钥、生产数据和不必要的凭据。
- 对金额、安全、权限和数据迁移代码保留更严格的人工审批。
终端 AI 代理最适合缩短“理解代码、形成审查意见、准备候选补丁”这条路径。它可以提高速度，但代码库中的测试、版本控制和人工判断仍然构成最终的质量边界。