Update Agent Config 是一个面向成熟仓库的文档维护技能，用于在代码重构后刷新已经存在但已与当前代码产生漂移的 AGENTS.md 层级文档。它假设 AGENTS 层级已经存在；如果是从零创建根目录与文件夹级 AGENTS.md，应改用 init-agent-config。
用途
当出现以下情况时使用：审计 AGENTS.md / CLAUDE.md / REVIEW.md 文件；重构后 AGENTS 文档过期需要刷新；验证 src/AGENTS.md 中每个 file:line 引用是否正确；重新计算 src/AGENTS.md 中的颜色、字号、间距频率表；文档声称 X 但代码现在是 Y，需要全面清理漂移；查找没有 AGENTS.md 的代码文件夹并为其编写文档；查看哪些文件夹已有 AGENTS.md 覆盖及每个文件大小；schema 版本变化后清理所有引用旧字面量的文档；修复标记为 NOT YET LANDED 但文件已存在的清单表。
不适用于：从零搭建根目录与文件夹 AGENTS.md（使用 init-agent-config）；PR 审查（使用 run-review Mode A）；技能创建与维护（使用 build-skill）；审计开销不划算的一次性文档修复（如修正单个拼写错误）；AGENTS 已准确时的原生审查适配器生成（由 init-agent-config 第 12 步覆盖）。
文件职责
AGENTS.md 描述代理应如何工作、代码位于何处、存在哪些本地边界；更新模式关注刷新引用、重新计数表格、删除已落地的 NOT YET LANDED 存根。CLAUDE.md 是兼容性伴随符号链接，指向 AGENTS.md；需验证符号链接完整性，并为新缺口文件夹创建。REVIEW.md 描述哪些 diff 应被标记、保护或适用更高标准；更新严重性引用，删除已变为错误的规则触发短语。文件夹级 AGENTS.md 只写本地增量，绝不重述根文档；同样处理，并为新发现的承载代码文件夹新增。
硬性约束
编辑前必须审计，质量报告先于任何 Edit/Write 调用发布。只做可证伪的声明：每条涉及 file:line、函数/符号/CLI 标志或计数的陈述，在修正前都通过 grep -n / sed -n / wc -l 对当前 HEAD 验证。采用并行 Opus 审计员再并行 Opus 写入者的两阶段硬边界：审计员不编辑，写入者不重新审计。保持语气、结构、长度，就地修补，不因新措辞更整洁而重写。保持内部一致性，修正 §1 时检查 §8 是否矛盾。缺口文件夹的新文件以最接近的同类文件为模板，不使用全新模板。保持伴随 CLAUDE.md 符号链接完整，编辑后验证，仅在禁止符号链接时回退到 @AGENTS.md 包装并说明。声明完成前重新审计，scripts/audit-agents-md.sh 在编辑前后各运行一次并对比表面计数。没有 3 条以上仓库特定事实不得新增章节；更新不等于扩展。
防偏离约束
不要在审计完成前编辑文档；不要凭记忆重写，始终重新 grep/sed 并引用实际文件行号；审计员只产出发现，写入者才行动；写入者不重新运行审计，仅针对具体重计数重新 grep；不要因频率表大致正确而跳过重计数；不要保留 NOT YET LANDED 存根，先 ls 声称缺失的文件；不要让内部矛盾静默存活；不要重写语气；不要只审计标题而遗漏正文声明；更新期间不新增章节；不要假设每个目录都需要 AGENTS.md，多数文件夹应跳过，每轮新增 2–4 个文件属健康；不要翻页浏览构建噪声；不要在过期工作树或 vendored 副本中验证声明。
脚本
scripts/audit-agents-md.sh 用于 Phase 0 清单与编辑后重新审计：现有表面、行数、伴随符号链接状态、文件夹覆盖图（每个代码文件夹的 src 文件数 / LOC / AGENTS.md）、重复源风险。该脚本不修改文件。仅用于初始化的 scaffold-agents-md.sh 已移除，更新模式不生成全新骨架。
五个阶段
Phase 0 扫描 + 缺口检测 + 变更信号：三次只读操作。从仓库根运行 scripts/audit-agents-md.sh 获取现有表面与覆盖图；优先使用 treezip . 进行树扫描，未安装时回退到 tree -dL 2 .（monorepo 用 -dL 3）；从覆盖图选择缺口文件夹，候选需同时满足承载代码、规模足够（约 10 个源文件或约 1500 LOC 下限）、不变量密集、尚未被最近祖先 AGENTS.md 覆盖，预期跳过多数文件夹；对每个现有文档用 git log -1 --format=%ct -- <doc> 获取最后编辑时间，再对文档引用的源文件列出该时间之后的提交，作为审计范围。
Phase 1 质量报告（编辑前）：输出报告，不做编辑。包含表面、数量、平均分、过期引用数、备注等标题行，以及覆盖表列出每个承载代码文件夹的源文件数、源 LOC、AGENTS.md 状态与决策，每个跳过行附一行原因。随后询问用户要修复哪些文件、填充哪些缺口文件夹，并默认跳过编辑后的原生适配器重新生成。
Phase 2 并行 Opus 审计员派发：用户确认范围后，派发 3–5 个并行 Opus 代理，每个负责一组逻辑文件。每个审计员引用每条涉及 file:line / 符号 / 计数的陈述，用 grep -n / sed -n / wc -l / ls 验证，报告 VERIFIED / STALE / INCORRECT / UNVERIFIED，不编辑，仅返回发现列表，并利用 Phase 0 的变更信号聚焦注意力。
Phase 3 发现分类：分为高影响（规则已错误，未来代理会错误路由工作）、中影响（内容缺失，如新文件、新导出、新动词未在清单中）、低影响（行号偏移但语义正确，可批量处理）、内部矛盾（同一文档 §1 说 X 而 §8 说非 X，选择真相并传播）。默认修复高与中影响，低影响仅在周边编辑中修复。
Phase 4 并行 Opus 写入者派发：按相同分组派发 3–5 个并行 Opus 写入者。每个写入者获得目标文件路径、该组的审计发现列表、保持语气/结构/长度的指示、为重计数重新 grep 但不重新审计的许可；缺口文件夹以最接近的同类 AGENTS.md 为模板并注明是哪一个。写入者就地应用 Edit，不新增章节，报告触及的路径及每个文件 3 行摘要。
Phase 5 编辑后重新审计 + 提交 + 推送：重新运行 scripts/audit-agents-md.sh 并与 Phase 0 快照对比，表面计数应匹配（或为新建缺口文件夹 +N），无新的孤立符号链接；用 grep 抽查 2–3 个高影响修正；按关注点分别提交，如 docs(agents): refresh stale refs + counts after <churn-event> 与 docs(<folder>): add AGENTS.md + REVIEW.md；推送并观察 CI。
创造性引导信号
使用 git log since doc's last edit 将范围导向实际发生变更的文件；用文件大小增量作为漂移代理，若引用文件自文档最后编辑以来增长 2 倍，则所有行号引用必然过期；对 NOT YET LANDED 存根执行 ls，存根表也是可证伪声明；对文档中每个编号表通过 grep -c 自动重计数；跨文档一致性检查，若两个文档独立引用同一符号位置，二者必须一致；符号重命名检测，若审计发现函数不再存在于引用行，运行 git log -S 'foo' -- <file> 查找重命名提交并更新；存根毕业清理，任何包含 NOT YET LANDED / not yet built / deferred 的行都是基于 ls 审计的候选；测试文件存在性交叉检查，声称 Tests: none 的清单表可通过 ls <module>.test.* 证伪；覆盖图阈值是对话而非法律，约 10 文件 / 约 1500 LOC 下限用于过滤候选，不变量密度测试决定最终取舍；从已合并 PR 描述与审查发现中挖掘缺口文件内容，并在编码前对 HEAD 验证。
参考路由
需要质量报告格式、漂移类别、编辑后验证、可证伪声明纪律时读 references/audit-and-update.md；需要审计员与写入者提示脚手架（并行 Opus 派发）时读 references/agent-dispatch.md；需要 AGENTS 编写、文件夹范围、WHAT/WHY/HOW 过滤时读 references/agents-md-format.md；需要伴随 CLAUDE.md 符号链接、原生审查适配器规则、跨代理表面时读 references/agent-entrypoints.md；需要 REVIEW.md 用途、根/范围拆分、严重性标记时读 references/review-context.md。
快速开始映射
大型重构刚落地需全面清理文档时，从 references/audit-and-update.md 开始，再读 references/agent-dispatch.md；只需刷新频率表时，从 references/audit-and-update.md 开始。