有时候，不得不感叹，AI 时代比任何时代都更擅长创造“新”的概念。

现在的程序员对这个设置过程一定不再陌生：装上 Claude Code 或 Codex，它第一件事就让你建一个 `CLAUDE.md` 或 `AGENTS.md`。明明仓库里已经有 README，为啥还要再写一份？

Context Engineering 本身不是新词。大约一年前，coding agent 开始普及，这个说法就从圈内讨论变成日常用语。大家谈的是：别只盯着一句 prompt 怎么写，得把模型干活前该读到的东西（规矩、文档、代码片段）当成工程来设计。

论文 *Context Engineering for AI Agents in Open-Source Software* 于 2025 年 10 月 24 日发表在 arXiv，作者来自 Heidelberg、Canterbury 与新加坡管理大学。作者的做法非常务实，他们去 GitHub 扒 `AGENTS.md` 这类文件，看开源世界里人类到底怎么给机器写"说明书"：写成了啥、有没有标准、会不会被当真维护。

接下来，我们先看采用率和内容偏重，再看为什么要写、写成啥样、这些声明式内容算不算工程。

## 一万个仓库里，只有约 5% 给 AI 写了手册
我们把论文最硬的一组数字摆出来说话：
```markdown
论文从 GitHub 捞了 49,311 个仓库
  → 按自定义排名挑了 10,000 个
    → 扫了一遍默认分支里的 AI 配置文件
      → 只有 466 个（≈5%）用了至少一种
        → 其中专门看 AGENTS.md，拿到 155 个文件
```
**5%。**
也就是说，你随机点开 20 个像样的开源项目，大约只有 1 个给 AI 写了"入职手册"。开源仓库里真正落成文件的，还是少数。差距就在这儿。

再把那 155 个 `AGENTS.md` 拆开看里面写了啥（按标题词频归类）

```markdown
约定 / 最佳实践    50 次
贡献指南              48 次
架构与项目结构     47 次
构建命令              40 次
项目描述              32 次
测试说明              32 次
文档元数据            29 次
测试策略              24 次
技术栈与依赖         15 次
上手与环境搭建      11 次
参考 / 速查表        9 次
排错                     8 次
模式与样例            8 次
安全                     6 次
```
排第一的是"约定 / 最佳实践"，也就是"我们这儿的规矩"。人给新人写的入职手册，第一页往往也是"我们的规矩"。所谓约定大于配置的原则。

![图片](https://developer.qcloudimg.com/http-save/yehe-2881505/3658fcf1ac3fb8940df4b43f9ec4a1b0.jpg)
停下来，先把几个术语说清楚。

## 提示工程管"怎么说"，上下文工程管"先读到什么"

**Prompt Engineering（提示工程）**：专攻"指令"和"输出格式"。你怎么跟模型说话、让它吐出什么形状的答案。

**Context Engineering（上下文工程）**：范围更大。它关心的是"在模型干活之前，你往它的上下文窗口里塞了什么"：准则、配置、文档、代码片段，全算。提示工程管"你怎么说"，上下文工程管"你让它先读到什么"。
论文里的定义很干脆：上下文工程是"为 LLM 设计、组织、提供相关信息的有意过程（the deliberate process of designing, structuring, and providing relevant information to LLMs）"。

**AI 配置文件**：就是 `AGENTS.md`、`CLAUDE.md`、`copilot-instructions.md`、`GEMINI.md` 这类 Markdown 文件。它们被放进仓库，Agent 一启动就自动把内容读进上下文。

**AGENTS.md**：一个开放、跟具体工具解耦的约定（由 agents.md 社区推动，OpenAI Codex 在用）。你可以把它理解成 `CLAUDE.md`（Anthropic 专属）和 `copilot-instructions.md`（GitHub 专属）的"去工具化"版本。这份文件不管是谁家的 Agent 都能读。

![图片](https://developer.qcloudimg.com/http-save/yehe-2881505/a98d807eaed8c8331ec3f5673b72f731.jpg)

## Agent 能自己干活了，项目规矩就得提前写进上下文

### 从补全器到自主 Agent

早年 Coding Assistant 是补全器。你写一行，它补半行，人需要全程盯着看，那个时候还远没有现在 Code Agent 的自主和智能。

以 Claude Code、Codex、Pi 为代表的 Code Agent，能自己开终端、跑命令、连干好几步，人可能只在中途点个头。能力上去了，麻烦也来了：一个没人盯着的 Agent，怎么知道"这个项目里数据库不能直连、要过 DAO 层"？怎么知道"提交信息必须带 Jira 编号"？

人靠在项目打磨的经验、利用各种 pair 活动，如 code review 学习这些本领。但是 Agent 没有经验，只能靠人来喂。

所以，因果链大致如下：
```markdown
Agent 自主干活，人不一定在旁边
  → 需要把"项目规矩"提前塞进它的上下文
    → 最省事的做法：写一份版本控制的 Markdown
      → 各家各搞各的（CLAUDE.md / copilot-instructions.md）
        → 需要一份"谁都能读"的标准 → AGENTS.md 冒头
```

上下文工程在实践里落地，也是一环扣一环，在社区力量的推动下，逐渐催生出了新一轮的标准。

![图片](https://developer.qcloudimg.com/http-save/yehe-2881505/ab6c053d717e875272348d03c87c402a.jpg)

可是，标准文件名有了，但没人规定它该长啥样。于是这篇论文尝试从实践中总结真理：人类自由发挥，到底写成了啥？

## 55 份 AGENTS.md：没有统一结构，语气却能分成五种

### 结构随意，写法却有章法

论文扒了那 155 个 `AGENTS.md`，结论很直白：目前没有任何公认的文档结构。有人按"架构 / 构建 / 测试"分章节，有人通篇就一段叮嘱，有人塞了一堆速查表。你想怎么写就怎么写。

有趣的是写作的"语气"。论文中把人类写指令的方式归成五种风格：

```请在此输入代码块语言
描述型（descriptive）    "我们用 TypeScript"
规定型（prescriptive）   "所有 PR 必须带测试"
禁止型（prohibitive）    "禁止直接改 main 分支"
解释型（explanatory）    "之所以要求签名，是因为……"
条件型（conditional）     "如果是紧急修复，可以跳过 CI"
```
对比一下就清楚了：
- 人类写 README：默认读者是人，能追问、能脑补、能容忍模糊。
- 人类写 AGENTS.md：默认读者是机器，照单全收、没有常识、不会问"为啥"。

README 写含糊了，人自己圆回来；`AGENTS.md` 写含糊了，Agent 可能一本正经地执行一个我们自己都没想清楚的规矩。

换句话说，人类在第一次大规模地、认真地在给一个"不会追问的实习生"写 SOP。

![图片](https://developer.qcloudimg.com/http-save/yehe-2881505/28c31a2eda49d3042d3fbe4589ba24e9.jpg)

### 写进去的多半是"土规矩"，不是技术栈

回看前面那张词频表。排前面的全是"软规矩"：约定、贡献流程、架构、构建。技术栈、安全这种"硬信息"反而排在后面。一个合理的猜测是：架构和构建命令，Agent 自己看代码大概率能猜个八九不离十；真正塞不进去的是"我们这儿的土规矩"，那种只活在老员工脑子里的东西。`AGENTS.md` 干的事，恰恰是把 tacit knowledge（隐性知识）外显成机器能读的文本。

## AGENTS.md 靠缝补演化，一半建了却没养

### 加指令、改指令，远多于推倒重来

论文追了那些改动最勤的 `AGENTS.md`（≥10 次提交的文件，10 个，169 次提交），统计每次改了啥：

```markdown
加指令       78 次
改指令       59 次
加章节       26 次
删指令       23 次
改标题       23 次
小修小补     19 次
重排格式     10 次
删章节        2 次
更新引用      2 次
```
最密集的动作是"加指令"和"改指令"，而不是"加章节 / 改结构"。这些文件很少推倒重来，更多是边用边补：今天发现 Agent 踩了坑，加一句"别这么干"；明天规矩细化，把一句话扩成一段。像不像你维护一份团队 wiki？

![图片](https://developer.qcloudimg.com/http-save/yehe-2881505/0db7dfabe58bcef5b912977f412b12d1.jpg)

还有个刺眼的数字：一半的 `AGENTS.md`，在第一次提交之后就再也没动过：“有人生，没人养”。很多人是觉得应该创建一个，但并不认为重要，也就没当回事，所以没再维护了。

### 该当软件制品来养，不能写完就扔

我同意论文中问观点：AI 配置文件应该被当成正经的、要被维护的软件制品。要版本化，要 code review，要质量保障，甚至要测试。

想想看，代码和注释是一起演化的（改了函数，注释得跟着改）。源代码和 `AGENTS.md`，将来大概率也会这样共演化：你重构了模块，就得去 `AGENTS.md` 里把"架构"那段改了，不然 Agent 读的是过期地图。

上下文工程不是"写一份文档就完事"，是"养一份会过期的文档"。这活儿不“AI”，但它是真的活工程。

## 像给不会追问的实习生写 SOP，但机器比实习生更娇贵

设想你招了个远程实习生：能力很强，能自己跑命令、改文件；但他没有常识，不会问"为什么"，你写啥他执行啥，而且记忆只有你给的那一页纸。

你会怎么给他写工作手册？你不敢写含糊，不敢写矛盾，因为一句"大概这样做吧"到了他手里就是"必须这样做"。你会把"我们这儿的规矩"一条条列清楚，会比平时更较真。`AGENTS.md` 就是那份 SOP。

但这个隐喻并不十分准确：真实习生会追问"这句啥意思"，机器不会。`README` 写给能追问的人，出了歧义人自己找补；`AGENTS.md` 写给不会追问的机器，一处写错，机器就当真理执行，还执行得理直气壮。所以"给机器写文档"比"给人写文档"更娇贵。它逼着你把平时懒得说清的隐性知识，逼成机器零歧义能执行的文本。这点不能搞混。

## 小结：为啥写、写成啥、算不算工程

**为什么要给 AI 员工手册？** 因为自主 Agent 没人盯着，只能你提前把"项目规矩"喂进它的上下文。`AGENTS.md` 就是这份"去工具化"的喂食文件。

** 人类自由发挥写成啥样了？** 仅有 5% 的采用率，没有统一结构，语气五花八门（描述、规定、禁止、解释、条件），但内容都偏"软规矩"，类似把老员工脑子里的隐性知识外显。

** 它能不能算正经的工程？** 目前还谈不上成熟，但演化方式很像团队 wiki（边用边缝补）。这份文档该被当成要维护的软件制品，跟代码一同演化。

现在的程序员对这个设置过程一定不再陌生：装上 Claude Code 或 Codex，它第一件事就让你建一个 CLAUDE.md 或 AGENTS.md。明明仓库里已经有 README，为啥还要再写一份？

给 AI 写"员工手册"的人——开源仓库里的 Context Engineering 长什么样？

论文 Context Engineering for AI Agents in Open-Source Software 帮我们揭晓了开源世界里人类到底怎么给机器写"说明书"：写成了啥、有没有标准、会不会被

人工智能

开发工具

编程语言

AI时代下，上下文工程正成为开发者新标配。研究显示仅5%开源项目采用AGENTS.md文件，内容侧重项目约定与最佳实践，而非技术栈细节。这类AI配置文件缺乏统一标准，写作风格多样，需像软件制品一样持续维护，与代码同步演化，将隐性知识转化为机器可执行的明确指令。

上下文工程

代码解释

TypeScript

数据库

GitHub

Agent

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

给 AI 写"员工手册"的人——开源仓库里的 Context Engineering 长什么样？-腾讯云开发者社区-腾讯云

给 AI 写"员工手册"的人——开源仓库里的 Context Engineering 长什么样？

给 AI 写"员工手册"的人——开源仓库里的 Context Engineering 长什么样？

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐