claude-md-progressive-disclosurer
Optimize, slim, or restructure CLAUDE.md/AGENTS.md with progressive disclosure and zero information loss. Use when the user explicitly asks to audit, 精简, 瘦身, 重构, split, or diagnose adherence problems in instruction files. Profiles the whole resident startup surface, allocates rules among prose, path rules, Skills, hooks, and references, then moves low-frequency sections verbatim with content-integrity checks. Also use when an active task starts moving or compressing instruction sections. Not for generic task drift unless instruction files are in scope.
1实现原理 · 为什么它能做到
这是一个带强纪律的‘方法论执行器’：SKILL.md 主体不是提示词技巧，而是一套可裁决的工作流（固定基线→信号分诊→分层→verbatim 迁移→整串校验→按宿主实测验收），每一步都内置反跑偏护栏。
**目标是让指令在实际任务中被正确加载、找到并执行。** 信息效率、可读性与可维护性服务于这个结果；文件大小、审阅次数和脚本绿灯都不能替代行为证据。
铁律：行数不是优化目标。判断标准是单一信息源、认知相关性、维护一致性；‘从 X 行精简到 Y 行/减少 Z%’被明令禁止作为成果汇报。
- 行数少不代表更好，行数多不代表更差 - 评判标准是：**单一信息源**（同一信息不在多处维护）、**认知相关性**（当前任务不需要的信息不干扰注意力）、**维护一致性**（改一处不需要同步另一处）——不是行数
两层架构 + 载体先于层级：先把规则路由到正确载体（常驻 L1 / reference / Skill / hook / 工具索引），再决定 L1↔L2 分层；用‘违规可恢复性 × 触发自报性 × 工具事件可观测性’矩阵判断某条规则能否移出常驻。
**先问载体，再问层级。** 判据是模型能否在决策前找到这条规则，以及现有机制能否覆盖所需条件。下表是候选路由，不证明机制已存在，也不授权安装新机制。
机械下沉由脚本完成：sink_sections.py 按 spec 把整节原文（fence 感知的精确标题定界）verbatim 追加到 reference，再把 L1 原位替换为压缩 snippet，全程‘先提取后替换、自底向上’避免行号漂移，最后做整串字节校验，失败回滚源文件。
extract [start_heading, end_heading) from the source (exact-line match, code-fence-aware) -> append verbatim to the target reference under a dated provenance header (new files get an intro) -> replace the L1 range with the compressed snippet, bottom-up so earlier line numbers stay valid -> verify every original is a WHOLE-BYTE-STRING substring of its target
完整性验证以字节整串为准：整段是否搬全不能用 grep（按行 OR 会放过丢半段），必须 python3 整串子串判断；每条压缩重述还要做子句级 diff（限定词如 ‘/forks’ 是主要丢失点）。
**不能用 grep** —— 原句多行时 `grep -F` 按行 OR，**丢半段照样报命中**， 必须用 python3 整串子串判断
测量仪器自带 fence 感知与 CJK token 比率校准：profile_claude_md.py 输出分节字节表/行长分布/最长行，且明确拒绝 chars/4 估 CJK token（实测 ~0.42 token/byte）。
Token estimates: chars/4 UNDERESTIMATES CJK-dense files by >2x. Measured ratio on a real CJK-heavy CLAUDE.md was ~0.42 tokens/byte.
宿主差异被显式对待：Claude 的 @import 是启动时全量展开（不省上下文）、.claude/rules 常驻、paths 按文件匹配触发；Codex 的 AGENTS 层级与预算另行用 `codex debug prompt-input` 实测，禁止把一个宿主的行为外推给另一个。
`@path` import 在**启动时全量展开载入**——拆成 `@import` 只改善组织，**不减少任何上下文**（官方 *memory* 文档原文）
2核心能力
3外部依赖
| Kind | Dependency / Endpoint |
|---|---|
| cli | python3 |
| cli | codex（官方 CLI，仅调试读取 prompt 注入） |
| cli | claude（/context、/memory、InstructionsLoaded hook） |
4管控建议与判定依据
- scripts/: 执行本地脚本或命令: scripts/profile_claude_md.py
- 本地工作目录: 文件读写与工件输出: 用户 CLAUDE.md/AGENTS.md 本体（仅已授权修改时）
5第二遍独立确认
- [ok] 无网络外发 — 脚本零网络；md 中 https 全为 references 的官方文档/论文引用
- [ok] 无凭证读取 — 脚本无 environ/getenv/settings.json 读取
- [ok] sink_sections.py 写入面与 SKILL 声称一致（含备份、回滚、symlink 拒绝） — main() 实测：preflight abort 条件、copy2 备份、whole-string 校验失败恢复源文件均在代码中
- [ok] ‘行数禁作 KPI’纪律是否被脚本弱化 — profile_claude_md.py 输出分节字节表，但说明明确仅作工作顺序与诊断，不输出‘精简目标’
- [ok] 宿主机制断言（@import 全量展开、96KiB 截断）有依据 — 引用官方 memory 文档并标注历史事故作‘必须实测’示例，SKILL 反复要求以当前官方文档与真实宿主读回裁决
6结论
57ac229162c67d07…