init

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When to use

使用场景

Use this skill when creating or updating

AGENTS.md

for a repository.

Use it especially when:

the current
```
AGENTS.md
```
is long, generic, or stale
agents repeatedly make the same avoidable mistakes
repository workflows changed and agent guidance needs pruning

在为仓库创建或更新

AGENTS.md

文件时使用本技能。

尤其适用于以下情况：

当前
```
AGENTS.md
```
过长、通用或已过时
Agent重复犯相同的可避免错误
仓库工作流发生变更，需要精简Agent指导内容

Instructions

指令

Treat

AGENTS.md

as a living list of non-discoverable landmines and workflow gotchas, not a codebase overview.

将

AGENTS.md

视为动态更新的非可发现“陷阱”与工作流注意事项列表，而非代码库概述。

Core rule: discoverability filter

核心规则：可发现性过滤器

Before adding any line, ask:

Can an agent discover this by reading the repo (
README
, code, config, scripts, directory tree)?

If yes: do not include it in
```
AGENTS.md
```
.
If no, and it materially affects task success/cost/safety: include it.

在添加任何内容前，请先自问：

Agent能否通过读取仓库内容（
README
、代码、配置、脚本、目录树）发现这一点？

如果能：请勿将其加入
```
AGENTS.md
```
。
如果不能，且该内容会对任务的成功/成本/安全性产生实质性影响：则将其加入。

What earns a line

可纳入的内容

Include only guidance that is:

Non-discoverable from repository files alone
Operationally significant (changes commands, outcomes, or safety)
Actionable (specific enough to execute)

Typical examples:

Non-standard tooling choices (e.g. use
```
uv
```
instead of
```
pip
```
)
Command caveats (e.g. tests must run with
```
--no-cache
```
due to fixture behavior)
Hidden constraints/landmines (deprecated directories still imported in production)
Critical local conventions that are not encoded in lint/tests/config

仅包含以下类型的指导：

非可发现：无法仅通过仓库文件获取
具有实际操作意义：会改变命令、结果或安全性
可执行：足够具体以便执行

典型示例：

非标准工具选择（例如：使用
```
uv
```
而非
```
pip
```
）
命令注意事项（例如：由于fixture特性，测试必须使用
```
--no-cache
```
运行）
隐藏约束/陷阱（已废弃的目录仍在生产环境中被引用）
未在lint/测试/配置中编码的关键本地规范

What to remove or avoid

需要移除或避免的内容

Do not include:

Tech stack summaries
Directory structure overviews
Architecture descriptions agents can infer from code
Generic best-practice advice
Rules already enforced by tooling (linters, typecheck, tests, CI)
Mandatory boilerplate headers unless the repo explicitly requires one

请勿包含：

技术栈概述
目录结构介绍
Agent可从代码中推断出的架构描述
通用最佳实践建议
已由工具（linter、类型检查、测试、CI）强制执行的规则
除非仓库明确要求，否则不要加入强制的模板头部

Recommended structure

Source files to check first

首先需要检查的源文件

Existing
```
AGENTS.md
```
```
README.md
```
```
PROJECT.md
```
(if present)
Cursor rules (
```
.cursor/rules/
```
or
```
.cursorrules
```
)
Copilot instructions (
```
.github/copilot-instructions.md
```
)
```
GEMINI.md
```
CI/workflow files and package manager config (for command/tooling mismatches)

AGENTS.md

exists, improve it incrementally instead of replacing it blindly.

现有
```
AGENTS.md
```
```
README.md
```
```
PROJECT.md
```
（如果存在）
Cursor规则（
```
.cursor/rules/
```
或
```
.cursorrules
```
）
Copilot指令（
```
.github/copilot-instructions.md
```
）
```
GEMINI.md
```
CI/工作流文件和包管理器配置（用于检查命令/工具不匹配问题）

如果

AGENTS.md

已存在，应逐步改进而非盲目替换。

Maintenance mindset

维护思路

AGENTS.md

is temporary guidance, not permanent configuration.

When recurring issues appear:

Prefer fixing the root cause in code/tooling (lint rule, test, script, structure)
Keep only the minimum instruction needed until the root cause is solved
Prune stale instructions aggressively

AGENTS.md

是临时指导文档，而非永久配置。

当出现重复问题时：

优先通过代码/工具（lint规则、测试、脚本、结构）修复根本原因
仅保留解决问题所需的最少指导内容，直至根本原因被解决
主动移除过时的指导内容

Quality gate before finalizing

最终定稿前的质量检查

For each line in

AGENTS.md

, verify:

Is it non-discoverable?
Is it still accurate today?
Does it materially reduce mistakes/cost/time?

Delete any line that fails one of these checks.

对于

AGENTS.md

中的每一条内容，验证：

它是否是非可发现的？
它当前是否仍然准确？
它是否能切实减少错误/成本/时间？

删除任何未通过上述任意一项检查的内容。