第 22 章详细提纲：AGENTS.md、CLAUDE.md 与仓库级规则

本章主张

仓库规则的价值不在于把所有要求塞进一个入口文件，而在于让 Agent 能以短入口定位稳定约束、当前状态和任务专用工件；任何产品特有加载机制都必须与本书的规则组织模型分开表达。

学习目标与依赖

项目	内容
章节目标	设计短入口、分层规则、可变状态与局部任务材料，并在行动前发现冲突、范围泄漏和过期状态。
前置章节	第 3 章（仓库上下文）、第 5 章（指令层）、第 10 章（状态）、第 12 章（权限）与第 21 章（产品适配）。
后续章节	第 23 章把重复流程放入 Skills、Hooks 与自动化；第 26、27、45 章处理协作、Git 与跨工具交接。
非目标	不教授产品内部提示词、hook 配置、Sandbox 实现、真实权限或跨产品优先级。

章节结构

1. 场景：规则越多，为什么反而更容易漏读

情景：入口文件同时复制风格、构建命令、当前任务、旧审查结论，下一位 Agent 不知道哪部分可信。
成功标准：读者能指出“重复的当前状态”与“缺少任务入口”是不同问题。
边界：不声称某产品必然漏读；这是仓库维护风险。

2. 五类工件按更新频率分层

层	回答的问题	更新责任	例子	不负责
根入口	从哪里开始、结束时验证什么？	维护者	`AGENTS.md`、`CLAUDE.md`	容纳完整流程或当前状态。
稳定规则	长期约束、质量门、禁止事项	团队	`BOOK_RULES.md`、风格指南	记录当天进度。
项目上下文	项目目的、设计理由、结构	维护者	`.context/PROJECT_CONTEXT.md`	替代任务验收。
可变状态	已完成、阻塞、下一步	当前执行者	`CURRENT_STATE.md`、`NEXT_TASK.md`	成为历史档案。
任务局部材料	具体范围、模板、研究与审查	任务执行者	Chapter Brief、模板	覆盖稳定安全约束。

3. 产品事实：两个入口解决的是相似问题，不是同一实现

Codex： 受 REF-075 限定，AGENTS.md 用于持久仓库指导；说明全局、仓库与目录层次，以及保持根文件短小的建议。
Claude Code： 受 REF-076 限定，CLAUDE.md 是持久上下文而不是强制配置；可将 AGENTS.md 导入 CLAUDE.md 避免重复。
可移植结论： 两者都支持“保持稳定说明可定位”，但不支持把一方的发现/覆盖细节迁移到另一方。
明确不推出： 文件读取、规则遵守、权限拦截、测试通过或真实效果。

4. Rule Record 与 Rule Packet

Rule Record 字段：id、layer、scope、directive、source、status、revision、可选 conflictKey。
Rule Packet 输入：任务路径、规则集合、状态新鲜度与本书策略。
Packet 输出：准备加载的有序规则、缺少层、陈旧状态、范围外规则和冲突原因。
这一协议是本书模型；各产品实际如何串接文件由写作日官方资料决定。

5. 读取顺序与保守出口

从适配当前工具的根入口识别启动流程。
读取稳定规则与项目上下文，得到不变量和目录职责。
读取可变状态与进度，确认当前任务、阻塞与最近校验。
读取任务局部规则、模板、来源和示例计划。
先做 Rule Packet 检查：缺层补证、状态未知/陈旧先复核、同层冲突阻止修改。
只在 Packet 就绪后编辑；完成后以真实校验回写状态和交接。

6. 图示：仓库规则加载与停止边界

从入口开始，依序流向稳定规则、项目上下文、可变状态、当前任务和局部模板。
状态新鲜度未知进入“核对最近可复现证据”；冲突进入“维护者裁决”；范围不匹配进入“缩小任务或补充专用规则”。
所有通过路径才允许准备 Rule Packet，不表示产品已自动加载或允许写入。

7. 最小示例：纯内存规则加载评估

assessRepositoryRuleLoading({ task, rules, state, policy })。
关键路径：完整分层、缺少必须层、状态不新鲜、同层同范围冲突、范围不匹配、已废弃规则和缺规则元数据。
不读取真实文件，不使用日期/时钟，不调用 Codex、Claude Code、hooks 或网络。

8. 工程案例：本书仓库的共同入口

Codex 入口保持导航性，指向启动、规则、状态与任务工件。
Claude 入口引用相同的稳定规则而不复制整本规则；只放工具需要的最小差异。
当前任务信息保留在状态文件而非入口；章节细节保留在目录下。
当入口与状态矛盾，最近可复现校验和实际工件优先；不能靠入口正文“看起来更新”判断。

9. 实现、测试与升级边界

函数输出 ready_to_load 只表示教学对象满足 Packet 的最小条件。
真实仓库需将读取日志、路径解析、版本、文件权限、敏感信息与执行授权交给相应工具和第 12、17、23、41 章。
规则变得过长或频繁跨目录变化时，优先拆分稳定规则、局部规则或 Skills，而不是继续向入口追加。

10. 常见错误、安全边界、总结与练习

错误：把 AGENTS.md 当知识库、把当前任务写进稳定规则、用“更高优先级”掩盖冲突、把文本规则当权限、把规则版本当真实状态。
总结：入口负责导航；规则定义预期；状态提供当前事实；验证与权限另有边界。
练习：为一个单服务仓库设计最小入口、Rule Record 表与陈旧状态演练。

计划交付物

原创正文、Research Brief、详细 Outline、事实核验与候选参考资料。
assessRepositoryRuleLoading 的纯内存示例及 Node 内置测试。
Mermaid 源、SVG、PNG 和图示审查。
技术、示例、图示、语言与终审记录；共享引用登记和状态更新由主线程执行。

完成检查

[x] 第 3、5、21 章与本章的职责明确分开。
[x] 产品事实仅使用 REF-075 与 REF-076 的限定范围。
[x] 读取顺序、Rule Record、Rule Packet 和案例均明确为本书工程模型。
[x] 纯内存示例、停止边界和后续升级触发已规划。