模块 1：SDLC 生产力提升 75 分钟¶

您的第一次真正的 Antigravity CLI 会话。 本模块涵盖了核心的日常工作流——理解代码、重构、生成测试和审查更改——以及如何使用插件扩展 CLI 以适应您团队的工具链。

1.0 — 首次交互式会话 5 分钟¶

在你的研讨会项目目录中启动 Antigravity CLI：

cd agy-cli-field-workshop
agy

你将进入交互式提示词界面。尝试：

> What files are in this project and what does each one do?

观察 agy 如何读取你的工作区 —— 它会索引 git 仓库，读取文件内容，并结合上下文进行响应。这是自动的：无需配置，也无需事先编写提示词。

1.1 — 代码理解 10 分钟¶

模式：修改前先解释 — 在修改代码之前先理解它。

练习：梳理陌生的代码库¶

# -i seeds the session with an initial prompt and stays interactive
agy -i "Give me a high-level architecture overview of this project. What are the main components and how do they connect?"

然后进行交互式跟进：

> Which file handles the entry point?
> What external dependencies does this project have?
> Are there any obvious code smells or tech debt?

1.2 — 重构 10 分钟¶

模式：提议、审查、应用 — 永远不要应用你没有阅读过的更改。

练习：定向重构¶

agy

> I want to refactor the error handling in this project. First, show me all the places where errors are currently caught or returned — don't change anything yet.

审查发现的问题。然后：

> Now propose a refactored version of [specific function] using a consistent error handling pattern. Show me the diff before applying.

只有在阅读了提议的更改后才进行应用。

权限模型¶

agy 具有一个 3 级权限模型，用于控制其处理工具审批的方式：

使用 /permissions 斜杠命令查看或更改当前级别。你也可以在 settings.json 中设置细粒度的规则：

{
  "permissions": {
    "allow": ["command(git)", "read_file"],
    "deny": ["command(rm -rf)"]
  }
}

📖 完整详情：权限文档 · 严格模式文档

1.3 — 测试生成 10 分钟¶

模式：测试现有代码 — 为真实代码生成测试，而不是假设的代码。

练习：生成单元测试¶

agy

> Look at [specific function or file]. Generate a comprehensive unit test suite for it. Include happy path, edge cases, and error conditions. Use the testing framework already in this project.

然后：

> Run the tests and fix any that fail.

1.4 — 代码审查 10 分钟¶

模式：提交前审查 — 在每次推送之前，将 agy 作为高级审查员使用。

练习：审查你的更改¶

# Stage some changes (or use an existing branch)
git add -p

# Start agy and review what's staged
agy

> Review my staged changes for: (1) correctness, (2) security issues, (3) missing test coverage, (4) anything that would block a PR. Be direct — don't soften findings.

无头变体（用于脚本）¶

# Review changes non-interactively — useful in pre-commit hooks or CI
git diff --cached | agy --print "Review these changes. Flag any bugs, security issues, or missing tests. Output as markdown."

1.5 — 使用 AGENTS.md 的项目上下文 5 分钟¶

模式：持久化上下文 — 告诉 agy 一次，它会在每个会话中记住。

agy 在会话开始时读取上下文文件。在项目根目录下创建一个：

cat > AGENTS.md << 'EOF'
# Project Context

This is a Node.js REST API built with Express and TypeScript.

## Key Conventions
- Language: TypeScript (strict mode, no `any`)
- Testing: Jest with 80% coverage minimum; run `npm test` to validate
- Style: ESLint + Prettier; run `npm run lint` before committing
- DO NOT modify `src/db/migrations/` — those are append-only
- DO NOT use `console.log` in production code; use the `logger` utility

## Architecture
Three-layer: `routes/` → `services/` → `repositories/`. All DB access goes through the repository layer. External HTTP calls go through `src/clients/`.

## Common Commands
- `npm run dev` — start local dev server on :3000
- `npm test` — run full test suite
- `npm run db:migrate` — apply pending DB migrations
EOF

现在启动一个新会话：

agy --print "What do you know about this project?"

agy 会自动将你的 AGENTS.md 整合到随后的每个会话中。

其他上下文来源¶

除了 AGENTS.md，agy 还会加载：

• .agents/rules.md（或 .agents/rules/*.md）— 作为系统提示词指令注入的项目级规则。将这些用于硬性要求，例如“永远不要删除迁移文件”或“始终使用 TypeScript 严格模式”。
• .gemini/ — 为了与 Gemini CLI 兼容，agy 会在读取 .agents/ 的同时读取 .gemini/ 目录。
• ~/.gemini/config/rules.md — 应用于所有会话的全局规则。

📖 完整详情：规则与工作流文档

示例代理定义（在 samples/agents/ 中）¶

1.6 — 交互式导航 5 分钟¶

模式：终端熟练度 — 了解让 agy 会话变得快捷的快捷键。 📖 完整参考：使用 Antigravity CLI

关键斜杠命令¶

📖 完整斜杠命令参考：CLI 功能

快速提示¶

📖 完整快捷键参考：使用 Antigravity CLI

1.7 — 使用插件扩展 15 min¶

模式：自带工具链 — 插件为 agy 添加技能、MCP 服务器、代理和规则。一次安装，在每个会话中均可使用。

Antigravity CLI 的插件系统有一个独特之处：它可以导入您已经在 Gemini CLI 中安装的插件 — 无需重新安装或重新配置。您现有的投入得以延续。

查看已激活的插件¶

agy plugin list

显示每个插件的名称、来源、导入日期和组件（技能、命令、mcpServers、代理）。

从 Gemini CLI 导入¶

agy plugin import gemini

agy 会扫描您本地的 Gemini CLI 安装，发现所有已安装的插件，并将其组件暂存到 ~/.gemini/antigravity/ 中。输出：

  [ok]    code-review
          ✔ skills      : 3 processed
          ✔ commands    : 2 processed
          - mcpServers  : skipped (not found)
  [ok]    gemini-deep-research
          ✔ commands    : 1 processed
          ✔ mcpServers  : 1 processed
  [skip]  superpowers (already imported)

agy plugin import gemini --force

What Gets Imported¶

Enable / Disable Per-Project¶

Not every plugin is appropriate for every codebase:

# 在此项目中禁用
agy plugin disable gemini-deep-research

# 重新启用
agy plugin enable gemini-deep-research

Plugin Locations¶

Building a Custom Plugin¶

A valid agy plugin needs a plugin.json manifest:

my-plugin/
├── plugin.json          ← 必填
├── mcp_config.json      ← MCP 服务器定义（可选）
├── hooks.json           ← 钩子事件处理程序（可选）
├── skills/              ← SKILL.md 文件（可选）
│   └── my-skill/
│       └── SKILL.md
├── agents/              ← 子代理定义（可选）
└── rules/               ← 规则文件（可选）
    └── my-rules.md

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "我的自定义 agy 插件",
  "components": ["skills"]
}

Validate it before shipping:

agy plugin validate ./my-plugin
# ✔ 插件清单有效

📖 完整参考：插件 · 迁移指南

模块 1 练习¶

下一模块¶

→ 模块 2：遗留代码库现代化 — 严格模式、代理自主入职、子代理，以及作为安全网的 /rewind。