From d4a3bd584711e945a8811cbfc405e309784685bb Mon Sep 17 00:00:00 2001 From: pigeon Date: Mon, 8 Jun 2026 13:17:05 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=20AI=20=E5=8A=A9?= =?UTF-8?q?=E6=89=8B=E5=BF=AB=E9=80=9F=E4=B8=8A=E6=89=8B=E6=8C=87=E5=8D=97?= =?UTF-8?q?=EF=BC=88=E9=9D=A2=E5=90=91=E5=BC=80=E5=8F=91=E8=80=85=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 开工准备、常用指令模板、GitNexus 速查 - AGENTS.md 精简原则和检查清单 - 目录结构速查 --- ai-skills/quickstart.md | 145 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 145 insertions(+) create mode 100644 ai-skills/quickstart.md diff --git a/ai-skills/quickstart.md b/ai-skills/quickstart.md new file mode 100644 index 0000000..0a75f68 --- /dev/null +++ b/ai-skills/quickstart.md @@ -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/ # 前端文档 +```