claude-md-progressive-disclosurer

1实现原理 · 为什么它能做到

这是一个带强纪律的‘方法论执行器’：SKILL.md 主体不是提示词技巧，而是一套可裁决的工作流（固定基线→信号分诊→分层→verbatim 迁移→整串校验→按宿主实测验收），每一步都内置反跑偏护栏。

daymade-claude-code/claude-md-progressive-disclosurer/SKILL.md

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

注：开篇就把验收标准定义为‘行为证据’而非文件大小，为后面‘行数禁作 KPI’的铁律定调。

铁律：行数不是优化目标。判断标准是单一信息源、认知相关性、维护一致性；‘从 X 行精简到 Y 行/减少 Z%’被明令禁止作为成果汇报。

daymade-claude-code/claude-md-progressive-disclosurer/SKILL.md

- 行数少不代表更好，行数多不代表更差 - 评判标准是：**单一信息源**（同一信息不在多处维护）、**认知相关性**（当前任务不需要的信息不干扰注意力）、**维护一致性**（改一处不需要同步另一处）——不是行数

注：与市面上大多数‘CLAUDE.md 瘦身’类技能的最大差异：把反 KPI 写进铁律并用案例（15/16/19）演示砍行数如何导致信息丢失。

两层架构 + 载体先于层级：先把规则路由到正确载体（常驻 L1 / reference / Skill / hook / 工具索引），再决定 L1↔L2 分层；用‘违规可恢复性 × 触发自报性 × 工具事件可观测性’矩阵判断某条规则能否移出常驻。

daymade-claude-code/claude-md-progressive-disclosurer/SKILL.md

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

注：矩阵三行（触发自报/时刻可观测/两者皆无）决定 skill、reference、hook 提醒或常驻 L1 的选择；强调 hook 只报时刻、判断仍归模型。

机械下沉由脚本完成：sink_sections.py 按 spec 把整节原文（fence 感知的精确标题定界）verbatim 追加到 reference，再把 L1 原位替换为压缩 snippet，全程‘先提取后替换、自底向上’避免行号漂移，最后做整串字节校验，失败回滚源文件。

daymade-claude-code/claude-md-progressive-disclosurer/scripts/sink_sections.py

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

注：SKILL Step 3 要求 ≥3 节脚本化禁手搬；脚本打印 OK 只代表所列机械检查通过，不代表语义无损。

完整性验证以字节整串为准：整段是否搬全不能用 grep（按行 OR 会放过丢半段），必须 python3 整串子串判断；每条压缩重述还要做子句级 diff（限定词如 ‘/forks’ 是主要丢失点）。

daymade-claude-code/claude-md-progressive-disclosurer/SKILL.md

**不能用 grep** —— 原句多行时 `grep -F` 按行 OR，**丢半段照样报命中**，必须用 python3 整串子串判断

注：‘假指针比丢内容更隐蔽’：Step 4 写指针前当场验证目标真有内容，禁止指向空文件。

测量仪器自带 fence 感知与 CJK token 比率校准：profile_claude_md.py 输出分节字节表/行长分布/最长行，且明确拒绝 chars/4 估 CJK token（实测 ~0.42 token/byte）。

daymade-claude-code/claude-md-progressive-disclosurer/scripts/profile_claude_md.py

Token estimates: chars/4 UNDERESTIMATES CJK-dense files by >2x. Measured ratio on a real CJK-heavy CLAUDE.md was ~0.42 tokens/byte.

注：脚本头部自带两个实测踩坑记录（假 45.9KB 节、token 低估），并要求先在已知答案样本上校准仪器。

宿主差异被显式对待：Claude 的 @import 是启动时全量展开（不省上下文）、.claude/rules 常驻、paths 按文件匹配触发；Codex 的 AGENTS 层级与预算另行用 `codex debug prompt-input` 实测，禁止把一个宿主的行为外推给另一个。

daymade-claude-code/claude-md-progressive-disclosurer/SKILL.md

`@path` import 在**启动时全量展开载入**——拆成 `@import` 只改善组织，**不减少任何上下文**（官方 *memory* 文档原文）

注：同一约束也写进 references 案例 11；引用格式四选一，原则 2 要求引用必须带触发条件。

2核心能力

01只读审计/热点测量：分节字节表、行长分布（>1KB 巨型行定位）、fence 感知 heading 解析

02信号分诊：对每节先过 Anthropic litmus（‘删掉会不会犯错’），区分信号与反信号

03整节 verbatim 下沉（sink_sections.py spec 驱动，多节批量机械迁移 + 回滚）

04内容完整性逐节对比（5b）与压缩重述的子句级保真审计（expected-hunks-only difflib 检查）

05防假指针硬 gate：写‘详见 X’前当场验证目标真有该内容（在=用 grep -F 抽特异串；完整=python3 整串）

06宿主真实加载面检查：/context、/memory、InstructionsLoaded hook、codex debug prompt-input 实测

3外部依赖

类型	依赖
cli	python3
cli	codex（官方 CLI，仅调试读取 prompt 注入）
cli	claude（/context、/memory、InstructionsLoaded hook）

4风险提醒风险提醒：蓝色 · 知晓即可

风险提醒：蓝色 · 知晓即可

复杂度与篇幅本身很高 — SKILL.md 559 行中文方法论 + 47KB 案例库；执行者需要相当理解成本，低水平 agent 可能把流程走成表演而丢失判断
sink_sections 无 dry-run — 一运行即写备份并改源文件；SKILL 要求先读 spec/恢复边界再执行，误 spec 会 abort，但每次运行都会留下备份与 reference 追加
写入对象是常驻指令文件 — 对 CLAUDE.md/AGENTS.md 的错误改写会影响后续所有会话行为；依赖 SKILL 内置授权边界与人工对 diff 的审阅（SKILL 要求给出原文→候选 diff→依据→行为后果）
诊断动作可能读入敏感上下文 — /context、/memory、codex debug prompt-input 会把宿主注入面内容带入会话——属正常调试读取，若文件含密钥则提示宿主通用注意（非本技能特有）

风险提醒：蓝色，知晓即可。自带脚本 stdlib-only（'Stdlib-only by design (skill scripts must run with no installs)'），纯本地：profile/markdown_headings 只读；sink_sections 对用户指令文件做有备份、可回滚、防 symlink 越界、整串校验的本地改写；无网络外发、无凭证读取、不接触 settings/密钥文件。写入对象是用户的 CLAUDE.md/AGENTS.md——应理解为‘对受控文件的本地可逆修改’，SKILL 自身有授权边界纪律约束 agent。

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结论

反行数 KPI 的完整方法论：把‘信息是否重复维护/认知相关/维护一致’设为唯一判据并配 19 个实战案例

机械下沉有保真工程：fence 感知定界、先提取后替换、字节整串校验、失败回滚、备份命名规范

对宿主机制逐一实证（@import 不省上下文、InstructionsLoaded、codex debug prompt-input 实测字节），拒绝跨宿主外推

安全设计具体：symlink 目标（含父目录）拒绝写入、假指针硬 gate、子句级保真审计抓限定词丢失

适合：适合需要系统性重组/瘦身 CLAUDE.md、AGENTS.md 且在乎‘零信息损失’与可复核保真的维护者；也适合想建立指令文件治理纪律的团队（多入口、SSOT、载体路由、验证判据）。中文/中英混排指令文件（CJK token 校准）与 Claude Code+Codex 双宿主用户尤其对口。

不适合：不适合只想要‘文件变小/行数变少’的快速瘦身（会被铁律拦住）；不适合没有明确授权边界、允许 agent 自由删除‘看着没用’内容的场景；不适合纯代码仓库重构（目标必须是 instruction 文件）；低配模型/短上下文下照搬整套流程性价比低。

安装 agent 直装可复制

① 本站镜像更新 2026-09-09

方式 A · 人下载镜像包下载 claude-md-progressive-disclosurer.tar.gz

sha256: 57ac229162c67d07…

方式 B · JSON 格式安装指南，复制给 agent

安装指南

agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。

② 上游 GitHub · 原始来源

能访问 GitHub？直接去上游安装（实时版，可能已更新）GitHub 原始 ↗

本页镜像锁定 commit d5c4678cb5；上游为实时仓库。

来源信息 GitHub 原始

作者 / 仓库daymade / daymade/claude-code-skills

原始 GitHubdaymade/claude-code-skills ↗

Stars1385

最近推送2026-09-09

本 skill commitd5c4678cb5

本站信息

收录日期2026-09-06

分类基础工具与工作流

侦查报告2026-09-06 · 2 遍

本站镜像与 GitHub 原始是不同来源：本站锁定 commit 快照经 /r2 分发；GitHub 为实时上游，内容可能已更新。

1实现原理 · 为什么它能做到

2核心能力

3外部依赖

4风险提醒 风险提醒：蓝色 · 知晓即可

5第二遍独立确认

6结论

4风险提醒风险提醒：蓝色 · 知晓即可