你把 AGENTS.md 写成咒语大全，Agent 还是会乱改
AGENTS.md 最该做的不是塞满规则，而是把 Agent 带到正确的规则门口：OpenSpec 管 WHAT，Superpowers 管 HOW，AGENTS.md 管 WHERE。
晚上十一点多，我盯着终端里那段 diff，第一反应不是生气，是有点懵。
我明明只让 Agent 改一个很小的接口判断。结果它顺手动了 service，改了 model，又把测试绕过去了。最后还很认真地补了一段解释：这些改动是为了保持架构一致性。
这句话最气人。
它不是胡来。它看起来甚至很努力。可你知道，这个项目里权限逻辑不能这么碰，数据库字段不能顺手改，测试没跑就说“已验证”更不能接受。
于是你打开 AGENTS.md，开始往里面加规则。
不要乱改。不要跳过测试。不要引入没确认的依赖。不要动工作区外的文件。不要提交。不要重构。不要假装验证。
过几天，它还是会在另一个地方犯同类错误。
更烦的是，它不是每次都乱。小改时挺听话，一到多文件联动、接口变更、数据库字段、安全策略，它又开始像一个拿到权限但没进过项目组的人：先动手，动完再解释。
这时候很多人的第一反应是继续加规则。
AGENTS.md 越写越长，CLAUDE.md 越写越像公司制度，Cursor Rules、OpenSpec、Superpowers、各种 skill 又各写一套。最后真正开工前，Agent 先读半天，人也要猜半天：今天到底该按哪份规则来？
问题不一定是规则太少。
更多时候，是你把不同层级的规则塞进了同一个入口。
AGENTS.md 不该是咒语大全。它更像 Agent 的入职导航。
它最重要的工作，不是把每一条纪律都背给 Agent 听，而是告诉它：这类问题去哪里读、什么事情必须先停下来、哪些文件才是当前项目真正的制度。
AGENTS.md 越长，未必越稳
AGENTS.md 官网对它的定位很朴素：README 是给人看的，AGENTS.md 是给 Coding Agent 看的。构建步骤、测试命令、代码约定、安全注意事项，这些不适合塞进 README 的 Agent 细节，可以放在这里。
这句话容易被误读。
很多人会把它理解成：既然 Agent 会读 AGENTS.md，那所有规则都往里面放。
于是一个文件开始膨胀：项目背景、架构说明、业务概念、测试命令、提交规范、分支策略、重构原则、安全边界、调试流程、代码风格、长期 roadmap，全放进去。
看起来很完整。
但 Agent 真正执行任务时，完整经常不等于清楚。
你让它修一个拼写错误，它读到一堆“重大变更必须先开 proposal”；你让它改认证策略，它又在同一个文件里看到“低风险修改可以直接执行”。规则没有分层，它就只能临场猜：这次到底算 typo，还是架构变更？
不给 Agent 分级，它就会把 typo 和架构重构用同一种速度处理。
这不是模型笨，而是制度没说清。
人类团队不会把新人入职手册、年度规划、数据库迁移审批、单元测试规范、代码评审 checklist 全塞进同一页 Notion。因为每类信息解决的问题不一样。
Agent 也一样。
它需要入口，但入口不是仓库垃圾桶。
一个更好的结构：让 AGENTS.md 只负责带路
我最近看到 Linux DO 上 Hexon-X 分享的一套做法，核心不是“写了一个很长的 AGENTS.md”，反而是把根目录 AGENTS.md 压成了入口。
根据主楼贴出的文件内容，它大概指向这些层：
| |
这套结构真正有价值的地方，不是文件名本身。
你完全可以不用 CLAUDE.md，也可以不用 OpenSpec。重要的是它把几种经常混在一起的东西拆开了。
AGENTS.md 只告诉 Agent：本项目的总规则去哪读，变更流程去哪读，项目知识去哪读，roadmap 去哪读；当前 shell、OS、包管理器和常用命令有什么坑。
它像一个门牌系统。
门牌系统不负责审批预算，也不负责写代码。它只负责让人不要走错楼层。
真正的协作章程，放到 CLAUDE.md 或等价文件里：哪些事能直接做，哪些事要先收集上下文，哪些事必须等人确认。比如把任务分成 L0、L1、L2：
| |
变更治理，再交给 OpenSpec 这类 spec-driven 文件：proposal 怎么写，tasks 怎么拆，design 什么时候需要，spec delta 怎么归档，实施中发现范围变了该怎么办。
项目知识，放到 project.md：技术栈、架构分层、业务概念、API 路径、安全约束、并发热点、验证命令。
roadmap 只放长期缺口和治理方向。它不是任务单，更不是让 Agent 自己发挥的愿望池。
这样拆完以后，AGENTS.md 反而可以更短。
短不是偷懒。短是因为它终于不抢别的文件的工作了。
OpenSpec 管 WHAT：这次到底要改什么
OpenSpec 的价值，不是让你显得流程很正规。
它解决的是一个更具体的问题：高风险变更不能只存在于聊天里。
你让 Agent “顺手把授权逻辑优化一下”，这句话在人脑里可能只是一个小需求，但落到代码里可能牵涉权限模型、数据库字段、API 契约、兼容性、测试策略。
如果没有一个变更对象，Agent 很容易直接开工。
开工之后，范围就开始滑。
先改 service，再改 model，再改 handler，再补测试，最后突然发现前端也要改。你问它为什么动这么多，它会给你一段很合理的解释。合理不代表可控。
OpenSpec 这类流程适合管 WHAT：
| |
它的核心不是文档，而是审批门。
什么算新能力？什么算破坏性变更？什么算安全策略调整？什么算性能优化但可能有回归风险？这些都应该在变更流程里说清楚。
只写“重大变更先规划”没有用。
Agent 不知道什么叫重大。
你要写成可判断的触发条件：
| |
这才是制度。
不是因为它严肃，而是因为它把“能不能直接动手”从模型感觉变成了项目规则。
Superpowers 管 HOW：动手时用什么纪律
另一个常见混乱，是把 OpenSpec 和 Superpowers 放在同一层比较。
这很容易吵偏。
OpenSpec 更像变更治理。它关心的是：要改什么，为什么改，边界在哪，谁批准，怎么归档。
Superpowers 更像执行方法。它关心的是：怎么 brainstorm，怎么写计划，怎么 TDD，怎么系统性 debugging，怎么在完成前 verification，怎么请求 code review。
一个管 WHAT，一个管 HOW。
你不能指望 OpenSpec 替你执行 TDD，也不该让 Superpowers 替代项目审批制度。
比如一个 L2 变更已经通过 proposal，接下来进入实现阶段。这时候 Superpowers 这类方法论就有用：先写计划，先复现问题，先定义验证标准，小步提交，完成前跑测试，请求 review。
但如果一开始就没说清楚这次变更能不能做、边界在哪里、哪些行为不能破坏，再强的执行方法也只是更认真地跑偏。
社区里也有人提到 Comet 这类把 OpenSpec 和 Superpowers 编排成管道的工具。这个方向很有意思，因为它承认两者不是替代关系，而是阶段关系：open、design、build、verify、archive。
但这里要收住。
Superpowers、Comet 都是社区工具，不是必选项。你完全可以不用它们，只保留自己的 TDD、debug、verification、review checklist。
关键不是装哪个工具。
关键是你有没有把“做什么”和“怎么做”分开。
很多项目的混乱，恰恰来自这里：审批制度还没建立，执行纪律先堆了一堆；或者流程文档写得很漂亮，真正写代码时没有任何验证习惯。
结果就是，一边有 proposal，一边还是不跑测试。
AGENTS.md 管 WHERE：让 Agent 去正确的地方读规则
AGENTS.md 最稳的位置，是 WHERE。
它告诉 Agent 去哪里找。
去哪里找仓库总规则。去哪里找变更流程。去哪里找项目知识。去哪里找 roadmap。去哪里找验证命令。当前机器是 Windows、macOS 还是 Linux，shell 是 bash 还是 PowerShell，rg、fd、jq、gh 这些工具是否可用，PATH 有什么坑。
这些信息很适合放在入口文件里。
因为它们影响 Agent 第一轮行动。
一个好的 AGENTS.md，开头应该像这样：
| |
这比写一百条“不要乱来”有效。
因为它不是在训话，它在路由。
AGENTS.md 不该和 OpenSpec 抢“变更流程”的职责，也不该和 Superpowers 抢“执行方法”的职责。它只要把 Agent 带到正确位置，已经很有价值。
全局规则越短，项目规则越具体
Linux DO 那个讨论里，13 楼有个简化派观点很重要：全局规则不要太长。
这点我很认同。
全局规则应该只放普适纪律：不越权，不碰工作区外文件，不假装验证，不做未请求的抽象，不引入投机性功能，版本敏感问题先查官方文档。
这些规则每个项目都适用。
越通用，越应该短。
项目规则则相反。它应该具体到当前仓库：技术栈是什么，目录结构怎么分层，哪些模块不能乱动，测试命令是什么，认证逻辑有什么坑，数据库迁移要怎么验证，提交信息要不要避开内部协作痕迹。
全局规则太长，会和工具本身的系统提示词打架。
项目规则太短，Agent 又只能靠猜。
一个比较稳的分层是：
| |
注意这里的顺序。
不是越重要越往 AGENTS.md 塞。
而是越入口，越短；越项目化，越具体；越高风险，越需要审批门。
规划文件不是无人值守许可证
很多人上 OpenSpec 或类似流程时，心里其实有一个期待：是不是 spec 写好后，就能让 Agent 放一晚上，第二天回来收 80% 的成果？
有时候可以。
但不要把这个当目标。
规划文件的价值，不是取消人工判断，而是把人工判断提前。
没有 proposal 时，你是在 Agent 改完之后才发现它理解错了。那时候你要 review diff、追溯动机、回滚错误、重新解释需求。
有 proposal 时，你可以在它动手前发现问题：范围太大，任务拆错，验证不足，影响面没写，兼容性没考虑。
这已经省了很多时间。
但它不等于无人值守。
权限、安全、数据模型、计费、认证、核心链路，仍然需要人类 checkpoint。Agent 可以执行得很快，但快不是授权。
越是高风险变更，越不能把“写了规划”当成“批准开工”。
规划文件不是无人值守许可证，它只是把人工审批点提前了。
你明天可以怎么改自己的项目
如果你现在已经有一个越来越长的 AGENTS.md，不用推倒重来。
先做一件事：把它拆开。
第一步，把入口瘦身。
只保留这些：规则入口、项目知识入口、变更流程入口、roadmap 入口、工具链事实、读取顺序。其他东西先挪出去。
第二步，补一张任务分级表。
不用复杂，先写清楚 L0、L1、L2。小修能直接做，中等改动要先计划，高风险变更必须 proposal。关键是把“高风险”写成具体触发条件。
第三步，把验证写成表，而不是口号。
| |
第四步，把项目知识从规则里拿出来。
技术栈版本、架构分层、业务概念、API 路径、安全约束、性能热点，这些不是纪律，是上下文。它们应该在 project.md 这类文件里稳定存在，而不是散落在聊天记录和 AGENTS.md 角落。
第五步，给 roadmap 一个边界。
roadmap 只写方向、缺口、优先级、完成标准。它不直接授权 Agent 开工。真正开工要变成 proposal 和 tasks。
这五步做完，你的 AGENTS.md 可能会变短。
这是好事。
因为一个项目真正成熟的标志，不是入口文件越来越厚，而是每类规则终于有了自己的位置。
约束 Agent 靠的不是更多咒语，而是更清楚的分层。
OpenSpec 管 WHAT。
Superpowers 或你自己的执行纪律管 HOW。
AGENTS.md 管 WHERE。
把这三件事分开，Agent 不会突然变聪明，但它至少不再需要猜：这一次，它到底该去哪找答案。
如果你已经在用 Coding Agent，不妨回头看一眼自己的 AGENTS.md。
它是在带路，还是在堆咒语？