AGENTS.md 文件规范
AGENTS.md 文件提供了一种标准化方案，用于在各类 AI 代码开发工具中配置 AI 智能体的行为。通过该文件，开发者可定义项目专属的指令、编码标准与规范准则，指导 AI 智能体在处理代码库时遵循统一要求。
AGENTS.md 定义
AGENTS.md 用于在软件项目中配置 AI 智能体的行为模式。它是一个存放于项目根目录的轻量级 Markdown 文件，内含面向 AI 代码助手的指令集。目前该标准已获得多款主流 AI 代码工具支持。
可以将 AGENTS.md 理解为面向 AI 智能体的自述文件（README） —— 它明确告知 AI 智能体如何适配特定项目、需遵循哪些编码约定，以及需要遵守的约束条件。
使用 AGENTS.md 的优势
跨工具兼容性： 无需修改即可在多款 AI 代码工具中运行
版本可管控性： 与项目代码一同存储于代码仓库，支持版本追踪
团队协作一致性： 确保团队所有成员的 AI 助手均遵循统一规范
项目定制化适配： 可根据项目独特需求与编码约定进行针对性配置
语法简洁性： 采用纯 Markdown 格式编写，无需掌握特殊语法或配置规则
文件命名与存放路径
项目级 AGENTS.md 文件
需将 AGENTS.md 文件放置在项目根目录下，目录结构示例如下：
my-project/
├── AGENTS.md # 主配置文件（推荐）
├── src/
├── package.json
└── README.md文件命名优先级（按识别顺序排列）：
AGENTS.md（大写复数形式，推荐使用）
AGENT.md（大写单数形式，降级备选）
⚠️ 文件名大小写规则：
文件名必须为全大写格式（AGENTS.md），不支持小写格式（agents.md）。该设计可确保在不同操作系统与开发工具中保持一致性。
子目录级 AGENTS.md 文件
开发者也可在子目录中放置 AGENTS.md 文件，用于定义上下文专属指令，目录结构示例如下：
my-project/
├── AGENTS.md # 根目录级全局指令
├── src/
│ └── backend/
│ └── AGENTS.md # 后端模块专属指令
└── docs/
└── AGENTS.md # 文档模块专属指令在子目录中进行开发时，VJSP 工具会同时加载根目录的 AGENTS.md 与当前子目录的 AGENTS.md 文件。当指令发生冲突时，子目录文件的指令优先级更高。
文件保护机制
在 VJSP 工具中，AGENTS.md 与 AGENT.md 均属于写保护文件，具体规则如下：
未经用户显式授权，AI 智能体不得修改此类文件
工具会弹出确认提示，需用户手动确认后才能执行文件修改操作
该机制可有效防止 AI 智能体误操作导致项目 AI 配置文件被篡改
基础语法与文件结构
AGENTS.md 文件采用标准 Markdown 语法编写，无强制结构要求。但通过标题与列表组织内容，可提升 AI 模型对指令的解析效率与理解程度。
推荐文件结构
# 项目名称
项目的简要描述与核心用途
## 编码风格
- 所有新文件均使用 TypeScript 开发
- 严格遵循 ESLint 配置规范
- 缩进采用 2 个空格
## 架构设计
- 遵循 MVC 设计模式
- 组件代码行数控制在 200 行以内
- 采用依赖注入模式
## 测试规范
- 所有业务逻辑代码均需编写单元测试
- 代码覆盖率需维持在 80% 以上
- 测试框架统一使用 Jest
## 安全规范
- 严禁将 API 密钥或敏感信息提交至代码仓库
- 所有用户输入必须执行合法性校验
- 数据库操作需使用参数化查询语句编写最佳实践
指令明确化： 采用具体可量化的规则，例如 “圈复杂度上限为 10”，避免 “编写高质量代码” 这类模糊表述
示例具象化： 嵌入代码示例，展示错误处理、命名约定或架构设计的标准范式
分类结构化： 将相关规范归类至清晰的标题下（如编码风格、架构设计、测试规范、安全规范）
内容简洁化： 使用项目符号与直述语句，避免冗长段落
维护常态化： 随着项目编码约定的迭代，定期评审与修订文件内容
AGENTS.md 在 VJSP 中的工作机制
文件加载流程
在 VJSP 中启动开发任务时，工具会执行以下操作：
检查项目根目录下是否存在
AGENTS.md或AGENT.md文件若检测到文件，则加载其内容并注入至 AI 智能体的上下文环境
AI 智能体在整个对话交互过程中均遵循文件内的指令要求
修改 AGENTS.md 文件后，新规则将在新建任务中生效（可能需要重启工具）
与其他规则系统的优先级关系
AGENTS.md 与 VJSP 的其他配置系统协同工作，优先级从高到低排序如下：
| 配置类型 | 范围 | 存放路径 | 核心用途 | 优先级 |
|---|---|---|---|---|
| 模式专属自定义规则 | 项目 | .vjsp/rules-{mode}/ | 针对特定开发模式的规则约束 | 1（最高） |
| 自定义规则 | 项目 | .vjsp/rules/ | VJSP 工具专属规则配置 | 2 |
| AGENTS.md 规则 | 项目 | 根目录 / 子目录 | 跨工具兼容的项目级规范 | 3 |
| 全局自定义规则 | 全局 | ~/.vjsp/rules/ | VJSP 工具全局规则配置 | 4 |
| 自定义指令 | 全局 | IDE设置 | 适用于所有项目的个性化偏好 | 5（最低） |
功能启用与关闭
VJSP 默认启用 AGENTS.md 功能。如需关闭，可在 settings.json 配置文件中添加如下参数：
{
"VJSP.useAgentRules": false
}