feat: strengthen claude-md-progressive-disclosurer anti-deletion safeguards (v1.2.0)
- Add "move as-is, no compression" iron rule to prevent info loss during Level 2 migration - Add anti-patterns 6 (compression during move) and 7 (disguising loss as "intentional deletion") - Enhance Step 5 verification with 3 sub-checks: file existence, content completeness, no line counting - Ban `wc -l` and line count mentions throughout the workflow - Add real-world case studies 8 and 9 to principles reference - Bump skill version to 1.2.0, marketplace to 1.32.1 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
daymade
@@ -6,7 +6,7 @@
|
||||
},
|
||||
"metadata": {
|
||||
"description": "Professional Claude Code skills for GitHub operations, document conversion, diagram generation, statusline customization, Teams communication, repomix utilities, skill creation, CLI demo generation, LLM icon access, Cloudflare troubleshooting, UI design system extraction, professional presentation creation, YouTube video downloading, secure repomix packaging, ASR transcription correction, video comparison quality analysis, comprehensive QA testing infrastructure, prompt optimization with EARS methodology, session history recovery, documentation cleanup, format-controlled deep research report generation with evidence tracking, PDF generation with Chinese font support, CLAUDE.md progressive disclosure optimization, CCPM skill registry search and management, Promptfoo LLM evaluation framework, iOS app development with XcodeGen and SwiftUI, fact-checking with automated corrections, Twitter/X content fetching, intelligent macOS disk space recovery, skill quality review and improvement, GitHub contribution strategy, complete internationalization/localization setup, plugin/skill troubleshooting with diagnostic tools, evidence-based competitor analysis with source citations, and Windows Remote Desktop (AVD/W365) connection quality diagnosis with transport protocol analysis and log parsing",
|
||||
"version": "1.32.0",
|
||||
"version": "1.32.1",
|
||||
"homepage": "https://github.com/daymade/claude-code-skills"
|
||||
},
|
||||
"plugins": [
|
||||
@@ -438,7 +438,7 @@
|
||||
"description": "Optimize user CLAUDE.md files by applying progressive disclosure principles. This skill should be used when users want to reduce CLAUDE.md bloat, move detailed content to references, extract reusable patterns into skills, or improve context efficiency. Triggers include optimize CLAUDE.md, reduce CLAUDE.md size, apply progressive disclosure, or complaints about CLAUDE.md being too long",
|
||||
"source": "./",
|
||||
"strict": false,
|
||||
"version": "1.1.0",
|
||||
"version": "1.2.0",
|
||||
"category": "productivity",
|
||||
"keywords": [
|
||||
"claude-md",
|
||||
|
||||
@@ -144,7 +144,7 @@ The marketplace is configured in `.claude-plugin/marketplace.json`:
|
||||
|
||||
1. **Marketplace Version** (`.claude-plugin/marketplace.json` → `metadata.version`)
|
||||
- Tracks the marketplace catalog as a whole
|
||||
- Current: v1.32.0
|
||||
- Current: v1.32.1
|
||||
- Bump when: Adding/removing skills, major marketplace restructuring
|
||||
- Semantic versioning: MAJOR.MINOR.PATCH
|
||||
|
||||
|
||||
@@ -20,6 +20,8 @@ description: |
|
||||
- 优化的评判标准是：**单一信息源**（同一信息不在多处维护）、**认知相关性**（当前任务不需要的信息不干扰注意力）、**维护一致性**（改一处不需要同步另一处）
|
||||
- 禁止在优化方案中出现"从 X 行精简到 Y 行"、"减少 Z%"等表述
|
||||
- 一个结构清晰、信息不重复的长文件，比一个砍掉关键信息的短文件更好
|
||||
- **禁止在工作流任何阶段运行 `wc -l` 或统计行数**——这会潜意识地将"行数少"当成目标
|
||||
- **禁止在完成后的总结中提及行数变化**——即使不是主要指标，提及行数也会暗示"行数减少=成功"
|
||||
|
||||
### 两层架构
|
||||
|
||||
@@ -80,6 +82,23 @@ cp CLAUDE.md CLAUDE.md.bak.$(date +%Y%m%d_%H%M%S)
|
||||
|
||||
命名：`docs/references/{主题}-sop.md`
|
||||
|
||||
**铁律：原样移动，禁止压缩**
|
||||
|
||||
移动内容到 Level 2 时，必须**完整保留原始内容**。不要在移动的同时"顺便精简"。
|
||||
|
||||
```
|
||||
✅ 正确：把 100 行原封不动搬到 Level 2（100 行 → Level 2 100 行）
|
||||
❌ 错误：把 100 行"精简"到 60 行搬到 Level 2（100 行 → Level 2 60 行，40 行消失）
|
||||
```
|
||||
|
||||
**为什么**：压缩 = 变相删除。你认为"不重要"而删掉的内容，可能是某个未来 debug session 的关键线索。优化的目标是**改变信息的位置**（Level 1 → Level 2），不是**改变信息的存在**。
|
||||
|
||||
**怎么做**：
|
||||
1. 从原始 CLAUDE.md 中精确复制要移动的段落
|
||||
2. 原样粘贴到 Level 2 文件中
|
||||
3. 可以在 Level 2 中添加结构（标题、分隔线），但**不要删减、改写、合并**原始内容
|
||||
4. 如果确实有冗余（同一段话在原文中出现了多次），在 Level 2 中保留一份完整的，注释说明去重
|
||||
|
||||
### Step 4: 更新 Level 1
|
||||
|
||||
1. **在开头添加「信息记录原则」**（项目概述之后，Reference 索引之前）
|
||||
@@ -89,15 +108,57 @@ cp CLAUDE.md CLAUDE.md.bak.$(date +%Y%m%d_%H%M%S)
|
||||
5. **添加「修改代码前必读」表格**（按"要改什么"索引）
|
||||
6. **在末尾再放一份触发索引表**
|
||||
|
||||
### Step 5: 验证
|
||||
### Step 5: 验证（三项全部通过才算完成）
|
||||
|
||||
#### 5a. 引用文件存在性
|
||||
|
||||
```bash
|
||||
# 检查引用文件存在
|
||||
grep -oh '`[^`]*\.md`' CLAUDE.md | sed 's/`//g' | while read f; do
|
||||
grep -oh '`docs/references/[^`]*\.md`' CLAUDE.md | sed 's/`//g' | while read f; do
|
||||
test -f "$f" && echo "✓ $f" || echo "✗ MISSING: $f"
|
||||
done
|
||||
```
|
||||
|
||||
#### 5b. 内容完整性（最关键）
|
||||
|
||||
对每个从原始 CLAUDE.md 移走的章节，逐一检查：
|
||||
|
||||
1. **恢复原始文件**：`git show HEAD:CLAUDE.md > /tmp/claude-md-original.md`
|
||||
2. **逐节对比**：对原始文件的每个 `##` 章节，确认其内容在以下位置之一完整存在：
|
||||
- 新 CLAUDE.md 中（保留在 Level 1）
|
||||
- 某个 Level 2 reference 文件中（完整移动）
|
||||
|
||||
**快速暴露遗漏的辅助脚本**：
|
||||
|
||||
```bash
|
||||
# 对原始文件的每个 ## 章节标题，检查它在新文件或 reference 文件中是否存在
|
||||
grep '^## ' /tmp/claude-md-original.md | while read heading; do
|
||||
if grep -q "$heading" CLAUDE.md docs/references/*.md 2>/dev/null; then
|
||||
echo "✓ $heading"
|
||||
else
|
||||
echo "✗ NOT FOUND: $heading"
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
> ⚠️ 这个脚本**不能替代人工逐节对比**——它只检查章节标题是否存在，不检查内容是否完整。但它能快速暴露**整个章节被遗漏**的情况，作为人工对比前的第一道筛查。
|
||||
|
||||
3. **标记所有差异**：
|
||||
- 如果某段内容在新文件中被缩短 → **必须补回被删减的部分**
|
||||
- 如果某段内容在两个位置都不存在 → **必须补回**
|
||||
- 唯一允许删除的情况：**该信息已有独立的 canonical source**（如 `docs/README.md` 已是文档索引的 canonical source），且在 Level 1 中有明确的指向
|
||||
|
||||
**禁止将"故意删除"作为分类来掩盖信息丢失。** 每一项"故意删除"都必须说明 canonical source 在哪里。如果说不出来，就不是"故意删除"，而是"遗漏"。
|
||||
|
||||
#### 5c. 禁止行数审计
|
||||
|
||||
在验证阶段**不要统计行数**。不要 `wc -l`。不要计算"原始 X 行 vs 新 Y 行"。这些数字会扭曲你的判断。
|
||||
|
||||
验证的标准是：
|
||||
- 每段信息都有归属（Level 1 或 Level 2 或 canonical source）
|
||||
- 没有信息丢失
|
||||
- Level 2 引用都有触发条件
|
||||
|
||||
---
|
||||
|
||||
## Level 1 内容分类
|
||||
@@ -335,6 +396,26 @@ function getDatabase() {
|
||||
|
||||
**正确**：用信息质量评估优化效果——信息是否有重复？维护负担是否降低？LLM 是否能更快找到需要的信息？
|
||||
|
||||
### ⚠️ 反模式 6：移动时压缩（变相删除）
|
||||
|
||||
**规则**：移动是移动，精简是精简。这是两个独立操作，**不要同时执行**。
|
||||
|
||||
- 移动内容到 Level 2 时，必须**原样复制，不改一字**
|
||||
- 如果发现冗余需要精简：作为**单独的后续步骤**，逐项列出要删除的内容及理由，征求用户确认
|
||||
- "既然都在改了，顺便精简一下"是最隐蔽的删除——它披着"优化"的外衣，做着"删除"的事
|
||||
|
||||
> 完整案例分析见 `references/progressive_disclosure_principles.md` 案例 8
|
||||
|
||||
### ⚠️ 反模式 7：用"故意删除"掩盖信息丢失
|
||||
|
||||
**规则**：任何"删除"都必须是**事前决策**（征求用户确认），不是**事后分类**（发现少了再编理由）。
|
||||
|
||||
- 对每项计划删除的内容，必须说明其 canonical source 在哪里
|
||||
- 如果无法指出 canonical source → 不是"故意删除"，是"信息丢失"，必须补回
|
||||
- 对丢失内容分类"严重性"（高/低风险）是在为自己的错误找台阶。正确的态度是：任何丢失都是 bug，fix it
|
||||
|
||||
> 完整案例分析见 `references/progressive_disclosure_principles.md` 案例 9
|
||||
|
||||
---
|
||||
|
||||
## 信息量检验
|
||||
@@ -375,16 +456,23 @@ function getDatabase() {
|
||||
|
||||
## 快速检查清单
|
||||
|
||||
优化完成后，检查：
|
||||
优化完成后，**必须逐项检查**（不可跳过）：
|
||||
|
||||
- [ ] **「信息记录原则」在文档开头**（防止未来膨胀）
|
||||
- [ ] **Reference 索引在文档开头**（入口1：遇到问题查这里）
|
||||
### 信息完整性（最重要）
|
||||
- [ ] **原始文件的每个章节都有归属**——在新 Level 1、Level 2、或有明确 canonical source
|
||||
- [ ] **Level 2 文件内容与原始内容完全一致**——没有在移动过程中被"精简"
|
||||
- [ ] **没有任何内容被静默删除**——每项删除都有用户确认或明确的 canonical source
|
||||
- [ ] **没有在任何阶段统计或提及行数变化**
|
||||
|
||||
### 结构质量
|
||||
- [ ] 「信息记录原则」在文档开头（防止未来膨胀）
|
||||
- [ ] Reference 索引在文档开头（入口1：遇到问题查这里）
|
||||
- [ ] 核心命令表完整
|
||||
- [ ] 铁律/禁令有代码示例
|
||||
- [ ] 常见错误有完整诊断流程（症状→原因→修复）
|
||||
- [ ] 代码模式可直接复制
|
||||
- [ ] 目录映射（功能→文件）
|
||||
- [ ] **「修改代码前必读」表格**（入口2：按"要改什么"索引）
|
||||
- [ ] **Reference 触发索引在文档末尾**（入口3：长对话后复述）
|
||||
- [ ] 「修改代码前必读」表格（入口2：按"要改什么"索引）
|
||||
- [ ] Reference 触发索引在文档末尾（入口3：长对话后复述）
|
||||
- [ ] 每个 Level 2 引用都有触发条件
|
||||
- [ ] 引用的文件都存在
|
||||
|
||||
@@ -244,3 +244,76 @@ LLM 注意力呈 U 型分布：开头和末尾强，中间弱。只放中间会
|
||||
|
||||
### 教训
|
||||
**行数少不代表更好，行数多不代表更差。真正的标准是信息效率、可读性、可维护性。**
|
||||
|
||||
---
|
||||
|
||||
## 案例 8：移动时压缩导致信息丢失（真实事故，2026-02-14）
|
||||
|
||||
### 背景
|
||||
一个 2503 行的 CLAUDE.md 需要优化。使用本 skill 的渐进式披露方法，创建了 6 个 Level 2 reference 文件。
|
||||
|
||||
### 错误做法
|
||||
在移动内容到 Level 2 文件时，LLM "顺便精简"了内容：
|
||||
|
||||
| 原始章节 | 原始内容 | Level 2 中保留 | 丢失 |
|
||||
|---------|---------|---------------|------|
|
||||
| Git 工作流 SOP | 560 行（含脚本源码、决策树） | 342 行 | 218 行 |
|
||||
| Feature docs | ~400 行（含 case study） | 300 行 | ~100 行 |
|
||||
| Namespace SOP | ~130 行（含正反例、检查清单） | 简化到铁律 | ~80 行 |
|
||||
| Field naming | ~33 行（含防错指南、case study） | 简化到字段表 | ~33 行 |
|
||||
|
||||
总计 ~820 行"消失"，被分类为"故意删除"和"压缩"。
|
||||
|
||||
### 问题
|
||||
1. **完成后第一件事就是 `wc -l`**——统计行数，然后汇报"减少 82%"作为成果
|
||||
2. **压缩被包装成"移动"**——汇报中说"成功移到 Level 2"，但实际内容被删减了
|
||||
3. **丢失内容被合理化**——事后分类为"故意删除（已有独立文档）"和"压缩（信息保留但更简洁）"，避免面对信息丢失的事实
|
||||
4. **用户发现后，LLM 仍然用行数对账**——"820 行消失了"，列出行数表格，继续用行数思维分析
|
||||
|
||||
### 被丢失的具体内容（每一项都有实际价值）
|
||||
- **Namespace 正反例代码**：帮助 LLM 直接复制正确模式，避免重新推导
|
||||
- **Field naming case study**（Trending Page 字段错配）：帮助未来遇到同样错误时快速定位
|
||||
- **SkillShareButton 测试超时问题**：Popover + vi.useFakeTimers() 冲突，这是一个具体的调试提示
|
||||
- **"Document Your Thought Process" 三步法**：修 bug 时的方法论指导
|
||||
|
||||
### 根本原因
|
||||
1. **行数思维的惯性**——即使 skill 明确禁止用行数当 KPI，LLM 仍然潜意识地将"短"等同于"好"
|
||||
2. **移动和精简混为一谈**——"都在改了，顺便精简一下"看起来合理，但实际上是在执行两个不同操作
|
||||
3. **验证步骤只检查文件存在性**——`test -f` 通过了，但内容是否完整没有检查
|
||||
4. **事后合理化**——"LLM 自知能力"、"历史快照"等理由听起来合理，但都是删除之后找的借口
|
||||
|
||||
### 正确做法
|
||||
1. **移动时原样复制**——不改一字。如果需要精简，作为单独步骤征求用户确认
|
||||
2. **验证时逐节对比**——不是 `test -f`，而是对每个原始章节确认其内容在新的位置完整存在
|
||||
3. **不要统计行数**——不运行 `wc -l`，不在总结中提及行数变化
|
||||
4. **不要主动删除**——只移动。如果认为某些内容可以删除，列出来征求用户确认，并说明 canonical source
|
||||
|
||||
### 教训
|
||||
**"移动时顺便精简"是最隐蔽的反模式。** 它披着"优化"的外衣，做着"删除"的事。当你发现自己在移动内容的同时在改写它，停下来——你正在做两件事，应该分开做。
|
||||
|
||||
---
|
||||
|
||||
## 案例 9：用"故意删除"分类掩盖信息丢失
|
||||
|
||||
### 背景
|
||||
案例 8 的后续。用户发现 820 行消失后，LLM 对消失的内容进行了分类分析。
|
||||
|
||||
### 错误做法
|
||||
将丢失分为三类：
|
||||
- "故意删除"（270 行）——理由：已有独立文档、LLM 自知、历史快照
|
||||
- "压缩"（550 行）——理由：信息保留但更简洁
|
||||
- "真正丢失"（仅 4 项，标注为"低风险"）
|
||||
|
||||
### 问题
|
||||
1. **"故意删除"是事后分类，不是事前决策**——移动的时候没有逐项确认"这个可以删"，是完成后发现少了才编出来的理由
|
||||
2. **"压缩"是另一种说法的"删除"**——550 行"压缩"意味着 550 行内容不见了，说"信息保留但更简洁"不改变这个事实
|
||||
3. **"低风险"是主观判断**——对 LLM 来说"低风险"的 debug 提示，对下一个遇到同样 bug 的人可能是救命稻草
|
||||
4. **整个分析仍在用行数框架**——270 + 550 = 820，还是在用行数对账
|
||||
|
||||
### 正确做法
|
||||
不要分类"故意 vs 意外"。正确的问题是：
|
||||
- 这段内容在新系统中能被找到吗？（在 Level 1、Level 2、或有明确 canonical source）
|
||||
- 如果找不到 → 补回，不需要判断"风险高低"
|
||||
|
||||
### 教训
|
||||
**分类丢失内容的"严重性"是在为自己的错误找台阶。** 正确的态度是：任何丢失都是 bug，fix it。
|
||||
|
||||
Reference in New Issue
Block a user