Theo重写AGENTS.md让AI编程效率翻倍的方法论

知名开发者、T3系列产品创始人 Theo（t3.gg）最近分享了一个反直觉但极具价值的经验：过去几天他"提交的代码量超过以往任何时候"，而背后的关键并非写了更多业务代码，而是花了整整六个小时在 VS Code 里编辑 Markdown 文件——也就是重写他的 AGENTS.md、CLAUDE.md 以及一系列 Skills 配置文件。

这里有必要解释一下这些文件的背景。AGENTS.md 和 CLAUDE.md 是近年来随着 AI 编程 Agent 生态兴起的一类新型配置文件。AGENTS.md 最初由 OpenAI 的 Codex CLI 推广，用于在代码仓库根目录放置一份 Markdown 文件，告诉 AI Agent 如何理解和操作该项目。CLAUDE.md 则是 Anthropic 为 Claude Code（其命令行 AI 编程工具）设计的等价物。这些文件本质上是一种"系统提示词的工程化管理"——它们会在 Agent 启动时被自动读取并注入上下文窗口，成为 Agent 行为的隐性约束。与传统的 .editorconfig 或 .eslintrc 不同，这类文件不是给工具链解析的结构化配置，而是用自然语言写成的、面向大语言模型的指令集，涵盖代码风格、协作规范、项目架构说明等内容。

这篇内容不是让你去复制他的配置，而是揭示一套如何系统性地驯服 AI 编程 Agent 的方法论。

为什么Markdown配置文件比业务代码更重要

Theo 坦言，他手上有 4-5 台机器专门跑 T3 Code 做并行开发，管理这些机器上的 Skills 分发、同步曾经让他抓狂到想自己写一套系统。这种 4-5 台机器并行开发的模式，代表了 AI 编程领域正在兴起的"Agent 集群"工作范式。在这种模式下，开发者不再是逐行写代码的执行者，而是同时管理多个 AI Agent 实例的协调者——每个 Agent 可能在不同的分支上处理不同的功能模块、bug 修复或性能优化任务。这种模式的瓶颈从"代码生成速度"转移到了"Agent 管理开销"：如何确保所有 Agent 遵循一致的代码规范、如何避免它们的改动互相冲突、如何高效审查它们的产出。

但最终他放弃了复杂方案，回归到最朴素的形式：一个叫 fleet 的仓库，里面全是 Markdown 文件。选择 Git 仓库管理配置而非自建分发系统，是因为 Git 本身就提供了版本控制、变更追踪和多机同步的能力，比任何定制化方案都更可靠也更简单。

他强调了一个核心认知转变——这些配置文件的价值不在于'内容本身'，而在于'思考过程'。这也是他刻意不公开自己 AGENTS.md 的原因：

"复制这些文件就像复制别人的通用代码模板，然后用它去做每一件事。你应该自己掌控这个文件、编辑它、根据你的需求随时间调整它。"

关于 Skills 的概念也值得展开说明。Skills 是 T3 Code 中的一种模块化能力配置机制。每个 Skill 本质上是一个独立的 Markdown 文件，包含 description（描述/触发条件）、instructions（执行指令）、以及可选的工具调用权限定义。当用户在对话中输入特定意图时，Agent 会根据 description 字段判断是否需要激活该 Skill，一旦激活则将完整的 instructions 注入上下文。这种设计类似于 LangChain 中的 Tool 概念或 OpenAI 的 Function Calling，但以更轻量、更人类可读的方式实现。Skills 可以在全局级别、项目级别或用户级别配置，支持跨机器同步。

Theo 的旧版全局配置用了近两年几乎没动过，里面只是零散的规则："避免使用 any"、"别乱起 dev server 破坏我的环境"、"优先用 bun 而非 pnpm"。而新版本则加入了大量关于语气、沟通方式和协作偏好的内容。

让模型模仿你的语气降低冗余输出

一个有趣的技巧是：Theo 在文件开头用第一人称做自我介绍——"我是 Theo，你是我的 Agent，我们要一起长期合作"。他解释说，模型擅长语气匹配（tone matching），你用什么方式跟它说话，它就更倾向于用同样的方式回应你。

语气匹配是大语言模型的一种涌现行为，根植于其训练方式。由于模型在预训练阶段学习了海量的对话数据，它天然倾向于延续输入文本的风格和语域进行生成——这在 NLP 研究中被称为"风格条件化生成"（style-conditioned generation）。当 Theo 在配置文件开头用简洁、直接的第一人称介绍自己时，模型会将这种语言风格作为隐性约束，后续生成也倾向于同样简洁直接。

这两句看似多余的介绍，实际显著减少了 GPT-5、Opus 5 等"过度积极"模型的冗余输出。这些经过大量 RLHF（基于人类反馈的强化学习）训练的模型，为了获得人类评估者的好评，往往存在"过度积极"和"过度冗长"的倾向——它们会添加不必要的免责声明、重复确认和过度解释。通过在系统提示中设定简洁的交流基调，可以有效对抗这种训练偏差。

Skills设计核心：description是触发器而非说明书

Theo 分享了他最核心的一个反直觉洞察——Skill 的 description 字段不该描述这个 Skill 做什么，而应该是触发关键词。

因为 description 无论 Skill 是否被调用都会被插入上下文，如果你把所有细节写进去，反而浪费 token 甚至让模型觉得"看完描述就够了，不用调用了"。这里涉及到上下文窗口管理的核心问题：Token 是大语言模型处理文本的基本单位，大致相当于 3/4 个英文单词或一个汉字。每次 Agent 交互时，所有被注入的配置文件、历史对话、代码上下文都会占用有限的上下文窗口。即使最新的模型如 Claude 3.5 支持 200K token、GPT-4o 支持 128K token，在复杂的编程任务中上下文空间仍然是稀缺资源。冗长的描述不仅浪费 token 配额，还可能因为信息过载导致模型注意力分散，降低关键指令的执行质量——这是 Transformer 架构中"注意力稀释"问题在工程实践中的直接体现。

正确做法是：

"当用户要求 monitor、watch 或 babysit 一个 PR 时使用"——只保留触发的魔法关键词。

基于这个原则，他把原本合并的 "file PR" 和 "babysit PR" 拆成两个独立 Skill，因为加了精准关键词后触发就足够准确了，而且他经常只需要其中一个功能。

用好例子和坏例子喂养模型

Theo 特别强调 Agent 对好坏示例极其敏感。这种用好坏对比来"教育" Agent 的做法，本质上是 few-shot learning（少样本学习）在提示工程中的应用。大语言模型具有强大的上下文学习能力——你不需要重新训练模型，只需在提示中给出少量示例，模型就能从中提取模式并应用到新任务中。研究表明，同时提供正例和反例（contrastive examples）的效果远优于只提供正例，因为反例帮助模型划定了行为边界，明确了"什么不该做"。

他曾深受烂 PR 标题之苦，比如：

• 坏例子：perf: server negotiate per-message deflate on the websocket
• 好例子：perf: server cut websocket frame size by 70% with gzipping

前者虽然技术上准确，但充满了实现细节术语；后者则聚焦于可量化的影响和直觉可理解的方法。这种对比让模型理解了一个隐性规则：PR 标题应该传达"为什么这很重要"，而非"具体做了什么技术操作"。

他在 Skill 里直接给出这样的对比，结果 Agent 立刻明白了什么叫"人类可读、解释为何重要"的标题。他的建议是：当你发现 Agent 反复做错某件事，就把一两个好坏对比塞进 Skill 或全局配置，相当于用你在意的东西给模型的权重播种。

他还加入了一条改变最大的规则：PR 描述要先用一句话说明"用户原始需求要解决什么问题"，再简述方案，不要一上来就堆实现清单。这让他后续的 PR 可读性发生了质变。

用Agent审查交互历史定位失败模式

这是整套方法论中最具启发性的部分。Theo 没有凭感觉重写配置，而是让 Agent 去审查他与各个模型的历史交互记录，量化统计每个模型的常见失败模式。

他给 Agent 的 prompt 是："看看我和 Fable、Opus、GPT-5.6 在 Claude Code 和 Codex 上的历史，找出最常见的错误，按出现次数分类，并统计每个模型的命中频率。"

结果非常具体：

• Opus 5 频繁"杀错进程"，经常把自己所在的 T3 Code 实例都杀掉——即使只用了两天，误杀次数就远超 Fable
• Sol（GPT） 有 40% 的概率提交 draft PR，其他模型则少得多
• 各模型都有"过早停止"、"不验证"的通病，而"回归错误"虽罕见但代价高昂

这些差异反映了当前大模型生态的一个重要现实：不同模型由于训练数据分布、RLHF 偏好调优策略、以及工具调用训练方式的差异，在执行相同的 Agent 任务时会表现出系统性的行为倾向差异。例如 Opus 5 频繁"杀错进程"可能源于其在工具调用时对 shell 命令的激进执行策略；Sol 高概率提交 draft PR 则可能与其训练中对"谨慎行为"的过度强化有关。这种跨模型的行为审计（behavioral auditing）在业界还处于早期阶段，目前主要依赖开发者的经验积累而非系统化的评估框架。

Theo 的观点是：逐条读完所有历史记录太痛苦，但让一群 Agent 帮你归类分析要容易得多。这是一种元认知方法——用 AI 来审计 AI 的行为模式，这比人工逐条阅读聊天记录高效得多。当你发现某个线程走偏了，就直接问 Agent"你为什么做这个决定？是什么让你觉得这方向对？"——答案往往指向配置文件里过时或被误读的内容。

AGENTS.md与README的本质区别

Theo 反复强调一个容易混淆的边界：AGENTS.md 应该与 README.md 截然不同。

• README 是给人和"评估要不要用这套代码"的读者看的项目介绍
• AGENTS.md 是告诉 Agent"如何在代码库里做修改、修改前需要知道什么"

他在 T3 Code 的项目级配置里做了几件关键的事：

1. 建立术语表（Glossary）。第一个定义的词就是"you"——指正在读这个文件并修改 T3 Code 的 Agent。还定义了 we、user、agent、provider、client、environment、project 等。

这看似简单，实则解决了自然语言提示中最棘手的问题之一：指代歧义（referential ambiguity）。在代码编辑器的语境中，"client"可能指浏览器端代码、API 客户端库、桌面应用客户端、或者使用 T3 Code 的终端用户；"environment"可能指运行时环境、开发环境配置、或环境变量。当模型在歧义中做出错误假设时，它的整个推理链都会偏离预期方向。通过预先定义术语，Theo 本质上是在构建一个共享的"语义锚点"系统——这与软件工程中 DDD（领域驱动设计）里的"统一语言"（Ubiquitous Language）概念不谋而合。特别值得注意的是他定义"you"的做法：明确告诉模型"你就是那个正在修改代码的 Agent"，避免模型在角色认知上产生混乱（例如误以为自己是在给人类解释代码的教学助手）。

这么做的核心目的不是让 Agent 理解他，而是让 Agent 用他想要的方式向他描述事情。

2. 明确"永不妥协的底线"。他列出了 T3 Code 的核心价值：开源（Open at the core）、极致性能、远程就绪、多端支持。这不是给人看的宣传语，而是告诉模型"如果某个改动会伤害这些，就不该做"。

3. 加入"Theo 的note"和逃生舱。他写道"我喜欢有野心的想法、简单的系统"，同时明确"开发者的偏好可以覆盖这里的任何内容"——避免 Agent 的配置和用户当下需求冲突时产生摩擦。

两个改变工作流的实战Skill案例

Theo 还展示了两个此前从未公开的 Skill。

文件上传 Skill：让 Agent 能把截图、录屏、日志上传到他自建的 files.tslop.org，返回公开 URL。这意味着当你在手机上用 T3 Code mobile app 时，可以让 Agent 把新功能录屏上传，你直接点链接就能看到真实机器上运行的效果，甚至嵌进 PR 里。

HTML 沟通 Skill（源自 Anthropic 的 Thoric）：让 Agent 生成可读的 HTML 文档——计划、规格、UI mock、报告等，并上传到稳定 URL。他用 A/B/C 标注不同 UI 方案便于快速选择。

最终效果是他的 prompt 变得极短。比如给营销站加 iOS/Android 应用入口，Agent 用 HTML skill 给出 A/B/C/D 四个 mock，他只回复："我要 C+D+A 组合。File and babysit。"——就完成了从设计到提 PR 全流程。

核心启示：优化AI沟通能力而非代码能力

Theo 在结尾点出了整套方法论的灵魂：

"我不是想让模型技术上更强。这一切的目的不是让模型更会写代码，而是让模型更擅长和我沟通。"

当 Agent 的输出是没有有用上下文的垃圾时，阅读它就是折磨。所有这些 Skills、配置、投入的时间，本质是给模型提供"如何更好地与人协作"的能力。

他最后再次警告：不要去他的仓库复制安装所有 Skills。就像你不会安装别人用过的所有 JS 包一样。真正的价值是理解你自己的 Agent 在哪里工作、在哪里失败——只有搞懂这个，你才能写出真正适合自己的配置。