开发日常
开发工具篇
AI工具

AI上下文文档与规则文档

# AI 上下文文档与规则文档

AI 编程助手（Claude Code、CodeFree-O、Cursor、Copilot 等）的"项目说明书"，让 AI 自动理解项目规范、技术栈、代码风格，减少重复沟通。

# 一、是什么

这类文件放在项目特定目录下，AI 启动时自动读取，作为理解项目的上下文。

文件名	适用工具	说明
`AGENTS.md`	CodeFree-O、Cursor、通用 Agent	通用规范，多数工具原生支持
`CLAUDE.md`	Claude Code（Anthropic）	Claude Code 专用，格式类似
`.cursorrules`	Cursor	Cursor 早期格式，现已支持 `AGENTS.md`
`copilot-instructions.md`	GitHub Copilot	Copilot 专用
`GEMINI.md`	Gemini Code Assist	Google Gemini 专用

建议：写 AGENTS.md 通用性最好，Claude Code 等工具也会读取。

# 二、为什么需要

问题：AI 每次会话都是"失忆"的，不知道你的项目：

用什么技术栈、什么框架版本
代码风格偏好（缩进、命名、注释）
项目目录结构、核心模块在哪
怎么构建、测试、部署
有哪些"坑"要避免

解决：把这些信息写进 AGENTS.md，AI 每次启动自动加载，省去重复说明。

# 三、层级体系

AI 上下文文档是分层加载的，从上到下，后者覆盖/补充前者。

┌─────────────────────────────────────────┐
│  企业级 (Enterprise)                      │  组织统一规范
├─────────────────────────────────────────┤
│  用户级 (User)                            │  个人偏好
├─────────────────────────────────────────┤
│  项目级 (Project)                         │  项目规范
├─────────────────────────────────────────┤
│  模块级 (Module)                          │  子模块规范
├─────────────────────────────────────────┤
│  本地级 (Local)                           │  本地覆盖（不提交）
└─────────────────────────────────────────┘

1
2
3
4
5
6
7
8
9
10
11

# 3.1 企业级（Enterprise / Organization）

组织统一配置，通常通过 MDM 或全局策略下发，全公司所有员工的所有项目都生效。

# 企业级 AGENTS.md

## 安全红线
- 禁止将密钥、Token 硬编码到代码中
- 禁止使用 eval()、反序列化不可信数据
- 所有外部输入必须校验
- 代码必须通过 SAST 扫描才能合并

## 技术栈限制
- 后端只能用 Java 11 / Spring Boot 2.7
- 前端只能用 Vue 3 + Element Plus
- 数据库只能用 MySQL 8.0

1
2
3
4
5
6
7
8
9
10
11
12

# 3.2 用户级（User）

位置：~/.codefree-o/AGENTS.md 或 ~/.claude/CLAUDE.md

~ 是用户主目录，Windows 下为 C:\Users\<用户名>

跨所有项目，体现个人编码偏好。

# 用户级 AGENTS.md

## 我的偏好
- 回答用中文
- 代码缩进：Java 4空格，前端 2空格
- 不喜欢冗余注释，只在复杂逻辑处加
- 优先使用 Stream API 而非 for 循环
- 变量命名要语义化，禁止 a/b/tmp

## 我的习惯
- 修改代码前先读完整个方法
- 每次改完跑一遍 mvn test
- commit message 用中文
- 不要自动 commit，等我确认

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 3.3 项目级（Project）

位置：项目根目录 /AGENTS.md

项目特定的技术规范、架构约定。

# 项目级 AGENTS.md

## 项目概述
基于 ruoyi-vue-plus 6.0.0-BETA 二开的沉梦点餐后端工程，新增点餐业务模块 ruoyi-ordering，
包含菜品、分类、购物车、订单、地址等管理功能。

## 目录结构
- ruoyi-admin/ — 启动模块，主类 RuoYiApplication
- ruoyi-common/ — 公共模块（core / mybatis / redis / satoken / web 等）
- ruoyi-modules/ — 业务模块（system / demo / ordering / workflow / gen / job / ai）
- ruoyi-api/ — 远程调用 API
- ruoyi-extend/ — 扩展模块

## 构建运行
- mvn clean package -DskipTests
- 启动：运行 ruoyi-admin 模块的 RuoYiApplication 主类
- 访问：http://localhost:8080

## 代码规范
- Controller 返回 R<T>，分页用 R<PageResult<T>>
- 异常抛 ServiceException，全局处理器统一处理
- 数据库操作用 MyBatis-Plus + BaseMapperPlus
- 对象映射用 MapstructUtils.convert()
- 当前用户用 LoginHelper.getUserId() / getUsername()

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# 3.4 模块级（Module / Subdirectory）

位置：子目录中的 AGENTS.md

project/
├── AGENTS.md                    # 项目级
├── ruoyi-modules/
│   └── ruoyi-ordering/
│       └── AGENTS.md            # 模块级：点餐业务专属规范
├── ruoyi-common/
│   └── AGENTS.md                # 模块级：公共模块专属规范
└── ruoyi-admin/
    └── AGENTS.md                # 模块级：启动模块专属规范

1
2
3
4
5
6
7
8
9

模块级示例（ruoyi-modules/ruoyi-ordering/AGENTS.md）：

# ruoyi-ordering 模块规范

## 说明
点餐业务模块，包含菜品分类、菜品、购物车、订单、收货地址等管理功能，
支持管理端和小程序端双端接口。

## 关键类
- OrderServiceImpl — 订单核心逻辑（下单、状态流转、取消）
- DishServiceImpl — 菜品管理逻辑
- AppOrderController — 小程序端订单接口

## 注意
- 订单状态机：待接单(1) → 已接单(2) → 制作中(3) → 已完成(4)，任意非完成状态可转已取消(5)
- 表前缀 fo_，新增表必须用 fo_ 前缀
- 小程序端 Controller 放 controller/app/ 下，路径前缀 /ordering/app/
- 分页必须用 R<PageResult<T>>，不要用 TableDataInfo

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# 3.5 本地级（Local）

位置：/AGENTS.local.md（加入 .gitignore）

个人本地覆盖，不影响团队。

# AGENTS.local.md（不提交）

## 本地环境
- 本地 MySQL 端口 3306，库名 cm-food-ordering，root/123456
- 本地 Redis 端口 6379，密码 123321
- 调试时启动参数加 -Dspring.profiles.active=local

## 临时备注
- 正在重构 OrderController 的取消逻辑，先别动
- 本地测试数据在 /tmp/test-data/ 下

1
2
3
4
5
6
7
8
9
10

# 四、各层级放什么

层级	放什么	不放什么
企业级	安全红线、技术栈限制、合规要求	项目信息
用户级	个人编码习惯、语言偏好	项目信息
项目级	技术栈、目录结构、构建命令	个人偏好
模块级	模块特有约定、关键类说明	通用规范
本地级	本地环境配置、临时备注	团队共享信息

核心原则：

越上层越稳定：企业级/用户级很少改，项目级偶尔改
越上层越通用：企业级管全公司，项目级管一个项目
后者补充前者：下层的规范补充上层，有冲突时看工具实现

# 五、规则文档（Rules）

除了 AGENTS.md 这类上下文文档，还有一类规则文档，用于强制约束 AI 行为。

# 5.1 上下文文档 vs 规则文档

维度	上下文文档 (AGENTS.md)	规则文档 (Rules)
性质	描述性、建议性	强制性、约束性
违反后果	AI 可能忽略	AI 必须遵守
典型内容	项目介绍、技术栈、习惯	安全红线、禁止操作、必检项
加载方式	自动读取	可配置为强制加载

# 5.2 规则文档的几种形式

形式一：嵌入 AGENTS.md 的"禁止"段落

## 禁止事项（强制）
- 禁止修改 pom.xml 的版本号
- 禁止引入新依赖
- 禁止提交 application-local.yml
- 禁止使用 System.out.println

1
2
3
4
5

形式二：独立规则文件

project/
├── AGENTS.md
├── .codefree/
│   └── rules/
│       ├── security.md       # 安全规则
│       ├── code-style.md     # 代码风格规则
│       └── git-rules.md      # Git 提交规则

1
2
3
4
5
6
7

形式三：Skill 中的规则

# backend-dev Skill 中的规则

## 强制检查项
1. 代码生成后必须运行 mvn test
2. 必须通过 SAST 安全扫描
3. 必须人工确认后才能 commit

1
2
3
4
5
6

# 5.3 规则文档示例

安全规则（.codefree/rules/security.md）：

# 安全规则（强制）

## 必检项
- [ ] 无硬编码密钥/Token
- [ ] SQL 参数化查询，无拼接
- [ ] 外部输入已校验（长度、类型、特殊字符）
- [ ] 日志不打印敏感信息（手机号、身份证、密码）
- [ ] 文件上传校验类型和大小
- [ ] 接口有权限校验

## 禁止
- 禁止使用 eval()、exec()
- 禁止反序列化不可信数据
- 禁止 SSRF（外部 URL 请求需白名单校验）

1
2
3
4
5
6
7
8
9
10
11
12
13
14

Git 提交规则（.codefree/rules/git-rules.md）：

# Git 提交规则

## Commit Message 格式
<type>(<scope>): <subject>

type: feat|fix|refactor|test|docs|chore
scope: 模块名
subject: 中文简述

## 禁止
- 禁止直接 push 到 main/master 分支
- 禁止 commit 中包含 .env、application-local.yml
- 禁止一个 commit 包含多个不相关功能

1
2
3
4
5
6
7
8
9
10
11
12
13

# 六、各工具层级对照

层级	CodeFree-O	Claude Code	Cursor	GitHub Copilot
企业级	全局策略	—	—	组织设置
用户级	`~/.codefree-o/AGENTS.md`	`~/.claude/CLAUDE.md`	`~/.cursor/rules`	—
项目级	`./AGENTS.md`	`./CLAUDE.md`	`./.cursorrules` 或 `./AGENTS.md`	`copilot-instructions.md`
模块级	`./sub/AGENTS.md`	`./sub/CLAUDE.md`	—	—
本地级	`./AGENTS.local.md`	`./CLAUDE.local.md`	—	—
规则	Skill / `.codefree/rules/`	—	`.cursor/rules/*.md`	—

# 七、写作原则

# 7.1 简洁高效

# 好
构建：mvn clean package -DskipTests

# 坏
我们项目使用 Maven 作为构建工具，构建时需要先执行 clean 命令清理
target 目录，然后执行 package 命令打包，为了加快速度可以跳过测试...

1
2
3
4
5
6

# 7.2 告诉 AI "怎么做"而非"为什么"

# 好
异常统一抛 ServiceException，全局处理器会处理。

# 坏
我们项目采用了全局异常处理机制，这样做的优点是代码更整洁，
原理是通过 @ControllerAdvice 注解...

1
2
3
4
5
6

# 7.3 标注"不要做什么"非常重要

AI 容易"自作主张"，明确禁止比正面引导更有效：

## 禁止
- 不要添加注释（除非我要求）
- 不要创建 README.md
- 不要自动 commit
- 不要修改配置文件中的端口号

1
2
3
4
5

# 7.4 控制长度

单个文档控制在 100-200 行，不是目录下所有文档加起来。

~/.codefree-o/AGENTS.md              ← 这个文件 100-200 行
project/AGENTS.md                    ← 这个文件 100-200 行
project/ruoyi-modules/ruoyi-ordering/AGENTS.md  ← 这个文件 100-200 行

1
2
3

太长会导致：

单个文件后半部分被"遗忘"（上下文窗口限制）
加载耗时增加
关键信息被淹没

# 7.5 内容太多怎么办

拆分到模块级，而不是把项目级写很长：

# 不好：项目级 AGENTS.md 写了 500 行
project/AGENTS.md  (500行)

# 好：拆分到各模块
project/AGENTS.md                              (100行，只写全局规范)
project/ruoyi-modules/ruoyi-ordering/AGENTS.md (100行，点餐业务专属)
project/ruoyi-common/AGENTS.md                 (100行，公共模块专属)

1
2
3
4
5
6
7

或者引用外部文档：

## 架构设计
详见 ./docs/architecture.md（需要时再读）

1
2

# 八、推荐的文档结构

~/.codefree-o/AGENTS.md              # 用户级：个人偏好
project/
├── AGENTS.md                        # 项目级：项目规范
├── AGENTS.local.md                  # 本地级：本地配置（gitignore）
├── .codefree/rules/
│   └── security.md                  # 规则：安全红线
├── ruoyi-modules/
│   └── ruoyi-ordering/
│       └── AGENTS.md                # 模块级：点餐业务规范
└── ruoyi-common/
    └── AGENTS.md                    # 模块级：公共模块规范

1
2
3
4
5
6
7
8
9
10
11

# 核心原则

越上层越稳定：企业级/用户级很少改，项目级偶尔改
越上层越通用：企业级管全公司，项目级管一个项目
后者补充前者：下层的规范补充上层，有冲突时看工具实现
规则 ≠ 上下文：规则是强制的，上下文是描述性的
别太长：每层控制在 100-200 行，太长 AI 会"失忆"

# 学习参考

Claude Code 官方文档：Memory - Claude Code Docs (opens new window)
Cursor 规则文档：Rules for AI - Cursor Docs (opens new window)
AGENTS.md 通用规范：agents.md - GitHub (opens new window)
Claude Code 记忆管理：CLAUDE.md 最佳实践 (opens new window)

上次更新: 2026/7/24 16:59:26

← Qoder Cli操作教程 lombok注解使用小结→