Files

T

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

- 开工准备、常用指令模板、GitNexus 速查
- AGENTS.md 精简原则和检查清单
- 目录结构速查

2026-06-08 13:17:05 +08:00

4.7 KiB

Raw Permalink Blame History

AI 助手使用指南（开发者手册）

本文档面向开发者，帮助你高效指挥 AI 助手完成开发任务。不是给 AI 读的——AI 的规则在仓库根目录的 AGENTS.md 中。

一、开工前准备

1. 确认 AI 已读取规则

让 AI 读一遍 AGENTS.md，确认它了解自己的身份和边界：

"读一下 AGENTS.md，确认你了解当前项目的规则"

2. 更新文档子模块

git submodule update --remote

全局技能、规范、GitNexus 指南都在 docs/ 子模块里，保持最新。

3. 更新 GitNexus 索引

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 会不会影响其他地方？"
查看变更范围	"帮我检查下改了哪些东西"
理解执行流	"退款流程是怎么走的，从头到尾画一下"
查找代码	"项目里哪里处理了支付回调？"

索引维护

# 重新分析代码库（建议每天或大改动后执行）
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/                   # 前端文档

4.7 KiB Raw Permalink Blame History Unescape Escape