多仓 Java 项目如何抽离独立 AI 工程：AGENTS / Rules / Skills 实战指南

适用场景：Monorepo 或多业务仓并行、基于 Spring/自研框架 的中后台定制开发、团队统一 AI 协同规范。
工具：Cursor（原理同样适用于 Codex CLI、Claude Code 等支持项目级规则的工具）。

---

一、为什么要抽离独立 AI 工程？

1.1 常见痛点

痛点	表现
配置碎片化	每人一套 Prompt，产出质量参差不齐
知识难沉淀	优秀实践留在聊天记录，新人无法复用
多仓难协同	商品、寻源、审批分属不同 Git 仓，AI 缺少全局上下文
污染业务库	AI 配置与业务代码混在一起，MR 噪音大

1.2 解决思路

把「人的经验结构化」，单独维护一个 AI 工程，业务仓通过软链引用。

1.3 能力等级对照（简版）

等级	特征	本方案目标
L1 辅助	单次问答、局部生成	—
L2 协同	项目级上下文、Rules、跨文件开发	本文落点
L3 原生	全流程工作流、可量化收益、团队治理	后续演进

---

二、独立 AI 工程长什么样？

2.1 推荐目录结构

workspace-root/
├── {project}-ai-workspace/          # 独立 AI 工程（可单独 Git 管理）
│   ├── AGENTS.md                    # Agent 总入口
│   ├── README.md
│   ├── docs/
│   │   ├── project-map.md           # 项目地图、跨仓调用链
│   │   └── platform-base.md         # 底座原理（如 Trantor 一页纸）
│   └── .cursor/
│       ├── rules/                   # 自动生效的规则 ⭐核心
│       │   ├── 00-workspace-entry.mdc
│       │   ├── 10-dev-standards.mdc
│       │   ├── 15-db-sql.mdc
│       │   └── 20-test-spec.mdc
│       └── skills/                  # 可复用技能包
│           ├── workspace/SKILL.md
│           ├── dev-standards/SKILL.md
│           ├── test-spec/SKILL.md
│           └── db-sql/SKILL.md
│
├── biz-module-a/                    # 业务仓 A
│   ├── AGENTS.md  → 软链
│   └── .cursor/
│       ├── rules/   → 软链
│       └── skills/  → 软链
│
├── biz-module-b/                    # 业务仓 B（结构同上）
└── biz-module-c/

2.2 三类配置的职责（务必分清）

组件	是什么	是否自动	作用
AGENTS.md	项目级 Agent 说明书	⚠️ 部分版本自动识别	仓库地图、跨域链路、协作约定
Rules	.mdc 规则文件	✅ 每条对话自动（alwaysApply）	硬约束：语言、分层、先分析再改代码
Skills	SKILL.md 技能包	⚠️ 由 Rule @ 引用或手动 @	详细 SOP：编码规范、测试清单、SQL 规范

最佳实践结论：关键约束写进 Rules，详细说明放 Skills，总览放 AGENTS.md。不要指望 Settings 里 “Skills” 面板——项目级 SKILL.md 通常不会显示在那里。

---

三、AGENTS / Rules / Skills 怎么用？

3.1 加载机制（一张图看懂）

3.2 AGENTS.md — 写什么？

定位：5 分钟能读完的项目总览，给 Agent「看地图」。

建议包含：

1. 业务仓列表与职责（表格）
2. 技术栈与分层约定（如 Model → Func → View）
3. 关键词 → 仓库 分流表
4. 跨域调用链（改代码必查）
5. 协作红线（先分析再改、DB 只读等）

示例结构（脱敏）：

# 电商中台 AI 协同开发

## 仓库地图
| 仓库 | 职责 |
|------|------|
| biz-item | 商品域 |
| biz-sourcing | 寻源域 |
| biz-workflow | 审批域 |

## 开发顺序
模型(BO) → 逻辑(Func) → 视图(XML/TS)

## 跨域链路
寻源定标 → CreateAgreementFunc（sourcing 调 item）

3.3 Rules — 怎么写才自动生效？

Rules 放在 {project}-ai-workspace/.cursor/rules/，扩展名 .mdc。

总入口 Rule（必须 alwaysApply）

---
description: 工作区总入口
alwaysApply: true
---

# 项目 AI 协同（自动生效）

## 仓库
- biz-item：商品域
- biz-sourcing：寻源域

## 开发顺序
模型 → Func → 视图

## 协作
- 中文回复；先定位仓库再改代码
- 未说「帮我改」则先分析
- 数据库默认只读

@../../AGENTS.md
@../skills/workspace/SKILL.md

文件类型 Rule（匹配时注入）

---
description: Java/XML 开发规范
globs:
  - "**/*.java"
  - "**/*.xml"
  - "**/*.ts"
alwaysApply: false
---

- Func：@Function 接口 + @FunctionImpl 实现
- 改 BO 字段必须同步视图 Field

@../skills/dev-standards/SKILL.md

验证 Rules 已加载

Cursor → Settings → Rules，应看到：

• 工作区总入口（Always Apply）
• Java/XML 开发规范（按文件类型）

看不到 → 检查业务仓 .cursor/rules 软链是否存在（见第四节）。

3.4 Skills — 什么时候需要手动 @？

场景	是否自动	说明
日常单仓改代码	❌ 不必 @ Skill	00-workspace-entry 已 @ workspace skill
写 Java/XML	❌ 不必 @	10-dev-standards 已 @ dev-standards skill
联调验收清单很细	✅ 建议 @test-spec/SKILL.md	内容长，手动 @ 更稳
跨仓改多个模块	✅ 建议 @project-map.md	Func 索引不在 alwaysApply 里

Skills 面板显示 “No Skills Yet” 是正常的——那是 Cursor UI 里另一套 Skill；项目里的 SKILL.md 通过 Rules 的 @ 引用 或 聊天里 @ 文件路径 使用。

3.5 日常对话模板

单仓（不用 @）：

实现寻源申请批量导入校验，先分析要改哪些文件，确认后再改。

跨仓（建议 @ project-map）：

实现寻源定标后生成价格协议，涉及 biz-sourcing 和 biz-item。
@docs/project-map.md
先梳理调用链，确认后再改。

新需求（建议 @ PRD）：

@AGENTS.md @biz-item/docs/需求说明.md
按规范实现品牌授权审批流程。

---

四、软链接：最佳实践的核心

4.1 为什么用软链？

方式	优点	缺点
每仓复制一份	简单	很快分叉，无法维护
只加 ai-workspace 到工作区	多仓时可用	单开业务仓时 Rules 不生效
业务仓软链 ai-workspace	单一数据源；单仓/多仓都生效	需一次性配置

4.2 软链配置命令（Linux / macOS）

在业务仓根目录执行（路径按实际调整）：

# 进入业务仓 A
cd biz-module-a

# 确保 .cursor 目录存在
mkdir -p .cursor

# 软链 rules 和 skills（单一数据源）
ln -sfn ../{project}-ai-workspace/.cursor/rules .cursor/rules
ln -sfn ../{project}-ai-workspace/.cursor/skills .cursor/skills

# 软链 AGENTS.md 到仓库根
ln -sfn ../{project}-ai-workspace/AGENTS.md AGENTS.md

# 验证
ls -la .cursor/
ls -la AGENTS.md

期望输出示例：

.cursor/rules  -> ../ecommerce-ai-workspace/.cursor/rules
.cursor/skills -> ../ecommerce-ai-workspace/.cursor/skills
AGENTS.md      -> ../ecommerce-ai-workspace/AGENTS.md

4.3 Windows 注意点

• 优先在 WSL 或 Git Bash 中创建软链
• 或使用 mklink /D（需管理员权限）
• 团队统一用 Git 时，软链会随仓库提交；Windows 同事克隆后需确认链接有效

4.4 多仓工作区（可选增强）

除软链外，可将 {project}-ai-workspace 与各业务仓一并加入 Cursor 工作区：

File → Add Folder to Workspace → 保存为 xxx.code-workspace

软链解决「单仓打开」；多仓工作区解决「同时浏览多模块代码」。两者建议同时使用。

---

五、从零搭建流程（可照抄）

Step 1：创建独立工程

mkdir -p ecommerce-ai-workspace/{docs,.cursor/{rules,skills/workspace}}

Step 2：最小可用文件清单

优先级	文件	说明
P0	AGENTS.md	仓库地图
P0	.cursor/rules/00-workspace-entry.mdc	alwaysApply
P1	docs/project-map.md	跨仓 Func 索引
P1	.cursor/rules/10-dev-standards.mdc	globs 匹配代码文件
P2	.cursor/skills/*/SKILL.md	详细规范
P2	docs/platform-base.md	底座原理一页纸

Step 3：业务仓批量挂软链

for repo in biz-module-a biz-module-b biz-module-c; do
  mkdir -p "$repo/.cursor"
  ln -sfn "../ecommerce-ai-workspace/.cursor/rules" "$repo/.cursor/rules"
  ln -sfn "../ecommerce-ai-workspace/.cursor/skills" "$repo/.cursor/skills"
  ln -sfn "../ecommerce-ai-workspace/AGENTS.md" "$repo/AGENTS.md"
done

Step 4：验收清单

• Cursor Settings → Rules 能看到 Always Apply 规则
• 只打开 biz-module-a 单仓，Rules 仍生效
• 发起对话不写 @，Agent 能说出正确仓库名
• 跨仓需求 @ project-map.md 后能列出上下游 Func
• 说「先分析」时不会直接改文件

---

六、Rules / Skills / @ 关系速查

问题	答案
每次对话会自动带 AGENTS 吗？	会（通过 alwaysApply Rule 里的 @AGENTS.md）
跨仓会自动带 project-map 吗？	不会，需手动 @ 补强
Skills 设置页为空正常吗？	正常，项目 Skill 走文件 + Rule 引用
必须每次 @ AGENTS 吗？	不必，Rule 已自动引用

---

七、团队治理建议

7.1 版本管理

• {project}-ai-workspace 单独 Git 仓库 或 monorepo 子目录均可
• 业务仓软链指向相对路径，克隆后路径结构需保持一致
• AI 配置变更走 MR Review，与业务代码分离

7.2 安全脱敏

Rules / AGENTS 中禁止写入：

• 数据库账号密码、VPN、内网 IP
• 客户真实名称、合同信息
• 未脱敏的生产数据样例

数据库类 Rule 建议写明：默认只读，写操作需人工授权。

7.3 迭代节奏

触发	更新哪里
新模块上线	AGENTS.md + project-map.md
编码踩坑	dev-standards skill
联调漏测	test-spec skill
新底座版本	platform-base.md

7.4 向 Level 3 演进（可选）

• 增加 hooks：保存后自动 mvn compile
• PR 模板：要求填写 AI 辅助范围与验证项
• 量化：需求周期、回滚率、AI 参与文件数

---

八、常见问题 FAQ

Q1：只把 ai-workspace 加进工作区，不配软链行吗？

单开业务仓时 Rules 可能不加载。软链是更稳的方案。

Q2：AGENTS.md 和 Rules 重复了怎么办？

AGENTS 写「地图」；Rules 写「硬约束」+ @ 引用 AGENTS。允许少量重复（如仓库列表写在 Rule 正文里作兜底）。

Q3：Codex / Claude Code 能用吗？

目录结构通用：AGENTS.md + rules/ + skills/。具体文件名按各工具文档微调（如 .codex/rules）。

Q4：和「Vibe Coding」有什么区别？

Vibe Coding 靠临时 Prompt；本方案把经验 文件化 + 自动注入，产出更稳定、可团队复用。

---

九、总结

1. 独立 AI 工程 = 配置与业务代码分离，单一数据源。
2. Rules 是自动生效的核心；AGENTS 是总览；Skills 是详细 SOP。
3. 业务仓软链 保证单仓/多仓都能加载同一套规则。
4. 单仓不用 @；跨仓建议 @ project-map；复杂场景再 @ PRD / test-spec。
5. 在 Cursor Settings → Rules 里能看到 Always Apply，说明链路已通。

---

附录：项目可替换名词表

本文通用名	你可替换为
{project}-ai-workspace	ecommerce-ai-workspace
biz-module-a	商品域仓库名
biz-module-b	寻源域仓库名
Model → Func → View	类似MVC三层架构
logicFunction	{moduleKey}_XxxFunc

---

如果本文对你有帮助，欢迎收藏。有问题可在评论区交流「Rules 不生效」「软链在 Windows 失效」等具体场景，便于补充踩坑篇。