Back to Details

agents-md

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
This skill covers agent context files — AGENTS.md (OpenCode, multi-agent harnesses) and CLAUDE.md (Claude Code). The principles are the same; only the loading mechanics differ. When the user's harness uses CLAUDE.md, substitute accordingly. These principles apply regardless of language or framework.
Include only what genuinely helps, cut what doesn't earn its place — but never delete useful information without relocating it first.
本技能覆盖Agent上下文文件——AGENTS.md（适用于OpenCode、多Agent运行框架）和CLAUDE.md（适用于Claude Code）。两者适用的原则一致，仅加载机制不同。如果用户使用的框架采用CLAUDE.md，对应替换即可。这些原则不受编程语言或框架的限制。
仅保留真正有帮助的内容，删掉没有存在价值的内容——但在转移有用信息之前绝对不要直接删除。

References

参考资料

Read on demand — do not load all reference files at once.
When the user mentions...Read
Auditing an existing file
references/audit-example.md
Testing, TDD, test conventions
references/tdd.md
按需读取——不要一次性加载所有参考文件。
当用户提到...读取
审核现有文件
references/audit-example.md
测试、TDD、测试规范
references/tdd.md

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.
  • Compaction is not summarization. When reducing a file, relocate correct content to scoped sub-files or 
    @import
    targets — never paraphrase or drop details. The goal is fewer lines in the root file, not fewer lines total.
  • 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.
  • Don't ship auto-generated files unedited. Tools like 
    /init
    are a fine starting point, but auto-generated output is stuffed with documentation the agent can already read. Always rewrite by hand before committing.
  • 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）长度问题——随着指令数量增加，模型对所有指令的遵从度都会均匀下降，不仅仅是新增指令。（2）任务无关要求——当前任务不需要的正确指令依然会被模型执行，会增加成本、降低成功率。
  • 精简不等于摘要。 缩减文件体积时，把正确内容转移到范围明确的子文件或者
    @import
    目标中——绝对不要改写原意或者丢失细节。目标是减少根文件的行数，而不是减少总内容行数。
  • 不要让LLM做linter的工作。 风格规范会增加指令和无关上下文，直接使用实际的linter，如果框架支持可以配置到钩子中。
  • 不要直接提交自动生成的文件。 
    /init
    这类工具可以作为不错的起点，但自动生成的输出里塞满了Agent本身就能读取的文档，提交前一定要手动重写。
  • 根文件里的架构和概览部分价值证据不足。 例外：范围明确的子文件可以承载更丰富的上下文，它们只会在Agent处理对应领域内容时才会加载。

Single File vs. Hierarchical System

单文件模式 vs 分层体系

Single root file for simple projects: one app, one language, one team. Target under 200 lines — long enough to cover real conventions, short enough that compliance doesn't degrade. Every line still needs to earn its place.
Hierarchical system for monorepos, large codebases, or multiple apps/packages/services. The harness auto-loads context files as the agent navigates — 
apps/web/AGENTS.md
only loads when the agent works there.
单根文件适用于简单项目：单应用、单语言、单团队。目标控制在200行以内——足够覆盖实际规范，又短到不会降低指令遵从度，每一行都要保证有存在价值。
分层体系适用于monorepo、大型代码库、多应用/包/服务的场景。框架会在Agent导航时自动加载对应上下文文件——
apps/web/AGENTS.md
只会在Agent处理该目录内容时加载。

Managing File Size Without Losing Content

控制文件大小且不丢失内容的方案

When a root file grows past ~200 lines, use these mechanisms to relocate content rather than delete it:
@import
pointers — reference external files that load alongside the root file:
markdown
undefined
当根文件行数超过200行左右时，使用以下机制转移内容而不是直接删除：
@import
指针——引用和根文件一起加载的外部文件：
markdown
undefined

Reference

参考

  • @docs/api-conventions.md
  • @docs/testing-strategy.md

**Path-scoped rules** (Claude Code `.claude/rules/`) — instructions that only load when the agent touches matching files:
```markdown
  • @docs/api-conventions.md
  • @docs/testing-strategy.md

**路径范围规则**（Claude Code `.claude/rules/`）——仅当Agent修改匹配路径的文件时才会加载的指令：
```markdown

.claude/rules/api-design.md

.claude/rules/api-design.md

paths:
  • "src/api/**"
All API endpoints must include input validation and OpenAPI comments.

**Scoped sub-files** — AGENTS.md or CLAUDE.md in subdirectories, loaded on demand when the agent works in that area.

Choose the mechanism that matches the harness. The principle is the same: move content to where it loads only when relevant, instead of deleting it.
paths:
  • "src/api/**"
All API endpoints must include input validation and OpenAPI comments.

**范围子文件**——存放在子目录下的AGENTS.md或CLAUDE.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
放在语义边界处——放在职责划分或者契约定义的位置，不需要每个目录都放。
共享知识放在最近公共祖先目录——共享信息应该放在覆盖所有相关路径的最浅层文件中，绝对不要在同级目录间重复。
父文件指向子文件——在父文件中引用子文件，方便Agent顺着层级查找：
undefined

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
    — 组件库规范
  • apps/api/AGENTS.md
    — API服务、鉴权、数据库访问

**从叶子节点开始构建**——先写最深层的文件，父文件汇总子目录AGENTS.md的内容，而不是直接汇总原始代码。

**范围文件可以更丰富**——仅给单个服务加载的文件里可以包含入口点、不变量、常见陷阱这类内容。

Writing a New AGENTS.md

编写新的AGENTS.md

markdown
undefined
markdown
undefined

Project or Area Name

项目或领域名称

One sentence: what it does and why it exists.
一句话说明它的功能和存在意义。

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.
技术栈信息，明确说明包管理器或构建工具（Agent会默认使用通用配置，所以一定要写清楚）。非标准路径别名，非显性的基础设施配置（数据库、缓存、队列）。仅当所有权边界不清晰时才放目录结构，最多展示1-2层。

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
).
仅列校验命令：类型检查、lint、测试，以及任务完成前需要运行的命令。省略可推断的命令，包含名称无法直观体现用途的非通用命令（比如
cf-typegen
、
db:migrate
、
dotnet ef database update
）。

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.
仅列Agent无法通过阅读代码推断的要求，不要放风格规则——用linter实现。

可以加参考文档板块——仅当Agent在该领域工作前确实需要读取对应内容时才添加引用指针。

Auditing an Existing AGENTS.md

审核现有AGENTS.md

Auditing is refactoring, not summarization. Every piece of correct, useful information must end up somewhere — in the root file, a scoped sub-file, a rules file, or an 
@import
target. Never compress or summarize content to reduce line count. If a detail was worth writing, it's worth preserving in the right location.
审核是重构，不是摘要。 每一条正确、有用的信息都必须有归宿：可以放在根文件、范围子文件、规则文件或者
@import
目标中。绝对不要为了减少行数压缩或者摘要内容，如果一个细节值得写，就值得在正确的位置保留。

Audit Workflow

审核工作流

  1. Measure. Count total lines, distinct instructions, style rules, overview sections.
  2. Classify each instruction:
    • Essential and universal → keep in root file
    • Correct but scoped to a specific area → move to a scoped sub-file or path-scoped rule, add a pointer from root
    • Style/lint rule → remove (enforce via linter/hook instead)
    • Redundant, stale, or inferrable → remove
  3. Relocate before removing. For any content classified as "move": create the destination file with the full original content, then replace it in the root with a pointer. Do not paraphrase or summarize the moved content.
  4. For hierarchical systems: check whether root content belongs in a scoped sub-file, and whether sub-files duplicate knowledge that belongs at their LCA.
  5. Present results: before/after line counts per file, what was moved and where, what was removed and why, and the complete rewritten file(s) including any new sub-files.
  1. 统计。 统计总行数、不同指令数量、风格规则、概览板块数量。
  2. 给每条指令分类：
    • 核心通用内容 → 保留在根文件
    • 正确但仅适用于特定领域 → 移动到范围子文件或者路径规则文件，在根文件加引用指针
    • 风格/lint规则 → 删除（改用linter/钩子来强制校验）
    • 冗余、过时、可推断的内容 → 删除
  3. 先转移再删除。 对于分类为「移动」的内容：先把完整原始内容写入目标文件，再把根文件里的对应内容替换为引用指针，不要改写或者摘要被移动的内容。
  4. 针对分层体系： 检查根文件内容是否应该放在范围子文件中，以及子文件是否有重复内容可以上移到最近公共祖先文件。
  5. 展示结果： 每个文件修改前后的行数对比，什么内容被移动到了哪里，什么内容被删除及原因，以及完整的重写后文件（包括所有新增的子文件）。

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来检测文件变更并自动提出更新建议，投入产出比很高。

Testing Effectiveness

效果测试

An AGENTS.md is working if the agent's behavior changes. After writing or auditing:
  1. Run a representative task without the file and note where the agent deviates from your expectations.
  2. Add/update instructions targeting those deviations.
  3. Re-run the same task and verify the behavior shifts.
If the agent keeps doing something wrong despite having a rule against it, the file is likely too long and the rule is getting lost. If the agent asks questions that are answered in the file, the phrasing may be ambiguous.
如果Agent的行为能按照预期改变，说明AGENTS.md是有效的。编写或审核完成后：
  1. 不加载该文件运行一个典型任务，记录Agent不符合预期的行为点。
  2. 针对这些偏差点新增/更新对应指令。
  3. 重新运行同一个任务，验证行为是否符合预期。
如果即使加了对应的规则，Agent还是不断出错，说明文件可能太长，规则被淹没了。如果Agent问的问题在文件里已经有答案，说明表述可能有歧义。

Monorepo Exclusions

Monorepo排除规则

In large monorepos, ancestor context files from other teams may load and add irrelevant context. Claude Code supports 
claudeMdExcludes
in 
.claude/settings.local.json
to skip specific files:
json
{
  "claudeMdExcludes": [
    "**/other-team/CLAUDE.md",
    "/repo/root/unrelated-service/.claude/rules/**"
  ]
}
This keeps each team's agent context focused without affecting other teams.
在大型monorepo中，其他团队的上级上下文文件可能会被加载，带来无关内容。Claude Code支持在
.claude/settings.local.json
中配置
claudeMdExcludes
来跳过特定文件：
json
{
  "claudeMdExcludes": [
    "**/other-team/CLAUDE.md",
    "/repo/root/unrelated-service/.claude/rules/**"
  ]
}
这可以让每个团队的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 by hand before committing.
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实现。
代码博物馆——放大量内联代码片段，改用
文件:行号
引用即可。
热修坟场——积累大量一次性修正规则，直接删除即可。
自动生成大文件——直接提交自动初始化命令的输出，提交前一定要手动重写。
过时引用——路径或者命令已经过期，要么更新要么删除。
同级重复——同一个信息出现在两个子文件中，上移到它们的最近公共祖先文件中。