writing-agents-md

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Writing Agents MD

编写 Agents MD 文件

Overview

概述

AGENTS.md

and

CLAUDE.md

should be minimal guardrails, not repo handbooks.

Do not assume more global instructions improve outcomes; extra always-on guidance often slows or misdirects work.

Keep only information that is all three:

hard to discover from the repo itself
globally relevant across most tasks
stable enough not to rot quickly

If a detail fails any of those tests, delete it, narrow it, or move it into a skill.

AGENTS.md

和

CLAUDE.md

应作为极简约束指南，而非仓库手册。

不要认为更多全局指令能提升效果；额外的常驻指导往往会拖慢工作或误导方向。

仅保留同时满足以下三个条件的信息：

无法从仓库本身轻易发现
与大多数任务全局相关
足够稳定，不会快速过时

若某条信息不满足任一条件，应删除、精简或将其移入Skill中。

When to Use

使用场景

Creating a new
```
AGENTS.md
```
or
```
CLAUDE.md
```
Reviewing, pruning, or rewriting an existing
```
AGENTS.md
```
or
```
CLAUDE.md
```
Removing repo summaries, stale rules, or handbook-style guidance from a global agent file
Deciding whether guidance belongs in a global rule file or a skill

创建新的
```
AGENTS.md
```
或
```
CLAUDE.md
```
文件
审核、精简或重写现有
```
AGENTS.md
```
或
```
CLAUDE.md
```
文件
从全局Agent文件中移除仓库摘要、过时规则或手册式指导
判断指导内容应放在全局规则文件还是Skill中

Workflow

工作流程

Identify the target file and whether the task is create, rewrite, or review.
Analyze the repo for high-value, non-obvious, global constraints.
If
```
AGENTS.md
```
or
```
CLAUDE.md
```
already exists, read it only after that analysis as historical input, not as the source of truth. If it conflicts with what the repo shows, trust the repo.
Classify each item as
```
keep
```
,
```
rewrite
```
,
```
delete
```
,
```
move-to-skill
```
, or
```
stale
```
.
Keep only rules that are non-discoverable, global, and stable.
Rewrite the file into a short, high-signal document.
Briefly explain what was removed or marked stale and why, so the file does not bloat again.

确定目标文件及任务类型（创建、重写或审核）。
分析仓库，找出高价值、非显而易见的全局约束。
若
```
AGENTS.md
```
或
```
CLAUDE.md
```
已存在，仅将其作为历史参考而非事实依据，在分析完成后再阅读。若其内容与仓库实际情况冲突，以仓库为准。
将每条内容分类为“保留”“重写”“删除”“移入Skill”或“过时”。
仅保留非易发现、全局适用且稳定的规则。
将文件重写为简短、高价值的文档。
简要说明移除或标记为过时的内容及原因，避免文件再次膨胀。

Core Filter

核心筛选标准

Before keeping any line, ask:

Can the model discover this easily and reliably by reading the repo?
Does this matter for most tasks, not just some tasks?
Is this likely to remain true as files, paths, and architecture evolve?

If the answer is

yes / no / no

, it does not belong in a global rule file.

Even if something is technically discoverable, keep it only when omitting it is likely to cause a costly mistake and the model is unlikely to infer the right choice reliably.

保留任何内容前，先问自己三个问题：

模型能否通过阅读仓库轻松且可靠地发现该信息？
该信息是否对大多数任务都重要，而非仅部分任务？
随着文件、路径和架构的演变，该信息是否仍可能保持有效？

若答案为“是/否/否”，则该内容不应放在全局规则文件中。

即使某信息在技术上可被发现，仅当省略它可能导致代价高昂的错误，且模型无法可靠推断正确选择时，才予以保留。

Keep

保留内容

Good candidates for

AGENTS.md

CLAUDE.md

non-obvious tool choices like
```
uv
```
, not
```
pip
```
environment-specific constraints like WSL path behavior
expensive landmines like false-positive cache behavior
legacy areas that still have production imports and must not be removed casually

Keep constraints that redirect the agent away from costly wrong defaults. Be cautious with instructions that add new standing requirements the agent would not otherwise follow.

适合放入

AGENTS.md

或

CLAUDE.md

的内容示例：

非显而易见的工具选择，如
```
uv
```
而非
```
pip
```
环境特定约束，如WSL路径行为
代价高昂的“陷阱”，如误报缓存行为
仍有生产导入、不能随意删除的遗留代码区域

保留那些能引导Agent避开代价高昂的错误默认值的约束。对于要求Agent遵循原本不会执行的新常规指令，需谨慎处理。

Delete Or Move Out

删除或移出内容

Usually remove these from global files:

package scripts copied from
```
package.json
```
directory tours and architecture summaries
tech stack summaries the repo already makes obvious
file-path-heavy instructions that will rot quickly
task-specific workflows, style preferences, or domain guidance

Move workflow or domain guidance into a skill instead of keeping it globally.

Every standing instruction is a potential landmine. Prefer a smaller file over a more prescriptive one.

通常需从全局文件中移除以下内容：

从
```
package.json
```
复制的包脚本
目录导览和架构摘要
仓库已明确体现的技术栈摘要
包含大量文件路径、易快速过时的指令
特定任务的工作流程、风格偏好或领域指导

将工作流程或领域指导移入Skill，而非保留在全局文件中。

每条常驻指令都可能成为潜在陷阱。优先选择更精简的文件，而非更具指令性的文件。

Guardrails

约束规则

Do not generate repo overviews, directory tours, or handbook-style summaries in global agent files.
Do not repeat information the model can discover from code, docs, or config.
Do not mention legacy technologies without clearly labeling them as legacy or avoid-using.
Do not keep broad instructions in the global file if they only matter for some tasks.
If the repo has little truly global guidance, prefer a very short file over a padded one.
If unsure whether a line earns its keep, cut it.

不要在全局Agent文件中生成仓库概述、目录导览或手册式摘要。
不要重复模型可从代码、文档或配置中发现的信息。
提及遗留技术时，需明确标记为“遗留”或“避免使用”。
若某宽泛指令仅对部分任务重要，不要保留在全局文件中。
若仓库几乎没有真正的全局、非显而易见的约束，宁可文件非常简短，也不要填充无关内容。
若不确定某内容是否值得保留，删除它。

Output Shape

输出格式

Aim for a short file that may include sections like:

environment or tooling constraints
important landmines
minimal routing notes to existing skills

Avoid turning the file into a setup guide, architecture document, or coding standards manual.

If the repo has almost no truly global, non-obvious constraints, a tiny file is acceptable and no file is sometimes acceptable too.

目标是创建简短文件，可包含以下部分：

环境或工具约束
重要陷阱
指向现有Skill的极简路由说明

避免将文件变成安装指南、架构文档或编码标准手册。

若仓库几乎没有真正的全局、非显而易见的约束，文件极小是可接受的，有时甚至不需要文件。

References

参考资料

See
```
references/checklist.md
```
for the full keep/delete decision list.
See
```
references/examples.md
```
for bad, better, and good examples.
See
```
references/principles.md
```
for the underlying rationale.

完整的保留/删除决策列表请见
```
references/checklist.md
```
反面、改进及正面示例请见
```
references/examples.md
```
底层原理请见
```
references/principles.md
```