SuperAPI AI 工具集

claude-md-progressive-disclosurer

办公与效率

查看项目

更新于 10-13 20:08

技能介绍

用途

该 Skill 面向 CLAUDE.md / AGENTS.md 这类 AI 指令文件,用于对其进行优化、审计、精简、瘦身或重构。其核心理念是「找到最小的高信号 token 集合,最大化期望结果的可能性」,目标是让指令在实际任务中被正确加载、找到并执行。信息效率、可读性与可维护性服务于这个结果;文件大小、审阅次数和脚本绿灯都不能替代行为证据。

在主文中保留决策与执行入口,验证命令和历史材料按触发读取。官方篇幅建议用于发现可拆分内容,不是通过/失败阈值。

执行边界与验收

先固定当前目标文件、消费它的宿主、授权范围、用户可见结果与停止条件。诊断/审计请求只读;明确要求优化或修复时,执行范围内的本地可逆修改与必要验证。发布、不可逆操作和范围扩张按当前用户授权处理。

「零信息损失」约束仍有效的契约与原样迁移,不要求旧错误永久留在现行规范里。每项改动先标记为:保留/原样移动、同源去重、依据现行权威纠错,或待用户裁决的退役/边界变更。

提案或验收正文给出:当前原文 → 候选文本/准确 diff → 依据 → 行为后果 → 未验证之处。依据分为当前宿主/官方契约、原始研究、用户长期契约、实测样例和待验证假设。

验收标准是:授权范围内的改动完整且无误、真实宿主加载路径正确、代表性任务符合预期。

铁律:行数禁作 KPI,可作诊断症状

禁止把「减少行数」作为优化目标或成功指标:行数少不代表更好,行数多不代表更差。评判标准是单一信息源、认知相关性、维护一致性,而非行数。禁止在优化方案或总结中出现「从 X 行精简到 Y 行」「减少 Z%」作为成果,也禁止把「减少行数」作为移动或删除某内容的理由。

行数可以作为诊断症状:允许把「行数异常大 + Claude 反复不遵守某规则」当成触发调查的信号,但调查动作是信号分诊 + 分层,不是「砍到 N 行」。

两层架构

Level 1(CLAUDE.md)每次对话都加载,通常包含:信息记录原则、Reference 索引、核心命令表、铁律/禁令、常见错误诊断、代码模式、目录映射、修改代码前必读、Reference 触发索引等。Level 2(references/)按需即时加载,包含详细 SOP 流程、边缘情况处理、完整配置示例、历史决策记录等。

该布局是项目级示例,不是要求每个文件补齐的模板。此外,渐进式披露发生在多个层:MCP 懒加载工具、RAG 按需取知识、Skills 描述常驻正文按需,以及 Claude Code 的动态工具选择。应先问载体,再问层级;判据是模型能否在决策前找到这条规则,以及现有机制能否覆盖所需条件。

多入口原则

同一 Level 2 资源可以有多个入口,服务于不同查找路径:Reference 索引(开头,按错误/问题查)、修改代码前必读(中间,按任务查)、Reference 触发索引(末尾,长对话定位)。多入口成立仅当每个入口 keyed 方式不同,且都只指向同一 Level 2 资源、不复制其正文;入口存的是「路标 + 触发条件」,不是「内容副本」。

优化工作流

Step 1:固定原始基线(写入前)。只读审计先读取,开始授权修改前记录精确源路径及解析后的真实目标,备份完整文件与涉及的 reference,保存路径、字节哈希和时间,使用唯一备份名。

Step 2:内容分类,分三阶段。2.0 热点测量,先确定用户要修的是不遵循、冲突、加载错误还是上下文负担,再量相关信号;可查看宿主真实注入面(如 /context、/memory),统计分节字节表与行长分布,并注意测量仪器自身的坑(heading 正则必须感知 code fence;不把 bytes/chars 当 token)。2.1 信号分诊,对每个章节先问「删掉这一条,Claude 会不会犯错」;不会犯错且属于可从代码推断、语言/框架标准约定、自明常识、已有 canonical source 覆盖、已过时的一次性修复等,则列入候选删除清单。2.2 分层分类,按高频使用、违反后果严重、是否每轮任务都需要、是否有明确触发条件等,决定放入 Level 1 或 Level 2。

Step 3:创建 Reference 文件。命名如 docs/references/{主题}-sop.md;铁律是原样移动,禁止压缩——把 100 行原封不动搬到 Level 2 是正确的,把 100 行「精简」到 60 行搬过去是错误的。整节批量下沉时用脚本(如 scripts/sink_sections.py)执行,注意拒写 symlink 目标、先全部提取后统一替换。

Step 4:更新 Level 1。保留当前有效的跨任务约束,更新受本次改动影响的既有入口;迁移细节后写明何时读、读哪里、能得到什么。写指针前有硬 gate:每写一条「→ 某 reference / 详见 X」指针前,当场确认目标文件真有这段内容,绝不写假指针。

Step 5:验证结构、加载与任务结果。包括校准判据与检查引用、内容完整性逐节对比、压缩重述的保真审计(子句级 diff 检查限定词是否丢失)、行数不进验证标准,并在相同宿主/cwd 核对改前改后的实际加载内容与来源,用代表性任务检验行为。

核心原则

原则 0:更新现有信息归属规则,仅补本次需要而缺失的触发、归属和维护来源。原则 1:索引位置服从检索需要,默认保留一个清晰入口。原则 2:引用必须有触发条件(错误示例「详见 native-modules-sop.md」;正确写法应写明何时读、包含什么)。原则 3:保留任务实际需要的代码模式,高频且重推导有可复现风险的保留最小可复制例。原则 4:用三态优先级(必须、禁止、可选),不要全标铁律;堆叠强调词会让新模型过度触发。原则 5:原因帮助决策时才补充。

引用格式有四种:详细格式、问题触发表格、任务触发表格、内联格式,各自服务不同场景;应使用能让读者可靠找到内容的最简单格式。注意 @import 不省上下文——它在启动时全量展开载入,拆成 @import 只改善组织,不减少任何上下文。常用的减负方式包括:把非通用内容移到项目级 CLAUDE.md、留纯文字指针让模型按需拉、转 skill。

反模式警告

该 Skill 列出多种反模式:以行数为目标的过度精简、无触发条件的引用、移走代码模式、删除而非移动、用行数当 KPI、移动时压缩(变相删除)、用「故意删除」掩盖信息丢失、纯否定规则(不给替代)、假指针(指向不存在的内容)。其中假指针比直接丢内容更隐蔽,会让「文件存在」检查通过,但读者点进去才发现内容不在。

适用场景与限制

适用于需要审计、精简、重构或瘦身 CLAUDE.md / AGENTS.md 的任务,以及用户说「太大/太长/精简/瘦身」时。此时应先 reframe 再动手:确认要改善的实际症状与已有授权,做相关测量与信号分诊,把「太大吗」当调查的起点,不是砍的许可。

限制与注意:诊断/审计请求只读;脚本的 OK 只证明所列机械检查通过;验证不能用 grep 证明整段完整搬运(多行原句会被按行 OR 命中,需用整串子串判断);行数在验证阶段不是任何标准。关于其所属来源、安装方式、收费或价格、具体支持平台等信息,当前资料暂未提供。