agents-md

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Maintaining AGENTS.md

维护AGENTS.md

AGENTS.md is the canonical agent-facing documentation. Keep it minimal—agents are capable and don't need hand-holding. Target under 60 lines; never exceed 100. Instruction-following quality degrades as document length increases.

AGENTS.md是面向Agent的标准文档。请保持文档极简——Agent具备自主能力，无需冗余指引。文档目标长度控制在60行以内，绝对不能超过100行。文档越长，Agent遵循指令的质量就越低。

File Setup

文件设置

Create
```
AGENTS.md
```
at project root
Create symlink:
```
ln -s AGENTS.md CLAUDE.md
```

在项目根目录创建
```
AGENTS.md
```
创建符号链接：
```
ln -s AGENTS.md CLAUDE.md
```

Before Writing

编写前准备

Analyze the project to understand what belongs in the file:

Package manager — Check for lock files (

pnpm-lock.yaml

yarn.lock

package-lock.json

uv.lock

poetry.lock

)

Linter/formatter configs — Look for
```
.eslintrc
```
,
```
biome.json
```
,
```
ruff.toml
```
,
```
.prettierrc
```
, etc. (don't duplicate these in AGENTS.md)
CI/build commands — Check
```
Makefile
```
,
```
package.json
```
scripts, CI configs for canonical commands
Monorepo indicators — Check for
```
pnpm-workspace.yaml
```
,
```
nx.json
```
, Cargo workspace, or subdirectory
```
package.json
```
files
Existing conventions — Check for existing CONTRIBUTING.md, docs/, or README patterns

先分析项目，明确文档应包含的内容：

包管理器 — 检查锁文件（

pnpm-lock.yaml

yarn.lock

package-lock.json

uv.lock

poetry.lock

）

代码检查/格式化配置 — 查找
```
.eslintrc
```
,
```
biome.json
```
,
```
ruff.toml
```
,
```
.prettierrc
```
等文件（不要在AGENTS.md中重复这些配置内容）
CI/构建命令 — 查看
```
Makefile
```
,
```
package.json
```
脚本, CI配置文件获取标准命令
单仓（Monorepo）标识 — 检查是否存在
```
pnpm-workspace.yaml
```
,
```
nx.json
```
, Cargo workspace或子目录下的
```
package.json
```
文件
现有规范 — 查看已有的CONTRIBUTING.md, docs/目录或README文档的格式

Writing Rules

编写规则

Headers + bullets — No paragraphs
Code blocks — For commands and templates
Reference, don't embed — Point to existing docs: "See
```
CONTRIBUTING.md
```
for setup" or "Follow patterns in
```
src/api/routes/
```
"
No filler — No intros, conclusions, or pleasantries
Trust capabilities — Omit obvious context
Prefer file-scoped commands — Per-file test/lint/typecheck commands over project-wide builds
Don't duplicate linters — Code style lives in linter configs, not AGENTS.md

标题+项目符号 — 不要使用段落
代码块 — 用于展示命令和模板
引用而非嵌入 — 指向现有文档："See
```
CONTRIBUTING.md
```
for setup" 或 "Follow patterns in
```
src/api/routes/
```
"
无冗余内容 — 不要写引言、结论或客套话
信任Agent能力 — 省略显而易见的上下文
优先使用文件级命令 — 优先提供针对单个文件的测试/检查/类型校验命令，而非全项目构建命令
不重复代码检查规则 — 代码风格规则已在检查器配置文件中定义，无需在AGENTS.md中重复

Required Sections

必备章节

Package Manager

包管理器

Which tool and key commands only:

markdown

undefined

仅说明工具及核心命令：

markdown

undefined

Package Manager

Use pnpm:

pnpm install

pnpm dev

pnpm test

undefined

Use pnpm:

pnpm install

pnpm dev

pnpm test

undefined

File-Scoped Commands

文件级命令

Per-file commands are faster and cheaper than full project builds. Always include when available:

markdown

undefined

针对单个文件的命令比全项目构建更快、成本更低。只要有可用的此类命令，务必包含：

markdown

undefined

File-Scoped Commands

Task	Command
Typecheck	`pnpm tsc --noEmit path/to/file.ts`
Lint	`pnpm eslint path/to/file.ts`
Test	`pnpm jest path/to/file.test.ts`

undefined

Task	Command
Typecheck	`pnpm tsc --noEmit path/to/file.ts`
Lint	`pnpm eslint path/to/file.ts`
Test	`pnpm jest path/to/file.test.ts`

undefined

Commit Attribution

提交署名

Always include this section. Agents should use their own identity:

markdown

undefined

必须包含此章节。Agent应使用自身身份署名：

markdown

undefined

Commit Attribution

AI commits MUST include:

Co-Authored-By: (the agent model's name and attribution byline)

Example:

Co-Authored-By: Claude Sonnet 4 <noreply@example.com>

undefined

AI commits MUST include:

Co-Authored-By: (the agent model's name and attribution byline)

Example:

Co-Authored-By: Claude Sonnet 4 <noreply@example.com>

undefined

Key Conventions

核心规范

Project-specific patterns agents must follow. Keep brief.

列出Agent必须遵循的项目特定格式，保持简洁。

Optional Sections

可选章节

Add only if truly needed:

API route patterns (show template, not explanation)
CLI commands (table format)
File naming conventions
Project structure hints (point to critical files, flag legacy code to avoid)
Monorepo overrides (subdirectory
```
AGENTS.md
```
files override root)

仅在确有必要时添加：

API路由格式（提供模板代码块，无需解释）
CLI命令（表格格式）
文件命名规范
项目结构提示（指向关键文件，标记需避开的遗留代码）
单仓覆盖规则（子目录下的
```
AGENTS.md
```
文件优先级高于根目录文件）

Anti-Patterns

避坑指南

Omit these:

"Welcome to..." or "This document explains..."
"You should..." or "Remember to..."
Linter/formatter rules already in config files (
```
.eslintrc
```
,
```
biome.json
```
,
```
ruff.toml
```
)
Listing installed skills or plugins (agents discover these automatically)
Full project-wide build commands when file-scoped alternatives exist
Obvious instructions ("run tests", "write clean code")
Explanations of why (just say what)
Long prose paragraphs

请勿包含以下内容：

"Welcome to..." 或 "This document explains..."之类的开场白
"You should..." 或 "Remember to..."之类的表述
已在配置文件（
```
.eslintrc
```
,
```
biome.json
```
,
```
ruff.toml
```
）中定义的代码检查/格式化规则
列出已安装的技能或插件（Agent可自动发现这些内容）
当存在文件级命令替代方案时，仍提供全项目构建命令
显而易见的指令（如"run tests", "write clean code"）
解释原因（只需说明要做什么）
冗长的段落

Example Structure

示例结构

markdown

undefined

markdown

undefined

Agent Instructions

Package Manager

Use pnpm:

pnpm install

pnpm dev

Use pnpm:

pnpm install

pnpm dev

Commit Attribution

AI commits MUST include:

Co-Authored-By: (the agent model's name and attribution byline)

AI commits MUST include:

Co-Authored-By: (the agent model's name and attribution byline)

File-Scoped Commands

Task	Command
Typecheck	`pnpm tsc --noEmit path/to/file.ts`
Lint	`pnpm eslint path/to/file.ts`
Test	`pnpm jest path/to/file.test.ts`

Task	Command
Typecheck	`pnpm tsc --noEmit path/to/file.ts`
Lint	`pnpm eslint path/to/file.ts`
Test	`pnpm jest path/to/file.test.ts`

API Routes

[Template code block]

CLI

Command	Description
`pnpm cli sync`	Sync data

undefined

Command	Description
`pnpm cli sync`	Sync data

undefined