AI 助手配置生效指南

本文档详细说明如何让 AI 助手规范文档真正生效,以及如何在不同工具中配置和验证。

🎯 核心概念

这些文档的性质

docs/ai/agents/ 目录下的文件（GEMINI.md、CLAUDE.md、AGENTS.md）是：

• ✅ 参考文档 - 供开发者阅读的项目规范
• ✅ 知识库内容 - 会显示在 VuePress 网站上
• ❌ 不是自动生效的配置 - AI 工具不会自动读取这些文件

如何让规范生效？

要让 AI 助手遵循这些规范,需要将内容配置到对应工具的设置中。每个工具的配置方式不同。

🔧 各工具配置方法

1. Google Gemini（Antigravity）

配置方式说明

Gemini 通过 User Rules 机制加载项目规范：

1. 位置: 在 Gemini 的设置中配置 "Memory" 或 "Custom Instructions"
2. 格式: 将 GEMINI.md 的内容复制到配置中
3. 生效: 每次对话时自动加载

具体配置步骤

1. 打开 Gemini 设置
2. 找到 "Memory" 或 "Custom Instructions" 选项
3. 将 docs/ai/agents/GEMINI.md 的内容粘贴进去
4. 保存设置

验证配置是否生效

方法 1: 直接询问

你能告诉我这个项目的主要技术栈是什么吗？

如果 Gemini 回答 "VuePress 2.x、Vue 3、Vite、vuepress-theme-hope",说明规范已生效。

方法 2: 测试编码规范

帮我创建一个新的文档文件

观察 Gemini 是否：

• 自动添加 frontmatter
• 从 H2 开始使用标题
• 使用项目规定的格式

方法 3: 检查系统提示

在对话中,Gemini 的系统提示会显示加载的 user_rules,你可以看到类似内容：

<user_rules>
<MEMORY[GEMINI.md]>
...
</MEMORY[GEMINI.md]>
</user_rules>

2. Anthropic Claude

配置方式 A: Claude Desktop（推荐）

Claude Desktop 支持项目级配置：

步骤 1: 创建配置文件

在项目根目录创建 .claude/project.json：

{
  "name": "OmniStack",
  "description": "VuePress 技术知识库项目",
  "instructions": "请参考 docs/ai/agents/CLAUDE.md 中的项目规范"
}

步骤 2: 引用文档

在对话中使用 @ 符号引用：

@docs/ai/agents/CLAUDE.md

配置方式 B: Claude Web 版

Web 版需要在每次对话时手动引用：

我正在开发一个 VuePress 项目,请先阅读以下规范：

[粘贴 CLAUDE.md 的内容]

现在请帮我...

验证 Claude 配置

测试文档创建：

帮我在 docs/ai/ 目录下创建一个新文档

检查 Claude 是否：

• 添加了正确的 frontmatter
• 遵循了标题层级规范
• 使用了项目的代码风格

3. Cursor

配置步骤

Cursor 使用 .cursorrules 文件：

创建配置文件

在项目根目录创建 .cursorrules：

# OmniStackHub 项目规范

请严格遵循以下规范进行开发：

## 项目信息
- 项目类型: VuePress 2.x 知识库
- 主要技术: Vue 3 + Vite + vuepress-theme-hope

## 文档规范
1. 所有 Markdown 文件必须包含 frontmatter
2. 使用 title 字段定义标题,正文从 H2 开始
3. 标题前后必须有空行
4. 代码块必须指定语言类型

## 配置文件规范
1. 使用 CommonJS 格式 (module.exports)
2. 2 空格缩进,单引号字符串
3. 更新侧边栏时同步更新导航栏

详细规范请参考: docs/ai/agents/AGENTS.md

Cursor 会自动读取此文件

验证 Cursor 配置

测试代码补全：

1. 创建新的 .md 文件
2. 输入 --- 并按 Tab
3. 观察 Cursor 是否自动补全正确的 frontmatter 格式

4. GitHub Copilot

配置步骤

创建 .github/copilot-instructions.md：

# GitHub Copilot 项目指南

## 项目概述

本项目是基于 VuePress 2.x 的技术知识库。

## 编码规范

### Markdown 文档

- 必须包含 frontmatter (title, date, category, tag)
- 正文从 H2 (`##`) 开始
- 标题前后保留空行
- 代码块必须指定语言

### JavaScript 配置

- 使用 CommonJS 格式
- 2 空格缩进
- 单引号字符串
- 保留尾随逗号

## 重要提醒

更新 sidebar 时必须同步更新 navbar！

详细规范: docs/ai/agents/AGENTS.md

验证 Copilot 配置

测试代码建议：

在 config.js 中添加新配置时,观察 Copilot 的建议是否符合项目风格。

5. 其他 AI 工具

Codeium 配置

在项目根目录创建 .codeium/config.json：

{
  "instructions": "参考 docs/ai/agents/AGENTS.md 中的项目规范"
}

Tabnine 配置

在设置中添加项目描述和规范链接。

Amazon CodeWhisperer 配置

在 IDE 设置中配置项目上下文。

✅ 验证清单

通用验证方法

无论使用哪个 AI 工具,都可以通过以下方式验证配置是否生效：

测试 1: 询问项目信息

这个项目使用什么技术栈？

期望回答: VuePress 2.x、Vue 3、Vite、vuepress-theme-hope

测试 2: 文档创建

帮我创建一个关于 Docker 的文档

检查点:

• ✅ 是否添加了 frontmatter
• ✅ 是否包含 title、date、category、tag
• ✅ 正文是否从 H2 开始
• ✅ 代码块是否指定了语言

测试 3: 配置修改

帮我在侧边栏添加一个新分类

检查点:

• ✅ 是否同时更新了 navbar
• ✅ 是否使用了正确的格式（2 空格、单引号）
• ✅ 是否添加了注释说明

测试 4: 规范理解

在这个项目中,我应该如何命名文件？

期望回答: 使用小写字母和连字符,避免中文文件名

🔄 文档内容调整建议

当前文档存在的问题

问题 1: 内容重复

GEMINI.md、CLAUDE.md、AGENTS.md 有大量重复内容

建议: 保留 AGENTS.md 作为主文档,其他文档只包含特定工具的配置说明

问题 2: 缺少配置示例

没有说明如何在各工具中实际配置

建议: 添加具体的配置步骤（本文档已补充）

问题 3: 验证方法不明确

用户不知道如何确认配置是否生效

建议: 添加验证清单（本文档已补充）

推荐的文档结构

docs/ai/agents/
├── README.md           # 导航页（保持现状）
├── AGENTS.md           # 通用规范（主文档,所有工具共用）
├── HOW-TO-USE.md       # 配置和验证指南（本文档）
├── GEMINI.md           # Gemini 特定配置（简化,只保留差异部分）
└── CLAUDE.md           # Claude 特定配置（简化,只保留差异部分）

📋 快速配置指南

新项目快速配置

1. 选择你的主要 AI 工具
2. 按照上述对应章节配置
3. 使用验证清单测试
4. 根据需要调整配置

多工具协作

如果你同时使用多个 AI 工具：

1. 创建统一的规范文件 (.cursorrules)
2. 在各工具中引用此文件
3. 保持规范的一致性

🚨 常见问题

Q1: 为什么配置后 AI 还是不遵循规范？

可能原因

• 配置文件路径错误
• 配置格式不正确
• 工具需要重启
• 规范描述不够明确

解决方法

1. 检查配置文件是否在正确位置
2. 验证配置文件语法
3. 重启 IDE 或 AI 工具
4. 使用更具体的规范描述

Q2: 不同 AI 工具给出的建议不一致怎么办？

原因分析

各工具对规范的理解可能有差异

解决方法

1. 使用更明确的规范描述
2. 提供具体的代码示例
3. 在规范中标注"必须"和"建议"

Q3: 如何更新已配置的规范？

更新步骤

1. 修改 docs/ai/agents/ 下的文档
2. 更新各工具的配置文件
3. 重启工具使配置生效
4. 重新验证

📚 相关资源

• README.md - 文档导航
• AGENTS.md - 通用项目规范
• GEMINI.md - Gemini 配置指南
• CLAUDE.md - Claude 配置指南

---

创建日期: 2026-02-04
最后更新: 2026-02-04
维护团队: OmniStack