SkillAgentSearch skills...

claude-md-progressive-disclosurer

Optimizes or restructures CLAUDE.md/AGENTS.md with progressive disclosure and zero information loss

Install / Use

npx skills add daymade/claude-code-skills --skill claude-md-progressive-disclosurer

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

90/100

Supported Platforms

Claude Code
OpenAI Codex

Our assessment of claude-md-progressive-disclosurer

claude-md-progressive-disclosurer scores 90/100 on our quality scale, 1374th of 4,700 Development & Engineering skills we index (top 30%).

Its SKILL.md is 19 KB long, well organised into 52 sections with 5 code examples: a thorough specification that gives an agent plenty to work with.

With 1,426 GitHub stars, it is one of the more widely adopted skills in the catalogue.

Substance
30/30
Structure
20/20
Description
12/15
Adoption
13/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so claude-md-progressive-disclosurer is actively maintained.
  • Our last check on 2026-10-30 found the source still online.
  • It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-10-01. Automated pattern scan on 2026-10-01. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

claude-md-progressive-disclosurer compared with similar skills

All 4 of these similar skills score higher than claude-md-progressive-disclosurer; compare them before choosing.

SkillScoreStarsUpdatedFormat
claude-md-progressive-disclosurer (this skill)by daymade901.4k53d agoSKILL.md
taste-skillby Leonxlnx100116.8k8d agoCLAUDE.md
ai-job-searchby ai-job-search-dev10072.1ktodayCLAUDE.md
claude-howtoby luongnv8910047.3k2d agoCLAUDE.md
lobehubby lobehub10085.6ktodayMCP Server

Frequently asked questions

How do I install claude-md-progressive-disclosurer?
Run npx skills add daymade/claude-code-skills --skill claude-md-progressive-disclosurer. The install tabs above show the steps for each supported agent.
Which AI agents does claude-md-progressive-disclosurer work with?
It is written for Claude Code and OpenAI Codex, as a SKILL.md file. Other agents that read the same format can often use it too.
Is claude-md-progressive-disclosurer safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is claude-md-progressive-disclosurer still maintained?
The repository was last updated about 2 months ago, so claude-md-progressive-disclosurer is actively maintained.

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 开头;核查外部机制或研究结论时读取,历史案例不覆盖这里的现行契约。用户问「有哪些最佳实践」或要求参考外部做法时,先读那张证据表作答;是否需要重新调研,按表下的刷新规则判断。

铁律:行数禁作 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

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars1.4k
CategoryDevelopment
Updated1mo ago
Forks219

Languages

Python

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions
claude-md-progressive-disclosurer — Claude Code Skill: Install & Safety Check | SkillAgent