claude-md-progressive-disclosurer

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

AGENTS.md

Audit 0.4.1 · source sha 36e089fae6e0 · 26 Oct 2026Report an issue or request a re-scan

• Publisherdaymade GitHub userOwner of the repository this skill is read from
• Source folderdaymade/claude-code-skills/daymade-claude-code/claude-md-progressive-disclosurerThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdict36e089fae6e0A new audit runs when the source changes
• Repository statusNot archivedPushed today
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its 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 (最佳实践),…

---
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,再动手**:1 确认用户要改善的实际症状与已有授权;2 按 Step 2.0 做相关测量,再进 Step 2.1 信号分诊,用「这段有没有 canonical source 重复 / 是不是反信号」决定去留,**不是**用「文件多长」;3 把「太大吗」当**调查的起点**,不是**砍的许可**。用户连续追问「还是太大」时同理——回应是「再做一轮分诊找重复 / 反信号」,分诊空了就诚实说「剩下都是高频核心,再砍会丢信号」,**不是**继续砍有信息的内容。(实战:把「太大吗」做成减行数任务、一路用「省 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 一并

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

1. 2026-10-26
   ✓SAFE B 89 / 100

   first audit · source 36e089fae6e0

Questions about claude-md-progressive-disclosurer

• github.com/daymade/claude-code-skills/tree/main/daymade-claude-c — the audited source at commit 36e089fae6e0 and every finding aboveObserved · 26 Oct 2026

Spotted something wrong? Report a correction · Methodology