企业官网建设流程全解析

1. 这个分析本身是怎么做的，结论依据在哪

先说结论：那个统计结果我看完并不意外。过去一年里，我见过太多仓库里的 agents.md 像是从同一份模板里复制出来的——大段小作文、空洞的价值观宣言、和实际代码毫无关系的技术栈描述，真正能指导 AI 代理干活的内容占比极低。所以当看到公众号和论坛里疯传"2500+ 个仓库里大多数 agents.md 都写错了"时，我想先搞清楚这个结论到底是怎么得出来的，而不是急着站队。

1.1 扫描口径：什么样的仓库算有效样本

这类分析通常不是把 GitHub 上所有仓库都拉一遍，那样噪音太大。常见的做法是设置几个硬性过滤条件：仓库里必须存在名为agents.md、AGENTS.md或.agents.md的文件；仓库要有一定的活跃度，比如最近 6 个月有 commit；另外还会按 star 数或者 fork 数做个分层，避免全是个人练习项目。

按这个口径筛下来，2500 多份样本是合理的。真正有价值的不是总数，而是这个分析对文件内容做了量化切割。我记得公开讨论里提到几个维度：文件行数、是否包含明确的命令式指令、是否引用了具体文件路径、是否包含"禁止/不要/绝不"这类否定约束、以及最后一次更新时间距仓库最新 commit 的天数。

这些维度选得很聪明。它们不是在看文档好不好读，而是在看一份 agents.md 是否能被机器稳定地消费。行数过长通常意味着信息过载，AI 代理在读取时会被无关信息干扰；没有具体路径引用的指令基本等于空话；否定约束缺失则意味着代理经常做出越界行为。

1.2 几个说得上话的统计结果

网上流传最多的几个数字，我根据自己的经验重新验证了一遍思考逻辑。

第一是行数分布。大量 agents.md 集中在 50 到 200 行之间。这个区间本身没问题，问题在于内容密度。很多文件表面上看有 100 多行，实际上真正对代理执行任务有约束作用的指令只有三五条，其余全是背景介绍、团队协作规范、代码风格理念。

第二是路径引用比例。只有不到四分之一的 agents.md 写了具体文件路径或命令。这意味着什么？意味着代理读完这份文件后，依然需要自己漫游整个仓库去推测"构建命令是什么""测试命令是什么""哪些目录不能动"。与其说是指导，不如说是给了代理一张模糊的地图。

第三是维护滞后性。相当一部分 agents.md 的最后修改时间已经超过半年，而仓库本身还在频繁提交。描述文件与代码状态脱节，这在 AI 代理场景下是致命的。人类开发者能凭经验识别过时信息，AI 代理不会，它会按文件里写的错误规则执行。

我还比较在意一个细节：有效样本里有多少文件包含"你将""你应该""作为一名 AI 助手"这类主体称谓。这类表述在我看来是典型的"伪指令"——它是在做角色扮演，而不是在给代理限定行为。统计里这类文件占比不低，这直接支撑了"大多数写错了"的结论。

2. 错写背后的三个通病，以及它们是怎么坑代理的

不把错误分类讲清楚，光说"写得不好"没意义。我从样本分析与自己的维护经验里，总结出三个高度重合的通病。与其说是技术问题，不如说是思维惯性问题——大家太习惯"给人写文档"的逻辑，忘了这次要看文档的是 AI 代理。

2.1 把 agents.md 写成了 README 的复读机

这是我见过最多的情况。文件开头就是一段项目简介："这是一个基于某某框架构建的微服务系统，支持高并发、高可用，使用 MySQL 作为主要存储……"然后是一段克隆和启动命令，接着是目录结构树，最后以一句"如有问题请联系某某"收尾。

问题是，这些信息 README 里全都有。AI 代理在执行任务时，如果既加载了 README 又加载了 agents.md，等于读了两个重复版本。浪费 token 不说，更麻烦的是两个文件如果措辞不一致，代理会产生规则冲突。比如 README 里写"测试使用 Jest"，agents.md 里继承了这句话但没指定要跑哪些文件，代理可能会在改完业务代码后只运行一个无关的测试文件，然后自信地汇报"测试已通过"。

正确的做法是，agents.md 只写 README 里没有的东西：这个项目在修改代码时有什么隐藏约束，哪个目录绝对不能乱动，测试命令的精确写法是什么，新增一个接口需要同步更新哪三个文件。如果一条信息在人类文档里已经存在且没有歧义，就不该在 agents.md 里重复。

2.2 把 agents.md 写成了价值观宣言

另一种高频错误是大量使用"你应该遵循最佳实践""请编写高质量的代码""保持代码整洁""注意可扩展性"这类表述。听起来很正确，但对 AI 代理毫无约束力。什么叫"高质量"？什么叫"整洁"？不同模型不同版本对这类词的理解可能完全不一样，甚至同一个模型在不同上下文里的执行也不一样。

我在某个仓库里看到过这样的句子："作为智能助手，你应该主动思考用户的真实意图，并做出准确的判断。"看得我头皮发麻。这句话既不告诉代理该做什么，也不告诉它不该做什么，唯一的作用是占用上下文窗口。如果 agents.md 能被压缩成这样一句话——"本文件用于限制代理行为，不提供任何新信息"——那整个文件就是多余的。

AI 代理需要的不是价值观，是可执行的条件反射。比如"当你在src/utils/下修改工具函数时，必须同步更新tests/unit/utils下对应的测试文件"就是一条可执行指令。它包含动作、范围、触发条件、验证方式，代理读完就知道自己该干什么。相比之下，"请确保代码质量"这种话，代理读完只会困惑。

2.3 把 agents.md 写成了没人维护的化石

这类仓库的 agents.md 往往写于项目初期，之后再也没有更新过。项目可能已经从单体重构为微服务，目录结构彻底变了，构建工具从 webpack 换成了 vite，但 agents.md 还在指导代理运行一个已经不存在的新项目启动命令。

人类看到这种文档会怀疑、会去翻代码确认，AI 代理不会。它会严格按照 agents.md 里写的命令去执行，然后在你面前报出一串莫名其妙的错误。这不是代理蠢，是文档给它的指令本身就是错的。分析里那组"最后更新时间与仓库最新 commit 之间的间隔"数据，说的就是这个问题。

要避免这种化石化，不是靠意志力，而是靠机制。下面我会讲到具体的维护策略，核心思路是让 agents.md 和仓库事实之间建立强关联，每次改动都能被验证。

3. 有用的 agents.md 长什么样：从高分仓库里提炼共性

看了一堆反面案例，也得说说什么样算对。分析报告里评分较高的 agents.md，几乎都跳出了"项目介绍"框架，更像是给一名新同事写的岗位职责说明。这块我结合自己的实践，把共性拆开讲清楚。

3.1 先定义角色和边界，再谈技术细节

好的 agents.md 开头往往是这么一句话："你是本仓库的维护型 AI 代理，可以修改src/和tests/下的代码，不可以修改.github/下的工作流配置，不可以修改docs/下的对外文档。"没有多余的自我介绍，没有对仓库的溢美之词，上来就划定边界。

这个边界为什么重要？因为 AI 代理在处理复杂任务时，如果没有明确禁令，会出于"帮忙"的心态动它不该动的文件。比如代理被要求优化日志输出，结果顺手把 CI 配置文件里的一个签名给改了，理由是"这样更规范"。禁止项不是限制，而是保护，既保护仓库关键文件不被误改，也保护代理自己不被无效工作拖累。

边界还包括执行方式。有些仓库会写明："所有命令必须从仓库根目录执行""禁止使用sudo""不要安装新的 npm 包，除非你在修改报告中单独说明原因"。这些都是人类开发者天然知道但代理容易忽略的隐规则。

3.2 规则要用"条件-动作"结构，而不是散文

高评分 agents.md 里很难看到大段连续的自然语言段落，更多的是短小的指令条目，每条指令都遵循"在什么情况下，采取什么动作"的结构。比如：

• 当修改src/下的组件时，同时更新src/__tests__/下的快照测试。
• 当新增 API 路由时，在docs/api.md中追加对应段落。
• 当运行npm test时，使用--runInBand参数，避免并行导致的端口冲突。

这种写法叫规则可解析性。它不是给人读着舒服，而是让代理在生成代码时能直接匹配。代理决策过程本质上是在做模式匹配，如果给它的是一个清晰的条件-动作对，它命中一条算一条，执行结果都可预期。

我见过一个特别好的例子，是在一个 Python 项目里看到的一条规则："当脚本运行超过 5 分钟时，终止执行并输出当前进度，不要尝试继续等待。"这条规则解决的是一个具体的超时问题，但它让代理不用自己"思考"超时策略，直接把决策路径固化下来了。

3.3 所有描述都能对应到代码事实

高分文件的另一个明显特征是路径引用密度高。它们不是泛泛地说"项目使用 pnpm 管理依赖"，而是直接给命令：pnpm install --frozen-lockfile。不是写"业务逻辑在 src 目录下"，而是写"路由定义集中在src/router/routes.ts，新增页面需要同时修改该文件和src/router/types.ts"。

这种具体性带来的最大好处是减少代理的搜索成本。AI 代理帮忙写代码最耗时的环节就是定位，一份详尽的 agents.md 相当于把地图画好了，代理直接按路径走就行。很多人低估了这一点，总觉得让代理自己探索就行，结果代理在棵目录里翻来翻去找不到测试文件，最后直接新建了一个测试目录——这往往就是一次"神秘事故"的起点。

3.4 用"决策日志"解释为什么，而不是只写是什么

评分较高的仓库还会有一个隐藏特征：它们会把关键决策写进 agents.md，比如"这里使用自定义构建脚本而不是官方 CLI，是因为 CLI 不支持 monorepo 场景下的增量编译"。

这类信息乍一看像多余的背景说明，但在 AI 代理场景下非常值钱。代理在改动代码时，如果不知道为什么某处是现在这个样子，很可能把代码"重构"成一个看起来更标准但会破坏隐性依赖的版本。决策日志就是给代理注射一针"别乱动这里"的疫苗。

我自己的习惯是，每一条重大决策记录都包含三要素：决策内容（我们选择了什么方案）、放弃的方案（我们为什么不选另一个方案）、触发代价（如果改动这里会破坏什么）。有了这三个要素，代理在面对类似场景时就有了判断依据，不会仅凭代码表象行事。

4. 撰写和维护 agents.md 的具体操作准则

理论说完了，回到实践。我并不建议一上来就写一个完美文件，而是先搭一个够用的骨架，然后靠持续更新把它养起来。

4.1 从零到一分步搭建一份及格线以上的 agents.md

第一步，写边界。列清楚代理能碰什么、不能碰什么。这一部分最多十条，直接列。如果说不出十条，也别硬凑，先把最重要的边界写清楚。

第二步，写命令。把项目常用的构建、测试、格式化、类型检查命令全部写全，并且注明是否需要在根目录执行、是否依赖环境变量、是否有已知的坑。命令这块宁多勿少，它是代理干活时最常查询的信息。

第三步，写工作流。针对这个仓库最常见的几类任务，给出操作顺序。比如"新增一个组件"的流程可能是：创建组件文件、导出、更新路由、加测试、跑 typecheck、提交 PR。把流程写清楚，代理就能照着执行，不会跳步。

第四步，写禁区与警告。包括不能动的目录、不能安装的依赖、不能修改的配置文件、已知会失败的测试用例。这些信息往往来自踩坑经验，写成文档之前它们只存在于老开发者的脑子里。

四步下来，一份够用的 agents.md 就有了。不用追求一次写全，可以边用边补。

4.2 让规则可验证的三个小技巧

第一，规定"由谁验证"。每一条规则后面可以写清楚如何验证，比如"运行npm run typecheck确认无类型错误""检查git status，确保没有意外的文件变更"。有了验证方式，代理执行完规则后能自检，不需要你反复提示。

第二，刻意加入否定词。"不要使用any""不要让测试依赖网络""不要复制node_modules内的文件到项目其他位置"。AI 模型的指令遵循能力，在"不要"句式上比"应该"句式更可靠，因为否定约束建立了禁区，代理的探索空间被收窄，出错概率下降。

第三，给文件加"最后验证日期"字段。每次修改 agents.md 时，顺手更新一下这个日期。这个操作看似简单，能起到提醒作用：哪天发现这个日期和仓库最近提交时间差距过大，就该花十分钟检查文件内容是否过时了。

4.3 什么时候该更新，什么时候不该更新

有一个很现实的问题：agents.md 更新频率太高，代理在每次加载时都会读到不同版本，可能导致行为不稳定；太低，又容易变成化石。我的经验是两个时间点必须更新：一是项目的工程化配置发生变化时，比如换了构建工具、改了目录结构；二是发现了代理反复犯的同类错误时，比如代理三次都在同一个路径上误改了文件，那就应该把它写成一条新规则。

反过来，代码内部的常规增删文件不需要频繁变动 agents.md。它管的应该是"相对稳定"的约束与工作流，而不是琐碎的现状。如果你发现 agents.md 快赶上 README 一样长，就该考虑是不是过度设计了。代理不是人类，它不会欣赏你的文档写得有多全面，它只会在几百条指令里迷路。

5. 这次分析真正值得吸收的东西

说了这么多，最后我想聊聊这次分析真正让我受益的地方。它不是告诉我"大家写得多烂"——这我早知道；而是在一堆失败样本的衬托下，让我更加确信 agents.md 的定位：它是一件配置，不是一篇文章。

写配置和写文章的逻辑完全不同。写文章讲究流畅、完整、有文采；写配置讲究精确、可解析、可验证。一份 agents.md 如果拿掉所有形容词和客套话之后不留多少硬性指令，那它就是用错了文体。

还有一个收获是，agents.md 的维护应该绑定到工作流里，而不是靠自觉。我现在会在每次提交代码时，如果有涉及项目根目录结构调整或脚本变动的，顺手检查一遍 agents.md 是否还准确。这个习惯看起来不起眼，长期坚持下来，文件就很少腐化。

最后再说个个人体会：别指望 agents.md 一次就写得完美，把它当一个活文档来养。任何项目里真正有用的约束都存在人的脑子里，agents.md 要做的是把其中可固化、可执行的那部分一项项挖出来写下来。你每次发现代理做了什么蠢事，其实都是文件该补一条规则的地方。写错不可怕，可怕的是写完之后再也没人管它。