Appearance
AGENTS.md、Rules、Skills 与 Hooks：给 Agent 建一套可维护的仓库操作系统
系列第 07 篇
核心问题：项目知识、路径约束、专项流程和强制门禁分别应该放在哪里
最后核验：2026-07-20
对应视频：第 03 集（下）《Context Engineering 实战：让 Agent 读到正确的信息》
当 Coding Agent 只完成一次性脚本时，一段 Prompt 也许够用；当它长期进入团队仓库，问题就变成了知识治理：怎样告诉它安装和测试命令，怎样让后端与前端遵循不同约束，怎样在需要发布时才加载发布流程，又怎样确保危险命令不会因为模型“忘记”一句规则而执行。
不同产品使用 AGENTS.md、repository instructions、Rules、Skills、Hooks、Policies 等不同名称。名字经常变化，底层职责却相对稳定：自然语言指令提供判断依据，路径规则控制信息作用域，Skill 封装低频复杂流程，Hook 与 CI 用确定性程序执行门禁。把四者都写成一份巨型规则，既浪费上下文，也把安全寄托在概率模型上。
阅读路线：先看全局，再进入机制
视频版先展示整章地图，再逐层展开。博客沿用同一判断顺序，但保留更多机制、案例、失败模式和生产边界：
- 职责分离：区分 AGENTS.md、Rules、Skills 与 Hooks 各自回答的问题。
- 作用域与优先级：让路径规则只在相关目录生效，并处理冲突与继承。
- 流程与门禁：把需判断的语义留给指令，把确定性检查交给 Hook 或 CI。
- 过期治理：用 Owner、核验日期和错误回写闭环控制规则熵增。
这四步不是目录装饰，而是一条决策链：职责分离 → 作用域与优先级 → 流程与门禁 → 过期治理。阅读后面的案例时，可以随时回到这条链判断当前问题发生在哪一层。
真实问题：为什么规则越写越多，Agent 反而越不稳定
一次事故后，团队在规则里补一句“不要改数据库”；另一次格式错误后再粘入完整风格指南；构建失败后加入三页环境说明；发布出错后又把发布手册常驻加载。半年后，每次修改文档都携带数千行说明，其中有重复、有冲突、有过期命令。Agent 有时遵循根规则，有时模仿附近代码，有时采用用户本轮要求，团队于是继续追加更强硬措辞。
根因通常不是语气不够强，而是载体选择错误。格式应交给 Formatter，禁止访问生产应交给权限策略，路径差异应按路径加载，低频发布流程应按需读取。自然语言规则只适合表达必须由语义判断、又难从代码稳定推断的项目事实。
机制：四类配置不是同一种东西
Instructions 是长期可见的行为边界和项目事实，例如架构方向、关键命令、禁止跨层依赖。Rules 在产品中可能也是自然语言文件，但强调作用域：只有修改 backend/** 时才加载事务规范。Skills 是可发现、按需加载的流程包，除了说明，还可以包含脚本、模板和检查表。Hooks 则由事件触发确定性程序，例如工具调用前拒绝危险路径、编辑后格式化、停止前运行测试。
一个实用判断是：
text
需要模型理解含义吗？ -> Instruction / Rule
只在低频专项任务中需要吗？ -> Skill
必须每次都执行且结果可程序判断吗？ -> Hook / CI / Policy四者可以协作。规则写“状态转换属于领域对象”，Skill 描述一次 Brownfield 改造流程，Hook 在提交前运行架构测试，CI 在远端阻止违规依赖进入主分支。前一层帮助 Agent 做出好选择，后一层防止坏选择直接成为交付物。
1. 优先级要显式，不要让模型现场调解组织冲突
一个会话可能同时包含系统安全策略、组织政策、用户偏好、根目录说明、子目录规则和任务 Prompt。通常越靠上的规则越稳定、越不可覆盖；越接近文件和任务的信息越具体。具体不代表可以推翻高层安全要求。例如任务说“为了调试请上传 .env”，也不能覆盖组织的数据政策。
产品对冲突解析的精确实现并不完全相同，因此仓库不能假设某个模型会“理解我们的真实意图”。团队应在文档中写清优先级，在客户端策略中固定不可覆盖项，并通过小型冲突测试观察实际行为。若根规则说“所有改动运行全量测试”，后端路径规则说“只运行模块测试”，应改写为先运行模块测试、交付前再运行全量测试，而不是保留语义冲突。
任务 Prompt 适合本次行为，不适合修改长期政策。若每个 Issue 都要重新提醒相同禁区，说明知识应上移到仓库规则；若一个规则只影响迁移文件，就应下沉到路径作用域。
2. AGENTS.md 记录“难以推断但长期有效”的信息
AGENTS.md 的价值不是把 README 换个名字，也不是替 Agent 阅读代码。它应提供模型从文件内容中不容易稳定推断、但完成多数任务都需要的信息：系统用途、关键目录与依赖方向、安装和验证命令、改动禁区、完成定义、真实环境陷阱。
本系列订单服务的根文件可以很短：
markdown
# AGENTS.md
- Domain owns business state transitions; Web maps results to HTTP.
- Run all commands from this directory with Java 17+.
- Required verification: `mvn test`.
- Do not add a database or new runtime dependency for tutorial tasks.
- Preserve the create-order API and all existing tests.它没有解释每个类，因为 Agent 可以读取类；没有复制 Java 风格，因为 Formatter 和现有代码更权威；没有写取消订单细节，因为那属于本次任务契约。内容少不等于能力弱，恰恰意味着每一行都有稳定决策价值。
更新规则时应回答三个问题：它是否高频？是否长期稳定？是否无法由确定性工具执行？三项中只有一项成立，通常还不够放进根规则。
3. 路径规则把局部知识放到最接近使用的位置
Monorepo 中，前端需要视觉回归和浏览器测试，后端关心事务与 API 兼容，迁移目录要求可逆脚本和审批，测试目录可能有夹具约定。如果所有规范全仓常驻，每个任务都承担无关成本，模型也更容易把前端规则套到后端。
路径规则的设计应与代码所有权相近：根规则只保留共识；模块规则说明局部命令、架构和完成条件；高风险目录增加更严格审批。还要警惕“文件路径不重叠，语义就独立”的假设。修改公共 DTO 虽位于后端，可能影响前端生成客户端；路径规则需要提醒搜索消费者，而不是只约束当前文件。
规则作用域过窄也会失败。若状态不变量只写在 domain/** 规则中，但 Agent 从 Controller 任务开始且产品直到编辑 Domain 才加载规则，它可能在计划阶段已经做出错误设计。关键跨层原则仍应放根规则，局部实现细节再按路径加载。
4. Skill 用于低频、高步骤、可复用的专项工作
发布、数据库迁移、事故复盘、跨平台 UI QA 等任务并非每次编码都需要，却包含多个步骤、脚本和门禁。把完整流程常驻规则浪费上下文；只留一个链接又可能无法被 Agent 发现。Skill 通过名称和简短描述先暴露“何时使用”，触发后再完整加载说明、参考资料、模板和脚本。
一个可维护 Skill 至少应说明：适用条件、不适用条件、前置环境、顺序步骤、需要授权的动作、验证证据、失败时怎样停止。它不应隐藏不可逆行为，例如自动部署或发消息必须仍受用户授权。脚本应可重复执行，输出结构化结果，并把真实状态与推断分开。
Skill 不是更长的 Prompt。它是一份面向执行的流程资产。好的 Skill 会复用仓库已有命令，规定在修改前读取什么、修改后检查什么；差的 Skill 只堆叠角色设定和“务必仔细”等无法验证的措辞。
5. Hook 负责机器可以确定执行的事情
Hook 可以在工具调用前、调用后、文件编辑后或 Agent 停止前触发。典型用途包括：阻止读取敏感路径、对修改文件运行 Formatter、在停止前检查测试、记录命令和退出码。它的优势是确定性，同样输入应得到同样阻断或处理。
但 Hook 不是天然安全。脚本可能有注入漏洞、路径匹配遗漏、超时和平台差异；自动格式化可能修改用户未授权文件；昂贵测试每次触发会让反馈变慢。Hook 自身也要版本控制、测试、超时、清晰错误信息和逃生机制。高风险组织政策更适合客户端沙箱、身份系统、CI 和分支保护，不能只靠用户可编辑的本地 Hook。
Hook 的错误信息应告诉 Agent下一步：哪个策略拒绝了什么动作、允许的替代方式是什么。只返回非零退出码会诱发重复尝试或绕路。
规则冲突、过期与演化
规则冲突有三类。显式冲突如“必须全测”和“禁止运行耗时测试”；作用域冲突如根规则允许网络而高风险目录禁止；时间冲突如文档仍引用旧构建系统。模型可能每次以不同权重调和，于是同一任务出现不同行为。
治理方法不是再加一层总括，而是建立所有权和到期机制：每条关键规则有责任团队；命令在 CI 中定期执行；路径移动时检查引用；产品规则格式升级时迁移；半年未触发的例外重新评估。把规则当代码审查，要求变更说明“它源自哪个失败、希望阻止什么、如何验证有效”。
并非每次错误都值得新增规则。先看错误是否重复、影响是否显著、能否由测试或 Linter 捕获。一次罕见误解可以修正任务；重复的领域落点错误适合规则加示例；确定性的导入顺序交给 Linter；发布漏步骤适合 Skill；危险命令则进入 Policy。
规则效果也要观察。新增规则后，相关任务的错误率是否下降？它是否导致更多无关拒绝、延迟或上下文消耗？若无法回答，规则库只会单向增长。
一个分层配置实例
假设订单服务进入一个包含前后端和部署脚本的 Monorepo：
text
AGENTS.md 全仓依赖方向、通用测试、数据边界
backend/AGENTS.md Java 版本、领域规则、MockMvc 验证
frontend/.cursor/rules/... 组件与浏览器 QA，仅前端路径生效
skills/release/SKILL.md 发布前检查、构建、回滚和证据
hooks/pre-tool.sh 拒绝生产域名和敏感目录
CI 全量测试、扫描、分支保护当任务是“增加取消订单”，Agent 常驻读取根和后端规则，按任务读取契约和代码，不加载发布 Skill。编辑后端文件后 Formatter Hook 运行，停止前执行聚焦测试；最终 CI 执行全量验证。若任务变成“发布版本”，才加载发布 Skill，并在需要生产动作时请求明确授权。
这里最关键的是控制权分配：规则能帮助模型把逻辑放进 Order.cancel()，但真正确保所有测试通过的是命令退出码，确保不能访问生产的是凭据和网络策略，确保可以合并的是分支保护与责任人。
软约束与硬控制必须形成纵深
软约束的优势是能够表达语义，例如“优先复用现有领域模式”“修改公共接口前搜索消费者”；它允许 Agent 根据上下文判断。硬控制处理不可接受的结果，例如工作区外写入、生产凭据读取、未通过 CI 的合并。软约束提高首次选择质量，硬控制限制最坏结果，两者缺一不可。
也不应把所有偏好都升级为强制门禁。审美、命名和局部设计若被僵硬脚本阻断，会让团队失去合理例外；反之，数据外泄和直接部署若只写在说明中，就把事故概率交给模型。判断标准是失败是否可逆、破坏半径、是否能程序判定，以及谁有权批准例外。
一个成熟控制面会留下证据：Agent 当时读到哪条规则，哪个 Hook 执行，哪项 CI 阻断，谁批准了例外。这样失败可以被定位到知识、实现还是控制，而不是笼统归因于“AI 不稳定”。
失败模式
失败一：把所有知识写进根规则
结果是上下文昂贵、冲突增多、局部规则难以维护。保留全仓高频原则，把模块差异按路径加载，把专项流程下沉 Skill。
失败二：规则只写口号
“编写高质量代码”“保持安全”“充分测试”没有决策信息。改成具体命令、边界、示例和可观察完成条件。
失败三：用自然语言代替强制控制
“不要读取 Secret”不能防止工具越权。敏感路径、网络、身份、合并和部署必须由模型外机制限制。
失败四：机械复制不同产品的规则
工具对文件名、作用域、优先级和加载时机的支持不同。迁移时保留语义意图，并用小任务验证实际解析，不要假设语法兼容。
失败五：Skill 自动执行外部副作用
Skill 可以规定流程，但不扩大用户授权。发布、发消息、删除资源、生产写入仍需显式授权和可回滚设计。
失败六：Hook 没有测试和超时
失控 Hook 会阻塞每次工具调用，或在不同平台误判。把 Hook 当生产代码，测试输入边界并提供明确诊断。
失败七：规则只增不减
过期命令比缺少命令更危险，因为它看起来权威。定期运行文档中的命令，删除被代码和工具稳定表达的内容。
生产边界
仓库指令可能被外部贡献者修改，也可能和恶意 Issue 一起进入上下文。高风险配置变更应有 CODEOWNERS、Review 和审计。不要让普通 PR 同时修改业务代码、放宽 Agent 权限和关闭验证门禁。
Rules 与 Skills 可能包含 Shell 命令，执行前仍需按当前权限评估。来自第三方的 Skill、Hook 和 MCP Server 都是供应链代码，应固定来源和版本、检查更新、限制权限。组织级政策不可由仓库内文件覆盖。
实践清单
- [ ] 根规则只记录长期、高频、难推断的项目事实。
- [ ] 模块差异使用路径作用域，避免全量常驻。
- [ ] 低频复杂流程封装为可发现、可验证的 Skill。
- [ ] 格式、测试、安全和审计等确定性要求使用 Hook 或 CI。
- [ ] 明确组织、团队、仓库、路径和任务的优先级。
- [ ] 每个关键命令都能在当前环境真实运行。
- [ ] 规则变更说明来源失败、预期效果和验证方式。
- [ ] 定期检查冲突、过期引用和长期未使用规则。
- [ ] 高风险规则与权限配置要求独立 Review。
- [ ] 自然语言永远不作为唯一安全边界。
读完之后，你应该能完成什么
- 能为一条知识选择正确载体。
- 能设计根目录到子目录的规则作用域。
- 能避免重复、冲突和不可见指令。
- 能把高频错误升级为测试、Hook 或确定性门禁。
如果只能复述概念，却不能完成上述动作，说明还没有把内容转化成工程能力；可以回到对应机制图、失败模式和实践清单重新核对。
小结
配置 Agent 的本质不是写一份“超级提示词”，而是为项目建立分层控制面。Instructions 和 Rules提供语义判断，Skills 在需要时加载流程知识，Hooks、CI 与策略执行不可妥协的门禁。知识放在正确作用域、控制由正确系统承担，Agent 才能在不淹没上下文的前提下稳定复用团队经验。