为什么需要规则？

大语言模型在不同对话之间不会保留记忆。规则在提示级别提供持久、可复用的上下文，确保 AI 在生成代码、理解编辑或协助工作流程时获得一致的指导。

常见应用场景

• 编码风格统一：定义团队使用的命名规范、代码格式、注释要求等
• 项目架构指导：说明项目的文件结构、依赖关系、分层架构等
• 技术栈限制：指定使用的框架、库版本、构建工具等
• 测试标准：定义测试框架、覆盖率要求、测试文件位置等
• 团队协作规范：PR 描述模板、commit message 格式、分支命名等

三工具规则层级对比

Cursor 规则详解

文件位置

project/
├── .cursor/
│   └── rules/
│       ├── react-patterns.mdc    # 带frontmatter的规则
│       ├── api-guidelines.md     # 纯markdown规则
│       └── frontend/
│           └── components.md     # 子目录组织
├── AGENTS.md                     # 根目录Agent指令(可选)
└── .cursorrules                  # 旧版(即将废弃)

四种激活方式

Glob 语法详解

完整配置示例

示例1: Always Apply (通用规范)

---
description: "项目通用编码规范"
alwaysApply: true
---

# 编码规范

- 使用 TypeScript 编写所有新文件
- 使用函数式组件和 React Hooks
- 数据库字段使用 snake_case
- API 响应使用 camelCase
- 所有导出函数必须有 JSDoc 注释

示例2: Apply to Specific Files (API规范)

---
description: "API 开发规范，适用于 src/api 目录"
alwaysApply: false
globs: ["src/api/**/*.ts", "src/routes/**/*.ts"]
---

# API 开发规范

- 使用 RESTful 命名约定
- 所有端点必须有错误处理中间件
- 返回格式: { success: boolean, data?: T, error?: string }
- 参考 @src/api/template.ts 作为模板

示例3: Apply Intelligently (按需判断)

---
description: "单元测试规范。当用户请求编写测试、test、jest、vitest相关内容时应用此规则。"
alwaysApply: false
---

# 测试规范

- 使用 Vitest 作为测试框架
- 测试文件放在 __tests__ 目录
- 命名格式: {filename}.test.ts
- 每个函数至少3个测试用例: 正常、边界、异常

用户规则 (全局)

在 Cursor Settings → Rules 中设置，适用于所有项目:

请以简洁风格回复。避免不必要的重复。
使用中文回复技术问题。
优先使用函数式编程范式。

团队规则 (Team/Enterprise)

通过 Cursor Dashboard 管理，对所有团队成员生效:

• 立即启用: 创建后即时生效
• 强制执行: 成员无法关闭
• 优先级最高: Team → Project → User

GitHub Copilot 指令详解

三种指令类型

Repository-wide 指令

# Project Overview

This is a React + Node.js web application.

## Tech Stack
- Frontend: React 18, TypeScript, Tailwind CSS
- Backend: Node.js, Express, PostgreSQL
- Testing: Jest, React Testing Library

## Coding Standards
- Use semicolons at the end of statements
- Use single quotes for strings
- Use function-based React components
- API responses follow { success, data, error } format

Path-specific 指令

---
applyTo: "src/api/**/*.ts,src/services/**/*.ts"
---

# Backend Development Rules

- Use dependency injection pattern
- All database queries must use parameterized statements
- Implement proper error handling with custom error classes
- Log all API requests with request ID

Glob 语法示例

excludeAgent 配置

控制指令适用于哪些 Agent:

---
applyTo: "**"
excludeAgent: "code-review"
---
这些指令只会被 Copilot Coding Agent 读取，
Code Review 功能不会使用。

个人指令 (Personal Instructions)

在 GitHub.com Copilot Chat 中设置，适用于所有仓库:

1. 打开 Copilot Chat
2. 点击左下角头像 → Personal Instructions
3. 添加个人偏好指令

Antigravity 规则详解

两层规则体系

激活方式

在规则面板中可配置:

• Manual: 通过 @rule-name 手动激活
• Always On: 始终应用
• Model Decision: 根据描述由模型判断
• Glob: 文件匹配模式激活

配置示例

# Coding Standards

- Use Bazel for managing Java dependencies
- JavaScript: double quotes and tabs
- Track work items in Jira
- All commits must reference a ticket number

@ 文件引用

在规则中使用 @filename 引用其他文件:

遵循 @/docs/api-spec.md 中定义的 API 规范。
参考 @templates/service.ts 作为服务模板。

为什么需要命令/工作流？

命令将常用的操作序列打包成可复用的模板，避免每次都输入相同的提示词。这不仅提高了效率，还确保了团队成员使用统一的最佳实践。

常见应用场景

• 代码审查：/code-review 自动执行代码质量检查清单
• 创建 PR：/create-pr 生成标准格式的 Pull Request
• 运行测试：/test-and-fix 运行测试并自动修复失败的用例
• 安全审计：/security-audit 检查常见安全漏洞
• 部署流程：/deploy 按步骤执行生产环境部署
• 新功能搭建：/setup-feature 初始化新功能的文件结构

三工具命令对比

Cursor Commands

文件位置

• 项目: .cursor/commands/*.md
• 全局: ~/.cursor/commands/*.md
• 团队: Dashboard 管理

# Code Review Checklist

审查当前文件:
1. 检查错误处理是否完整
2. 验证输入参数校验
3. 评估性能影响
4. 检查安全问题
5. 提出改进建议

使用: 在聊天中输入 /code-review

Copilot Prompt Files

启用方式

文件位置

所有 IDE 使用相同的文件位置：.github/prompts/*.prompt.md

文件格式

---
agent: 'agent'
description: 'Generate a clear code explanation with examples'
---

Explain the following code in a clear, beginner-friendly way:

Code to explain: ${input:code:Paste your code here}
Target audience: ${input:audience:Who is this for?}

Please provide:
* A brief overview of what the code does
* Step-by-step breakdown of the main parts
* Common use cases

触发方式

文件引用语法

• Markdown link: [index](../../web/index.ts)
• #file 语法: #file:../../web/index.ts
• 输入变量: ${input:name:placeholder}

Antigravity Workflows

文件位置

• 项目: .agent/workflows/*.md

Turbo 自动执行注解

示例：单步自动执行

---
description: 部署到生产环境
---

1. 运行测试确保通过
// turbo
2. npm test

3. 构建生产版本
// turbo
4. npm run build

示例：全部自动执行

---
description: 快速测试流程
---
// turbo-all

1. npm install
2. npm test
3. npm run lint

为什么需要技能？

Skills 是一种可移植、受版本控制的知识包，用于教会 Agent 如何执行特定领域的任务。与规则不同，技能更侧重于“如何做”而不是“遵循什么”。

Rules vs Skills 的关键区别

常见应用场景

• Web 测试技能：封装 Playwright/Cypress 测试最佳实践
• 代码审查技能：定义完整的审查清单和输出格式
• 数据库迁移技能：封装数据库 schema 变更流程
• API 设计技能：包含 RESTful 或 GraphQL 设计规范
• 文档生成技能：自动生成 API 文档、README 等

技能目录与触发方式

Copilot 技能详解 (2025年12月 GA)

文件位置

project/
└── .github/
    └── skills/
        └── my-skill/
            ├── SKILL.md        # 主指令文件 (必需)
            ├── scripts/        # 辅助脚本 (可选)
            └── examples/       # 参考实现 (可选)

SKILL.md 格式

---
name: web-testing
description: Web应用测试技能。当用户请求编写E2E测试、Playwright、Cypress相关内容时使用。
---

# Web Testing Skill

## When to Use
- 编写端到端测试
- 配置 Playwright/Cypress
- 测试 Web 表单交互

## Instructions
- 使用 Playwright 作为默认测试框架
- 测试文件放在 tests/e2e/ 目录
- 每个页面一个测试文件

触发方式

Copilot 会根据用户的提示和 SKILL.md 的 description 自动判断是否加载技能，无需手动触发。

Cursor 技能触发详解

自动发现

Cursor 启动时自动扫描技能目录，将可用技能注册到 Agent。

触发方式

Antigravity 技能激活

当 Agent 执行任务时，会根据 SKILL.md 的 description 判断是否需要使用该技能。你也可以通过 view_file 工具主动查看技能文件来激活它。

激活流程

1. 将技能文件夹放入 .agent/skills/
2. 确保包含 SKILL.md 文件
3. Agent 根据任务上下文自动加载

SKILL.md 标准格式

---
name: code-review
description: 代码审查技能。当用户请求review、audit、检查代码质量时使用。
---

# Code Review Skill

## When to Use
- 用户请求代码审查
- PR 合并前检查
- 代码质量评估

## Review Checklist
1. **正确性**: 代码是否按预期工作？
2. **边界情况**: 错误条件是否处理？
3. **风格**: 是否符合项目规范？
4. **性能**: 有无明显低效？

## Output Format
提供逐行注释，使用 markdown 格式输出。

技能目录结构

.agent/skills/my-skill/
├── SKILL.md        # 主指令文件 (必需)
├── scripts/        # 辅助脚本 (可选)
│   └── helper.py
├── examples/       # 参考实现 (可选)
│   └── sample.ts
└── resources/      # 模板资源 (可选)
    └── template.md

为什么需要子智能体？

子智能体解决了两个核心问题：上下文窗口限制和串行执行效率。复杂任务可以拆分给多个专业化的子代理并行处理，而不占用主会话的上下文空间。

关键优势

• 上下文隔离：每个子代理有独立的上下文窗口，耗时的调研任务不会占用主会话空间
• 并行执行：同时启动多个子代理，在代码库不同部分并行工作
• 专业能力：为子代理配置特定领域的提示词、工具和模型
• 可复用：自定义子代理可在多个项目之间复用

常见应用场景

• 代码库分析：将不同模块分配给多个子代理并行分析
• 验证代理：独立验证已完成的工作是否符合预期
• 测试生成：后台生成测试，主会话继续其他工作
• 文档生成：保持上下文隔离，不污染主对话窗口
• 安全审计：专业的安全审计员子代理检查漏洞

三工具对比

Copilot Custom Agent 配置

---
name: test-specialist
description: 专门编写和优化测试用例
---

You are a testing specialist focused on:
- Writing comprehensive unit tests
- Improving test coverage
- Optimizing test performance

Always use Jest with TypeScript.
Follow AAA pattern: Arrange, Act, Assert.

Antigravity Browser Subagent 触发详解

Copilot Custom Agent 调用示例

1. 创建 Agent 文件

---
name: doc-writer
description: 专门编写技术文档和 README
---

You are a documentation specialist.

## Responsibilities
- Write clear README files
- Create API documentation
- Generate usage examples

## Style Guidelines
- Use headings for structure
- Include code examples
- Write concise explanations

2. 在 Chat 中调用

@doc-writer 请为这个项目生成 README.md

Cursor Subagent 使用场景

• 代码库分析: 将不同模块分配给多个 Subagent 并行分析
• 测试生成: 主 Agent 继续对话，Subagent 后台生成测试
• 文档生成: 保持上下文隔离，不污染主对话窗口

为什么需要 Mentions？

AI 需要精确的上下文才能给出准确的回答。Mentions 让你能够快速将文件、代码片段、整个代码库或外部文档加入到对话上下文中。

常见应用场景

• 引用文件：@file 让 Agent 看到指定文件的完整内容
• 引用代码片段：@Code 引用特定函数或类，比整个文件更精确
• 搜索代码库：@codebase 让 Agent 在整个项目中搜索相关代码
• 查阅文档：@docs 让 Agent 查阅框架/库的官方文档
• 引用规则：@rule-name 手动触发特定规则

三工具 @ 引用对比

为什么需要 MCP？

MCP 作为 AI 与外部工具之间的桥梁，无需手动复制粘贴上下文（如数据库 schema、日志等），Agent 可以直接读取并操作这些资源。

核心能力

• 上下文资源：AI 可以读取连接的 MCP 服务器的数据（如数据库 schema、构建日志等）
• 自定义工具：MCP 允许 Agent 执行安全的操作（如创建 Linear issue、搜索 Notion 等）

常见应用场景

• 数据库集成：连接 PostgreSQL/MongoDB，编写 SQL 时自动获取正确的表名和字段
• 项目管理：集成 Linear/Jira，自动创建 issue 或更新状态
• 设计系统：集成 Figma，直接获取设计稿信息
• 知识库：集成 Notion，搜索团队文档和最佳实践
• 云服务：集成 Firebase/Supabase/Stripe 等云服务

配置方式对比

Cursor MCP 配置

项目级配置

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_URL": "postgresql://user:pass@localhost:5432/db"
      }
    }
  }
}

全局配置

在 ~/.cursor/mcp.json 中配置，对所有项目生效。

Copilot MCP 配置

VS Code 项目级配置

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxx"
      }
    }
  }
}

VS Code 全局配置

在 settings.json 中添加 MCP 配置，或通过 GitHub.com 仓库设置界面配置。

Antigravity MCP Store

支持的一键安装服务:

• GitHub
• Firebase
• Supabase
• Neon
• MongoDB
• Redis
• Notion
• Linear
• Figma
• Stripe
• BigQuery
• Prisma