claude-md-progressive-disclosurer

CLAUDE.md 渐进式披露优化器

核心理念

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

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

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

执行边界与验收

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

当前依据与适用边界见 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 的“替代机制探针”；未完成实证时不得缩成“已由 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 用自己的权威渲染器，不凭配置猜：

   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 的“验证器校准与引用检查”。其中 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、予算をチェックします。今回の問題に対応する代表的なタスクで動作を検証し、従うべきケースと発動してはいけないケースの対照を残します。モデル、ホスト、サンプル数、実行上の制限を報告します。一度の成功、初期化のみでモデルを実行していない状態、またはツールからの成功応答だけでは、安定した遵守率の向上を証明できません。クォータ／ネットワークの制限でモデルを実行していない場合は、「未検証」と記載します。測定項目名を変えて成功したように見せてはいけません。

（注：診断段階では、疑わしい点を示すシグナルとして行数を確認できます。冒頭の「鉄則」を参照してください。ただし、検証段階では行数はどのような基準にもなりません。この2つの段階では行数の扱いが異なるため、混同しないでください。）

---

Level 1 の内容分類

🔴 常時配置の候補：まず現在のタスクで必要か確認

内容タイプ	理由
コアコマンド	現在の範囲で頻繁に使われ、既存の入口から確実に見つけられない場合は保持
権限／重要な禁止事項	決定前に確認が必要な適用範囲、条件、停止点を保持
コードパターン	高頻度で、再導出に再現可能なリスクがある場合は最小限の例を保持。それ以外はタスクに応じて案内
エラー診断	入口と重要な落とし穴を保持し、完全な SOP は症状に応じて読み込む
ディレクトリマップ	ファイル構成から確実に推測できないナビゲーションのみ残す
トリガー索引	実際の検索ニーズに応じて設定し、固定の場所や表形式を必須にしない

🟡 要約とトリガー条件を保持

内容タイプ	Level 1	Level 2
SOP の手順	トリガー条件 + 重要な落とし穴	完全な手順
設定例	最もよく使う 1-2 個	完全な設定
API ドキュメント	よく使うメソッドシグネチャ	完全なパラメーターの説明

🟢 完全に移動可能

内容タイプ	理由
過去の意思決定記録	アクセス頻度が低い
パフォーマンスデータ	参考情報
技術的負債の一覧	必要に応じて確認
例外的なケース	明確なトリガー条件がある場合に読み込む

---

参照形式（4種類）

4種類の参照形式はそれぞれ異なる場面に適しています。「トリガー条件」の標準的な書き方は、以下の 原則 2 を参照してください（コピーして使える例を含みます）。

形式	用途	トリガーとなる場面
詳細形式	本文中の重要な参照	個々の reference について、いつ読むべきかを詳しく説明する必要がある
問題別トリガーテーブル	冒頭／末尾の Reference 索引	「エラー／問題」を手がかりに探す
タスク別トリガーテーブル	「コードを変更する前に必ず読む」	「何を変更するか」を手がかりに探す
インライン形式	簡潔な参照	本文中で一言触れる

📖 4種類の形式の、コピーして使える完全なテンプレートは references/progressive_disclosure_principles.md の付録 B にあります：トリガーとなる場面——Reference 索引／タスク表／インライン参照／詳細な参照を作成する場合。

形式の選択：読者が内容を確実に見つけられる、最もシンプルな形式を使います。「多様性」のために形式を混在させてはいけません。

⚠️ @import はコンテキストを節約しません（技術的な正確性、最も陥りやすい点）

@path import は起動時に全体を展開して読み込みます。@import に分割しても整理が改善するだけで、コンテキストはまったく削減されません（公式 memory ドキュメントの原文）。「内容を @import に分割したから最適化できた」というのは、見せかけの最適化です。

負荷を軽減する一般的な方法は次の3つです。現在のホストがサポートしているかに応じて、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：索引の位置は検索ニーズに合わせる

デフォルトでは、わかりやすい入口を1つ残します。検索経路が異なる場合や、実測で見落としが確認された場合に限り、複数の入口を追加します。各入口は、同じ正式な本文のみを指すようにします。Lost in the Middle の研究は、すべての最新モデルで指示ファイルの先頭と末尾に索引をコピーする必要があることを直接証明しているわけではなく、汎用的な最適位置も示していません。ケース 4 ではレイアウトに関する経験を1つ紹介していますが、使用時には現在のタスクで検証してください。

原則 2：参照にはトリガー条件が必要

誤り：詳しくは native-modules-sop.md を参照

正しい例：

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

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

理由：トリガー条件がなければ、LLM はいつ読むべきかわかりません。

原則 3：タスクで実際に必要なコードパターンを保持する

そのパターンを常時配置する必要があると確認済みのタスクでは、「遅延読み込みパターンを使う」とだけ書いて完全な実装を削除するのは誤りです。以下のコピーして使える例を保持してください。

正しい例：Level 1 にコピーして使える完全なコードを保持する：

// ✅ 正确：懒加载，只在需要时加载
let _Database = null;
function getDatabase() {
  if (!_Database) {
    _Database = require("better-sqlite3");
  }
  return _Database;
}

適用条件：この例を常時配置するのは、そのコードパターンの使用頻度が高く、信頼性の向上が見込める場合に限ります。特定のコンポーネントやまれなタスクにしか当てはまらない場合は、トリガーとなる入口を残し、完全な内容を対応する reference に置きます。すべてのプロジェクトのコード例をグローバルレベルにコピーしてはいけません。

原則 4：3段階の優先度を使い、すべてを「鉄則」にしない

すべてのルールを最高優先度にすると、実際の境界が見えにくくなります。同じ場面で相反する動作を指示するルールを先に解消し、その後、必須、禁止、任意を、それぞれのトリガー条件と停止条件とともに明確にします。ラベルや配置場所によって、実際のホストにおける指示の優先順位を覆すことはできません。

強調語（太字、CRITICAL、MUST、「鉄則」「絶対禁止」、罰則を示す脅し）を積み重ねるのも、同じ問題の一種です。Anthropic 公式のガイダンスでは、新しいモデルはそのような表現によって過剰に反応するようになると指摘しています。書き換える際は平易な表現にし、適用条件と理由を明記してください。ルールの境界と停止点は変えないでください。

✅／⚠️／🚫 は表示スタイルとして使用できますが、比較実験によって最適と証明された構成ではありません。「ルールは150–200個」「高リスクのルールだけ5–7個残す」を、最新の GPT／Claude に共通する上限とする十分な根拠はありません。数量と位置に関する研究の適用範囲については、reference 冒頭のエビデンステーブルを参照してください。最終的な判断は、現在のホストでの実際の動作に基づいて行います。

原則 5：意思決定に役立つ場合に限り、理由を補足する

簡潔な理由は、適用範囲の理解に役立つ場合に有用です。エンジニアリング記事の推奨は、「すべてのルールに Why を1行付けなければならない」ことの実験的証明ではありません。

直感的でない制限には具体的な結果を補足します。すでに明確なルールの説明を繰り返したり、事故の経緯をコピーしたり、過去の事実を捏造したりしてはいけません。

誤り：🚫 fallback のデフォルト値を禁止

正しい例：必須の認証情報がない場合は明示的にエラーを返してください。別の環境への誤接続を防ぐため、組み込みのキーにフォールバックしてはいけません。

⚠️ ルールを言い換える際の厳守事項：元の文が case study の混在した段落に含まれている場合、原則 4／5 に基づいてその文を直接書き換えてはいけません。反パターン 6（まず段落全体を verbatim で L2 に移動、ケース 14）を参照してください。

---

反パターンに関する警告

⚠️ 反パターン 1：行数を目標にした過度な簡略化

ケース：「行数を減らす」ために、コードパターン、診断手順、ディレクトリマップを移動した

結果：

• コードパターンが失われ、LLM が毎回あらためて導出する
• 診断手順が失われ、エラー発生時に何を調べればよいかわからなくなる
• ディレクトリマップが失われ、ファイルを探す効率が下がる

正しい対応：頻繁に使う内容はすべて保持します。最適化の判断基準は、情報が重複してメンテナンスされているか、現在のタスクと無関係かであり、「ファイルが長すぎる」ことではありません。

⚠️ 反パターン 2：トリガー条件のない参照

ケース：詳しくは xxx.md を参照

問題：LLM はいつ読み込めばよいかわからず、無視するか、毎回読むかのどちらかになります。

正しい対応：トリガー条件 + 内容の概要。

⚠️ 反パターン 3：コードパターンを移動する

ケース：よく使うコード例を Level 2 に移動した

問題：LLM はコードを書くたびに先に Level 2 を読む必要があり、レイテンシとトークン消費が増えます。

正しい対応：頻繁に使うコードパターンは 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 或监控。