146 lines
4.7 KiB
Markdown
146 lines
4.7 KiB
Markdown
# 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/ # 前端文档
|
||
```
|