---
name: claude-md-progressive-disclosurer
description: >-
  Optimizes or restructures CLAUDE.md/AGENTS.md with progressive disclosure and zero
  information loss. Use when the user asks to optimize, audit, 精简/瘦身/重构, or split instruction
  files, asks for their best practices (最佳实践), sees Memory files taking a large share of
  /context, reports rules in instruction files being ignored, or a task starts moving
  instruction sections. Not for generic task drift unless instruction files are in scope; not
  for moving memory entries into docs (use claude-code-ops-router).
---

# CLAUDE.md 渐进式披露优化器

## 核心理念

> "找到最小的高信号 token 集合，最大化期望结果的可能性。" — Anthropic

**目标是让指令在实际任务中被正确加载、找到并执行。** 信息效率、可读性与可维护性服务于这个结果；文件大小、审阅次数和脚本绿灯都不能替代行为证据。

> 本 skill 在主文保留决策与执行入口，验证命令和历史材料按触发读取。官方篇幅建议用于发现可拆分内容，不是通过/失败阈值；用户需要的是正确行为，不是达到一个行数。

## 执行边界与验收

- 先固定当前目标文件、消费它的宿主、授权范围、用户可见结果与停止条件。诊断/审计请求只读；明确要求优化或修复时，执行范围内的本地可逆修改与必要验证。发布、不可逆操作和范围扩张按当前用户授权处理，已答过的同一事项不反复确认。
- “零信息损失”约束**仍有效的契约与原样迁移**，不要求旧错误永久留在现行规范里。每项改动先标为：保留/原样移动、同源去重、依据现行权威纠错，或待用户裁决的退役/边界变更。已有明确裁定按其执行；不能把“优化”当作撤销未获授权契约的许可。
- 提案或验收正文给出：**当前原文 → 候选文本/准确 diff → 依据 → 行为后果 → 未验证之处**。先做出可审阅的本地结果，再请求尚缺的决策；不能只贴改后版本或让用户自行翻文件拼差异。
- 依据分为当前宿主/官方契约、原始研究、用户长期契约、实测样例和待验证假设。标出研究的模型、任务、样本与限制；不能把旧模型结果、公司实践或单次成功改写成 GPT/Claude 全系通用阈值。
- 先修会改变当前任务决策的冲突、失效规则、权限歧义、假指针或真实截断。只有在问题确实是常驻负担时，才用测量贡献度安排减负顺序；不因文件最大就先改它，也不为缩小指令而新建 hook、监控或 Skill。
- 验收是：授权范围内的改动完整且无误、真实宿主加载路径正确、代表性任务符合预期。完成必要检查后停止；仅因新改动、失败或未决疑点扩大验证。普通小修改不自动加独立审阅，复杂且缺少机械裁判的改动按当前协作契约做一次有界审阅。

当前依据与适用边界见 [references/progressive_disclosure_principles.md](references/progressive_disclosure_principles.md) 开头；核查外部机制或研究结论时读取，历史案例不覆盖这里的现行契约。用户问「有哪些最佳实践」或要求参考外部做法时，先读那张证据表作答；是否需要重新调研，按表下的刷新规则判断。

### 铁律：行数禁作 KPI，可作诊断症状

**禁作优化目标 / 成功指标**（不可削弱——案例 7/8/9 的防线就是这条）：

- 行数少不代表更好，行数多不代表更差
- 评判标准是：**单一信息源**（同一信息不在多处维护）、**认知相关性**（当前任务不需要的信息不干扰注意力）、**维护一致性**（改一处不需要同步另一处）——不是行数
- 禁止在优化方案 / 总结中出现"从 X 行精简到 Y 行"、"减少 Z%"作为成果
- 禁止把"减少行数"作为移动 / 删除某内容的理由
- 一个结构清晰、信息不重复的长文件，胜过砍掉关键信息的短文件

**可作诊断症状**（官方依据：Claude Code 文档"文件太长 → 规则被淹没 → Claude 不遵守"）：

- 允许把"行数异常大 + Claude 反复不遵守某规则"当成**触发调查的信号**，不是结论
- 调查动作仍是信号分诊（Step 2.1）+ 分层，**不是"砍到 N 行"**
- 一句话区分：行数可以让你**开始怀疑**，不可以成为你**优化的目标**或**汇报的成果**

#### 触发即 reframe（用户说「太大 / 太长 / 精简 / 瘦身」时——最易在此处跑偏）

这些词触发的本能是「砍行数」。**先 reframe，再动手**：① 确认用户要改善的实际症状与已有授权；② 按 Step 2.0 做相关测量，再进 Step 2.1 信号分诊，用「这段有没有 canonical source 重复 / 是不是反信号」决定去留，**不是**用「文件多长」；③ 把「太大吗」当**调查的起点**，不是**砍的许可**。用户连续追问「还是太大」时同理——回应是「再做一轮分诊找重复 / 反信号」，分诊空了就诚实说「剩下都是高频核心，再砍会丢信号」，**不是**继续砍有信息的内容。（实战：把「太大吗」做成减行数任务、一路用「省 39%」当成果汇报、被连续追问拽着越砍越多 → 案例 15、16。）

### 两层架构

下图是项目级布局示例，不是要求每个文件补齐的模板。全局层只留跨项目决策约束；命令、代码、诊断和目录导航按实际任务频率与可靠检索路径分配。

```
Level 1 (CLAUDE.md) - 每次对话都加载
├── 信息记录原则               ← 防止未来膨胀的自我约束
├── Reference 索引（开头）     ← 入口1：遇到问题查这里
├── 核心命令表
├── 铁律/禁令（含代码示例）
├── 常见错误诊断（症状→原因→修复）
├── 代码模式（可直接复制）
├── 目录映射（功能→文件）
├── 修改代码前必读             ← 入口2：改代码前查这里
└── Reference 触发索引（末尾） ← 入口3：长对话后复述

Level 2 (references/) - 按需即时加载
├── 详细 SOP 流程
├── 边缘情况处理
├── 完整配置示例
└── 历史决策记录
```

### 但「两层」只是文件层——先选载体，再选层级

渐进式披露不是一个文件内部的事，它在**多个层**同时发生：MCP 懒加载工具、RAG 按需取知识、
Skills 描述常驻正文按需、以及 **Claude Code 的动态工具选择（工具索引层的渐进式披露）**。
只在 CLAUDE.md 内部搬 L1↔L2，等于把**下表四种载体**里的两种（常驻 L1 / reference）当成全部。

**先问载体，再问层级。** 判据是模型能否在决策前找到这条规则，以及现有机制能否覆盖所需条件。下表是候选路由，不证明机制已存在，也不授权安装新机制。

|  | **违规可恢复** | **违规不可恢复** |
|---|---|---|
| **触发自报**（我知道我要做 X） | Skill / 带触发条件的 reference | 可机械判定时考虑现有拦截机制；保留必要授权规则 |
| **触发不自报，但「时刻」工具事件可观测** | 按需 reference；需要事前提醒时评估注入 | 评估 hook 提醒与最小常驻约束；语义判断仍需模型或用户 |
| **触发不自报，且无可观测时刻** | 按错误代价和任务频率决定是否常驻 | 必要的常驻 L1 约束 |

**两条轴的定义**：
- **触发自报** = 动手前那一刻，命令/文件名/关键词里就写着「我要做这件事」——
  `aliyun ...`、写 `.tf`、跑打包。skill 的描述匹配能接住这类。
- **「时刻」可观测** ≠ 触发自报。**这是第三行存在的全部理由**：
  「我在修测试」不自报「我正要删功能」，但 `Write` 一个 `.py` 文件**是一个工具事件**，
  hook 能在那一刻开火。**规则的语义 hook 判断不了，但时刻它看得见** —— 于是
  hook 只负责报时刻、把规则怼到面前，判断仍归模型。
- 即使存在可挂载事件，跨项目授权与用户决策原则仍可能需要常驻。不能仅凭“可挂 hook”认定可以移走。

**Hook 两种形态**：拦截器只在宿主支持阻断的事件和可判定条件下拒绝操作；注入器在支持的事件返回上下文提醒。触发、执行成功、提醒可见和模型遵守是四件事，不能互相代证。已加载的提醒仍占上下文；注册了 hook 不等于零成本、全覆盖或始终存活。

对不可逆且只能语义判断的规则，保留必要的常驻授权句；现有注入机制可以提醒，但不替代授权或阻断。规则正文保留唯一现行来源，历史记录明确标为历史。

**宿主区别**：Claude 的 `@import` 是展开加载，`.claude/rules/` 无条件规则也常驻；`paths:` 规则依赖匹配文件的读取，不能当作所有工具事件的触发器。Codex 的 AGENTS 层级、override/fallback 与加载预算另行核对。用当前官方文档与真实宿主读回裁决，不把一个宿主的行为外推给另一个，也不自动开启 memory。

**核查替代机制时**：先读真实注册与实现，再用无副作用的健康输入和危险形态样例双向校准，记录事件/matcher、结果与覆盖边界。周期性机制还须核对最近成功时间。详细 payload、shell 陷阱和探针模板见 [references/verification-recipes.md](references/verification-recipes.md) 的“替代机制探针”；未完成实证时不得缩成“已由 X 覆盖”。

### 多入口原则（重要！）

同一 Level 2 资源可以有**多个入口**，服务于不同查找路径：

| 入口 | 位置 | 触发场景 | 用户心态 |
|------|------|----------|----------|
| Reference 索引 | 开头 | 遇到错误/问题 | "出 bug 了，查哪个文档？" |
| 修改代码前必读 | 中间 | 准备改代码 | "我要改 X，要注意什么？" |
| Reference 触发索引 | 末尾 | 长对话定位 | "刚才说的那个文档是哪个？" |

**这不是重复，是多入口。** 就像书有目录（按章节）、索引（按关键词）、快速参考卡（按任务）。

**边界（与 SSOT 的张力，必须守住）**：多入口成立**仅当**——每个入口 keyed 方式不同（错误索引 / 任务索引 / 末尾复述），且都只**指向**同一 Level 2 资源、**不复制它的正文**。如果你把同一段规则正文抄到 3 个地方，那是违反 SSOT 的重复（会各自漂移），不是多入口。一句话判据：入口存的是"路标 + 触发条件"，不是"内容副本"。

---

## 优化工作流

### Step 1: 固定原始基线（写入前）

只读审计先读取，不因“先备份”改变目标环境。开始已授权修改前，记录精确源路径及解析后的真实目标；备份完整文件与涉及的 reference，保存路径、字节哈希和时间。使用唯一备份名，不覆盖旧备份。后续 5b 使用这次明确记录的路径，禁止从目录里按最早/最新文件名猜基线。

目标在 Git 中时可用本次工作前的不可变 ref 与仓根相对路径取原文；先确认包含未提交内容的现状是否也需要保存。个人全局文件不必在 Git 中，独立备份同样适用。备份保护被保存的字节，不自动证明其他文件可恢复。

### Step 2: 内容分类

分三阶段：按当前症状测量、依权威分诊、按触发分层。诊断无关的整机盘点不属于本步骤；不能把低信号内容机械搬成一座 reference 垃圾场。

#### 2.0 热点测量（先于一切提案——性能优化的第一课）

先确定用户要修的是不遵循、冲突、加载错误还是上下文负担，再量相关信号。案例 19 的大文件曾是实测热点，但不能推出所有任务都按 bytes 排序。`scripts/profile_claude_md.py` 只描述单文件内部，不测规则遵循或整套启动延迟；做加载/体积诊断时再盘点下列启动面。

1. **宿主真实注入面**：Claude 用 `/context` 看类别占比、`/memory` 看实际加载的 memory/instruction 文件；需要持续观测加载事件时用官方 `InstructionsLoaded` hook。Codex 用自己的权威渲染器，不凭配置猜：

   ```bash
   codex debug prompt-input 'startup-instruction-audit' |
     jq -r '.[] | [.role, ([.content[]? | select(.type == "input_text") | .text] | join("") | utf8bytelength)] | @tsv'
   ```

   同时读各条 developer message 的开头，区分全局指令、项目指令、Skill catalog、hook/plugin 注入；**单量 CLAUDE.md 会漏掉常驻 Skill 描述和 hook 文字**。

   Claude 的 `/context` 把 auto memory 的 `MEMORY.md` 与 CLAUDE.md 一并计入 Memory files。官方 memory 文档写明它每次会话加载前 200 行或 25KB（先到为准），开关是设置项 `autoMemoryEnabled` 或环境变量 `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`。它由模型自己写入，常与用户写的指令重复或矛盾（例如用户规定经验落文档，auto memory 却仍开着），按冲突处理。把 memory 条目迁进文档是另一个 Skill 的职责，经 `claude-code-ops-router` 路由到 `claude-migrate-memory-to-doc`；本 Skill 只负责把它列为加载面和冲突来源。
2. **分节字节表**：按 heading 统计 bytes/lines；父节包含子节，只在同层比较，不能相加当总量。体积用于定位，不直接决定改动顺序；优先级仍由当前失败、错误代价、任务相关性与可验证收益决定。
3. **行长分布**：>1KB 的巨型行是「规则+战例焊死在一个 bullet」的签名（实战：4.4% 的行承载 35.6% 的字节）
4. **载入语义与上限**：逐宿主实测，禁把历史版本的默认值当当前不变量。当前 Codex 的 `project_doc_max_bytes` 是**项目层级文档的累计预算**；全局用户指令可走另一条加载路径，不能拿该值推断它是否截断。先查 `~/.codex/config.toml`，再以同 cwd 的 `codex debug prompt-input` 实际字节为裁决。历史上确有 96 KiB 配置配合旧加载行为导致 164KB 文件尾部 41% 不可见的事故，但它只证明「必须实测」，不证明今天仍按 32 KiB 或同一路径截断。确认真截断后，在当前授权内选择能恢复所需内容可见的最小修复；修改预算、重组文件、增加监控是不同动作，不自动捆绑。
5. **常驻触发器审计**：Skill frontmatter `description` 会进入常驻 catalog；generic 纠偏句、普通质量词或维护动作若写成触发词，会让 Skill 和 Stop hook 自激活。逐条查描述是否只声明**明确任务意图**，并检查 hook 是否会在最终回答阶段临时创造一个开工前本不存在的新 obligation。描述按官方上限保持 ≤1024 字符；不用列完整方法论。

Claude 侧若某些 instruction 文件对当前项目永远无关，可用官方 `claudeMdExcludes` 显式排除；它是 scope 配置，不是拿 `@import` 假装省上下文。路径相关规则优先放 `.claude/rules/` 的 `paths:` 条件载体。

⚠️ 测量仪器自身的两个坑（都实测踩过，脚本已内建规避；先在已知答案的样本上校准，见案例 17/19）：
- **heading 正则必须感知 code fence**——fence 里的 `# 注释` 会被当成标题，凭空造出不存在的大节（实测造出过一个假的 45.9KB 节，热点排序整个失真）
- **不把 bytes/chars 当 token**。CJK 的历史样本比率不能推广到所有文件和模型；没有当前 tokenizer 或宿主实测就省略估算。明确提供经验比率时标 `est.`，同时记录比率来源与适用样本。

#### 2.1 信号分诊（必要性闸门，先决）

对每个章节先问 Anthropic 官方 litmus：**"删掉这一条，Claude 会不会犯错？"**

- **会犯错** → 是信号，进入 2.2 分层
- **不会犯错**，且属以下任一 → 是**反信号**，列入"候选删除"清单：
  - 能从代码 / 项目结构 / 文件名推断的（如"本项目用 TypeScript"）
  - 语言 / 框架的标准约定（如"遵循 PEP 8"）
  - 自明常识（如"写干净的代码""提交前测试"）
  - 已有独立 canonical source 覆盖的（注明 source 在哪）
  - 已过时的一次性修复（不会再复发）
  - **需要确定执行的检查**（如提交前 lint）→ 核对现有 hook/CI/工作流是否覆盖。给出载体候选、触发时机、覆盖与遗漏；不能因“需要确定性”就预设 hook，也不能把 Skill 描述匹配当成确定性保证。此审计不自动授权实现新机制。

**安全栏**：候选删除不等于已获授权。逐项给出原文、依据和行为变化；未被当前用户指令、既有裁定或现行权威决定的取舍留给用户。已有明确裁定不重复问；不确定的必要性保留 unknown，不能把“模型应该知道”当证据。

> 与案例 8/9 的边界：8/9 是把**真信号**（debug 提示、代码模式）在移动时压缩掉 = 永远错；这一步是移除**已确认反信号**（可推断 / 自明）= 正确。区别在"删的是不是信号"，不在"删不删"。详见 `references/progressive_disclosure_principles.md` 案例 10。

#### 2.2 分层分类

对**通过分诊的信号**分类：

| 问题 | 是 | 否 |
|------|----|-----|
| 高频使用？ | Level 1 | ↓ |
| 违反后果严重？ | Level 1 | ↓ |
| 每轮任务都需要且难以可靠检索的代码模式？ | Level 1 保留最小模式 | ↓ |
| 有明确触发条件？ | Level 2 + 触发条件 | ↓ |
| 历史/参考资料？ | Level 2 | 考虑删除 |

### Step 3: 创建 Reference 文件

只有当前任务已授权修改时才执行。`profile_claude_md.py` 只读；`sink_sections.py` 一运行就写备份、reference 和源文件，没有 dry-run。先读其 `--help` 与精确 spec，再检查所有目标、恢复边界；共享围栏解析器 `scripts/markdown_headings.py` 是内部实现，无独立 CLI。脚本的 `OK` 只证明所列机械检查通过。

命名：`docs/references/{主题}-sop.md`

**铁律：原样移动，禁止压缩**

移动内容到 Level 2 时，必须**完整保留原始内容**。不要在移动的同时"顺便精简"。

```
✅ 正确：把 100 行原封不动搬到 Level 2（100 行 → Level 2 100 行）
❌ 错误：把 100 行"精简"到 60 行搬到 Level 2（100 行 → Level 2 60 行，40 行消失）
```

**范围**：本步骤只做原样迁移，因此不在搬运时暗改语义。去重、事实纠错和已授权退役分别声明与验证；保留有效契约不等于把失效规则继续标成现行规范。

**怎么做**：
1. 从原始 CLAUDE.md 中精确复制要移动的段落
2. 原样粘贴到 Level 2 文件中
3. 可以在 Level 2 中添加结构（标题、分隔线），但**不要删减、改写、合并**原始内容
4. 如果确实有冗余（同一段话在原文中出现了多次），在 Level 2 中保留一份完整的，注释说明去重

#### 整节批量下沉的机械流程（≥3 节时脚本化，禁手搬）

多节手搬容易造成行号漂移或遗漏。用 `scripts/sink_sections.py`（spec 驱动；实战一次通过 10 节 / 119KB，整串验证 10/10 零丢失）：**按精确标题行定界提取原文（fence 感知）→ verbatim 追加到目标 reference（带日期 provenance header，新文件配 intro）→ 自底向上替换 L1 压缩版（行号不失效）→ 每节整串子串验证（grep 对多行原文按行 OR、会放过丢半段的搬运，必须 python `in` 整串判断）→ 验证失败恢复源文件，保留 reference 追加以便核查**。它不是跨文件事务；I/O 中途失败后先检查源备份和各目标，不盲目重跑以免重复追加。两条硬规则：

- **拒写 symlink 目标（含父目录）**：目标路径任一环节是 symlink（文件本身、或**父目录**——文件级 `islink` 检查会被目录级 symlink 静默穿透，独立审阅实测打穿过），"本地追加"实际在改 link 指向的那个仓（触发它的版本 bump / commit 义务，且那个仓可能 public）。脚本按 `realpath ≠ abspath` 判定并 abort，特意跨 link（如 macOS `/tmp`）用 `--allow-symlinked-target` 显式放行；正确动作是落一个本地兄弟文件 + provenance 注明「与 symlink 源后续合并」
- **先全部提取、后统一替换**：提取按原始行号一次做完，替换自底向上——两步交错会让未处理节的行号漂移。压缩版 snippet **必须在代码围栏外恰好保留一次完整 start_heading 行**（写前检查，写后复验；正文子串不算标题）；用作定界的标题在源文件里必须唯一（重名 abort）

### Step 4: 更新 Level 1

1. 保留当前有效的跨任务约束，更新实际受本次改动影响的既有入口。
2. 迁移细节后写明何时读、读哪里、能得到什么。
3. 代码模式、诊断和目录导航按 Step 2.2 的任务频率与检索可靠性放置。
4. 有真实查找需求时使用问题索引、任务表或内联链接，不为凑模板重复首尾索引。
5. 只有目标确实缺少且本次范围需要时才补最小信息记录原则；不自动注入整套治理章程。

**⚠️ 写指针前的硬 gate（事中验证，最易跳过、本次最大踩坑）**：每写一条「→ 某 reference / 详见 X」指针前，**当场确认目标文件真有这段内容**。
⚠️ **验的方式看你要验什么**（verification-recipes.md 的判据陷阱表已实测）：只验「这段在不在」→ 抽 3–5 个**特异串**用 `grep -F` 查即可；
要验「**整段完整搬过去了**」→ **不能用 grep** —— 原句多行时 `grep -F` 按行 OR，**丢半段照样报命中**，
必须用 python3 整串子串判断。三种结果：① 目标已有完整内容 → 写指针；② 目标没有 / 不确定是否完整 → 先把原文 verbatim cut 到目标（回 Step 3），再写指针；③ **绝不写「指向一个其实没有该内容的文件」的假指针**。假指针比丢内容更隐蔽——它让 5a「文件存在」通过、却在读者点进去时才发现是空的。Why：5a/5b 是**事后**验证，假指针那一刻已写进文件；事中 gate 才能在源头拦住。（实战：写「详见 anti-patterns」但那里 0 命中 Stripe 端点 → 案例 15。）

### Step 5: 验证结构、加载与任务结果

#### 5.0–5a. 校准判据与检查引用

先在已知健康与失败样例上校准将使用的判据，区分未命中、仪器错误和不可判定；解析真实路径后验证链接目标的**实际内容**。标题或文件存在只证明能找到入口，不能证明整段内容完整。原样迁移用原始 bytes 整串匹配；只查关键词不能证明无丢失。

执行链接检查、跨 shell 校准或完整性验证时，读取 [references/verification-recipes.md](references/verification-recipes.md) 的“验证器校准与引用检查”。其中 shell 命令是辅助筛查：出现跳过项须逐项解释，打印成功或 exit 0 不替代未覆盖的判断。

#### 5b. 内容完整性（最关键）

对每个从原始 CLAUDE.md 移走的章节，逐一检查：

1. 使用 Step 1 已记录的精确原始备份路径与哈希，不按文件名排序猜最早版本。Git 对照必须早于本次工作，路径相对仓根；不拿已经包含本次提交的 HEAD 自证。全局个人文件可以使用独立备份，无须假定它属于 Git 仓库。

2. **逐节对比**：对原始文件的每个 `##` 章节，确认其内容在以下位置之一完整存在：
   - 新 CLAUDE.md 中（保留在 Level 1）
   - 某个 Level 2 reference 文件中（完整移动）

   **📖 快速暴露整章遗漏的辅助脚本见 `references/progressive_disclosure_principles.md` 附录 C**：触发场景——做下面逐节对比前的第一道筛查（脚本不替代人工逐节对比，只查章节标题是否存在）。

3. **逐项解释差异**：原样移动应完整保留字节；同源去重须有可达的权威来源；事实纠错或已授权退役须引用当前依据与授权，并说明行为变化。无法指认到这几类的缺失就是回归，恢复后再验证。

不要用事后“故意删除”掩盖遗漏，也不要把已经被用户或现行权威推翻的旧规则补回现行规范。历史原文可由备份、Git 历史或标注清楚的事故资料保留。

**压缩重述的保真审计（L1 留了压缩版时必查）**：压缩最容易丢的不是整段——是**限定词**。实战（案例 19）：原句「public + 0 stars/forks 且用户明确授权」被压成「0 stars 且明确授权」，6 个字符消失，一道闸门的条件字面上放宽了一半；同场审计还抓到「自称只省略战例、实际连 4 条可执行判据也省了」的申报口径不符。两个审计动作：① 对每条压缩重述，把**操作性子句**（条件 / 数值 / 枚举 / hook 名 / 否定词）与原句逐词 diff——整段丢失 5b 能抓，一个 "/forks" 只有子句级 diff 能抓；② 全文跑 expected-hunks-only 检查——difflib 比对基线，每个非 equal hunk 必须指认到一条已声明的改动，指认不了的就是计划外差异。

**独立审阅按当前协作契约触发**：普通小修改且机械检查足以裁决时，不自动派 reviewer；复杂、高风险且缺少独立机械判据的修改，冻结原始基线与最终候选，做一次有界 fresh-context 审阅，禁 fork 和嵌套派发。需要逐节保真审阅时可用 `references/progressive_disclosure_principles.md` 附录 D 的模板。

finding 是待验证假设，先用原始字节、准确 diff、链接内容或真实任务裁决。完成相关修复与检查即停止；只有新增高风险语义问题无法机械裁决或用户明确要求，才扩大审阅。记录已执行的方法、finding 处置及未验证项；遵循现有私有知识仓/项目 SSOT 的记录约定，不为普通指令小修改另造治理项目。

#### 5c. 行数不进验证标准

验证**不以行数为通过条件**，不计算"原始 X 行 vs 新 Y 行 = 减少 Z%"——这种对账会把你拉回 KPI 思维。

必要结构检查：
- 每项原内容有保留、迁移、去重、纠错或已授权退役的明确处置
- 没有信号丢失（反信号经确认删除不算丢失）
- Level 2 引用都有触发条件

**再检查真实结果**：在相同宿主/cwd 核对改前改后的实际加载内容与来源，检查 override、import、symlink 和预算。用与本次问题对应的代表性任务检验行为，保留应该遵循与不应触发的对照；报告模型、宿主、样本数和执行限制。一次成功、只初始化未跑模型、或工具成功回执都不能证明稳定的遵循率提升。模型受配额/网络限制没有执行时，写“未验证”，不改测量名称冒充成功。

（注：诊断阶段可以看行数当怀疑信号，见开头「铁律」；但**验证阶段**行数不是任何标准——这两个阶段对行数的态度不同，别混。）

---

## Level 1 内容分类

### 🔴 常驻候选：先看当前任务是否需要

| 内容类型 | 原因 |
|---------|------|
| **核心命令** | 当前范围高频且不能从现有入口可靠发现时保留 |
| **授权/关键禁令** | 保留决策前必须可见的适用范围、条件与停止点 |
| **代码模式** | 高频且重推导有可复现风险时保留最小例；否则按任务路由 |
| **错误诊断** | 保留入口和关键陷阱，完整 SOP 可按症状加载 |
| **目录映射** | 只留无法从文件结构可靠推断的导航 |
| **触发索引** | 根据实际查找需求设置，不强制固定位置或表格 |

### 🟡 保留摘要 + 触发条件

| 内容类型 | Level 1 | Level 2 |
|---------|---------|---------|
| SOP 流程 | 触发条件 + 关键陷阱 | 完整步骤 |
| 配置示例 | 最常用的 1-2 个 | 完整配置 |
| API 文档 | 常用方法签名 | 完整参数说明 |

### 🟢 可以完全移走

| 内容类型 | 原因 |
|---------|------|
| 历史决策记录 | 低频访问 |
| 性能数据 | 参考性质 |
| 技术债务清单 | 按需查看 |
| 边缘情况 | 有明确触发条件时再加载 |

---

## 引用格式（四种）

四种引用格式各服务不同场景；规范的"触发条件"写法见下方 `原则 2`（已含可复制示例）。

| 格式 | 用途 | 触发场景 |
|---|---|---|
| 详细格式 | 正文中的重要引用 | 单条 reference 需展开说明何时读 |
| 问题触发表格 | 开头/末尾 Reference 索引 | 按"错误/问题"查 |
| 任务触发表格 | 「修改代码前必读」 | 按"要改什么"查 |
| 内联格式 | 简短引用 | 正文一句话带过 |

**📖 四种格式的完整可复制模板见 `references/progressive_disclosure_principles.md` 附录 B**：触发场景——产出 Reference 索引 / 任务表 / 内联 / 详细引用时。

**格式选择**：使用能让读者可靠找到内容的最简单格式；不为“多样性”混用格式。

### ⚠️ @import 不省上下文（技术正确性，最易踩）

`@path` import 在**启动时全量展开载入**——拆成 `@import` 只改善组织，**不减少任何上下文**（官方 *memory* 文档原文）。"我把内容拆进 `@import` 了所以优化了"是假优化。

常用的减负方式包括以下三种；还可按当前宿主支持情况评估 paths 规则或显式 scope 排除，不把此列表当穷尽枚举：

1. 把非通用内容**移到项目级 CLAUDE.md**（全局文件会被无关项目加载）
2. 留**纯文字指针**（"需要时 Read `references/xxx.md`"，**不是 `@`**），让模型按需拉
3. 转 **skill**（描述常驻、正文按需）

本 skill 产出的引用一律用反引号路径，**禁止用 `@import` 做卸载**。详见 `references/progressive_disclosure_principles.md` 案例 11。

---

## 核心原则

### 原则 0：更新现有信息归属规则

先看目标是否已经说明信息放在哪里。仅补本次需要而缺失的触发、归属和维护来源，不机械添加一整章。`references/progressive_disclosure_principles.md` 附录 A 是可裁剪模板，供确实需要补齐归属规则时使用。

### 原则 1：索引位置服从检索需要

默认保留一个清晰入口。只有存在不同查找路径或实测漏读时才增加多入口；每个入口只指向同一权威正文。Lost in the Middle 研究不能直接证明所有现代模型都需要在指令文件首尾复制索引，也不能给出通用最优位置。案例 4 保留一种布局经验，使用时以当前任务验证。

### 原则 2：引用必须有触发条件

**错误**：`详见 native-modules-sop.md`

**正确**：
```markdown
**📖 何时读 `native-modules-sop.md`**：
- 遇到 `ERR_DLOPEN_FAILED` 错误
- 需要添加新的原生模块

> 包含：ABI 机制、懒加载模式、手动修复命令
```

**原因**：没有触发条件，LLM 不知道什么时候该去读。

### 原则 3：保留任务实际需要的代码模式

**在已确认该模式需要常驻的任务中**，只写“使用懒加载模式”却丢掉完整实现是错误的；应保留下面的可复制例。

**正确**：Level 1 保留完整的可复制代码：
```javascript
// ✅ 正确：懒加载，只在需要时加载
let _Database = null;
function getDatabase() {
  if (!_Database) {
    _Database = require("better-sqlite3");
  }
  return _Database;
}
```

**适用条件**：此例只在该代码模式高频且存在可靠性收益时常驻。若只对某个组件或偶发任务适用，保留触发入口并完整放入对应 reference；不要把所有项目代码例子复制到全局层。

### 原则 4：用三态优先级，不要"全标铁律"

把所有规则标成最高优先级会掩盖实际边界。先消除在同一场景给出相反动作的规则，再明确必须、禁止、可选及各自触发与停止条件；标签或位置不能覆盖真实宿主的指令优先级。

堆叠强调词（加粗、`CRITICAL`、`MUST`、「铁律」「绝对禁止」、惩罚威胁）属于同一问题。Anthropic 官方提示建议指出新模型会因此过度触发；改写时换成平常语气，写清适用条件和原因，规则的边界与停止点保持不变。

✅/⚠️/🚫 可作为显示样式，不是经对照实验证明的最佳结构。没有足够证据把“150–200 条规则”“只保留 5–7 条高危规则”设为现代 GPT/Claude 的通用上限。数量与位置相关研究的适用范围见 reference 开头的证据表；以当前宿主上的实际行为裁决。

### 原则 5：原因帮助决策时才补充

简短原因在帮助理解适用边界时有用；工程文章的建议不构成“所有规则必须附一行 Why”的实验证明。

对不直观的限制补充具体后果；已经明确的规则不再重复解释，不复制事故过程或编造历史。

**错误**：`🚫 禁止 fallback 默认值`

**正确**：`必需凭据缺失时显式报错；不要回退到内置密钥，以免误连其他环境。`

> ⚠️ 重述规则时的硬边界：若原句嵌在 case study 混合段落里，原则 4/5 不得直接改写原句——见反模式 6（先整段 verbatim 移 L2，案例 14）。

---

## 反模式警告

### ⚠️ 反模式 1：以行数为目标的过度精简

**案例**：为了"减少行数"，移走了代码模式、诊断流程、目录映射

**结果**：
- 丢失代码模式，LLM 每次重新推导
- 丢失诊断流程，遇错不知查哪
- 丢失目录映射，找文件效率低

**正确**：保留所有高频使用的内容。优化的判断标准是信息是否重复维护、是否与当前任务无关，而不是"文件太长"。

### ⚠️ 反模式 2：无触发条件的引用

**案例**：`详见 xxx.md`

**问题**：LLM 不知道何时加载，要么忽略，要么每次都读。

**正确**：触发条件 + 内容摘要。

### ⚠️ 反模式 3：移走代码模式

**案例**：把常用代码示例移到 Level 2

**问题**：LLM 每次写代码都要先读 Level 2，增加延迟和 token 消耗。

**正确**：高频使用的代码模式保留在 Level 1。

### ⚠️ 反模式 4：删除而非移动

**案例**：删除"不重要"的章节

**问题**：信息丢失，未来需要时无处可查。

**正确**：有效的低频内容完整移到 Level 2 并保留触发；过时规则按明确依据和授权纠错或退役，不伪装成原样迁移。

### ⚠️ 反模式 5：用行数当 KPI

**案例**：优化方案写"从 2000 行精简到 500 行，减少 75%"

**问题**：把行数当成功指标，会驱动错误决策——为了凑数字而砍掉有用的信息。

**正确**：用信息质量评估优化效果——信息是否有重复？维护负担是否降低？LLM 是否能更快找到需要的信息？

### ⚠️ 反模式 6：移动时压缩（变相删除）

**规则**：移动是移动，精简是精简。这是两个独立操作，**不要同时执行**。

- 移动内容到 Level 2 时，必须**原样复制，不改一字**
- 去重、纠错或退役单独声明与核验，依本次及既有授权执行；只把尚缺的实质选择交给用户
- "既然都在改了，顺便精简一下"是最隐蔽的删除——它披着"优化"的外衣，做着"删除"的事
- **混合段落**：在原样迁移模式下先完整保留原段落，再生成 L1 的检索入口；逐项核对条件、数值、否定词和停止点。历史原文与现行规则分开标注，不能让过时原文与新决定同时冒充权威。已授权的纠错/退役不受“旧规则永不改写”约束，但必须有独立基线和准确 diff。
  ⚠️ **这条判据别用 grep 验**（Step 5.0 表第 4 行实测）：原句多行时 `grep -F` 把它拆成多个 pattern 按行 OR，
  **丢了半段照样报命中** —— 它会为一次有损搬运出具无罪证明。用整串子串判断：
  把原句存进临时文件，用 `Path("orig").read_bytes() in Path("target").read_bytes()` 检查连续完整字节匹配；先从 `pathlib` 导入 `Path`。
  原则 4/5 管 L1 *如何呈现*，不授权销毁信号原句

> 完整案例分析见 `references/progressive_disclosure_principles.md` 案例 8、案例 14

### ⚠️ 反模式 7：用"故意删除"掩盖信息丢失

**规则**：每项删除或行为变化在修改前说明依据与授权，不能发现少了之后才编理由。

- 同源去重指出现有权威源和可达入口。
- 纠错或已授权退役指出较新的权威事实/用户裁定；失效内容不必继续作为运行时规则保存。
- 没有上述依据的丢失是回归，恢复并验证；不能用“低风险”掩盖。

> 完整案例分析见 `references/progressive_disclosure_principles.md` 案例 9

### ⚠️ 反模式 8：纯否定规则（不给替代）

**案例**：`🚫 不要用 X` —— 没说改用什么。

**问题**：缺少必要替代路径可能让执行者不知下一步；这是一项可验证的可执行性问题，不是所有否定句都会导致模型失败。

**正确**：存在已知且获授权的替代路径时写清；有效的停止/禁止规则不因没有替代方案而失效。

```
🚫 不要用全局 mutable 单例存请求状态
✅ 改用显式参数传递或 request-scoped context
```

遇到禁令先保留其真实边界；只有当前证据支持时补替代动作，不能编造 fallback，也不能据此删掉必要禁令。

> ⚠️ 但若禁令原句嵌在 case study 混合段落里，先按反模式 6 整段 verbatim 移 L2，再在 L1 派生重述——不可改写原句（案例 14）。

### ⚠️ 反模式 9：假指针（指向不存在的内容）

**案例**：移走一段内容后写「详见 `X.md`」，但 `X.md` 里根本没有这段——指针指向空。

**问题**：比直接丢内容更隐蔽。`5a`「文件存在」会通过（`X.md` 确实存在），但内容不在那里；读者点进去才发现，且此时已无从知道原文是什么。本质是反模式 6（移动时压缩）+ 反模式 7（掩盖丢失）的组合：内容被砍 + 用一个看似合规的指针掩盖。

**正确**：写指针前当场验证目标真有该内容（Step 4 硬 gate；**验「在不在」用 `grep -F` 抽特异串，验「整段完整」必须用 python3 子串判断——grep 会给假阳性，见 verification-recipes.md 的判据陷阱表**）。指针指错文件（内容在 A、却写「详见 B」）是同类问题，按内容实际所在地修正、不是删指针。

> 完整案例分析见 `references/progressive_disclosure_principles.md` 案例 15

---

## 信息量检验

### ✅ 正确的信息量

| 检验项 | 通过标准 |
|--------|---------|
| 日常任务 | 可发现所需命令，按现有项目惯例完成 |
| 常见错误 | 能按症状找到可信诊断流程 |
| 代码编写 | 需要的非默认模式可可靠获取 |
| 特定问题 | 知道何时读哪个 Level 2 |
| 触发索引 | 入口可达且不复制权威正文，位置/格式不作硬闸 |

### ❌ 不足的信号

- LLM 反复问同样的问题
- LLM 每次重新推导代码模式
- 用户需要反复提醒规则

### ❌ 过多的信号

- 大段低频详细流程在 Level 1
- **完全相同的内容**在多处（注意：多入口指向同一资源 ≠ 重复）
- 边缘情况和常见情况混在一起

---

## 项目级 vs 用户级

| 维度 | 用户级 | 项目级 |
|------|--------|--------|
| 位置 | `~/.claude/CLAUDE.md` | `项目/CLAUDE.md` |
| References | `~/.claude/references/` | `docs/references/` |
| 信息范围 | 个人偏好、全局规则 | 项目架构、团队规范 |

### 硬检查：scope 错放（官方层级文档裁定）

用户级 `~/.claude/CLAUDE.md` 会被**所有项目**加载，**只能放普遍适用**的东西。优化时对每节做 scope 检查：

| 内容特征 | 归属 | 不这样做的后果 |
|---|---|---|
| 项目名 / 部署目标 / 逐项目路径 / 项目凭据 | **项目级**，绝不全局 | 无关项目被污染；没人按项目维护 → 路径/状态腐烂（典型 staleness） |
| 个人偏好、跨项目行为规则 | 用户级 | — |
| 团队规范、项目架构 | 项目级（入 VCS） | — |

**Step 2.1 先判断内容职责**：具体项目状态/实现细节进入其项目 SSOT；跨项目导航可以保留带触发条件的指针。发现项目名不自动授权搬迁或删除，也不能把全局路由指针误判为项目事实。详见 `references/progressive_disclosure_principles.md` 案例 13。

---

## 金丝雀检测法（仅作诊断候选）

单条无害命名指令只能探测该指令在该样例是否可见/被执行，不能证明整份文件在“遵循度阈值内”，也不能证明失败源自文件过长。只有用户需要这类诊断时才在隔离样例里使用；不自动向全局契约植入无关规则。优先验证真实任务中应该遵循与不应触发的行为。

## 快速检查清单

- [ ] 用户目标、授权范围、准确原文/候选 diff、依据与未验证项已明确；没有重复请求已有授权。
- [ ] 原样移动保持字节；纠错、去重、退役分别有依据，不以“零损失”恢复失效规则。
- [ ] 每个引用的目标内容真实存在，触发、scope 与权威来源清楚；无假指针或双重现行规则。
- [ ] 所用判据已用健康/失败样例校准，工具错误和未覆盖项没有伪装成成功。
- [ ] 当前宿主实际加载面已检查；代表性任务验证了本次行为，未测的模型/分支如实标注。
- [ ] 必要的独立审阅按当前协作契约执行；修复后检查相关范围，达到停止条件即收尾。
- [ ] 没有把 bytes、行数、reviewer 数量、命名金丝雀或脚本 OK 当业务结果。
- [ ] 全局文件只承载跨项目职责；未自动新增模板章节、memory、hook、Skill 或监控。