手写Agents.md，让AI编程稳定性大幅提升

在AI编程工具日益普及的今天，很多开发者习惯让AI自动生成一切，包括项目配置文件。但一位B站UP主基于两个真实项目的对比经验，提出了一个反直觉的观点：Agents.md一定要手写。这并非教条，而是源于对AI智能体工作机制的深刻理解。

两个项目，两种开发模式

UP主以自己正在开发的两个项目为例。第一个是高性能视频编辑器，基于Rust原生技术构建，支持4K视频流畅滑动和字幕、透明度编辑，对性能要求极高。第二个是卡牌推塔游戏，属于网页多人游戏，前端后端俱全，业务逻辑和美术资源复杂，但工程难度相对较低。

这两个项目不仅类型不同，开发方式也截然不同。视频编辑器采用半AI开发：UP主会精细审查AI生成的每一行代码，手动修改或通过对话指导调整，保留了传统程序员的微操习惯。即便如此，借助AI加持，这个3万行Rust代码的项目仅用三个月完成，速度达到以往手写代码的12倍。而卡牌游戏则采用全AI开发：99.9%的代码由AI直接生成，9天产出4.6万行，纯增量平均每天5000行，效率是半AI模式的15倍。

速度的飙升带来一个新问题：开发者不可能再逐行检查代码，甚至看都看不过来。那么，如何保持对项目的记忆和掌控？UP主指出，关键在于建立人与AI的共同记忆，而Agents.md和设计文档正是承载这份记忆的载体。

半AI开发与全AI开发的划分，核心区别在于人类对AI生成代码的审查粒度。半AI开发中，开发者仍保持对每一行代码的可见性，AI扮演的是高速打字机的角色，人类负责逻辑正确性和架构决策；全AI开发则将审查粒度从“行”上移到“功能”和“文档”，人类只在需求层面和验收层面介入。这种粒度变化带来的风险是：AI可能在实现中引入人类未察觉的隐性假设或架构漂移，而开发者因为不再逐行阅读，很难在早期发现。因此，全AI开发模式对文档化上下文（如Agents.md、设计文档）的依赖度远高于半AI模式，文档成了人类监督的唯一抓手。

Agents.md与技能：本质区别在于注入机制

很多开发者对Agents.md和技能（Skill）的区别感到困惑。UP主解释，两者都是上下文注入，但机制完全不同。技能是动态注入的：智能体将技能的description发给模型，模型根据当前任务判断是否相关，再决定是否加载技能正文。这个过程是概率性的、有条件的。而Agents.md是静态注入的：每一条对话，智能体都会将Agents.md完整注入模型上下文，它相当于一个永远启动的技能。

正因如此，Agents.md对模型的影响频率更高、程度更深。如果它写得不好，就会成为持续的上下文污染。反过来，如果由人手写，Agents.md就成了人和模型共同认可的“合同”——模型每轮对话必读，人也清楚其中每一条内容。若让AI自动修改Agents.md，内容可能散落在上百次对话中，开发者根本不知道最终写了什么。UP主手写的Agents.md仅22行（含空格不过十几行），而AI自动生成往往会膨胀到80行，导致共同记忆的丧失。

上下文注入指的是智能体在调用大语言模型（LLM）时，将特定文本内容拼接到模型的输入提示（prompt）中，从而影响模型输出的过程。由于LLM的上下文窗口有限（常见为8K至200K token），注入什么、注入多少，直接决定了模型能否获得完成任务所需的信息。常见的注入方式包括系统提示词（system prompt）、检索增强生成（RAG）和工具描述等。Agents.md本质上属于系统提示词的一种工程化封装，它通过文件形式固定下来，便于版本管理和团队协作。理解注入机制的关键在于区分“无条件注入”与“条件注入”：前者每轮对话都占据上下文空间，后者只在模型判断相关时才加载，两者在上下文预算和影响稳定性上差异显著。

设计文档：项目稳定性的第二基石

除了Agents.md，UP主强烈建议手写项目设计文档或产品需求文档。他分享了一个具体案例：游戏中主角名牌的鼠标悬停效果原本是一个圆圈，他希望改为整个UI高亮。于是他将这条需求写入设计文档，再发送给AI执行。

这个动作看似和直接在对话框输入没有区别，但对项目流程影响深远。几天后若功能被意外改坏，开发者可以开一个新对话（甚至换一个模型），粘贴需求文档让AI检查项目是否符合文档。AI能准确找到名牌悬停仍显示圆圈的问题并定位修改点。此外，设计文档还能用于自查前后矛盾，随着项目推进不断细化。

UP主强调，人脑记忆有限，但驱动AI稳定工作并不需要记住所有细节。只要手写好Agents.md和设计文档这两份文件，就能为AI提供清晰的上下文引导，同时让自己保持对项目的掌控。对于不擅长写技能的开发者，技能可以交给AI，但这两份文件建议亲力亲为。

产品需求文档（PRD） 在传统软件工程中是产品经理与开发团队之间的契约，描述功能行为、边界条件和验收标准。在AI编程场景下，PRD的角色发生了微妙变化：它不仅是给人看的，更是给模型看的。当开发者把PRD粘贴给AI并要求“检查项目是否符合文档”时，模型实际上在做一次基于自然语言规格的静态审查。这种审查的有效性取决于文档的精确程度——模糊的描述会导致模型做出宽泛的解读，从而漏检问题。因此，面向AI的设计文档应尽量使用可验证的表述（如“鼠标悬停时整个UI高亮，而非仅圆形图标”），避免“体验流畅”这类主观形容词。这与传统PRD的写作原则一脉相承，但在AI执行场景下，精确性的收益被放大了。

适用边界与核心启示

UP主特意澄清，这一观点并非适用于所有人。对于小型项目或临时脚本，让AI自动生成Agents.md完全可行。但对于复杂度较高、持续迭代的项目，尤其是非科班出身、借助AI入门的开发者，手写Agents.md和设计文档是避免项目失控的有效手段。

AI编程的速度优势肯定的是，但速度也意味着人类监督的粒度必须调整。从逐行审查到文档驱动，开发者的角色从代码编辑者转变为项目架构的定义者。Agents.md和设计文档就是这一转变的锚点——它们既是AI的上下文，也是人的记忆外脑。