agents-md

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Manage AGENTS.md

管理AGENTS.md

AGENTS.md

gives coding agents scoped, current, repo-specific instructions. It is not a README, runbook, architecture doc, changelog, tutorial, or evidence log. Good guidance is evidence-backed, concise, scoped to the file's directory tree, and behavioral: it tells agents what to do differently in this repository.

AGENTS.md

为编码Agent提供限定范围、实时且针对特定仓库的指令。它不是README、运行手册、架构文档、变更日志、教程或证据日志。优质的指导内容需有证据支撑、简洁明了、限定在文件所在目录树范围内，且具备行为指导性：告诉Agent在本仓库中应采取哪些不同的操作。

When to Use

使用场景

Create, update, review, split, move, or repair a repository
```
AGENTS.md
```
.
Capture verified local commands, repo contracts, path ownership, or recurring agent mistakes.
Convert repo evidence into rules that future agents can follow.

创建、更新、审核、拆分、移动或修复仓库中的
```
AGENTS.md
```
文件。
记录已验证的本地命令、仓库契约、路径归属或Agent反复出现的错误。
将仓库证据转化为可供未来Agent遵循的规则。

When NOT to Use

禁用场景

Standalone skills, prompts, global instructions, READMEs, architecture docs, changelogs, or runbooks.
Broad documentation rewrites where
```
AGENTS.md
```
is not an explicit deliverable.
Aspirational process guidance that is not supported by current repo evidence.

独立技能、提示词、全局指令、README、架构文档、变更日志或运行手册。
未明确将
```
AGENTS.md
```
作为交付内容的宽泛文档重写工作。
无当前仓库证据支持的理想化流程指导。

Modes

模式

patch: small text fix, typo, stale path, or narrow rule change. Inspect the affected section and evidence only.
create: no suitable
```
AGENTS.md
```
exists. Run the analyzer, sample source/config/docs, then draft the smallest useful file.
update: existing file needs new or corrected guidance. Preserve valid rules, remove stale or duplicated material, and add only evidenced changes.
split/move: scope boundaries are changing. Inspect existing root and nested files, then use references/topology-and-handoff-guidance.md.
review: do not edit unless asked. Return findings by severity with evidence and residual risk.
exhaustive: monorepos, contract-heavy repos, safety-sensitive guidance, operational handoffs, major topology changes, or unclear evidence.

patch（补丁）：小型文本修正、错别字、过时路径或窄范围规则变更。仅检查受影响的章节和相关证据。
create（创建）：不存在合适的
```
AGENTS.md
```
文件。运行分析器，采样源码/配置/文档，然后起草最小可用版本的文件。
update（更新）：现有文件需要新增或修正指导内容。保留有效规则，移除过时或重复内容，仅添加有证据支撑的变更。
split/move（拆分/移动）：范围边界发生变化。检查现有根目录和嵌套文件，然后参考references/topology-and-handoff-guidance.md。
review（审核）：除非被要求，否则请勿编辑。按严重性排序返回发现结果，并附上证据和残留风险。
exhaustive（全面处理）：单体仓库、契约密集型仓库、安全敏感型指导、操作交接、重大拓扑变更或证据不明确的场景。

Workflow

工作流程

Pick the mode and target scope. Read the nearest existing
```
AGENTS.md
```
, nested
```
AGENTS.md
```
files that may overlap, and
```
git status --short
```
when available.
For create, update, split/move, or exhaustive modes, run
```
python <skill-root>/scripts/analyze_project.py --repo-root <target-repo> --format json
```
. Treat it as a sampling guide, not authority.
For normal authoring details, use references/normal-authoring.md. Inspect only the sources needed for the claims you will make.
Draft from the smallest applicable template in references/template-selection.md. Prefer assets/agentsmd-minimal.md unless the repo clearly needs a specialized template.
Keep evidence in working notes or the final summary. Add an evidence file only when the repo already owns one or the user asks.

Validate with

python <skill-root>/scripts/validate_agentsmd.py --repo-root <target-repo> --agents-file <target-agents-file> --mode <quick|standard|exhaustive>

and

python <skill-root>/scripts/semantic_check_agentsmd.py --repo-root <target-repo> --agents-file <target-agents-file>

选择模式和目标范围。阅读最近的现有
```
AGENTS.md
```
文件、可能存在重叠的嵌套
```
AGENTS.md
```
文件，若可用则查看
```
git status --short
```
输出。
对于创建、更新、拆分/移动或全面处理模式，运行
```
python <skill-root>/scripts/analyze_project.py --repo-root <target-repo> --format json
```
。将其视为采样指南，而非权威依据。
关于常规编写细节，参考references/normal-authoring.md。仅检查支撑你所提出声明所需的来源。
从references/template-selection.md中选择最小适用模板进行起草。除非仓库明确需要专用模板，否则优先使用assets/agentsmd-minimal.md。
将证据保存在工作笔记或最终摘要中。仅当仓库已有证据文件或用户要求时，才添加证据文件。

使用

python <skill-root>/scripts/validate_agentsmd.py --repo-root <target-repo> --agents-file <target-agents-file> --mode <quick|standard|exhaustive>

和

python <skill-root>/scripts/semantic_check_agentsmd.py --repo-root <target-repo> --agents-file <target-agents-file>

进行验证。

Rule Quality Rubric

规则质量标准

Keep a rule only when it is:

specific: names actual paths, commands, contracts, or local conventions.
current: supported by live files or user-provided current facts.
scoped: applies to this
```
AGENTS.md
```
directory tree.
behavioral: changes what an agent should do.
evidence-backed: traceable to inspected repo evidence.
safe: avoids secrets, unauthorized access, destructive commands, and production execution.
non-duplicative: does not restate global instructions, language basics, or README content.
concise: short enough to scan during normal coding work.

仅保留满足以下条件的规则：

具体明确：指明实际路径、命令、契约或本地约定。
实时有效：由现有文件或用户提供的当前事实支撑。
范围限定：适用于此
```
AGENTS.md
```
所在的目录树。
行为指导：改变Agent的操作方式。
证据支撑：可追溯至已检查的仓库证据。
安全合规：避免泄露机密、未授权访问、破坏性命令和生产环境执行操作。
无重复性：不重复全局指令、语言基础知识或README内容。
简洁精炼：简短到可在常规编码工作中快速浏览。

Escalation Matrix

升级参考矩阵

Load extra references only when the task needs them:

Trigger	Read
Tool, CLI, MCP, API, generated file, migration, schema, or public contract guidance	references/contract-bearing-agentsmd.md
Split, move, nested scopes, stale topology, or ownership handoff	references/topology-and-handoff-guidance.md
Live operations, degraded tools, manual dispatch, stop states, or environment resets	references/degraded-tool-surface.md, references/evidence-invalidation.md
Subagents or delegated review workflows	references/subagent-coordination-patterns.md
Python, TypeScript, other stack, Databricks/Spark, or ML-specific evidence prompts	references/language-specific/python-guidance.md, references/language-specific/typescript-guidance.md, references/language-specific/other-stack-guidance.md, references/domain-specific/databricks-spark.md, references/domain-specific/ml-projects.md
Review-only or judgment-heavy audit	references/manual-audit.md

仅在任务需要时加载额外参考内容：

触发场景	参考文档
工具、CLI、MCP、API、生成文件、迁移、架构或公共契约相关指导	references/contract-bearing-agentsmd.md
拆分、移动、嵌套范围、过时拓扑或所有权交接	references/topology-and-handoff-guidance.md
实时操作、工具降级、手动调度、停止状态或环境重置	references/degraded-tool-surface.md, references/evidence-invalidation.md
子Agent或委托审核工作流	references/subagent-coordination-patterns.md
Python、TypeScript、其他技术栈、Databricks/Spark或ML特定证据提示	references/language-specific/python-guidance.md, references/language-specific/typescript-guidance.md, references/language-specific/other-stack-guidance.md, references/domain-specific/databricks-spark.md, references/domain-specific/ml-projects.md
仅审核或需大量判断的审计	references/manual-audit.md

Final Response

最终响应要求

For edit modes, include changed files, rules added/changed/removed, evidence sources sampled, validation commands and results, and residual risks.

For review mode, lead with findings ordered by severity. Each finding needs the affected

AGENTS.md

section or line, supporting repo evidence, why it matters, and the recommended fix. Then list open questions, test/validation gaps, and a brief summary only after findings.

对于编辑模式，需包含变更的文件、新增/修改/移除的规则、采样的证据来源、验证命令及结果，以及残留风险。

对于审核模式，优先按严重性排序展示发现结果。每个发现需包含受影响的

AGENTS.md

章节或行号、支撑的仓库证据、影响原因及建议修复方案。之后列出未解决问题、测试/验证缺口，最后附上简短总结。

Deterministic Tools

确定性工具

Tool	Use
scripts/analyze_project.py	Stack, config, test, path, and suggestion inventory
scripts/validate_agentsmd.py	Structural validation
scripts/semantic_check_agentsmd.py	Path, command, link, and example validation
scripts/check_agentsmd_templates.py	Skill template and guidance hygiene
scripts/run_agentsmd_fixture_checks.py	Known fixture behavior for validator changes

工具	用途
scripts/analyze_project.py	技术栈、配置、测试、路径及建议清单
scripts/validate_agentsmd.py	结构验证
scripts/semantic_check_agentsmd.py	路径、命令、链接及示例验证
scripts/check_agentsmd_templates.py	技能模板及指导内容合规性检查
scripts/run_agentsmd_fixture_checks.py	验证器变更时的已知固定行为检查

References

参考资料

references/tool-contracts.md and references/template-selection.md - helper CLI contracts, modes, and templates
assets/agentsmd-minimal.md, assets/agentsmd-contract-bearing.md, assets/agentsmd-operational.md, assets/agentsmd-full.md - starter templates
assets/example-validated-agentsmd.md, assets/example-contract-bearing-agentsmd.md, assets/example-operational-agentsmd.md, assets/writing-tips.md - compact examples

references/tool-contracts.md 和 references/template-selection.md - 辅助CLI契约、模式及模板
assets/agentsmd-minimal.md, assets/agentsmd-contract-bearing.md, assets/agentsmd-operational.md, assets/agentsmd-full.md - 起始模板
assets/example-validated-agentsmd.md, assets/example-contract-bearing-agentsmd.md, assets/example-operational-agentsmd.md, assets/writing-tips.md - 精简示例