来自 open source 的 AGENTS.md 例子

理解 AGENTS.md 最快的方法，是读好例子。不是完美例子。是好例子。那种能让 agent 在前 60 秒看懂 repo 的例子：这个项目是什么，怎么跑，什么不能碰，truth 在哪里，哪些本地坑已经伤过人。

这篇会走一遍我希望在真实 open-source repos 里看到的代表性 AGENTS.md patterns。有些参考了 public conventions，包括 OpenAI 的 Codex repo 和更大的 AGENTS.md ecosystem。其他是从 audit pattern 合成的：Vercel-style frontend apps、Rust backends、Python uv projects、monorepos。把这些 snippets 当 copy-paste 起点，不要当神圣模板。

重点不是每个项目都该长一样。重点是好的 AGENTS.md 会让重要差异变得明显。

例子一：Codex-style repository guidance

大型 agent-facing repos 通常需要关于 code shape、review discipline、generated artifacts、tests 的规则。有用模式是具体，但不要把文件写成 handbook。

# AGENTS.md

## Repository guidelines
- Prefer small modules. If a Rust file is already over 800 lines, add new
  behavior in a new module unless there is a documented reason not to.
- Avoid helper functions that are referenced only once.
- When adding or changing a public API, update the docs in docs/ in the same PR.
- Use existing test helpers before adding new fixtures.

## Rust style
- Prefer exhaustive match statements. Avoid wildcard arms unless the type is
  intentionally open-ended.
- Avoid bool parameters in new APIs. Use enums, named methods, or newtypes when
  the callsite would otherwise read like `foo(false)`.
- Prefer comparing whole values in tests over asserting one field at a time.

## Validation
- Run cargo test for the crate you touched.
- UI text or snapshot output changes require updated snapshots.

为什么有效：每条规则都会改变 edit。“Avoid bool parameters” 会影响 API design。“Update docs” 产生可 review 的 artifact。“Run cargo test for the crate you touched” 把 validation scope 收窄，而不是假装每个 contributor 都能每次跑全世界。

这个文件也诚实地承认 AGENTS.md 能做什么。它没有说 “ensure quality”。它命名了 review 和 tests 能抓到的 behaviors。

例子二：Vercel-style frontend project

Frontend AGENTS.md 最容易在变成 design manifesto 时失败。agent 需要 stack facts、component boundaries、validation commands。

# AGENTS.md

## Project facts
This is a Next.js marketing and docs site. App routes live in app/.
Shared UI primitives live in components/ui/. Content lives in content/.

## Commands
- Install: pnpm install
- Dev server: pnpm dev
- Build: pnpm build
- Lint: pnpm lint
- Typecheck: pnpm typecheck

## UI rules
- Use components/ui primitives before adding new visual primitives.
- Keep cards to repeated content items, modals, or tool panels. Do not wrap
  entire page sections in cards.
- Do not introduce a new color scale without updating tailwind.config.ts.
- Images used above the fold must have explicit width/height or aspect-ratio.

## Content rules
- Blog slugs come from content/blog filenames.
- Each new post needs a title, description, canonical URL, and OG image entry.
- Do not edit generated .next/ or out/ output by hand.

为什么有效：这些规则具体到能避免常见 agent mistakes。agent 知道 content 在哪，哪些 command 真实，应该复用哪个 design system。“cards” 规则有观点，但可证伪。reviewer 可以指着一个被 card 包住的 page section 说规则被违反了。

Content section 是杠杆最高的部分。agents 经常加 markdown post，却忘记 sitemap、metadata 或 OG images。好的 AGENTS.md 会把这些 coupled files 写出来，让 change 完整落地。

例子三：Rust 和 Cargo backend

Rust repos 需要另一种 AGENTS.md。agent 需要 crate boundaries、migration policy、test expectations。

# AGENTS.md

## Project facts
This is a Rust backend workspace. Crates live under crates/.
Database migrations live in migrations/. The public HTTP API lives in
crates/api/.

## Commands
- Format: cargo fmt --all
- Lint: cargo clippy --workspace --all-targets -- -D warnings
- Test touched crate: cargo test -p <crate>
- Test workspace: cargo test --workspace

## Workspace rules
- Do not add new workspace dependencies without checking workspace Cargo.toml.
- Keep crate boundaries explicit. Shared code belongs in crates/core only when
  it has at least two consumers.
- Do not use wildcard imports outside tests.
- New public errors must implement thiserror::Error and include a stable code.

## Database rules
- Migrations must be forward-only in production.
- Every migration needs a comment explaining the rollout assumption.
- Schema changes require an integration test or a documented reason in the PR.

为什么有效：Rust agents 很容易过度 generalize。它们太早加 shared utilities，把 errors 藏进 strings，或者只跑 local unit test。这个文件把压力点写明。它也不教 Rust 本身。AGENTS.md 不是解释 ownership 或 lifetimes 的地方。它是解释这个 repo 选择的地方。

“shared code” 规则尤其有用。agents 很爱抽 helper。规则设了门槛：至少两个 consumers。这能挡住 abstraction churn。

例子四：使用 uv 的 Python project

Python projects 常常死在 environment ambiguity。agent 看到 requirements.txt、pyproject.toml，也许还有 poetry.lock，也许有 uv.lock，然后开始猜。AGENTS.md 应该移除这个猜测。

# AGENTS.md

## Project facts
This is a Python 3.12 service. Dependency and environment management use uv.
Application code lives in src/service/. Tests live in tests/.

## Commands
- Install: uv sync
- Run service: uv run python -m service
- Unit tests: uv run pytest tests/unit
- Full tests: uv run pytest
- Lint and format: uv run ruff check . && uv run ruff format --check .
- Typecheck: uv run pyright

## Python rules
- Do not use pip, poetry, or conda commands in this repo.
- Do not edit uv.lock by hand. Run uv lock when dependency metadata changes.
- Public functions require type annotations.
- New external HTTP calls must set an explicit timeout.
- Do not catch Exception unless the handler re-raises or logs enough context.

## Configuration
- Environment variables are documented in docs/configuration.md.
- Never print secret values. Refer to secrets by environment variable name only.

为什么有效：它消除了 package-manager 分支。“Use uv” 不够；文件给了 exact commands。error-handling 和 timeout rules 都很具体。secret rule 是 operational，也能 review。

重点是 uv.lock 没被当作普通 text file。agents 很习惯编辑任何能打开的东西。AGENTS.md 应该说清楚哪些文件是 tool-owned。

例子五：apps 和 packages 混合的 monorepo

Monorepos 是 AGENTS.md 真正有价值的地方。root file 应该是 map，不是垃圾桶。

# AGENTS.md

## Repository map
This is a TypeScript monorepo.
- apps/web: customer-facing Next.js app
- apps/admin: internal admin app
- packages/ui: shared UI primitives
- packages/api-client: generated API client
- packages/config: shared lint, TypeScript, and test config

## Root commands
- Install: pnpm install
- Build all: pnpm build
- Lint all: pnpm lint
- Test all: pnpm test
- Build one package: pnpm --filter <name> build

## Cross-package rules
- Do not import from one app into another app.
- Shared UI belongs in packages/ui only after two apps use it.
- packages/api-client is generated. Update the OpenAPI schema and regenerate.
- Changes to packages/config require running lint and typecheck in both apps.

## Local overrides
Subdirectories may contain their own AGENTS.md for narrower rules.
The closer file wins when it conflicts with this root file.

为什么有效：它把 AGENTS.md 当 index。它不试图解释每个 app。它给 agent 足够结构来导航，也给了足够边界避免 cross-app coupling。

local override note 很关键。Codex 会通过 scope 发现 instruction files。root AGENTS.md 应该告诉 agent：更窄的 files 可能存在，而且应该对自己的 subtree 更权威。

例子六：docs-heavy open-source library

Libraries 需要强 documentation rules，因为 code 不是全部产品。

# AGENTS.md

## Project facts
This is an open-source TypeScript library. Source lives in src/.
Examples live in examples/. Public docs live in docs/.

## Commands
- Install: npm ci
- Build: npm run build
- Test: npm test
- Docs check: npm run docs:check

## Public API rules
- Do not change exported names without updating docs/api.md and CHANGELOG.md.
- Every new option needs one docs example and one test.
- Deprecated APIs must keep working until the next major version.
- Examples must use public imports only. Do not import from src/internal.

## Release notes
- User-visible fixes need a CHANGELOG.md entry.
- Internal refactors do not need a changelog entry unless behavior changes.

为什么有效：它把 docs 和 examples 当 contract 的一部分。agents 经常改 implementation，却漏掉 public surface。这个文件让 surface 可见。

“examples must use public imports” 这条很小，但很有价值。它抓住一个常见捷径：因为 example 里更方便，就 import internals。这样会破坏 docs 的教学价值。

例子七：仍然能工作的 minimal repo

不是每份 AGENTS.md 都要长。一个小 CLI 可以有一个小文件。

# AGENTS.md

## Project
Small Go CLI for validating config files.

## Commands
- Format: gofmt -w .
- Test: go test ./...
- Build: go build ./cmd/configlint

## Rules
- Keep the CLI dependency-free unless a dependency removes substantial code.
- Error messages must name the file path and config key when available.
- Golden test files live in testdata/. Update them only with intentional output changes.

为什么有效：没有 padding。没有 “best practices”。没有 generic Go tutorial。它只命名这个项目最重要的两件事：dependency discipline 和 useful errors。

这些例子的共同点

共同点不是模板，而是密度。好的 AGENTS.md 说更少的事，但说的事能被执行。它列真实 commands。命名 generated files。定义 ownership boundaries。链接更深 docs，而不是复制它们。它告诉 agent 什么不能做，不只是项目是什么。

如果你的 AGENTS.md 不能通过跑 commands、检查 paths，或按具体规则 review diff 来测试，它大概率太模糊。AgentLint 抓的就是这种弱点：过期 commands、过期 paths、冲突、模糊 guidance，以及围绕 agents 依赖的 instruction file 缺少 enforcement。