Theo实战：用Markdown指令文件让AI真正懂你的开发意图

知名科技UP主、T3系列产品创始人Theo（t3.gg）最近坦言，他写视频少了，因为写代码的时间多得离谱——过去三天合并了几十个PR。而这一切效率跃升的背后，并非某个新模型或新工具，而是他花了整整两天、十几个小时打磨的一堆Markdown文件：全局 agents.md、CLAUDE.md 以及一系列自定义Skills。

这篇文章将系统梳理他的做法：如何编写这些指令文件、如何用AI审计自己的历史记录来发现失败模式，以及如何把这些配置同步到五台开发机器上。核心观点只有一个——你不该复制别人的配置，而该理解他是怎么思考的。

为什么全局指令文件如此重要

Theo坦言，过去近两年他几乎没动过全局的 agents.md 和 CLAUDE.md，因为他一度认为这些文件"没那么重要"。但当他开始大规模使用多个模型协作时，问题集中爆发了。

这里有必要解释一下这些文件的技术背景：agents.md 和 CLAUDE.md 是Claude Code（Anthropic推出的命令行AI编程工具）以及类似工具所支持的配置文件。当AI智能体启动时，会自动读取项目根目录或全局配置路径下的这些Markdown文件，并将其内容作为系统提示（System Prompt）的一部分注入到对话上下文中。全局文件影响所有项目，项目级文件只影响特定代码库。这种设计让开发者可以用自然语言定义AI的行为边界、编码风格偏好和工作流程规范，而无需修改任何代码。

他重写后的全局文件里，最有意思的是开头的自我介绍："我是CEO，你是我的智能体。"这看似多余，实则关键。他解释道：模型极其擅长匹配语气——你用什么方式和它说话，它就更可能用同样的方式回应你。这与大语言模型的训练方式密切相关：模型在海量对话数据中学到了"角色一致性"的模式，当你明确建立了一个权威-执行者的对话框架，模型会更倾向于遵循指令而非自作主张。

随后是一段"CEO留言"，明确表达偏好：喜欢有野心的想法、简单的系统、力所能及的软件；不要仅因复杂性已存在就保留它，不要因为某个机制"架构上看起来厉害"就引入它。这些话直接压制了模型动辄写一大堆不必要代码的倾向。

他特别强调加的两条："提问是只读不改"——解决了模型在你只是询问时就急着动手改代码的毛病；以及一条关于YAGNI（You Aren't Gonna Need It）的原则，抵制范围蔓延。

YAGNI是极限编程（Extreme Programming）中的核心原则之一，由Ron Jeffries在1990年代提出，核心主张是不要因为预测未来可能需要某个功能就提前实现它。在AI辅助编程的语境下，这个原则尤为重要——大语言模型天然倾向于生成「完整」的解决方案，包括抽象层、配置系统、错误处理的错误处理等你当前根本不需要的东西。Theo将YAGNI写入全局指令，本质上是在对抗模型的过度工程化（over-engineering）倾向，让它专注于当前需要解决的问题，而不是去构建一个面向未来的完美架构。

用AI审计AI：让数据告诉你模型在哪失败

这是整套方法论中最具启发性的一环。Theo没有凭空写规则，而是让一个智能体翻遍他在这台机器上跑过的所有历史记录，找出每个模型、每个运行环境最常见的失败模式，并按频率分类。

这种方法的深层逻辑值得展开：AI编程工具（如Claude Code、Cursor、Windsurf等）通常会在本地存储所有会话的完整日志，包括用户的每条指令、模型的每次回复、每次工具调用（文件读写、命令执行等）。这些日志本身就是一座数据金矿——它记录了模型在真实工作场景中的所有决策路径和失败点。Theo的创新在于用一个AI智能体去系统性地分析这些日志，相当于做了一次自动化的"事后回顾"（post-mortem），将主观的"这模型有时候不太对"变成了可量化的"这个模型在这类任务上有X%的失败率"。

结果非常直观：

• Opus 5 会激进地"杀错进程"，经常把自己运行所在的T3 Code实例都杀掉——两天内杀进程的次数比他过去用其它工具的总和还多
• Sonnet 提交的PR中有**40%**是无人审查的Draft PR，远高于其他模型
• 工具误用方面Opus是最糟的；过度构建方面Opus 5和4.8最激进

他还统计了"每100条用户消息对应的纠正次数"，虽然承认某些模型被纠正多是因为他把最难的活交给它、给的上下文更少，但这些数据依然帮他把主观直觉变成了可量化的改进方向。

Theo给出的通用建议是：当你发现某个AI会话没按预期走，去问智能体"你为什么做这个决定"。可能是 CLAUDE.md 里有过时内容，也可能是它一开始读错了东西然后一路错下去。让模型对自己的工具调用做分类复盘，你就能针对性地优化。这种做法在机器学习领域有一个更正式的名字——可解释性（Explainability）：不只关心模型的输出结果，还要理解它为什么做出这个决策，从而找到系统性的改进方向。

Skills的精髓：Description是触发关键词而非说明书

Theo分享了几个改变他工作方式的Skill，其中最重要的一个认知是大多数人（和AI）都写错了Skill的Description。

要理解这个观点，需要先了解Skills的技术机制。Skills是Claude Code和类似工具中的一种模块化配置系统。每个Skill由Description（描述）和Content（内容）两部分组成。Description会在每次对话开始时被无条件加载到上下文窗口中，供模型判断是否需要调用该技能；而Content只有在模型决定使用该Skill时才会被展开读取。这种设计类似于操作系统的按需加载（lazy loading）——Description相当于函数签名，Content相当于函数体。

他指出：Description会被无条件插入上下文，无论该Skill是否被使用。因此Description的意义不是详尽解释这个技能做什么，而是告诉模型什么时候该引入它——它应该是一组"神奇的触发关键词"。他见过很多Skill把所有细节都写进Description，结果模型根本不需要真正调用就已经拿到了全部信息，完全违背了设计初衷。更糟的是，过长的Description还会持续占用有限的上下文窗口（context window）空间——即使是拥有200K token窗口的模型，当上下文被无关信息塞满时，其对关键信息的注意力也会显著下降，这就是所谓的"中间丢失"（Lost in the Middle）问题。

基于这个原则，他把原本合二为一的PR技能拆成了两个：

File PR：让PR标题变成人话

他吐槽自己的智能体过去生成的PR标题晦涩到"连自己都看不懂"，比如那种堆满实现细节的长句。解决方法是给出明确的好坏对比示例：

• 坏例子：Perf: Server 在 WebSocket 上协商逐条消息 Deflate
• 好例子：Perf: Server 用 gzip 压缩 WebSocket 帧，大小减少 70%

他强调：智能体极其擅长从好例子和坏例子中学习。你只要把一两个真实的正反案例放进技能或全局配置，模型立刻就明白对你而言什么是好、什么是坏。这在AI领域被称为"少样本学习"（Few-shot Learning）——通过在提示中提供少量示例来引导模型行为，其效果往往远超纯文字描述的规则。研究表明，对比性的示例（同时给出正面和负面案例）比单独给出正面案例的引导效果更强，因为它帮助模型建立了一个明确的决策边界。他还要求描述开头必须先用大白话说明"问题是什么、解决方案是什么"，而不是一上来就列实现清单。

Baby Sit PR：让智能体照看PR直到变绿

这个技能负责监控PR、在需要时rebase、回应AI审查机器人的评论，并持续循环直到所有检查通过、所有人批准。关键规则包括：修改前先对照原代码核实机器人的每个发现、区分真实缺陷与基础设施偶发故障（即CI/CD流水线中的flaky test——那些因网络超时、资源竞争等非代码原因偶尔失败的测试）、以"代表CEO"的明确格式回复评论。

而最重要的一条是："不要让审查反馈把PR扩展得超出用户的原始目标。" 处理真正的缺陷，但避免范围蔓延。这再次呼应了YAGNI原则——AI审查机器人经常会建议"顺便也改一下这里"，如果智能体不加判断地全盘接受，一个简单的Bug修复PR可能膨胀成一次大规模重构。

文件上传与HTML沟通：让AI更会汇报工作

Theo反复强调一个核心主题：这一切的重点不是让模型更会写代码，而是让模型更擅长和我沟通。

这个观点反映了AI辅助编程的一个重要演进方向。早期人们关注的是"模型能不能写出正确的代码"，但随着模型编码能力的快速提升，瓶颈逐渐转移到了人机协作的沟通效率上——模型完成了工作，但你需要花大量时间去理解它做了什么、为什么这样做、结果是否符合预期。解决这个沟通瓶颈，比继续提升代码生成质量更能带来实际的生产力增益。

为此他构建了两个实用技能：

文件上传技能允许智能体把截图、录屏、日志、构建产物上传到他自建的服务器，返回一个公开URL。这样即便他在手机上用T3 Code，也能让AI把新功能的录屏URL发给他，或直接嵌入到PR里。他还在元数据里加了 requires 字段——没有配置token的机器就不该使用这个技能，而是提示用户，而不是去猜。这个 requires 字段的设计体现了一种"优雅降级"（graceful degradation）的思想：与其让智能体在缺少必要条件时尝试各种变通方案（往往导致更多错误），不如让它明确告知用户"我无法执行此操作，原因是缺少X配置"。

HTML沟通技能（源自Postplan）则用于生成供人阅读的HTML产物：规划、规格、调研结果、UI Mock对比等。他同样把它拆分：一个 Postplan Read 负责用curl（而非浏览器）读取URL，一个 HTML Communication 负责生成。他甚至做了个巧妙设定——只要提示词末尾出现"HTML"而无其他上下文，就自动触发该技能。这种设计让他可以用最短的指令触发复杂行为，比如在一段任务描述后面加一个"HTML"，AI就知道需要把工作结果渲染成可视化的HTML报告。

有了这些，他的提示词短得惊人。一个真实例子：修复某个CSS Bug，他只需说"我有个醒来的线程想结算但按钮点不动，诊断并修复，提交PR并盯着"——大约15分钟后就得到一个可合并的PR。这种极简提示之所以有效，是因为所有的行为规范、工作流定义和质量标准都已经预先编码在了全局配置和Skills中——他不需要每次都重复说明"PR标题要怎么写""检查失败了怎么处理"，这些信息已经成为了智能体的"肌肉记忆"。

关键认知：别复制要理解

面对无数"能不能把你的agents.md发出来"的请求，Theo明确拒绝——这是故意的。

他的理由很深刻：这些文件的价值不在于具体写了哪些指令，而在于他为什么加入这些内容、他走到这一步的过程。直接复制别人的全局配置，就像把别人的通用代码模板套用到你接触的每一个项目上，会污染你所有智能体在每件事里的工作方式。更具体地说，每个人的开发习惯、技术栈、团队规模、代码风格偏好都不同——Theo作为一个写TypeScript/Next.js的创业公司CEO的最优配置，对一个写Python/Django的大厂员工来说可能完全不适用，甚至有害。

他也顺带澄清了一个常见误区：agents.md 不该等同于 README.md。README是给人和AI判断"要不要引入这份代码"的项目背景；而 agents.md/CLAUDE.md 是告诉AI如何修改代码库、修改前应该了解什么。前者面向读者，后者面向执行者。用一个类比来说：README像是一栋建筑的外墙铭牌和导览图，告诉你"这是什么地方"；而agents.md像是施工规范手册，告诉装修工人"承重墙在哪、电线怎么走、哪些东西绝对不能动"。

他还特别推崇在文件里写术语表（Glossary）：定义清楚"你、我们、用户、AI智能体、提供商、客户端、环境、项目"这些基础词。这不只是帮AI理解他，更重要的是让AI按他想要的方式向他描述事物，让沟通对齐。这个做法解决的是一个被广泛低估的问题——语义歧义。当你说"用户"时，在不同上下文中它可能指终端用户、API调用者、或Theo本人；当你说"环境"时，它可能指开发/生产环境、操作系统环境、或Python虚拟环境。术语表消除了这种歧义，让每次对话都建立在共同的语义基础上。

AI工程正在变成写文案

Theo在视频最后感慨：他本质上是在"写文案"，却能借此改变自己网络上所有机器上AI智能体的行为，改动还能通过Tailscale + SSH自动同步到五台机器。

Tailscale是一个基于WireGuard协议的零配置网状网络（mesh network）服务，它能让分布在不同网络环境中的设备像处于同一局域网一样互相访问。Theo利用Tailscale + SSH实现配置文件同步，意味着他只需在一台机器上修改全局agents.md，就能通过脚本自动将更改推送到其他四台开发机上，确保所有环境中AI智能体的行为一致性。这种"一处修改、处处生效"的模式，让他对智能体行为的迭代周期从"每台机器分别调试"缩短到了"改一个文件、等几秒同步"。

这背后是一个正在成型的趋势：上下文工程（Context Engineering）正取代传统的代码编写，成为高效AI协作的核心技能。 上下文工程与早期的提示工程（Prompt Engineering）有本质区别：提示工程关注单次交互中如何措辞以获得更好的输出；而上下文工程关注的是如何系统性地管理AI在整个工作流程中接收到的所有信息——包括系统提示、项目文档、历史对话、工具定义、文件内容等。Shopify CEO Tobi Lütke曾公开表示，上下文工程是他认为未来最关键的技能之一。这个领域的核心挑战在于：模型的上下文窗口有限（即使是100K+ token的窗口也会因信息过载而性能下降），因此如何精确控制「什么信息在什么时候进入上下文」成为了关键决策。

而它的门槛不在于技术，而在于你是否愿意花时间——审计历史、发现失败模式、用好坏例子校准模型、精简触发关键词——去真正理解你的智能体如何工作、在哪里失败。

正如Theo所言："别盲目照搬我做的所有东西，借这个机会去更好地理解你的智能体在你的项目中是如何工作的。"这或许才是这篇文章最值得带走的一句话。

核心要点