仓库规约文件 AGENTS.md

AGENTS.md 是什么

AGENTS.md 是一种为 AI 辅助研发工具提供规约的文件，相当于为 AI 提供的 Readme。

与 Claude Code 的 CLAUDE.me 定位类似，AGENTS.md 这一名称旨在提供工具无关的通用规约文件规范。各类主流研发工具都原生支持 AGENTS.md 文件的自动识别。

AGENTS.md 本质上是一个普通 markdown 文档，不存在硬性结构化要求。但是遵循一套清晰、一致的规范，能显著提升AI的理解准确性和执行效率。

如何写 AGENTS.md

AGENTS.md 通常放在项目根目录，是专为 AI 编码助手准备的“操作手册”，一般涵盖：

• 项目概览
• 常用命令（构建、运行、测试等）
• 编码规范
• 测试指南
• 安全与边界
• 必要的领域知识

可以看到，AGENTS.md 与 README.md 覆盖内容不可避免的有所交叉。在编写时，应遵循以下原则：

• 面向 AI 而非人类：文本清晰、具体、可执行
• 聚焦例外与领域知识：专注于项目独有的规范（与通用标准不同的部分），以及从代码中无法推断的业务背景或设计决策。
• 链接优于复制：若信息已存在于 README.md 或其它文档中，直接引用链接，不必重复搬运。
• 示例优于解释：对 AI 而言，一个准确的命令或代码片段，胜过一大段文字描述。

建议把AI当作一个刚加入团队的新同事，AGENTS.md 作为“新人上路指南”，手把手带他熟悉工作流程、代码约定和注意事项。

如何创建与维护

快速开始：基于模板分段落填写内容

# AGENTS.md

## 项目概览
[用1-2句话描述项目是什么]

## 常用命令
- 安装依赖: [如 `npm install`]
- 运行测试: [如 `npm test`]
- 启动开发服务器: [如 `npm run dev`]

## 编码规范
- [例如: 使用 ES Module, 遵循 StandardJS]
- [例如: 变量命名使用 camelCase]

## 测试指南
- 测试框架: [如 Jest]
- 运行单个测试: [如 `npm test -- -t "test name"`]

## 安全与边界
- **不要**提交包含密钥的文件。
- **不要**修改 `/legacy` 目录下的代码。

## 领域知识
- XXXXXXX

Claude code 默认提供 /init 命令，可以快速生成 CLAUDE.md，主要包含项目背景信息。可以在在此基础上进行补充

AGENTS.md 应当作为“活文件”。开发者需要在项目演进过程中，根据项目变化与AI具体表现，不断更新和优化其中的信息。

方法论

可以写一个Skill，提供仓库 AGENTS.md 文件的生成：

• 项目概览信息：AI自动探索并总结
• 常用命令、编码规范、测试指南、安全与边界：预置社区通用规范、存量代码分析推断、用户输入补充
• 领域知识：用户提供