create-agentsmd

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create high‑quality AGENTS.md file

创建高质量的AGENTS.md文件

You are a code agent. Your task is to create a complete, accurate AGENTS.md at the root of this repository that follows the public guidance at https://agents.md/.

AGENTS.md is an open format designed to provide coding agents with the context and instructions they need to work effectively on a project.

你是一个代码Agent。你的任务是在本仓库的根目录创建一份完整、准确的AGENTS.md文件，需遵循https://agents.md/上的公开指导规范。

AGENTS.md是一种开放格式，旨在为编码Agent提供有效开展项目工作所需的上下文信息和操作说明。

What is AGENTS.md?

什么是AGENTS.md？

AGENTS.md is a Markdown file that serves as a "README for agents" - a dedicated, predictable place to provide context and instructions to help AI coding agents work on your project. It complements README.md by containing detailed technical context that coding agents need but might clutter a human-focused README.

AGENTS.md是一份Markdown文件，充当「面向Agent的README」——它是一个专门的、可预测的位置，用于为AI编码Agent提供上下文信息和操作说明，帮助它们在你的项目中工作。它是对README.md的补充，包含了编码Agent需要但可能会让面向人类的README显得杂乱的详细技术上下文。

Key Principles

核心原则

Agent-focused: Contains detailed technical instructions for automated tools
Complements README.md: Doesn't replace human documentation but adds agent-specific context
Standardized location: Placed at repository root (or subproject roots for monorepos)
Open format: Uses standard Markdown with flexible structure
Ecosystem compatibility: Works across 20+ different AI coding tools and agents

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

File Structure and Content Guidelines

文件结构与内容指南

1. Required Setup

1. 必备设置

Create the file as
```
AGENTS.md
```
in the repository root
Use standard Markdown formatting
No required fields - flexible structure based on project needs

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

2. Essential Sections to Include

2. 建议包含的核心章节

Project Overview

项目概述

Brief description of what the project does
Architecture overview if complex
Key technologies and frameworks used

项目功能的简要描述
若架构复杂则需提供架构概述
使用的核心技术与框架

Setup Commands

配置命令

Installation instructions
Environment setup steps
Dependency management commands
Database setup if applicable

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

Development Workflow

开发工作流

How to start development server
Build commands
Watch/hot-reload setup
Package manager specifics (npm, pnpm, yarn, etc.)

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

Testing Instructions

测试说明

How to run tests (unit, integration, e2e)
Test file locations and naming conventions
Coverage requirements
Specific test patterns or frameworks used
How to run subset of tests or focus on specific areas

如何运行测试（单元测试、集成测试、端到端测试）
测试文件的位置与命名规范
覆盖率要求
使用的特定测试模式或框架
如何运行子集测试或聚焦特定领域

Code Style Guidelines

代码风格指南

Language-specific conventions
Linting and formatting rules
File organization patterns
Naming conventions
Import/export patterns

特定语言的约定
代码检查与格式化规则
文件组织模式
命名规范
导入/导出模式

Build and Deployment

构建与部署

Build commands and outputs
Environment configurations
Deployment steps and requirements
CI/CD pipeline information

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

3. Optional but Recommended Sections

3. 可选但推荐的章节

Security Considerations

安全注意事项

Security testing requirements
Secrets management
Authentication patterns
Permission models

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

Monorepo Instructions (if applicable)

单仓库（Monorepo）说明（如适用）

How to work with multiple packages
Cross-package dependencies
Selective building/testing
Package-specific commands

如何处理多包项目
跨包依赖
选择性构建/测试
包专属命令

Pull Request Guidelines

拉取请求（Pull Request）指南

Title format requirements
Required checks before submission
Review process
Commit message conventions

标题格式要求
提交前需完成的检查
评审流程
提交信息规范

Debugging and Troubleshooting

调试与故障排除

Common issues and solutions
Logging patterns
Debug configuration
Performance considerations

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

Example Template

示例模板

Use this as a starting template and customize based on the specific project:

markdown

undefined

可将此作为起始模板，根据项目具体情况进行自定义：

markdown

undefined

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]
```

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

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]

undefined

[任何项目专属上下文]
[常见陷阱或故障排除技巧]
[性能注意事项]

undefined

Working Example from agents.md

来自agents.md的实际示例

Here's a real example from the agents.md website:

markdown

undefined

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

markdown

undefined

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.

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.

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.

undefined

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

undefined

Implementation Steps

实施步骤

Analyze the project structure to understand:
- Programming languages and frameworks used
- Package managers and build tools
- Testing frameworks
- Project architecture (monorepo, single package, etc.)
Identify key workflows by examining:
- package.json scripts
- Makefile or other build files
- CI/CD configuration files
- Documentation files
Create comprehensive sections covering:
- All essential setup and development commands
- Testing strategies and commands
- Code style and conventions
- Build and deployment processes
Include specific, actionable commands that agents can execute directly
Test the instructions by ensuring all commands work as documented
Keep it focused on what agents need to know, not general project information

分析项目结构，以了解：
- 使用的编程语言与框架
- 包管理器与构建工具
- 测试框架
- 项目架构（单仓库、单包等）
识别核心工作流，可通过以下文件查看：
- package.json脚本
- Makefile或其他构建文件
- CI/CD配置文件
- 文档文件
创建全面的章节，涵盖：
- 所有核心配置与开发命令
- 测试策略与命令
- 代码风格与约定
- 构建与部署流程
包含具体、可执行的命令，让Agent可直接运行
测试说明文档，确保所有命令均按文档所述正常工作
保持内容聚焦，仅保留Agent需要了解的信息，而非通用项目信息

Best Practices

最佳实践

Be specific: Include exact commands, not vague descriptions
Use code blocks: Wrap commands in backticks for clarity
Include context: Explain why certain steps are needed
Stay current: Update as the project evolves
Test commands: Ensure all listed commands actually work
Consider nested files: For monorepos, create AGENTS.md files in subprojects as needed

具体化：包含精确的命令，而非模糊描述
使用代码块：将命令用反引号包裹以提升清晰度
添加上下文：解释某些步骤的必要性
保持更新：随项目演进及时更新文档
测试命令：确保列出的所有命令均可正常运行
考虑嵌套文件：对于单仓库，按需在子项目中创建AGENTS.md文件

Monorepo Considerations

单仓库注意事项

For large monorepos:

Place a main AGENTS.md at the repository root
Create additional AGENTS.md files in subproject directories
The closest AGENTS.md file takes precedence for any given location
Include navigation tips between packages/projects

对于大型单仓库：

在仓库根目录放置一份主AGENTS.md文件
在子项目目录中创建额外的AGENTS.md文件
对于任意位置，最近的AGENTS.md文件优先级更高
包含包/项目间的导航提示

Final Notes

最终说明

AGENTS.md works with 20+ AI coding tools including Cursor, Aider, Gemini CLI, and many others
The format is intentionally flexible - adapt it to your project's needs
Focus on actionable instructions that help agents understand and work with your codebase
This is living documentation - update it as your project evolves

When creating the AGENTS.md file, prioritize clarity, completeness, and actionability. The goal is to give any coding agent enough context to effectively contribute to the project without requiring additional human guidance.

AGENTS.md支持20余种AI编码工具，包括Cursor、Aider、Gemini CLI等
该格式具有故意设计的灵活性——可根据项目需求进行调整
聚焦于可操作的说明，帮助Agent理解并处理代码库，无需额外人工指导
这是一份活文档——随项目演进及时更新

在创建AGENTS.md文件时，优先保证内容清晰、完整且可执行。目标是为任何编码Agent提供足够的上下文信息，使其无需额外人工指导即可有效参与项目贡献。