claude-md-progressive-disclosurer

# 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