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.)

如何启动开发服务器
构建命令
watch/hot-reload 设置
包管理器细节（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

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

Code Style Guidelines

代码风格指南

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

语言特定约定
linting 和格式化规则
文件组织模式
命名约定
import/export 模式

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

如何处理多个 package
跨 package 依赖
选择性构建和测试方式
package 专用命令

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

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

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]

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

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

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

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

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

分析项目结构，以了解：
- 使用的编程语言和框架
- 包管理器和构建工具
- 测试框架
- 项目架构（monorepo、单 package 等）
通过检查以下内容识别关键工作流：
- package.json scripts
- 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

具体明确：包含精确命令，而非含糊描述
使用代码块：使用反引号包裹命令以提高清晰度
提供上下文：解释为什么需要执行某些步骤
保持最新：随着项目演进及时更新
测试命令：确保列出的所有命令均能正常工作
考虑嵌套文件：对于 monorepo，根据需要在子项目中创建 AGENTS.md

Monorepo Considerations

Monorepo 注意事项

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

对于大型 monorepo：

在仓库根目录放置主 AGENTS.md
在子项目目录中创建额外的 AGENTS.md 文件
对于任意给定位置，距离最近的 AGENTS.md 文件具有优先效力
包含 package 或项目之间的导航提示

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 都能获得足够的上下文，有效地为项目作出贡献，而无需额外的人工指导。