Theo优化Claude编程代理的实战方法论：AGENTS.md与Skills配置指南

知名开发者、T3技术栈创始人 Theo 最近沉迷于编程，据他自述在过去三天里合并了数十个 PR。但真正引发关注的，不是他写了多少代码，而是他花了大约六个小时只编辑 Markdown 文件，随后又用六到十个小时测试这些改动。这些看似微不足道的文本修改，据他描述极大改善了他与 AI 编程代理协作的体验。

Theo 是 YouTube 上拥有数十万订阅者的知名技术内容创作者，也是 T3 Stack（一套包含 Next.js、TypeScript、tRPC、Prisma、Tailwind CSS 的全栈开发技术组合）的创建者，以及 T3 Code 编辑器的创始人。他在开发者社区中以对开发工具和开发体验的深度思考著称。

本文将梳理 Theo 的核心方法论——如何通过精心撰写 AGENTS.md、CLAUDE.md 以及 Skills（技能）文件，让 Claude、Codex 等编程代理变得更「聪明」、更懂你。

AGENTS.md 与 CLAUDE.md 是什么？

AGENTS.md 和 CLAUDE.md 是放置在代码仓库根目录或用户全局配置目录下的 Markdown 文件，用于向 AI 编程代理（如 Claude Code、OpenAI Codex）提供持久化的上下文指令。这些文件会在每次会话开始时被自动注入到模型的系统提示（system prompt）中，相当于为代理设定了一个持续生效的「操作规范」。

系统提示是大语言模型交互中的一个特殊输入层，它在用户消息之前被处理，为模型设定角色、行为边界和输出格式。相比在对话中手动输入的指令，系统提示层面的内容具有更高的优先级和更持久的影响力——模型会将其视为底层约束而非临时请求。AGENTS.md/CLAUDE.md 的注入机制正是利用了这一特性，使得文件中的规则能够跨越整个会话持续生效。

与每次对话中手动输入指令不同，这种文件化配置确保了跨会话的一致性。Claude Code 使用 CLAUDE.md，而 AGENTS.md 则是更通用的命名规范，适用于包括 Codex 在内的多种代理平台。这些文件支持层级覆盖——全局配置设定通用行为，项目级配置提供仓库特定的规则，子目录配置则针对特定模块。

全局配置：写给AI代理的「自我介绍」

Theo 坦言，他那份沿用了近两年的全局 AGENTS.md / CLAUDE.md 其实写得并不好，他一直凑合着用。而新版本最关键的改进，是在开头加入了一段自我介绍：「我是 Theo，你是我的代理，我们经常一起工作。」

这段看似闲聊的文字带来了显著效果。他解释道，像 GPT-5.6、Sonnet、Opus 5 这类「过于积极」的模型，往往在不需要写很多代码时就急着大量编码。所谓模型「过于积极」是 AI 编程代理的一个常见失败模式——当用户仅仅是提问或讨论时，模型会误判意图并直接开始修改代码、创建文件或执行命令。

这种行为的根源在于 RLHF（基于人类反馈的强化学习）训练机制。在 RLHF 阶段，人类标注员对模型的不同回复进行偏好排序，模型通过强化学习算法（如 PPO 或 DPO）优化自身以产出更受偏好的输出。由于标注过程中「有帮助的回复」通常获得更高评分，模型习得了一种「行动偏好」——宁可做多也不做少。在代码代理场景下，这种偏好被进一步放大：模型拥有执行工具调用的能力（如写文件、运行命令），使得「过度积极」不再只是回复冗长，而是会产生实际的代码修改副作用。GPT-5.6 和 Claude Opus 5 等最新一代模型由于能力更强，这一倾向更加明显——它们「能做更多事」，所以也更容易「做过头」。而 Theo 那两句自我介绍加上明确的偏好说明，大幅缓解了这个问题。

更巧妙的一点在于语气匹配。Theo 特意用一种特定的口吻书写指令，因为「模型很擅长语气匹配」——你用什么方式跟模型说话，它就更倾向于用什么方式回应你。这一现象源于 Transformer 模型的注意力机制：模型在生成每个 token 时会参考上下文中所有先前文本的风格特征（词汇选择、句子长度、正式程度等），由于自回归生成的特性，产出的文本会在统计分布上趋近输入风格。这意味着如果你用简洁技术性的语言书写配置文件，模型输出也会更简洁和技术导向；反之亦然。这是很多人忽略的细节：配置文件不仅传递规则，也传递沟通风格。

他还设置了几条关键约束：

• 「提问是只读的」（Questions are read-only）——防止模型在你只是询问项目情况时就擅自动手改代码
• 「让仪式感匹配任务」（Match ceremony to the task）——避免代理为一个简单任务动辄启动多个子代理

Skills技能文件：把重复指令变成可复用的规则

Skills 是 Claude Code 等代理平台提供的一种结构化指令封装机制。每个 Skill 由三部分组成：description（描述/触发条件）、instructions（具体执行指令）和可选的 file patterns（文件匹配模式）。当用户输入匹配到某个 Skill 的 description 时，该 Skill 的完整 instructions 会被注入到当前上下文中，指导代理执行特定工作流。这类似于编程中的函数抽象——将重复的多步骤操作封装为一个可复用的单元。

Theo 发现自己总在对代理重复同样的话，于是把这些沉淀成了 Skills。最典型的是「babysit PR」（照看 PR）技能——因为他的很多项目都挂着三四个 AI 代码审查机器人（如 CodeRabbit、Ellipsis 等），他需要代理持续监控 PR：适时 rebase、拉取 main、读取并回应审查意见，直到 PR 变绿、所有人批准。

CodeRabbit 和 Ellipsis 是当前流行的 AI 代码审查工具，它们作为 GitHub App 安装后会自动对每个 PR 进行代码审查并留下评论。CodeRabbit 使用大语言模型分析代码差异，检查潜在 bug、性能问题和风格不一致；Ellipsis 则专注于增量审查和代码质量度量。当多个审查机器人同时激活时，一个 PR 可能收到来自不同 bot 的数十条评论，每条都需要被处理或回应——这正是自动化「照看」能力的价值所在。

在打磨过程中，他修复了很多恼人的失败模式。比如代理通过他的账号评论却不标明自己是 AI，或者把每条评论都当成关键任务处理，导致 PR 膨胀到原来的三倍大。这里就涉及到 AI 代理场景中的「范围蔓延」（scope creep）问题：当代码审查机器人提出建议时，AI 代理会试图「完美」地回应每一条反馈，包括那些属于「可选优化」而非「必须修复」的建议，导致一个原本只改 20 行的 PR 被不断追加代码变成 200 行的重构。为此他加入了这条堪称「最重要」的指令：

不要让审查反馈让 PR 超出用户的原始目标。处理真正的缺陷，但避免范围蔓延（scope creep）。

Skill description的关键洞察

Theo 强调了一个大多数人（以及代理本身）都会搞错的点：Skill 的 description 不应该描述这个技能「做什么」，而应该告诉模型「什么时候该调用它」。

因为 description 总会被注入上下文，无论技能是否被使用。这涉及到一个重要的技术限制：AI 代理的每次交互都受限于上下文窗口大小（如 Claude 的 200K token 窗口），所有被注入的配置文件、Skill descriptions、代码文件内容都会占用这个有限空间。即使窗口容量看似充裕，在实际编程场景中它会被快速消耗——系统提示（数千 token）、AGENTS.md 内容（数千 token）、所有 Skill descriptions（数百到数千 token）、被读取的代码文件（可能数万 token）、对话历史（持续增长）都在竞争这一有限资源。更重要的是，研究表明当上下文接近饱和时，模型对中间位置内容的注意力会显著衰减（即「lost in the middle」现象），导致指令被忽略。

所有 Skill 的 description 会始终占据上下文空间，无论它们是否被触发——所以它更应该像一组「触发关键词」而非详细说明。过长的 description 会挤占代理用于理解代码和生成回复的可用空间，反而降低输出质量。

比如「照看 PR」技能的 description 完全可以简化为「当用户要求 monitor、watch 或 babysit 一个 PR 时使用」。理解这一点，能显著提升技能被正确触发的概率。

用好坏示例教会AI代理你的审美标准

Theo 曾对代理生成的 PR 标题深恶痛绝。他举了一个反面例子：某个 PR 标题叫「Fix Server. Parse CLI version in update preflight」，配上一段谁也看不懂的摘要。

他的解决方案是给代理提供具体的好坏对照：

• 差的标题：Perf server negotiate per message deflate on the web socket
• 好的标题：Perf server cut web socket frame size by 70% with gzipping

他总结道：「代理非常擅长从好坏示例中学习。如果你发现代理某个行为很糟糕，把一两个正反例子放进技能或全局文件里，代理就知道了什么对你来说是好、什么是坏。」

这种方法的有效性与大语言模型的 few-shot learning（少样本学习）能力直接相关。模型不需要大量示例就能从少数对比案例中提取出抽象规则——在上面的例子中，模型能学到「好的 PR 标题应该包含具体的量化影响（70%）和用户可感知的结果（frame size reduction），而不是技术实现细节（negotiate per message deflate）」。

另一条改变了他工作流的指令是：PR 描述应「先用简单语言基于用户原始需求解释问题，再简要说明解决方案，不要一上来就罗列实现清单」。这让 PR 从一堆技术堆砌变成了人类可读的清晰说明。

让AI代理审计自己：数据驱动的配置优化

Theo 分享的最具启发性的做法，是让代理去审计自己的历史记录。

Claude Code 在本地文件系统中以 JSON 格式保存每次会话的完整记录，通常位于 ~/.claude/sessions/ 目录下，包含时间戳、用户输入、模型输出、工具调用（如 Bash 命令执行、文件读写操作）的详细日志。OpenAI Codex 则通过云端 API 保存交互记录。这些结构化日志使得系统性的事后分析成为可能。

让代理「审计自己」的做法，本质上是让模型读取这些结构化的历史日志，运用其分析能力识别重复出现的错误模式。这种元认知（meta-cognition）策略利用了大语言模型强大的模式识别能力——模型可能无法在执行时避免某个错误，但事后回顾大量案例时，它能准确地归纳出系统性问题并提出修正建议。这类似于人类的「复盘」行为，但模型能在数百次会话记录中进行统计级别的分析，发现人类凭记忆难以捕捉的低频模式。

他让 Claude 翻查自己在 Claude Code 和 Codex 上与 Opus、GPT-5.6 等模型的交互历史，统计最常见的错误模式，并按模型和 harness 分类计算频率。

结果相当有价值：他发现 Opus 5 极其频繁地「杀错进程」——经常把它自己运行所在的 T3 Code 实例给关掉了，而且这一行为在仅两天使用中的次数就远超他用了很久的其他模型。数据还显示 Codex 有 40% 的时候会提交 draft（草稿）PR，其他模型则很少这样。

Theo 建议：当某个任务的结果不如预期时，直接问代理「你为什么这么做？是什么让你觉得这个方向是对的？」答案往往能暴露出 CLAUDE.md 里过时的信息，或是早期误读后一路将错就错的上下文。基于这些真实失败案例来优化配置，远比凭感觉猜测更有效。

项目级AGENTS.md配置：不是README而是操作手册

Theo 特别指出一个常见误区：AGENTS.md 应该与 README.md 截然不同。README 是给人类和代理判断「要不要用这个项目」的上下文；而 AGENTS.md/CLAUDE.md 的核心是告诉代理如何在代码库中做修改、以及修改前需要知道什么。

在 T3 Code 的项目配置中，他写了一份词汇表（glossary），用极其简单的语言定义术语：「you」指正在读这个文件并修改 T3 Code 的代理；「we/us/maintainers」指 Theo、Julius 和团队；「provider」指 Codex、Claude、Cursor 等运行时。他强调词汇表的价值不只是让代理理解他，更是让代理用他想要的方式向他描述事物。

他还写了一段「T3 Code 的特别之处」，列出绝不能妥协的核心原则——开源、极致性能、远程就绪、多端支持（web/desktop/mobile）。T3 Code 是一款基于远程优先（remote-first）架构的代码编辑器，基于 VS Code 的开源内核构建，但重新设计了对 AI 代理的深度集成能力，支持 Web、桌面和移动端多端运行。远程优先意味着计算密集型操作（如语言服务器、AI 推理、文件索引）运行在远程服务器上，本地客户端仅负责 UI 渲染和用户交互，从而实现跨设备的一致开发体验。这段内容的价值在于告诉模型「哪些东西无论如何都不能破坏」，同时省去了代理花前几个工具调用去搜索和翻文件搞清楚项目是什么的时间。

多端架构的完整性检查清单

针对 T3 Code 多端架构的特点，Theo 加入了一条极具实用价值的指令：

这个仓库最常见的缺陷，就是一个改动只在你测试的路径上生效，却在其他地方全部缺失。

T3 Code 支持 Web（浏览器）、Desktop（Electron/Tauri 桌面应用）和 Mobile（移动端）三种运行环境，同一个功能可能需要在不同的渲染层、不同的 API 接口、不同的平台限制下分别实现或适配。AI 代理在修改代码时，往往只关注当前正在编辑的文件路径，而忽略了相同逻辑在其他平台入口的对应实现——模型缺乏对项目整体架构的「空间感知」，不会主动思考「这个改动是否需要在其他地方同步」。

他要求代理在完成前端工作前，逐项检查所有入口（设置页、命令面板、快捷键）、所有客户端（web、desktop、mobile）、所有 provider 适配器，以及描述跨 WebSocket 传输内容的 contracts 包。

WebSocket 是一种在客户端和服务器之间建立持久双向通信通道的协议。与传统 HTTP 的请求-响应模式不同，WebSocket 维持一个长连接，允许服务器随时向客户端推送数据——在 T3 Code 的架构中，这意味着实时代码补全、诊断信息和 AI 生成内容都通过 WebSocket 流式传输到前端。contracts 包则定义了通过 WebSocket 传输的数据结构和接口规范（类似于 API 的 schema 定义），确保前后端对消息格式的理解一致。Per-message deflate 是 WebSocket 协议的一个扩展，允许对每条消息单独进行 gzip 压缩以减少带宽消耗——这对远程编辑器的响应速度至关重要。

这一条大幅减少了「只改了桌面端却漏掉网页和移动端」的问题。

最终效果：更短的prompt，更懂你的代理

所有这些工作的最终目标，用 Theo 的话说：「我不只是想让模型技术上更强，更重要的是让模型更擅长与我沟通。」

他展示了配置到位后的真实工作流。比如他要给营销网站加 iOS/Android 应用入口，代理用他的 HTML 技能生成了 A/B/C/D 几个方案的模拟图，他只需回复：「用 C+D+A，file and babysit（提交并照看）。」这个极短的 prompt 就能完成他想要的一切——因为 C+D+A 是代理刚给他的上下文，而 file、babysit 会触发对应技能补全其余细节。

他还有一个「文件上传」技能，允许代理把截图、录屏上传到 R2 生成公开 URL，嵌入到 PR 里。R2 是 Cloudflare 推出的对象存储服务，兼容 Amazon S3 API 但不收取出站流量费用，常用于存储静态资源和媒体文件。在这个工作流中，代理可以自动截取 UI 变更的效果图或录制交互演示视频，上传到 R2 获取公开链接，然后将链接嵌入到 PR 描述的 Markdown 中。这样即便在手机上，也能让代理构建功能、录制演示、上传并在 PR 中展示视频，极大改善了远程协作的反馈闭环。

核心原则：别复制配置，要理解方法论

Theo 全程反复强调一个观点：不要直接复制他的配置文件。他甚至故意不公开这些文件。

这些文件的价值不在于我具体写了什么指令，而在于我思考它的方式、我添加这些内容的原因，以及我到达这里的路径。

他的核心主张是：AGENTS.md、CLAUDE.md 和 Skills 应该由你自己基于实际需求和与代理协作的经验逐步构建。要写出好的技能文件，你必须理解你的代理如何工作、在哪里失败。这个打磨过程本身，就是提升你对 AI 编程理解的最佳途径。

对于任何深度使用 Claude Code、Codex 等编程代理的开发者而言，Theo 的这套方法论提供了一个清晰的框架：把重复的口头指令沉淀为规则，用真实数据驱动优化，用好坏示例校准审美，并始终记得——配置的终极目的不只是让代理写更好的代码，更是让它更好地与你沟通。

核心要点

核心要点