Back to Details

create-agents

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Include only what genuinely helps, ruthlessly cut everything else. These principles apply regardless of language or framework — C#, Python, TypeScript all follow the same rules.
只保留真正有帮助的内容，果断删除其他所有无关内容。这些原则适用于所有语言和框架——C#、Python、TypeScript均遵循相同规则。

Core Principles

核心原则

  • Minimum viable requirements. Ask of each line: "Does this earn its cost on nearly every session?" If not, cut it. Every line loads on every session — brevity has direct cost benefits.
  • Two failure modes. (1) Length — as instruction count grows, compliance degrades uniformly, not just for new instructions. (2) Task-irrelevant requirements — correct instructions not needed for the current task still get followed, increasing cost and reducing success.
  • Don't send an LLM to do a linter's job. Style guidelines add instructions and irrelevant context. Use actual linters, wired to hooks if the harness supports it.
  • Never auto-generate. Auto-generated files are stuffed with documentation the agent can read directly. Write by hand.
  • Architecture and overview sections have weak evidence in root files. Exception: scoped sub-files can carry richer context — they only load when the agent is already working in that area.
  • 最小可行要求：对每一行内容都要问：“这在几乎每次会话中都能体现出价值吗？”如果不能，就删掉。每一行内容都会在每次会话中加载——简洁性直接关系到成本效益。
  • 两种失效模式：(1) 冗长——随着指令数量增加，Agent的合规性会整体下降，而不仅仅是针对新指令。(2) 与任务无关的要求——即使当前任务不需要某些正确的指令，Agent仍会执行，这会增加成本并降低成功率。
  • 不要让LLM做代码检查工具（linter）的工作：样式指南会增加指令和无关上下文。请使用实际的linter，如果工具支持的话，将其与钩子（hooks）关联。
  • 绝不自动生成：自动生成的文件包含大量Agent可以直接读取的文档内容。请手动编写。
  • 根文件中的架构和概述部分作用有限：例外情况：范围化的子文件可以包含更丰富的上下文——它们仅在Agent进入对应工作区域时才会加载。

Single File vs. Hierarchical System

单文件与分层系统

Single root file for simple projects: one app, one language, one team. Keep it under 100 lines.
Hierarchical system for monorepos, large codebases, or multiple apps/packages/services. The harness auto-loads AGENTS.md files as the agent navigates — 
apps/web/AGENTS.md
only loads when the agent works there.
单根文件适用于简单项目：单个应用、单一语言、单个团队。文件长度控制在100行以内。
分层系统适用于单体仓库（monorepos）、大型代码库或包含多个应用/包/服务的项目。当Agent在代码库中导航时，工具会自动加载对应的AGENTS.md文件——例如
apps/web/AGENTS.md
仅在Agent处理该区域的工作时才会加载。

Hierarchical Rules

分层规则

Place files at semantic boundaries — where responsibilities shift or contracts matter. Not in every directory.
Least Common Ancestor for shared knowledge — shared facts belong in the shallowest file covering all relevant paths. Never duplicate across siblings.
Downlink from parent to children — reference child files so the agent can follow the hierarchy:
undefined
将文件放置在语义边界处——即职责转移或契约重要的位置。不要在每个目录都放置。
共享知识放在最近公共祖先（Least Common Ancestor）文件中——共享信息应放在覆盖所有相关路径的最浅层文件中。绝不要在同级文件中重复。
从父文件到子文件的下行引用——在父文件中引用子文件，以便Agent可以遵循层级结构：
undefined

Sub-areas

Sub-areas

  • packages/ui/AGENTS.md
    — component library conventions
  • apps/api/AGENTS.md
    — API server, auth, database access

**Build leaf-first** — write deepest files first. Parents summarize children's AGENTS.md files, not raw code.

**Scoped files can be richer** — entry points, invariants, and pitfalls are appropriate in a file that only loads for one service.
  • packages/ui/AGENTS.md
    — component library conventions
  • apps/api/AGENTS.md
    — API server, auth, database access

**从叶子节点开始构建**——先编写最底层的文件。父文件应总结子文件AGENTS.md的内容，而非直接引用原始代码。

**范围化文件可以更丰富**——针对单个服务的文件中可以包含入口点、不变量和注意事项等内容。

Writing a New AGENTS.md

编写新的AGENTS.md文件

markdown
undefined
markdown
undefined

Project or Area Name

Project or Area Name

One sentence: what it does and why it exists.
One sentence: what it does and why it exists.

Stack

Stack

Tech stack. Package manager or build tool (be explicit — agents assume defaults). Path aliases if non-standard. Infrastructure if non-obvious (DB, cache, queue). Directory tree only if ownership boundaries aren't obvious. 1-2 levels max.
Tech stack. Package manager or build tool (be explicit — agents assume defaults). Path aliases if non-standard. Infrastructure if non-obvious (DB, cache, queue). Directory tree only if ownership boundaries aren't obvious. 1-2 levels max.

Development

Development

Verification commands only: typecheck, lint, test. What to run before finishing. Skip inferrable commands. Include non-obvious ones whose names don't reveal purpose (e.g. 
cf-typegen
, 
db:migrate
, 
dotnet ef database update
).
Verification commands only: typecheck, lint, test. What to run before finishing. Skip inferrable commands. Include non-obvious ones whose names don't reveal purpose (e.g. 
cf-typegen
, 
db:migrate
, 
dotnet ef database update
).

Conventions

Conventions

Only things the agent can't infer from reading the code. No style rules — use a linter.

A Reference Docs section is fine — only add a pointer if the agent genuinely needs to read it before working in that area.
Only things the agent can't infer from reading the code. No style rules — use a linter.

可以添加参考文档部分——只有当Agent在该区域工作前确实需要阅读相关文档时，才添加指向该文档的链接。

Auditing an Existing AGENTS.md

审核现有的AGENTS.md文件

Measure first: total lines, distinct instructions, style rules, overview sections. Classify each: essential and universal (keep), task-specific or architectural (cut or demote to pointer), style/lint rule (remove), redundant or stale (remove).
For hierarchical systems: check whether root content belongs in a scoped sub-file, and whether sub-files duplicate knowledge that belongs at their LCA.
Present before/after line counts, what was cut and why, and the complete rewritten file.
首先进行度量：统计总行数、不同指令数量、样式规则数量、概述部分内容。对每部分进行分类：必要且通用的内容（保留）、特定任务或架构相关内容（删除或降级为链接）、样式/代码检查规则（删除）、冗余或过时内容（删除）。
对于分层系统：检查根文件中的内容是否应该放在范围化的子文件中，以及子文件中是否存在应放在最近公共祖先（LCA）文件中的重复知识。
展示修改前后的行数对比、删除的内容及原因，以及完整的重写后的文件。

Maintenance

维护

On significant changes, update affected AGENTS.md files leaf-first. A CI agent that detects changed files and proposes updates is worth building.
当代码库发生重大变更时，从叶子节点开始更新受影响的AGENTS.md文件。值得构建一个CI Agent来检测变更的文件并提出更新建议。

Anti-Patterns to Flag

需要注意的反模式

Command dump — inferrable commands like 
dev
, 
build
, 
start
listed in full.
Deep tree — directory structures more than 2 levels deep. Replace with a sentence.
Architecture tour — system overviews in a root file. One sentence of purpose, or push into a scoped sub-file.
Style guide — formatting rules. Use a linter.
Code museum — large inline snippets. Use 
file:line
references.
Hotfix graveyard — accumulated one-off corrections. Delete them.
Auto-generated blob — output from auto-init commands. Rewrite from scratch.
Stale reference — outdated paths or commands. Update or remove.
Duplicated siblings — the same fact in two sub-files. Hoist to their LCA.
命令堆砌——列出所有可推断的命令，如
dev
、
build
、
start
。
深层目录树——目录结构超过2级。应替换为一句话描述。
架构漫游——在根文件中包含系统概述。应简化为一句话的用途描述，或者移到范围化的子文件中。
样式指南——包含格式化规则。应使用linter来处理。
代码博物馆——包含大型内联代码片段。应使用
file:line
的引用方式。
临时修复墓地——累积了大量一次性的修复内容。应删除这些内容。
自动生成的大段内容——自动初始化命令生成的输出内容。应从头重写。
过时引用——包含过时的路径或命令。应更新或删除。
同级文件重复——在两个同级子文件中存在相同的信息。应将其提升到它们的最近公共祖先（LCA）文件中。