agents-md

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Maintaining AGENTS.md

维护AGENTS.md

Goal: concise, actionable agent instructions. Target under 60 lines; never exceed 100.

目标：简洁、可执行的Agent指令。目标行数控制在60行以内；绝对不超过100行。

Workflow

工作流程

Inspect before writing:
- package manager: lock files and manifests
- commands:
```
package.json
```
  ,
```
Makefile
```
  , task runners, CI workflows
- docs/specs/policies:
```
README.md
```
  ,
```
CONTRIBUTING.md
```
  ,
```
docs/
```
  ,
```
specs/
```
  ,
```
policies/
```
  ,
```
SECURITY.md
```
  ,
```
.github/
```
- conventions: current code patterns, test layout, generated files, legacy areas to avoid
Choose scope:
- root
```
AGENTS.md
```
  : repo-wide defaults
- nested
```
AGENTS.md
```
  : only when a subtree has different commands or rules
- closest instruction file wins; keep narrower files shorter than root files
Write the smallest useful file.
Verify exact paths and commands exist.

编写前检查：
- 包管理器：锁定文件和清单
- 命令：
```
package.json
```
  、
```
Makefile
```
  、任务运行器、CI工作流
- 文档/规范/政策：
```
README.md
```
  、
```
CONTRIBUTING.md
```
  、
```
docs/
```
  、
```
specs/
```
  、
```
policies/
```
  、
```
SECURITY.md
```
  、
```
.github/
```
- 约定：当前代码模式、测试布局、生成文件、需要避开的遗留区域
选择范围：
- 根目录
```
AGENTS.md
```
  ：仓库级默认规则
- 嵌套
```
AGENTS.md
```
  ：仅当子目录有不同命令或规则时使用
- 优先级以最近的说明文件为准；窄范围文件需比根目录文件更简短
编写最小化的实用文件。
验证路径和命令确实存在。

File Setup

文件设置

Create
```
AGENTS.md
```
at the repository root.
If a Claude-compatible entrypoint is required, symlink
```
CLAUDE.md
```
to
```
AGENTS.md
```
.
Do not maintain divergent
```
AGENTS.md
```
and
```
CLAUDE.md
```
copies.

在仓库根目录创建
```
AGENTS.md
```
。
如果需要兼容Claude的入口点，将
```
CLAUDE.md
```
软链接到
```
AGENTS.md
```
。
不要维护内容不一致的
```
AGENTS.md
```
和
```
CLAUDE.md
```
副本。

Default Sections

默认章节

Use only sections that add non-obvious value.

markdown

undefined

仅保留能提供非显而易见价值的章节。

markdown

undefined

Agent Instructions

Agent 指令

Package Manager

包管理器

Use pnpm:
```
pnpm install
```

使用 pnpm：
```
pnpm install
```

Commands

命令

Task	Command
Test file	`pnpm vitest run path/to/file.test.ts`
Lint file	`pnpm eslint path/to/file.ts`

任务	命令
测试文件	`pnpm vitest run path/to/file.test.ts`
检查文件	`pnpm eslint path/to/file.ts`

External References

外部参考

Need	File
Setup	`CONTRIBUTING.md`
Architecture	`docs/architecture.md`
Security policy	`SECURITY.md`

需求	文件
环境搭建	`CONTRIBUTING.md`
架构说明	`docs/architecture.md`
安全政策	`SECURITY.md`

Key Conventions

核心约定

Generated files: update with
```
pnpm generate
```
; do not edit by hand.

生成文件：使用
```
pnpm generate
```
更新；请勿手动编辑。

Commit Attribution

提交署名

AI commits MUST include:

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

undefined

AI提交必须包含：

Co-Authored-By: (Agent的名称和署名行)

undefined

Writing Rules

编写规则

Use headings, bullets, and tables; avoid paragraphs.
Use repo-relative paths; avoid vague references like "see docs".
Reference existing docs/specs/policies instead of copying them.
List exact external files for setup, architecture, API specs, security, release, and policy docs when they exist.
Prefer file-scoped test/lint/typecheck commands; include full builds only when no narrower command exists.
Put commands in tables when there is more than one.
Keep one rule per bullet.
Keep rationale out unless it prevents a likely mistake.
Do not restate linter, formatter, or typechecker config.
Do not list installed skills or plugins.
Do not include generic quality slogans.

使用标题、项目符号和表格；避免段落。
使用仓库相对路径；避免模糊引用如“查看文档”。
引用现有文档/规范/政策，而非复制内容。
当存在相关文件时，列出用于环境搭建、架构、API规范、安全、发布和政策文档的具体外部文件。
优先使用文件级别的测试/检查/类型校验命令；仅当没有更窄范围的命令时才包含完整构建命令。
当命令超过一个时，将其放入表格。
每个项目符号只保留一条规则。
除非能避免可能的错误，否则不要添加理由说明。
不要重复说明检查器、格式化工具或类型校验器的配置。
不要列出已安装的技能或插件。
不要包含通用的质量口号。

External Reference Rules

外部参考规则

Good:

markdown

undefined

示例：

markdown

undefined

External References

外部参考

Need	File
API contract	`docs/api.md`
Release process	`docs/releasing.md`

undefined

需求	文件
API 契约	`docs/api.md`
发布流程	`docs/releasing.md`

undefined

Anti-Patterns

反模式

welcome text, intros, conclusions, or pleasantries
long prose explaining why instructions matter
duplicated content from
```
README.md
```
,
```
CONTRIBUTING.md
```
, or policy docs
project-wide commands when file-scoped commands are available
nested
```
AGENTS.md
```
files that repeat root instructions

欢迎语、介绍、结论或客套话
长篇大论解释指令的重要性
重复
```
README.md
```
、
```
CONTRIBUTING.md
```
或政策文档中的内容
当存在文件级命令时仍使用项目级命令
嵌套
```
AGENTS.md
```
文件重复根目录指令