# 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/                   # 前端文档
```