编码代理入职文档：AGENTS.md 的生产级写法

2026年8月，The New Stack 发表了一篇观察犀利的文章：《你的编码代理得到了你从未给过开发者的入职培训》。Google 2025 年《AI 辅助软件开发现状》报告显示，AI 辅助开发采纳率已达 90% 的组织，一年涨了 14 个百分点。但收益并不平均——AI 会放大你现有的交付系统：强的工程体系更强，混乱的体系更混乱。决定结果的分水岭，就是你写给代理的入职文档。

现代开发工作流中的AI代理

一、代理的入职文档：AGENTS.md 是什么

现在给代理配的开发环境里，通常有一个或多个为编码代理写的文件：AGENTS.md、CLAUDE.md、GEMINI.md。这些纯文本或 Markdown 文件包含技术栈、构建和测试命令、禁区目录、团队约定。The New Stack 指出，很多组织（比如 Sourcegraph）都在争相创建和维护这些代理入职文档——而这恰恰是人对人文档从未享受过的待遇：人的文档往往被无限搁置，代理的文档却被持续优化。

# AGENTS.md — the agent's onboarding document
# Best practice: keep it under 60-300 lines. Every line is
# re-read in EVERY session, so it must earn its place.
# (The HumanLayer team keeps theirs under 60 lines)

# Stack
- Next.js 16 + Tailwind + next-intl, TypeScript strict
- Tests: vitest (unit) + Playwright (e2e)

# Commands
- npm run dev       # local dev
- npm test          # unit tests, must pass before merge
- npm run build     # required before every push

# Off-limits
- src/lib/tools.ts  # 1100+ tool metadata, NEVER edit casually
- *.config.prod.ts  # production configs, human approval only

# Conventions
- i18n: every user-facing string in zh + en
- Small batches: max 5 files per PR

二、为什么代理文档不会腐烂

和开发者文档不同，代理入职文件创建后不会腐烂。团队会持续优化它以提升任务成功率、降低推理成本。HumanLayer 团队把自己的文件保持在 60 行以内——业内最佳实践是 300 行以内——因为每一行在每个会话里都会被重读，必须「挣得自己的位置」。而维基百科式的人用文档，通常等不到这种待遇。

# CLAUDE.md / GEMINI.md: per-tool variations
# Keep the SAME core facts, tune the format per agent
---
model_hint: claude
pinned_files:
  - AGENTS.md          # always read this first
  - src/lib/schema.ts  # source of truth for data shapes
tone: concise
max_output_tokens: 4000
---
# Never invent function signatures. Verify against
# src/lib/api/client.ts before writing call sites.

三、Faros AI 的数据：上下文切换正在淹没所有人

跳过纪律的代价写在数据里。Faros AI 2026 年的遥测显示：使用 AI 辅助的开发者每天要处理 67.4% 更多的 PR 上下文和 17.7% 更多的任务上下文（上一年分别是 47% 和 9%）；工作重启增加了近 14%；超过四分之一的进行中任务被搁置无人问津。「人和代理都在被更好的批处理本可以避免的上下文切换淹没。」

# The 2026 data: why context quality is a competitive edge
# Google's 2025 State of AI-assisted Software Development:
#   adoption reached 90% of organizations (+14 pts in a year)
# Faros AI telemetry (2026):
#   devs juggle 67.4% more PR contexts per day
#   17.7% more task contexts per day
#   work restarts up ~14%
#   >25% of in-progress tasks sit untouched
# AI amplifies existing delivery systems — strong teams
# get stronger, dysfunctional ones get more chaotic.

四、小批量是人与代理的共同解药

DORA 用十年证明了小批量工作能降低风险、加快交付。过去这套纪律总被「我们这里行不通」打发掉；如今大规模变更集让做代码审查的代理都犯难，小批量突然变得合理。最佳实践：把功能拆成最多 5 个文件的批次，代理实现→跑测试→人类审查→按反馈修正，人和代理都保持在环里。

# Small-batch workflow that agents and humans can both follow
# DORA evidence: small batches reduce risk and speed delivery
def plan_work(feature):
    batches = split_into_batches(feature, max_files=5)
    for batch in batches:
        agent.implement(batch)
        agent.run_tests()
        human.review(batch)      # both sides stay in the loop
        if human.requests_changes:
            agent.fix(batch)     # small diff = fast correction
    return merge_all()

# "Both humans and agents are drowning in context switches
#  that better batching would have prevented."

五、写 AGENTS.md 的实战清单

一份生产级 AGENTS.md 至少包含五块：技术栈（框架+严格度）、命令（dev/test/build，注明每个 push 前必须跑什么）、禁区（关键文件与生产配置，禁止代理乱动）、约定（i18n 双语、PR 大小上限）、以及「先读什么」的固定入口。控制在 60-300 行，每行都要有存在理由。

六、把入职文档当产品来迭代

最后的心态转变：把 AGENTS.md 当作产品而不是文档。用任务成功率、token 消耗、返工率来度量它的质量；每次代理表现异常，先问「是不是入职文档没写清楚」而不是责怪模型。2026 年，决定 AI 团队胜负的往往不是模型选型，而是你花多少心思写好了那份代理入职文档。