docs: 新增 AI 助手快速上手指南（面向开发者）

- 开工准备、常用指令模板、GitNexus 速查 - AGENTS.md 精简原则和检查清单 - 目录结构速查
2026-06-08 13:17:05 +08:00
parent 8b2de75b5f
commit d4a3bd5847
1 changed files with 145 additions and 0 deletions
@@ -0,0 +1,145 @@
+# AI 助手使用指南（开发者手册）
+
+> 本文档面向**开发者**，帮助你高效指挥 AI 助手完成开发任务。
+> 不是给 AI 读的——AI 的规则在仓库根目录的 `AGENTS.md` 中。
+
+---
+
+## 一、开工前准备
+
+### 1. 确认 AI 已读取规则
+
+让 AI 读一遍 `AGENTS.md`，确认它了解自己的身份和边界：
+
+> "读一下 AGENTS.md，确认你了解当前项目的规则"
+
+### 2. 更新文档子模块
+
+```bash
+git submodule update --remote
+```
+
+全局技能、规范、GitNexus 指南都在 `docs/` 子模块里，保持最新。
+
+### 3. 更新 GitNexus 索引
+
+```bash
+npx gitnexus analyze
+```
+
+索引过期会导致 AI 无法准确分析代码影响，建议每次开工前跑一次。
+
+---
+
+## 二、常用指令
+
+以下是你可以直接发给 AI 的指令模板。
+
+### 代码探索
+
+| 你想做什么 | 发给 AI |
+|-----------|---------|
+| 理解某个功能怎么运作 | "支付订单创建流程是怎么走的？" |
+| 查看某个类的所有调用者 | "PayOrderServiceImpl 被哪些地方调用了？" |
+| 了解项目整体架构 | "帮我梳理下支付模块的结构" |
+
+### 代码修改
+
+| 你想做什么 | 发给 AI |
+|-----------|---------|
+| 新增功能 | "在支付渠道中新增一个 XX 渠道" |
+| 修复 Bug | "支付回调偶尔会重复处理，帮我排查" |
+| 重构代码 | "PayOrderService 太大了，帮我拆分" |
+| 重命名 | "把 PayOrderServiceImpl 的 createOrder 方法改名为 createPayOrder" |
+
+### 工单处理
+
+| 你想做什么 | 发给 AI |
+|-----------|---------|
+| 读取工单 | "看下 #3 号工单" |
+| 处理工单 | "处理一下 #3 号工单的需求" |
+| 跨仓库提需求 | "支付需要框架新增一个 XX 工具，帮我提个 Issue 给 rui-framework" |
+| 查看未关闭工单 | "看下当前仓库有哪些未关闭的 Issue" |
+
+---
+
+## 三、GitNexus 速查
+
+AI 通过 GitNexus 知识图谱理解代码。以下是你可能用到的操作：
+
+### 常用场景
+
+| 场景 | 你可以说 |
+|------|---------|
+| 修改前评估影响 | "改 PayOrderServiceImpl 会不会影响其他地方？" |
+| 查看变更范围 | "帮我检查下改了哪些东西" |
+| 理解执行流 | "退款流程是怎么走的，从头到尾画一下" |
+| 查找代码 | "项目里哪里处理了支付回调？" |
+
+### 索引维护
+
+```bash
+# 重新分析代码库（建议每天或大改动后执行）
+npx gitnexus analyze
+
+# 查看索引状态
+npx gitnexus status
+```
+
+---
+
+## 四、精简 AGENTS.md
+
+AGENTS.md 是 AI 的规则文件，应该保持精简。以下原则供你维护时参考：
+
+### 分类原则
+
+| 类型 | 放哪里 | 举例 |
+|------|-------|------|
+| AI 必须遵守的硬规则 | `AGENTS.md` | 禁止改框架、修改前必须 impact 分析 |
+| AI 需要的技能/知识 | `docs/ai-skills/` | Gitea API 用法、Nacos 配置规范 |
+| 通用编码规范 | `docs/standards/` | 命名规范、数据库规范 |
+
+### 检查清单
+
+- [ ] 同一件事有没有在多处重复？→ 只保留一处
+- [ ] 有没有把代码示例写进规则？→ 代码示例是技能，不是规则
+- [ ] 编码规范是否指向了全局文档？→ 不在本仓库重复
+- [ ] 仓库名、路径是否正确？→ spring-ai 已改为 rui-framework
+- [ ] GitNexus 段落是否精简？→ 只保留规则和资源表
+
+### 典型精简操作
+
+**删除技能混入规则：**
+- Feign/REST 代码示例 → AI 已知，不需要教
+- 工单路由表 → 已在 `docs/ai-skills/gitea-api.md`
+
+**合并重复项：**
+- "仓库职责" + "允许范围" → 合并为"项目结构"+"只允许修改"
+- GitNexus Always/Never 6 条 → 合并为 4 条规则
+
+---
+
+## 五、目录结构速查
+
+```
+docs/                           # 全局文档（rui-docs submodule）
+├── ai-skills/                  # AI 技能库
+│   ├── quickstart.md           # 👈 你在这里
+│   ├── gitea-api.md            # Gitea API + 工单路由规则
+│   ├── issue-workflow.md       # 工单处理流程
+│   ├── commit-standards.md     # 提交规范
+│   ├── nacos-config-rules.md   # Nacos 配置规范
+│   ├── menu-config.md          # 菜单配置规范
+│   └── gitnexus/               # GitNexus 技能（6个）
+├── standards/                  # 通用规范
+│   ├── coding-standards.md     # 编码规范
+│   ├── API设计规范.md
+│   └── 数据库设计规范分析.md
+├── backend/                    # 后端文档
+│   ├── guides/                 # 操作指南
+│   ├── design/                 # 设计文档
+│   ├── specs/                  # 规格说明
+│   └── templates/              # 文档模板
+└── frontend/                   # 前端文档
+```