创建高质量的 AGENTS.md 文件

你是一个代码代理。你的任务是在此仓库的根目录下创建一个完整、准确的 AGENTS.md 文件，该文件遵循 https://agents.md/ 上的公共指南。

AGENTS.md 是一个开放格式，旨在为代码代理提供有效工作所需的上下文和指令。

什么是 AGENTS.md？

AGENTS.md 是一个 Markdown 文件，作为“面向代理的 README”——一个专用的、可预测的位置，用于为 AI 代码代理提供处理项目所需的上下文和指令。它通过包含编码代理需要但可能会使面向人类的 README 变得臃肿的详细技术上下文，来补充 README.md。

关键原则

• 面向代理：包含为自动化工具准备的详细技术指令
• 补充 README.md：不替代面向人类的文档，而是添加代理特定的上下文
• 标准化位置：位于仓库根目录（对于 monorepo，位于子项目根目录）
• 开放格式：使用具有灵活结构的标准 Markdown
• 生态系统兼容性：可与 20 多种不同的 AI 编码工具和代理协同工作

文件结构和内容指南

1. 必要设置

• 在仓库根目录下创建名为 AGENTS.md 的文件
• 使用标准 Markdown 格式
• 无必填字段 – 根据项目需求灵活构建结构

2. 应包含的基本部分

项目概述

• 项目功能的简要描述
• 如果架构复杂，提供架构概述
• 使用的关键技术栈和框架

设置命令

• 安装说明
• 环境设置步骤
• 依赖管理命令
• 数据库设置（如果适用）

开发工作流程

• 如何启动开发服务器
• 构建命令
• 监听/热重载设置
• 包管理器具体说明（npm、pnpm、yarn 等）

测试说明

• 如何运行测试（单元、集成、端到端）
• 测试文件位置和命名约定
• 覆盖率要求
• 使用的特定测试模式或框架
• 如何运行测试子集或专注于特定区域

代码风格指南

• 语言特定的约定
• 代码检查 (linting) 和格式化规则
• 文件组织模式
• 命名约定
• 导入/导出模式

构建与部署

• 构建命令和输出
• 环境配置
• 部署步骤和要求
• CI/CD 流水线信息

3. 可选但推荐的部分

安全考量

• 安全测试要求
• 密钥管理
• 身份验证模式
• 权限模型

Monorepo 说明（如果适用）

• 如何处理多个包
• 跨包依赖
• 选择性构建/测试
• 特定于包的命令

拉取请求指南

• 标题格式要求
• 提交前需要通过的检查
• 审查流程
• 提交消息约定

调试与故障排除

• 常见问题及解决方案
• 日志记录模式
• 调试配置
• 性能考量

示例模板

使用此作为起始模板，并根据具体项目进行定制：

# AGENTS.md

## 项目概述

[项目的简要描述、其目的和关键技术]

## 设置命令

- 安装依赖项：`[包管理器] install`
- 启动开发服务器：`[命令]`
- 为生产环境构建：`[命令]`

## 开发工作流程

- [开发服务器启动说明]
- [热重载/监听模式信息]
- [环境变量设置]

## 测试说明

- 运行所有测试：`[命令]`
- 运行单元测试：`[命令]`
- 运行集成测试：`[命令]`
- 测试覆盖率：`[命令]`
- [特定的测试模式或要求]

## 代码风格

- [语言和框架约定]
- [代码检查规则和命令]
- [格式化要求]
- [文件组织模式]

## 构建与部署

- [构建流程详情]
- [输出目录]
- [特定于环境的构建]
- [部署命令]

## 拉取请求指南

- 标题格式：[组件] 简要描述
- 必须通过的检查：`[代码检查命令]`，`[测试命令]`
- [审查要求]

## 附加说明

- [任何项目特定的上下文]
- [常见陷阱或故障排除技巧]
- [性能考量]

来自 agents.md 的工作示例

这是来自 agents.md 网站的一个真实示例：

# 示例 AGENTS.md 文件

## 开发环境技巧

- 使用 `pnpm dlx turbo run where <项目名称>` 跳转到包，而不是用 `ls` 扫描。
- 运行 `pnpm install --filter <项目名称>` 将包添加到你的工作区，以便 Vite、ESLint 和 TypeScript 可以看到它。
- 使用 `pnpm create vite@latest <项目名称> -- --template react-ts` 快速创建一个带有 TypeScript 检查的 React + Vite 包。
- 检查每个包 package.json 中的 name 字段以确认正确的名称——跳过顶级名称。

## 测试说明

- CI 计划可在 .github/workflows 文件夹中找到。
- 运行 `pnpm turbo run test --filter <项目名称>` 来运行为该包定义的每个检查。
- 从包根目录，你可以直接调用 `pnpm test`。提交前应通过所有测试。
- 要专注于一个步骤，添加 Vitest 模式：`pnpm vitest run -t "<测试名称>"`。
- 修复任何测试或类型错误，直到整个套件变绿。
- 移动文件或更改导入后，运行 `pnpm lint --filter <项目名称>` 以确保 ESLint 和 TypeScript 规则仍然通过。
- 为你更改的代码添加或更新测试，即使没人要求。

## PR 说明

- 标题格式：[<项目名称>] <标题>
- 提交前始终运行 `pnpm lint` 和 `pnpm test`。

实施步骤

1. 分析项目结构 以了解：
   • 使用的编程语言和框架
   • 包管理器和构建工具
   • 测试框架
   • 项目架构（monorepo、单个包等）
2. 识别关键工作流程 通过检查：
   • package.json 脚本
   • Makefile 或其他构建文件
   • CI/CD 配置文件
   • 文档文件
3. 创建全面的部分 涵盖：
   • 所有基本的设置和开发命令
   • 测试策略和命令
   • 代码风格和约定
   • 构建和部署流程
4. 包含具体、可操作的命令，代理可以直接执行
5. 测试指令，确保所有列出的命令按文档说明工作
6. 保持专注于代理需要知道的内容，而不是通用项目信息

最佳实践

• 具体明确：包含确切的命令，而非模糊描述
• 使用代码块：用反引号包裹命令以提高清晰度
• 包含上下文：解释为何需要某些步骤
• 保持最新：随着项目发展更新文件
• 测试命令：确保所有列出的命令实际有效
• 考虑嵌套文件：对于 monorepo，根据需要创建子项目中的 AGENTS.md 文件

Monorepo 考量

对于大型 monorepo：

• 在仓库根目录放置一个主 AGENTS.md 文件
• 在子项目目录中创建额外的 AGENTS.md 文件
• 最接近的 AGENTS.md 文件对于给定位置具有优先权
• 包括包/项目之间的导航技巧

最终说明

• AGENTS.md 可与 20 多种 AI 编码工具协同工作，包括 Cursor、Aider、Gemini CLI 等
• 该格式有意保持灵活性——可根据项目需求进行调整
• 专注于可操作的指令，帮助代理理解和处理你的代码库
• 这是一个动态文档——随着项目的发展而更新它

在创建 AGENTS.md 文件时，优先考虑清晰性、完整性和可操作性。目标是让任何编码代理都有足够的上下文，能有效地为项目做出贡献，而无需额外的人工指导。