💡 进阶技巧：分类管理

如果你的规则很多，可以把它们拆分成多个文件放在 `knowledge` 目录下，Antigravity 会读取该目录下所有的 Markdown 文件：

  • `frontend-rules.md` (放代码规范)
  • `company-api-docs.md` (放公司的 API 文档，方便随时调用)
  • `ui-design-system.md` (放设计系统的配色和字体规范)

这样，无论你在哪里，AI 都随身携带着你的"前端开发百科全书"

第一步：创建你的"前端规范"文件

在这个 `knowledge` 文件夹里，你可以创建任意数量的 `.md` (Markdown) 文件。建议创建一个名为 `frontend-rules.md` 的文件，专门存放你的前端开发铁律。

文件内容示例（你可以直接复制并修改）：

```markdown
1# 前端开发核心规范
2
3## 1. 技术栈偏好
4- 框架: 始终优先使用 React (Next.js App Router)。
5- 语言: 必须使用 TypeScript，严禁使用 `any` 类型。
6- 样式: 必须使用 Tailwind CSS。禁止使用原生 CSS 文件或 styled-components。
7- 图标: 优先使用 `lucide-react`。
8
9## 2. 代码风格
10- 组件: 使用函数式组件和 Hooks。
11- 命名: 文件使用 kebab-case (如 `user-card.tsx`)，组件使用 PascalCase。
12- 结构: 保持组件单一职责，一个文件只导出一个主要组件。
13
14## 3. UI/UX 原则
15- 响应式: 所有布局必须默认移动端优先 (Mobile First)。
16- 交互: 按钮和链接必须有 `hover` 状态反馈。
17- 无障碍: 图片必须包含 `alt` 属性，表单输入必须关联 `label`。
18
19## 4. 禁止事项
20- ❌ 禁止使用 jQuery。
21- ❌ 禁止使用内联样式 `style="..."`。
22- ❌ 禁止在组件中硬编码文字内容。
```

🚀 验证生效

配置完成后，重启 Antigravity 客户端（如果它正在运行）。

你可以通过以下方式验证是否生效：

  1. 随便打开一个项目（或者新建一个空项目）。
  2. 在对话框输入："帮我写一个登录框"。
  3. 观察结果
    • 如果 AI 自动使用了 React + TypeScript。
    • 如果 AI 自动使用了 Tailwind CSS 类名。
    • 如果 AI 自动考虑了 移动端适配。

那么恭喜你，你的全局 Knowledge 已经成功"附体"到 AI 身上了！

第二步：接口文档，变成了 AI 随时能查阅的"随身笔记"

这个文件其实就是把你那些原本要反复复制粘贴的接口文档，变成了 AI 随时能查阅的"随身笔记"。

它的核心目的只有一个：让 AI 在不联网、不看 Swagger 的情况下，也能精准地写出符合你后端要求的 API 调用代码。

一个高质量的 `company-api-docs.md` 通常包含以下 4 个核心板块。你可以直接参考这个模板来填充你们公司的实际接口信息：

📋 通用配置板块

这部分告诉 AI 请求的基础信息，避免它每次都问你"接口地址是多少"或者"Header 要带什么"。

```markdown
1## 1. 基础配置
2- Base URL: `https://api.your-company.com/v1\`
3- 认证方式: Bearer Token (JWT)
4- 通用请求头:
5 - `Content-Type`: `application/json`
6 - `Authorization`: `Bearer `
7- 通用响应结构:
8 所有接口返回的数据都包裹在一个标准结构中：
9 ```json
10 {
11 "code": 200, // 200表示成功，非200表示业务错误
12 "msg": "success", // 错误信息
13 "data": { ... } // 实际数据载荷
14 }
```

```markdown
1
2### 📚 核心数据模型板块
3不要把所有字段都写上去，只写高频复用的实体。这能防止 AI 瞎编字段名（比如把 `userName` 写成 `username`，导致前端报错）。
4
5```markdown
6## 2. 核心数据类型
7### 用户
8- `id`: string - 用户唯一标识 (UUID)
9- `username`: string - 登录用户名
10- `email`: string - 邮箱
11- `role`: enum - 角色 ('admin', 'editor', 'viewer')
12- `status`: enum - 状态 ('active', 'banned')
13
14### 商品
15- `sku`: string - 库存单位编码
16- `price`: number - 价格 (单位: 分，不是元！)
17- `stock`: number - 库存数量
```

🔌 高频接口板块

这是最有价值的部分。只记录最常用的接口，或者逻辑最复杂的接口。

格式建议：使用类似 Swagger 的简洁写法，或者直接贴 curl 示例。

```markdown
1## 3. 常用接口定义
2
3### 获取用户列表 (分页)
4- URL: `GET /users`
5- 参数:
6 - `page`: number (默认 1)
7 - `pageSize`: number (默认 10)
8 - `role`: string (可选，筛选角色)
9- 返回示例:
10 ```json
11 {
12 "code": 200,
13 "data": {
14 "list": [ ...用户数组... ],
15 "total": 100
16 }
17 }
```

创建订单

  • URL: `POST /orders`

  • 请求体

    ```json
    1{
    2 "userId": "string",
    3 "items": [
    4 { "sku": "string", "count": "number" }
    5 ]
    6}
    ```

  • 特殊逻辑: 创建订单前必须检查库存，如果库存不足直接返回 code 4001。

```markdown
1
2### ⚠️ 业务逻辑与坑点板块
3这是 AI 绝对不知道的"隐形知识"。比如某些字段虽然叫 `price`，但其实是"分"不是"元"；或者某些状态流转的特殊规则。
4
5```markdown
6## 4. 业务规则与注意事项
7- 金额处理: 所有涉及金额的字段（price, totalAmount）后端返回的都是整数（分），前端展示时必须除以 100。
8- 日期格式: 后端所有时间字段都是 Unix 时间戳 (毫秒)，不是字符串。
9- 图片地址: 接口返回的 `avatar` 只是相对路径，前端需要拼接 CDN 域名 `https://cdn.your-company.com`。
10- 状态码:
11 - `401`: Token 过期，需跳转登录。
12 - `4001`: 库存不足。
13 - `4002`: 优惠券不可用。
```

📌 总结：怎么写才好用？

  1. 只写"热"数据：不要把你公司几百个接口全贴上去，AI 会看晕。只贴你每天开发都要用的那 10-20 个核心接口。
  2. 保持更新：如果后端改了字段（比如把 `userName` 改成了 `nickname`），记得同步更新这个文件。
  3. 格式清晰：AI 喜欢结构化的数据，用 Markdown 的列表和代码块排版，它理解得最快。

把这个文件放进全局 `knowledge` 目录后，你下次只要说："帮我写个获取用户列表的函数"，AI 就会自动知道要请求 `/users`，要处理分页，还要把金额除以 100。

第三步：UI 设计系统规范 ui-design-system.md

本文件定义了项目的全局视觉规范。所有前端代码生成必须严格遵循以下变量和原则，以确保 UI 的一致性。

1. 设计令牌

所有样式必须使用 Tailwind CSS 的 `extend` 配置或标准工具类，禁止使用硬编码的十六进制颜色或像素值。

色彩系统

  • 主色调: `primary-500` (#3B82F6) - 用于主要按钮、激活状态、链接。

  • 功能色

    • `success-500` (#10B981) - 成功提示、完成状态。
    • `warning-500` (#F59E0B) - 警告提示、待处理状态。
    • `danger-500` (#EF4444) - 错误提示、删除操作。

  • 中性色

    • 背景: `gray-50` (浅色模式背景), `gray-900` (深色模式背景)。
    • 文本: `gray-900` (主标题), `gray-600` (正文), `gray-400` (次要文本/占位符)。

  • 边框: `gray-200` (默认分割线), `gray-300` (输入框边框)。

排版系统

  • 字体家族: Inter, system-ui, sans-serif.

  • 字号

    • 超大标题: `text-4xl` (2.25rem) - 页面主标题。
    • 大标题: `text-2xl` (1.5rem) - 卡片标题。
    • 正文: `text-base` (1rem) - 标准内容。
    • 小字: `text-sm` (0.875rem) - 辅助说明、图注。

  • 字重

    • 粗体: `font-bold` (700) - 强调。
    • 中等: `font-medium` (500) - 按钮、标题。
    • 常规: `font-normal` (400) - 正文。

间距与布局

  • 基础单位: 4px (Tailwind 默认单位)。

  • 常用间距

    • 紧凑: `p-2`, `p-4` (组件内部填充)。
    • 标准: `p-6`, `p-8` (卡片、容器填充)。
    • 宽松: `gap-4`, `gap-6` (元素间距)。

  • 圆角

    • 小元素: `rounded` (4px) - 按钮、标签。
    • 容器: `rounded-lg` (8px) - 卡片、模态框、输入框。
    • 全屏: `rounded-full` - 头像。

阴影与层级

  • 卡片阴影: `shadow-sm` (默认), `shadow-md` (悬浮/悬停)。

  • 模态框阴影: `shadow-xl`。

  • 层级

    • 下拉菜单: `z-10`。
    • 模态框: `z-50`。
    • 提示条: `z-50`。