create-agentsmd

创建高质量的 AGENTS.md 文件

你是一名编码 Agent。你的任务是在此仓库根目录创建一个完整、准确的 AGENTS.md，使其遵循 https://agents.md/ 上的公开指南。

AGENTS.md 是一种开放格式，旨在为编码 Agent 提供在项目上高效工作所需的上下文和指令。

什么是 AGENTS.md？

AGENTS.md 是一个 Markdown 文件，充当“Agent 的 README”——一个专用且可预期的位置，用于提供上下文和指令，帮助 AI 编码 Agent 在你的项目上工作。它通过包含编码 Agent 需要但可能会让面向人类的 README 显得杂乱的技术上下文，来补充 README.md。

关键原则

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

文件结构与内容指南

1. 必需设置

• 在仓库根目录创建文件 AGENTS.md
• 使用标准 Markdown 格式
• 无必填字段——可根据项目需要灵活组织结构

2. 应包含的核心章节

项目概览

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

设置命令

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

开发工作流

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

测试说明

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

代码风格指南

• 语言特定约定
• Lint 和格式化规则
• 文件组织模式
• 命名约定
• 导入/导出模式

构建与部署

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

3. 可选但推荐的章节

安全注意事项

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

Monorepo 说明（如适用）

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

拉取请求指南

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

调试与故障排除

• 常见问题及解决方案
• 日志记录模式
• 调试配置
• 性能注意事项

示例模板

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

# AGENTS.md

## Project Overview

[Brief description of the project, its purpose, and key technologies]

## Setup Commands

- Install dependencies: `[package manager] install`
- Start development server: `[command]`
- Build for production: `[command]`

## Development Workflow

- [Development server startup instructions]
- [Hot reload/watch mode information]
- [Environment variable setup]

## Testing Instructions

- Run all tests: `[command]`
- Run unit tests: `[command]`
- Run integration tests: `[command]`
- Test coverage: `[command]`
- [Specific testing patterns or requirements]

## Code Style

- [Language and framework conventions]
- [Linting rules and commands]
- [Formatting requirements]
- [File organization patterns]

## Build and Deployment

- [Build process details]
- [Output directories]
- [Environment-specific builds]
- [Deployment commands]

## Pull Request Guidelines

- Title format: [component] Brief description
- Required checks: `[lint command]`, `[test command]`
- [Review requirements]

## Additional Notes

- [Any project-specific context]
- [Common gotchas or troubleshooting tips]
- [Performance considerations]

来自 agents.md 的工作示例

以下是来自 agents.md 网站的真实示例：

# Sample AGENTS.md file

## Dev environment tips

- Use `pnpm dlx turbo run where <project_name>` to jump to a package instead of scanning with `ls`.
- Run `pnpm install --filter <project_name>` to add the package to your workspace so Vite, ESLint, and TypeScript can see it.
- Use `pnpm create vite@latest <project_name> -- --template react-ts` to spin up a new React + Vite package with TypeScript checks ready.
- Check the name field inside each package's package.json to confirm the right name—skip the top-level one.

## Testing instructions

- Find the CI plan in the .github/workflows folder.
- Run `pnpm turbo run test --filter <project_name>` to run every check defined for that package.
- From the package root you can just call `pnpm test`. The commit should pass all tests before you merge.
- To focus on one step, add the Vitest pattern: `pnpm vitest run -t "<test name>"`.
- Fix any test or type errors until the whole suite is green.
- After moving files or changing imports, run `pnpm lint --filter <project_name>` to be sure ESLint and TypeScript rules still pass.
- Add or update tests for the code you change, even if nobody asked.

## PR instructions

- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing.

实施步骤

1. 分析项目结构，以了解：

   • 所使用的编程语言和框架
   • 包管理器和构建工具
   • 测试框架
   • 项目架构（monorepo、单包等）

2. 识别关键工作流，通过检查：

   • package.json 脚本
   • Makefile 或其他构建文件
   • CI/CD 配置文件
   • 文档文件

3. 创建全面的章节，涵盖：

   • 所有必要的设置和开发命令
   • 测试策略和命令
   • 代码风格和约定
   • 构建和部署流程

4. 包含具体的、可执行的命令，让 Agent 可以直接运行

5. 测试说明，确保所有命令都如文档所述正常工作

6. 保持聚焦于 Agent 需要知道的内容，而不是一般项目信息

最佳实践

• 要具体：包含精确的命令，而不是模糊的描述
• 使用代码块：用反引号包裹命令以便清晰
• 包含上下文：解释为什么需要某些步骤
• 保持最新：随项目演进更新
• 测试命令：确保所有列出的命令确实有效
• 考虑嵌套文件：对于 monorepo，按需在子项目中创建 AGENTS.md 文件

Monorepo 注意事项

对于大型 monorepo：

• 在仓库根目录放置一个主 AGENTS.md
• 在子项目目录中创建额外的 AGENTS.md 文件
• 对于任何给定位置，最近的 AGENTS.md 文件优先
• 包含包/项目之间的导航提示

最后说明

• AGENTS.md 可与 20+ AI 编码工具配合使用，包括 Cursor、Aider、Gemini CLI 以及许多其他工具
• 该格式有意保持灵活 - 根据你项目的需求进行调整
• 专注于可操作的说明，帮助 Agent 理解并使用你的代码库
• 这是活文档 - 随项目演进而更新

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