agents-md

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

agents-md

Repository-scoped hygiene for

AGENTS.md

: create it, measure it, audit its content, and check it against its harness mirrors. One canonical file, harness-neutral, no frontmatter.

.github/copilot-instructions.md
authoring and Copilot code-review setup live in
/github-copilot-repo-instructions
(if installed). This skill only checks that file's mirror status against
AGENTS.md
; it does not write Copilot-specific content or
applyTo
path rules.
Personal or machine-global instruction files (a user's own
~/.claude/CLAUDE.md
, personal Copilot instructions) are out of scope. This skill only touches files committed to the repository.

面向仓库的

AGENTS.md

治理：创建、测量、审计其内容，并检查其与 harness 镜像文件是否一致。保持单一规范文件、harness 中立且不使用 frontmatter。

.github/copilot-instructions.md
的编写和 Copilot 代码审查设置由
/github-copilot-repo-instructions
（如果已安装）负责。本 skill 仅检查该文件相对于
AGENTS.md
的镜像同步状态；不会写入 Copilot 专用内容或
applyTo
路径规则。
个人或机器全局的指令文件（用户自己的
~/.claude/CLAUDE.md
、个人 Copilot 指令）不在范围内。本 skill 仅处理已提交到仓库中的文件。

Why AGENTS.md hygiene matters

为什么 AGENTS.md 治理很重要

AGENTS.md is a vendor-neutral, plain-Markdown convention with no required fields (agents.md). Harnesses load applicable files at different times. Loaded text uses context, so keep instructions concise and commands current. Do not equate loaded context with billed tokens or assume every file loads on every turn.

Effectiveness evidence is mixed. Keep repository rules that help agents act, not rules based on a promised task-success gain. See

references/harness-matrix.md

for loading behavior and

references/content-checklist.md

for study limits.

AGENTS.md 是一种厂商中立的纯 Markdown 约定，没有必填字段（agents.md）。各 harness 会在不同时机加载适用文件。加载的文本会占用上下文，因此应让指令保持简洁、命令保持最新。不要将加载的上下文等同于计费 token，也不要假设每个文件都会在每一轮加载。

现有效果证据并不一致。保留能帮助 Agent 行动的仓库规则，不要保留仅以任务成功率提升承诺为依据的规则。有关加载行为，请参阅

references/harness-matrix.md

；有关研究限制，请参阅

references/content-checklist.md

。

Protocol

流程

1. Inventory instruction files

1. 盘点指令文件

List what exists, repository-relative, root and nested:

bash

find . -maxdepth 4 \( -name AGENTS.md -o -name CLAUDE.md -o -name CLAUDE.local.md \
  -o -name GEMINI.md -o -path '*/.github/copilot-instructions.md' -o -path '*/.cursor/rules*' \) \
  -not -path '*/node_modules/*'

Each harness reads a different subset with different precedence and caps. Read

references/harness-matrix.md

before assuming one file's presence or absence is equivalent to another's — nearest-file precedence is the norm (agents.md spec, Codex, Copilot, Cursor), but Claude Code's own trigger is different: it reads

AGENTS.md

only when no

CLAUDE.md

CLAUDE.local.md

exists above the working file, or via an explicit

@AGENTS.md

import inside a

CLAUDE.md

列出仓库相对路径下的现有文件，包括根目录和嵌套目录：

bash

find . -maxdepth 4 \\( -name AGENTS.md -o -name CLAUDE.md -o -name CLAUDE.local.md \\
  -o -name GEMINI.md -o -path '*/.github/copilot-instructions.md' -o -path '*/.cursor/rules*' \\) \\
  -not -path '*/node_modules/*'

每个 harness 读取不同的文件子集，并采用不同的优先级和大小上限。在假定某个文件是否存在能够代表另一个文件之前，请先阅读

references/harness-matrix.md

——最近文件优先是通行做法（agents.md 规范、Codex、Copilot、Cursor），但 Claude Code 自身的触发机制不同：只有当前工作文件的上级目录中没有

CLAUDE.md

CLAUDE.local.md

时，它才读取

AGENTS.md

；也可以通过

CLAUDE.md

中显式的

@AGENTS.md

导入来读取。

2. Measure

2. 测量

bash

python3 "$AGENTS_MD_CHECK" [path/to/AGENTS.md]

Resolve

AGENTS_MD_CHECK

from the loaded

SKILL.md

directory (

scripts/agents_md_check.py

), resolving symlinks first. Do not assume the skill sits at

skills/agents-md/

in the target repository.

Reports bytes, lines, the heading map, every referenced

just <recipe>

checked against a nearby

justfile

, every referenced repo-relative path, and the mirror status of

CLAUDE.md

.github/copilot-instructions.md

, and

GEMINI.md

. Flag a file over ~200 lines as a soft readability warning. The script also sums the

AGENTS.md

chain from the repository root to each directory at or below the checked file. A chain over 32 KiB fails outright. OpenAI Codex concatenates that chain from the root down. It stops adding files when the combined size reaches

project_doc_max_bytes

(32 KiB by default), so the files nearest the working directory drop first (https://developers.openai.com/codex/guides/agents-md/).

Root discovery and skip rules follow Codex:

The root is the nearest directory at or above the checked file that contains
```
.git
```
. With no
```
.git
```
, each chain is the checked file only, and the report says "file directory" instead of "repository root".
Per directory,
```
AGENTS.override.md
```
counts when present, else
```
AGENTS.md
```
.
Sizes are raw on-disk bytes, so CRLF line endings count in full.
The walk skips dot directories,
```
node_modules
```
, broken symlinks, and any subdirectory with its own
```
.git
```
(a nested project root).

Exit codes: 0 when no chain breaches the cap, no mirror has diverged, and every referenced recipe and path exists. 1 on a cap breach, on any drift (diverged mirror, missing recipe, or missing path), or when the file does not exist.

--json

prints these fields:

path

bytes

chain_bytes

chain_dir

(the deepest directory of the largest chain, relative to the root),

root_marker

(true when a

.git

root was found),

lines

byte_cap

cap_breach

near_cap

line_warn

headings

justfile

referenced_just_recipes

missing_recipes

referenced_paths

missing_paths

mirrors

diverged_mirrors

, and

drift

bash

python3 "$AGENTS_MD_CHECK" [path/to/AGENTS.md]

从已加载的

SKILL.md

所在目录解析

AGENTS_MD_CHECK

（

scripts/agents_md_check.py

），并先解析符号链接。不要假设该 skill 位于目标仓库的

skills/agents-md/

中。

报告会列出字节数、行数、标题映射、每个被引用的

just <recipe>

（与附近的

justfile

核对）、每个被引用的仓库相对路径，以及

CLAUDE.md

、

.github/copilot-instructions.md

和

GEMINI.md

的镜像状态。将超过约 200 行的文件标记为软性可读性警告。脚本还会汇总从仓库根目录到被检查文件所在目录及其下每个目录的

AGENTS.md

链。链大小超过 32 KiB 将直接判定失败。

OpenAI Codex 会按从根目录向下的顺序连接该链。当组合大小达到

project_doc_max_bytes

（默认 32 KiB）时，它会停止添加文件，因此离工作目录最近的文件最先被排除（https://developers.openai.com/codex/guides/agents-md/）。

根目录发现和跳过规则遵循 Codex：

根目录是被检查文件所在目录或其上级目录中包含
```
.git
```
的最近目录。如果没有
```
.git
```
，则每条链都只包含被检查文件，报告会显示 "file directory" 而不是 "repository root"。
在每个目录中，存在
```
AGENTS.override.md
```
时以它为准，否则使用
```
AGENTS.md
```
。
大小按磁盘原始字节数计算，因此 CRLF 行尾也会被完整计入。
遍历会跳过点目录、
```
node_modules
```
、失效符号链接，以及拥有自身
```
.git
```
的任何子目录（嵌套项目根目录）。

当没有链突破上限、没有镜像发生偏离，且所有被引用的 recipe 和路径均存在时，退出码为 0。出现上限突破、任何漂移（镜像偏离、recipe 缺失或路径缺失），或文件不存在时，退出码为 1。

--json

会打印以下字段：

path

、

bytes

、

chain_bytes

、

chain_dir

root_marker

（找到

.git

根目录时为 true）、

lines

、

byte_cap

、

cap_breach

、

near_cap

、

line_warn

、

headings

、

justfile

、

referenced_just_recipes

、

missing_recipes

、

referenced_paths

、

missing_paths

、

mirrors

、

diverged_mirrors

和

drift

。

3. Content audit

3. 内容审计

For every command and path AGENTS.md names, verify it against the real repository, not against memory:

Every backticked
```
just <recipe>
```
exists in the
```
justfile
```
— the script checks this; treat a
```
FAIL missing just recipes
```
line as a stale command, not a script bug.
Every backticked repo-relative path exists — same treatment for
```
FAIL missing referenced paths
```
.
Quality gates, conventions, and "do not touch" boundaries match the project's actual CI and review practice, not an aspirational one.
PR and commit rules are stated, not implied.

Anti-patterns to flag and remove, per

references/content-checklist.md

: narrative history, README duplication, secrets or tokens, per-person preferences, and any command that no longer runs.

对于 AGENTS.md 提到的每个命令和路径，都要根据真实仓库进行验证，而不是凭记忆：

每个用反引号括起的
```
just <recipe>
```
都必须存在于
```
justfile
```
中——脚本会检查这一点；将
```
FAIL missing just recipes
```
行视为过期命令，而不是脚本缺陷。
每个用反引号括起的仓库相对路径都必须存在——同样应将
```
FAIL missing referenced paths
```
视为过期引用，而不是脚本缺陷。
质量门禁、约定和 "do not touch" 边界应符合项目的实际 CI 和评审实践，而不是理想化目标。
PR 和 commit 规则应明确写出，而不是仅靠暗示。

根据

references/content-checklist.md

，需要标记并移除以下反模式：叙述性历史、README 重复内容、密钥或 token、个人偏好，以及任何已无法运行的命令。

4. Mirror strategy

4. 镜像策略

Keep exactly one canonical

AGENTS.md

. For each mirror:

```
CLAUDE.md
```
: either absent, or contains only
```
@AGENTS.md
```
(a Claude Code import — https://code.claude.com/docs/en/memory). Do not duplicate content into it.
```
.github/copilot-instructions.md
```
: either absent (Copilot reads
```
AGENTS.md
```
directly) or a short pointer. If the user wants Copilot-specific content (path-scoped
```
applyTo
```
rules, code-review knobs), route to
```
/github-copilot-repo-instructions
```
— do not author that file here.
```
GEMINI.md
```
: either absent or a short pointer, same pattern as CLAUDE.md.

Report any mirror the check script marks

diverged

as drift, and propose collapsing it to a pointer or removing it.

每个范围只保留一个规范的

AGENTS.md

。对于每个镜像文件：

```
CLAUDE.md
```
：要么不存在，要么只包含
```
@AGENTS.md
```
（Claude Code 导入—— https://code.claude.com/docs/en/memory）。不要在其中重复内容。
```
.github/copilot-instructions.md
```
：要么不存在（Copilot 会直接读取
```
AGENTS.md
```
），要么只包含一个简短指针。如果用户需要 Copilot 专用内容（按路径限定的
```
applyTo
```
规则、代码审查选项），请转至
```
/github-copilot-repo-instructions
```
——不要在此处编写该文件。
```
GEMINI.md
```
：要么不存在，要么只包含一个简短指针，与 CLAUDE.md 的模式相同。

如果检查脚本将任何镜像标记为

diverged

，则将其报告为漂移，并建议将其折叠为指针或删除。

5. Nested AGENTS.md

5. 嵌套 AGENTS.md

For a monorepo or multi-package layout, put a nested

AGENTS.md

in each package that needs its own rules. Codex, Claude Code, Cursor, Gemini CLI, and Copilot CLI load the nested file together with every ancestor file. No harness replaces the root file with the nested file. The nearer file wins only on conflict. See

references/harness-matrix.md

for each harness.

Put only the subtree's delta in the nested file: its own commands, boundaries, and exceptions. A copied root rule duplicates context when both files load and can drift.
State each exception to a root rule explicitly, and name the root rule that it replaces. VS Code warns that harnesses do not share one precedence order.
Keep every root-to-leaf chain under the Codex 32 KiB cap. Codex drops the nearest files first.
Claude Code reads a nested
```
AGENTS.md
```
only when that directory has no
```
CLAUDE.md
```
of its own.

对于 monorepo 或多包布局，在每个需要独立规则的包中放置嵌套

AGENTS.md

。 Codex、Claude Code、Cursor、Gemini CLI 和 Copilot CLI 会将嵌套文件与每个祖先文件一起加载。没有任何 harness 会用嵌套文件替换根文件。只有在发生冲突时，距离更近的文件才优先。有关各 harness 的行为，请参阅

references/harness-matrix.md

。

嵌套文件中只写子树的增量内容：其自身命令、边界和例外。复制根规则会在两个文件同时加载时造成上下文重复，并可能产生漂移。
明确说明每一条根规则例外，并指出它所替代的根规则。VS Code 提醒各 harness 并不使用统一的优先级顺序。
确保每条从根到叶的链都低于 Codex 的 32 KiB 上限。Codex 会最先排除距离工作目录最近的文件。
只有在该目录没有自己的
```
CLAUDE.md
```
时，Claude Code 才会读取嵌套的
```
AGENTS.md
```
。

6. Trim or rewrite

6. 精简或重写

Always show the proposed change as a diff against the current file. Then stop and ask for explicit approval before writing

AGENTS.md

or any mirror. A request to skip the diff ("I don't need to see the diff") does not waive this step and is not approval. Write only after the user approves the diff that you showed.

Never run

git commit

git push

. Leave the changes in the working tree. The user owns commits.

Use

assets/AGENTS.md.template

as the starting shape for a new file, not as boilerplate to paste unedited — every section must reflect this repository's actual commands and boundaries.

始终以相对于当前文件的 diff 形式展示拟议更改。然后停止并请求明确批准，之后才能写入

AGENTS.md

或任何镜像文件。要求跳过 diff （"I don't need to see the diff"）并不豁免此步骤，也不构成批准。只有用户批准你展示的 diff 后才能写入。

绝不运行

git commit

或

git push

。将更改留在工作树中，commit 由用户负责。

对于新文件，使用

assets/AGENTS.md.template

作为初始结构，不要原样粘贴其中的样板内容——每个部分都必须反映该仓库实际使用的命令和边界。

7. Verify

7. 验证

bash

python3 "$AGENTS_MD_CHECK" --self-test
python3 "$AGENTS_MD_CHECK"

Both must exit 0. Re-run any command the audit changed or added before reporting done.

bash

python3 "$AGENTS_MD_CHECK" --self-test
python3 "$AGENTS_MD_CHECK"

两者都必须以退出码 0 结束。在报告完成之前，重新运行审计过程中修改或新增的所有命令。

Rules

规则

One canonical
```
AGENTS.md
```
per directory scope. Mirrors point at it; they do not restate it.
Never invent a command or path. Every backticked
```
just <recipe>
```
and every referenced path must exist — the check script verifies this, do not skip it.
Do not add narrative, README duplication, secrets, or per-person preferences. See
```
references/content-checklist.md
```
for the full list.
Do not write
```
.github/copilot-instructions.md
```
content beyond a short pointer — that authoring belongs to
```
/github-copilot-repo-instructions
```
.
Do not touch personal or machine-global instruction files.
Show the diff and get explicit approval before overwriting an existing
```
AGENTS.md
```
or mirror. A request to skip the diff is not approval.
Never run
```
git commit
```
,
```
git push
```
, or any other publication command. Leave changes in the working tree.

每个目录范围只保留一个规范的
```
AGENTS.md
```
。镜像指向它，不复述其内容。
绝不虚构命令或路径。每个用反引号括起的
```
just <recipe>
```
和每个被引用的路径都必须存在——检查脚本会验证这一点，不得跳过。
不要添加叙述性内容、README 重复内容、密钥或 token、个人偏好。完整列表请参阅
```
references/content-checklist.md
```
。
不要在
```
.github/copilot-instructions.md
```
中写入超出简短指针的内容——该文件的编写工作属于
```
/github-copilot-repo-instructions
```
。
不要处理个人或机器全局的指令文件。
覆盖现有
```
AGENTS.md
```
或镜像文件前，必须展示 diff 并获得明确批准。要求跳过 diff 不构成批准。
绝不运行
```
git commit
```
、
```
git push
```
或其他任何发布命令。将更改留在工作树中。

References

参考资料

```
references/harness-matrix.md
```
— which harness reads which file, with precedence and size caps, cited.
```
references/content-checklist.md
```
— what belongs in AGENTS.md and what does not. Harness-behavior claims are cited; the lists are this skill's guidance.
```
assets/AGENTS.md.template
```
— a short, sectioned starting template.

```
references/harness-matrix.md
```
——哪些 harness 读取哪些文件，并附有优先级、大小上限及引用来源。
```
references/content-checklist.md
```
——哪些内容应放入 AGENTS.md，哪些内容不应放入。 harness 行为相关论断附有引用；这些列表则是本 skill 的指导准则。
```
assets/AGENTS.md.template
```
——一个简短、分章节的初始模板。