agents-md

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Writing Effective AGENTS.md Files

编写高效的AGENTS.md文件

AGENTS.md is a README for coding agents. It lives at the repo root and tells agents how to build, test, lint, navigate, and contribute to the project. Based on the agents.md open format (https://agents.md) and lessons from OpenAI's harness engineering approach.

AGENTS.md是面向编码Agent的说明文档，存放在仓库根目录，用于告知Agent如何构建、测试、检查代码、导航代码库以及为项目做贡献。它基于agents.md开放格式（https://agents.md）和OpenAI harness工程方法的实践经验。

Core Principle: Map, Not Manual

核心原则：做目录，而非手册

Keep AGENTS.md short (~100-150 lines). It's a table of contents, not an encyclopedia.

The "one big instruction file" approach fails because:

Context is scarce. A giant file crowds out the actual task and code.
Everything-is-important becomes nothing-is-important. Agents pattern-match locally instead of navigating intentionally.
It rots instantly. A monolithic manual becomes a graveyard of stale rules.
It's hard to verify. A single blob doesn't lend itself to freshness checks.

Point to deeper docs elsewhere. The agent starts with AGENTS.md and drills into references as needed.

保持AGENTS.md简洁（约100-150行）。它是一份目录，而非百科全书。

“单一巨型说明文件”的方法存在以下问题：

上下文稀缺：过大的文件会挤占实际任务和代码的空间。
全重要=全不重要：Agent会进行本地模式匹配，而非有目的地导航代码。
内容极易过时：单一的大型手册会很快成为过时规则的“墓地”。
难以验证：单一的大文件不便于进行内容新鲜度检查。

请指向其他更详细的文档。Agent从AGENTS.md入手，根据需要深入查阅参考资料。

What to Include

应包含的内容

1. Dev Environment & Commands

1. 开发环境与命令

The most immediately useful section. Concrete commands, not prose.

markdown

undefined

这是最实用的部分。请提供具体命令，而非冗长描述。

markdown

undefined

Commands

命令

Install:
```
npm install
```
Dev server:
```
npm run dev
```
Test single file:
```
npx vitest run path/to/test.ts
```
Test all:
```
npm test
```
Lint:
```
npm run lint
```
Format:
```
npm run format
```
Type check:
```
npm run typecheck
```


Include any prerequisites or non-obvious setup. If the project uses Docker, Nix, or
a custom build system, say so here.

安装依赖：
```
npm install
```
启动开发服务器：
```
npm run dev
```
测试单个文件：
```
npx vitest run path/to/test.ts
```
测试所有文件：
```
npm test
```
代码检查：
```
npm run lint
```
代码格式化：
```
npm run format
```
类型检查：
```
npm run typecheck
```


请包含任何前置条件或非显而易见的配置步骤。如果项目使用Docker、Nix或自定义构建系统，请在此说明。

2. Repository Structure

2. 仓库结构

Key paths and what lives where. Keep it high-level — 1 line per directory.

markdown

undefined

关键路径及其用途。保持高层面描述——每个目录用1行说明。

markdown

undefined

Repository Structure

仓库结构

```
src/api/
```
— HTTP API layer, routes and validation
```
src/store/
```
— Database access, all SQL lives here
```
src/worker/
```
— Background job processing
```
src/types/
```
— Shared domain types
```
tests/
```
— Test files mirror source structure
```
docs/
```
— Architecture and design documentation


For the full treatment of how to write an architecture codemap with boundaries
and invariants, see the `architecture-md` skill.

```
src/api/
```
— HTTP API层，包含路由和验证逻辑
```
src/store/
```
— 数据库访问层，所有SQL代码都在此处
```
src/worker/
```
— 后台任务处理模块
```
src/types/
```
— 共享领域类型定义
```
tests/
```
— 测试文件，与源码结构镜像对应
```
docs/
```
— 架构与设计文档


关于如何编写包含边界和约束的架构代码地图，请参考`architecture-md`技能文档。

3. Architecture Boundaries

3. 架构边界

What can depend on what. What's deliberately absent. These are the rules agents violate most often without explicit guidance.

markdown

undefined

模块间的依赖规则，以及刻意排除的内容。这些是Agent在没有明确指导时最容易违反的规则。

markdown

undefined

Architecture Boundaries

架构边界

API layer never accesses the database directly — always goes through
```
src/store/
```
```
src/types/
```
has zero dependencies on other source modules
Workers communicate via the store interface, never import API code
No circular dependencies between top-level modules

undefined

API层永远不直接访问数据库——必须通过
```
src/store/
```
层
```
src/types/
```
不依赖任何其他源码模块
任务处理模块通过store接口通信，从不导入API代码
顶层模块之间禁止循环依赖

undefined

4. Coding Standards (Non-Obvious Only)

4. 编码规范（仅列出非显而易见的规则）

Don't list things the agent already knows (like "use const over let"). List only project-specific conventions the agent couldn't infer from reading the code.

markdown

undefined

不要列出Agent已经知晓的内容（比如“优先使用const而非let”）。仅列出Agent无法通过阅读代码推断出的项目特定约定。

markdown

undefined

Coding Standards

编码规范

Strict TypeScript — no
```
any
```
, no
```
as
```
casts except in test files
Errors: use
```
Result<T, E>
```
pattern from
```
src/types/result.ts
```
, not thrown exceptions
Logging: always use structured logger from
```
src/logger.ts
```
, never
```
console.log
```
Naming: database columns are snake_case, TypeScript properties are camelCase

undefined

严格遵循TypeScript规范——禁止使用
```
any
```
，除测试文件外禁止使用
```
as
```
类型断言
错误处理：使用
```
src/types/result.ts
```
中的
```
Result<T, E>
```
模式，而非抛出异常
日志：始终使用
```
src/logger.ts
```
中的结构化日志工具，禁止使用
```
console.log
```
命名规则：数据库列使用snake_case，TypeScript属性使用camelCase

undefined

5. Testing Instructions

5. 测试说明

How to run tests, where they live, patterns to follow, what to cover.

markdown

undefined

如何运行测试、测试文件位置、遵循的模式以及测试覆盖范围。

markdown

undefined

Testing

测试

Tests live next to source:
```
src/foo.ts
```
->
```
src/foo.test.ts
```
Use
```
describe
```
/
```
it
```
blocks, not
```
test()
```
Mock external services, never hit real APIs in tests
New features require tests — cover success, failure, and edge cases
Run relevant tests before submitting:
```
npx vitest run src/path/
```

undefined

测试文件与源码放在一起：
```
src/foo.ts
```
对应
```
src/foo.test.ts
```
使用
```
describe
```
/
```
it
```
代码块，禁止使用
```
test()
```
模拟外部服务，测试中绝不调用真实API
新功能必须包含测试——覆盖成功、失败和边缘场景
提交前运行相关测试：
```
npx vitest run src/path/
```

undefined

6. PR & Commit Conventions

6. 提交与PR约定

markdown

undefined

markdown

undefined

Commits & PRs

提交与PR规范

Conventional commits:
```
feat:
```
,
```
fix:
```
,
```
refactor:
```
,
```
test:
```
,
```
docs:
```
PR title format:
```
type(scope): description
```
Run
```
npm run lint && npm test
```
before committing
Keep PRs focused — one logical change per PR

undefined

符合Conventional Commits规范：
```
feat:
```
、
```
fix:
```
、
```
refactor:
```
、
```
test:
```
、
```
docs:
```
PR标题格式：
```
type(scope): description
```
提交前运行
```
npm run lint && npm test
```
PR需聚焦单一逻辑变更

undefined

7. Boundaries (Do / Don't / Ask First)

7. 边界规则（允许/禁止/需先询问）

Explicit guardrails prevent costly mistakes.

markdown

undefined

明确的约束可以避免代价高昂的错误。

markdown

undefined

Boundaries

边界规则

Never: commit secrets, credentials, or tokens
Never: use destructive git operations (force push, hard reset) without asking
Never: edit generated files by hand when a generation workflow exists
Ask first: large cross-module refactors, new dependencies, migration changes

undefined

禁止：提交密钥、凭据或令牌
禁止：未经询问使用破坏性Git操作（强制推送、硬重置）
禁止：当有生成工作流时，手动编辑生成的文件
需先询问：跨模块的大型重构、新增依赖、迁移变更

undefined

8. References

8. 参考资料

Pointers to deeper documentation. This is where the "table of contents" pattern pays off — keep AGENTS.md lean, point elsewhere for depth.

markdown

undefined

指向更详细文档的链接。这正是“目录”模式的优势——保持AGENTS.md简洁，将详细内容放在其他文档中。

markdown

undefined

References

参考资料

Architecture: see
```
ARCHITECTURE.md
```
API docs: see
```
docs/api-reference.md
```
Design decisions: see
```
docs/design-docs/
```
Deployment: see
```
docs/deployment.md
```

undefined

架构文档：查看
```
ARCHITECTURE.md
```
API文档：查看
```
docs/api-reference.md
```
设计决策：查看
```
docs/design-docs/
```
部署文档：查看
```
docs/deployment.md
```

undefined

What to Omit

应排除的内容

README content — Don't duplicate project description, installation for end users, badges
Language basics — Don't explain TypeScript/Python/Rust fundamentals
Every lint rule — Only list non-obvious, project-specific ones
Prose paragraphs — Use bullet points and code blocks. Agents parse structure, not essays
Things that change every PR — Only include stable conventions
Implementation details — "How the scheduler works" belongs in ARCHITECTURE.md, not here

README内容——不要重复项目描述、面向终端用户的安装步骤、徽章等
语言基础——不要解释TypeScript/Python/Rust的基础知识
所有代码检查规则——仅列出非显而易见的项目特定规则
长篇段落——使用项目符号和代码块。Agent能解析结构化内容，而非散文式文字
每次PR都会变更的内容——仅包含稳定的约定
实现细节——“调度器如何工作”属于ARCHITECTURE.md的内容，而非此处

Monorepo Pattern

单体仓库模式

Root AGENTS.md for global rules. Nested AGENTS.md per package for package-specific instructions. The closest file to the edited code wins.

AGENTS.md                    # global: commit conventions, CI, shared tooling
packages/api/AGENTS.md       # API-specific: routes, middleware, auth patterns
packages/worker/AGENTS.md    # worker-specific: job patterns, retry behavior
packages/shared/AGENTS.md    # shared lib: no side effects, pure functions only

Keep nested files focused on what's different about that package. Don't repeat global rules — the agent reads both the nearest file and the root.

根目录的AGENTS.md存放全局规则。每个子包下的AGENTS.md存放包特定的说明。离编辑代码最近的文件优先级最高。

AGENTS.md                    # 全局规则：提交约定、CI、共享工具
packages/api/AGENTS.md       # API包特定：路由、中间件、认证模式
packages/worker/AGENTS.md    # 任务处理包特定：任务模式、重试机制
packages/shared/AGENTS.md    # 共享库特定：无副作用、仅纯函数

子包下的文件应聚焦于该包的独特规则。不要重复全局规则——Agent会同时读取最近的文件和根目录文件。

Anti-Patterns

反模式

The novel — 500+ lines of prose. Nobody reads it, agent or human.
Stale rules — "Always use library X" when the team switched to Y months ago. Stale rules are worse than no rules — agents follow them faithfully.
Redundant guidance — Restating what the linter already enforces. If
```
eslint
```
catches it, don't list it.
Vague instructions — "Write clean code" is useless. "Use structured logger, never console.log" is actionable.
Missing commands — The agent should be able to build, test, and lint from AGENTS.md alone without reading CI config.

“长篇小说”——500行以上的散文式内容。无论是Agent还是人类都不会阅读。
过时规则——“始终使用库X”但团队几个月前就切换到Y了。过时规则比没有规则更糟——Agent会严格遵循它们。
冗余指导——重复代码检查工具已经能强制执行的规则。如果eslint能检测到，就不要列出来。
模糊指令——“编写整洁的代码”毫无用处。“使用结构化日志工具，禁止使用console.log”才是可执行的指令。
缺失关键命令——Agent应仅通过AGENTS.md就能完成构建、测试和代码检查，无需阅读CI配置。

agents-md

Original

Translation

Writing Effective AGENTS.md Files

编写高效的AGENTS.md文件

Core Principle: Map, Not Manual

核心原则：做目录，而非手册

What to Include

应包含的内容

1. Dev Environment & Commands

1. 开发环境与命令

Commands

命令

2. Repository Structure

2. 仓库结构

Repository Structure

仓库结构

3. Architecture Boundaries

3. 架构边界

Architecture Boundaries

架构边界

4. Coding Standards (Non-Obvious Only)

4. 编码规范（仅列出非显而易见的规则）

Coding Standards

编码规范

5. Testing Instructions

5. 测试说明

Testing

测试

6. PR & Commit Conventions

6. 提交与PR约定

Commits & PRs

提交与PR规范

7. Boundaries (Do / Don't / Ask First)

7. 边界规则（允许/禁止/需先询问）

Boundaries

边界规则

8. References

8. 参考资料

References

参考资料

What to Omit

应排除的内容

Monorepo Pattern

单体仓库模式

Anti-Patterns

反模式

Quality Checklist

质量检查清单