editing-claude

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

editing-claude

编辑CLAUDE工具

Validate and optimize CLAUDE.md files to maintain focus and effectiveness.

验证并优化CLAUDE.md文件，以保持内容的聚焦性和有效性。

Purpose

用途

This skill validates CLAUDE.md files against Anthropic's best practices, detects quality issues (contradictions, redundancy, excessive length, emphasis overuse), and suggests safe automated fixes or extraction strategies. Based on comprehensive research into context engineering best practices.

本技能依据Anthropic的最佳实践验证CLAUDE.md文件，检测质量问题（矛盾内容、冗余信息、过长篇幅、强调过度），并建议安全的自动修复方案或内容提取策略。基于对上下文工程最佳实践的全面研究构建。

When to Use - Explicit, implicit, and file type triggers
What This Skill Does - 8-step workflow and health scoring
Instructions - Complete implementation guide
- Step 1: Discover CLAUDE.md Files - Find global, project, and local files
- Step 2: Analyze Structure - Parse headings, measure sections, detect orphans
- Step 3: Analyze Emphasis Usage - Count MUST/NEVER/ALWAYS markers
- Step 4: Detect Redundancy - Intra-file and cross-file duplication
- Step 5: Detect Contradictions - Find conflicting directives
- Step 6: Identify Extraction Opportunities - Content for specialized docs
- Step 7: Validate Links - Check internal/external links
- Step 8: Generate Health Report - Compile comprehensive analysis
Safe Automated Fixes - Fixes that can be applied automatically
- Fix 1: Remove Cross-File Redundancy - Replace duplication with references
- Fix 2: Fix Broken Links - Update links to correct paths
- Fix 3: Fix Orphaned Sections - Promote or nest sections
- Fix 4: Reduce Emphasis Density - Remove redundant emphasis
Examples - Real-world usage scenarios
Validation - Verify skill execution and outcomes
Integration Points - Quality gates, git workflow, documentation reviews

适用场景 - 显式、隐式触发条件及支持的文件类型
技能功能 - 8步工作流与健康评分
操作指南 - 完整实现说明
- 步骤1：发现CLAUDE.md文件 - 查找全局、项目及本地文件
- 步骤2：分析结构 - 解析标题、统计章节长度、检测孤立章节
- 步骤3：分析强调使用情况 - 统计MUST/NEVER/ALWAYS等标记的使用
- 步骤4：检测冗余信息 - 文件内部及跨文件重复内容
- 步骤5：检测矛盾内容 - 查找冲突的指令
- 步骤6：识别内容提取机会 - 可拆分至专业文档的内容
- 步骤7：验证链接 - 检查内部/外部链接有效性
- 步骤8：生成健康报告 - 编译综合分析结果
安全自动修复方案 - 可自动应用的修复措施
- 修复1：移除跨文件冗余 - 用引用替换重复内容
- 修复2：修复失效链接 - 更新链接至正确路径
- 修复3：修复孤立章节 - 升级章节层级或嵌套至合适父章节
- 修复4：降低强调密度 - 移除冗余的强调标记
示例 - 实际使用场景
验证 - 验证技能执行结果
集成点 - 质量门禁、Git工作流、文档评审

Advanced Topics

进阶主题

Supporting Files - Scripts, templates, and references
Red Flags - Common mistakes to avoid
Troubleshooting - Common issues and fixes
Requirements - Python, bash tools, and dependencies

支持文件 - 脚本、模板及参考资料
注意事项 - 需避免的常见错误
故障排除 - 常见问题及解决方法
环境要求 - Python、Bash工具及依赖项

Supporting Resources

支持资源

Reference - Anthropic best practices, algorithms, validation checklist
Examples - Quarterly review, redundancy fixes, extraction strategy

参考文档 - Anthropic最佳实践、算法、验证清单
示例文档 - 季度评审、冗余修复、提取策略示例

Quick Start

快速开始

Analyze current CLAUDE.md:

bash

Skill(command: "editing-claude")

Expected output: Health report (0-50 score), issues found (critical/warning/info), extraction opportunities, automated fixes available.

分析当前CLAUDE.md文件：

bash

Skill(command: "editing-claude")

预期输出： 健康报告（0-50分）、发现的问题（严重/警告/信息）、内容提取机会、可用的自动修复方案。

When to Use

适用场景

Explicit Triggers:

"Edit CLAUDE.md"
"Optimize CLAUDE.md"
"Check for contradictions in CLAUDE.md"
"Validate documentation"
"CLAUDE.md is too long"

Implicit Triggers:

Before committing CLAUDE.md changes
Document exceeds 200 lines (warn at 200, error at 500)
Quarterly documentation reviews
After adding new rules/sections

File Types:

CLAUDE.md (project or global)
.claude/*.md (specialized docs)
*.CLAUDE.md (local overrides)

显式触发条件：

"编辑CLAUDE.md"
"优化CLAUDE.md"
"检查CLAUDE.md中的矛盾内容"
"验证文档"
"CLAUDE.md太长"

隐式触发条件：

提交CLAUDE.md修改前
文档超过200行（200行时警告，500行时报错）
季度文档评审
添加新规则/章节后

支持的文件类型：

CLAUDE.md（项目级或全局级）
.claude/*.md（专业文档）
*.CLAUDE.md（本地覆盖文件）

What This Skill Does

技能功能

8-Step Workflow:

Discovery - Find all CLAUDE.md files (global, project, local)
Structure Analysis - Parse headings, measure sections, detect orphans
Emphasis Analysis - Count MUST/NEVER/ALWAYS/MANDATORY/CRITICAL markers
Redundancy Detection - Find duplicate content (intra-file and cross-file)
Contradiction Detection - Find conflicting directives
Extraction Opportunities - Identify content for specialized docs
Link Validation - Verify all internal/external links
Report & Recommendations - Generate health score with prioritized fixes

Health Score Components (50 points):

Length: 10 points (100-200 lines = 10, >500 = 0)
Emphasis Density: 10 points (<1% = 10, >2% = 0)
Contradictions: 10 points (0 = 10, >3 = 0)
Redundancy: 10 points (0 instances = 10, >5 = 0)
Links: 5 points (all valid = 5)
Structure: 5 points (no orphans = 5)
Extraction Potential: 5 points (<20% = 5)
Freshness: 5 points (updated <30 days = 5)

8步工作流:

1.发现文件 - 查找所有CLAUDE.md文件（全局、项目、本地） 2.结构分析 - 解析标题、统计章节长度、检测孤立章节 3.强调分析 - 统计CRITICAL/MANDATORY/MUST/NEVER/ALWAYS等标记的使用 4.冗余检测 - 查找重复内容（文件内部及跨文件） 5.矛盾检测 - 查找冲突的指令 6.提取机会识别 - 识别可拆分至专业文档的内容 7.链接验证 - 验证所有内部/外部链接有效性 8.报告与建议 - 生成健康评分及优先级修复建议

健康评分构成（50分）：

篇幅：10分（100-200行得10分，超过500行得0分）
强调密度：10分（<1%得10分，>2%得0分）
矛盾内容：10分（无矛盾得10分，超过3处得0分）
冗余信息：10分（无冗余得10分，超过5处得0分）
链接有效性：5分（全部有效得5分）
结构合理性：5分（无孤立章节得5分）
提取潜力：5分（可提取内容<20%得5分）
新鲜度：5分（30天内更新过得5分）

Instructions

操作指南

Step 1: Discover CLAUDE.md Files

步骤1：发现CLAUDE.md文件

Find all CLAUDE.md files in hierarchy:

bash

undefined

查找层级结构中的所有CLAUDE.md文件：

bash

undefined

Global CLAUDE.md

全局CLAUDE.md

test -f ~/.claude/CLAUDE.md && echo "Global: ~/.claude/CLAUDE.md" || echo "No global"

Project CLAUDE.md

项目CLAUDE.md

test -f ./CLAUDE.md && echo "Project: ./CLAUDE.md" || echo "No project"

Get line counts

统计行数

wc -l ~/.claude/CLAUDE.md ./CLAUDE.md 2>/dev/null


**Read the target CLAUDE.md file (usually project).**

wc -l ~/.claude/CLAUDE.md ./CLAUDE.md 2>/dev/null


**读取目标CLAUDE.md文件（通常为项目级文件）。**

Step 2: Analyze Structure

步骤2：分析结构

Extract headings and calculate section lengths:

bash

undefined

提取标题并计算章节长度：

bash

undefined

Extract all headings with line numbers

提取所有标题及行号

grep -n "^#" ./CLAUDE.md

Count sections

统计章节数量

grep -c "^## " ./CLAUDE.md # H2 sections grep -c "^### " ./CLAUDE.md # H3 subsections


**Use Python script for detailed analysis:**

```bash
python .claude/skills/editing-claude/scripts/analyze_structure.py ./CLAUDE.md

Detect issues:

Document >200 lines (warning), >500 lines (error)
Sections >100 lines (suggest extraction)
Orphaned sections (H3 without H2 parent)
Heading hierarchy skips (H1 → H3 without H2)

grep -c "^## " ./CLAUDE.md # H2章节 grep -c "^### " ./CLAUDE.md # H3子章节


**使用Python脚本进行详细分析：**

```bash
python .claude/skills/editing-claude/scripts/analyze_structure.py ./CLAUDE.md

检测问题：

文档超过200行（警告）、超过500行（报错）
章节超过100行（建议提取）
孤立章节（无H2父章节的H3章节）
标题层级跳跃（H1直接到H3，无H2）

Step 3: Analyze Emphasis Usage

步骤3：分析强调使用情况

Extract emphasis markers:

bash

undefined

提取强调标记：

bash

undefined

Find all CRITICAL/MANDATORY/MUST/NEVER/ALWAYS instances

查找所有CRITICAL/MANDATORY/MUST/NEVER/ALWAYS实例

grep -n "(CRITICAL|MANDATORY|MUST|NEVER|ALWAYS)" ./CLAUDE.md


**Calculate emphasis density:**

```bash
python .claude/skills/editing-claude/scripts/analyze_emphasis.py ./CLAUDE.md

Thresholds:

<1%: ✅ Optimal (restrained)
1-2%: ✅ Acceptable (within range)
2-5%: ⚠️ Warning (overuse)
5%: ❌ Error (nothing is critical)

grep -n "(CRITICAL|MANDATORY|MUST|NEVER|ALWAYS)" ./CLAUDE.md


**计算强调密度：**

```bash
python .claude/skills/editing-claude/scripts/analyze_emphasis.py ./CLAUDE.md

阈值：

<1%: ✅ 最优（克制使用）
1-2%: ✅ 可接受（在范围内）
2-5%: ⚠️ 警告（使用过度）
5%: ❌ 错误（所有内容都标为关键等于没有关键）

Step 4: Detect Redundancy

步骤4：检测冗余信息

Intra-file redundancy (same file):

Run semantic similarity analysis:

bash

python .claude/skills/editing-claude/scripts/detect_redundancy.py ./CLAUDE.md

Distinguish redundancy from reinforcement:

Redundancy: Exact duplication in same context → Fix
Reinforcement: Same info in escalating contexts (catalog → section → checklist) → Keep

Cross-file redundancy (global vs project):

bash

python .claude/skills/editing-claude/scripts/detect_redundancy.py ~/.claude/CLAUDE.md ./CLAUDE.md

Common redundant rules:

MultiEdit requirement
Testing philosophy
Critical thinking principle

Fix: Replace project duplication with reference to global.

文件内部冗余（同一文件内）：

运行语义相似度分析：

bash

python .claude/skills/editing-claude/scripts/detect_redundancy.py ./CLAUDE.md

区分冗余与强化：

冗余： 同一语境下的完全重复内容 → 需要修复
强化： 不同语境下的相同信息（如目录→章节→清单） → 保留

跨文件冗余（全局vs项目）：

bash

python .claude/skills/editing-claude/scripts/detect_redundancy.py ~/.claude/CLAUDE.md ./CLAUDE.md

常见冗余规则：

MultiEdit要求
测试理念
批判性思维原则

修复方案： 用全局文件的引用替换项目文件中的重复内容。

Step 5: Detect Contradictions

步骤5：检测矛盾内容

Run semantic contradiction analysis:

bash

python .claude/skills/editing-claude/scripts/detect_contradictions.py ./CLAUDE.md

Contradiction patterns:

Direct opposition: "ALWAYS use X" + "NEVER use X"
Priority conflicts: "X is critical" + "X is optional"
Conflicting delegation: Multiple agents for same task
Tool preference conflicts: Skill vs direct tool (check if conditional)

Validation: Check if apparent contradictions are actually conditional fallbacks (not true contradictions).

运行语义矛盾分析：

bash

python .claude/skills/editing-claude/scripts/detect_contradictions.py ./CLAUDE.md

矛盾模式：

直接对立：“ALWAYS use X” + “NEVER use X”
优先级冲突：“X是关键” + “X是可选”
代理冲突：多个Agent负责同一任务
工具偏好冲突：Skill vs 直接工具（需检查是否为条件性选择）

验证： 检查看似矛盾的内容是否为条件性回退方案（非真正矛盾）。

Step 6: Identify Extraction Opportunities

步骤6：识别内容提取机会

Analyze each section:

bash

python .claude/skills/editing-claude/scripts/identify_extractions.py ./CLAUDE.md

Extraction criteria:

Section >50 lines
Detailed how-to content (should be in guide)
Low-frequency content (edge cases)
Catalog-style content (lists of items)

Common extraction targets:

Skills Catalog (if >40 lines) → .claude/docs/skills-index.md
Workflow details → .claude/docs/workflow-guides.md
Anti-pattern details → .claude/docs/enforcement-guide.md
Agent reference → ../orchestrate-agents/references/dispatch.md (if not already there)

Keep in CLAUDE.md:

5 most critical items from each catalog
Core principles (not implementation details)
Links to specialized docs

分析每个章节：

bash

python .claude/skills/editing-claude/scripts/identify_extractions.py ./CLAUDE.md

提取标准：

章节超过50行
详细的操作指南内容（应放入专门指南）
低频内容（边缘案例）
目录式内容（项目列表）

常见提取目标：

技能目录（超过40行）→ .claude/docs/skills-index.md
工作流细节 → .claude/docs/workflow-guides.md
反模式细节 → .claude/docs/enforcement-guide.md
Agent参考 → ../orchestrate-agents/references/dispatch.md（若尚未存在）

保留在CLAUDE.md中的内容：

每个目录中的5个最关键项
核心原则（而非实现细节）
指向专业文档的链接

Step 7: Validate Links

步骤7：验证链接

Extract and validate all links:

bash

python .claude/skills/editing-claude/scripts/validate_links.py ./CLAUDE.md

Check:

Internal links (file exists)
Relative paths (not absolute)
External links (HTTP 200) - optional
Link text descriptive (not "click here")

Fix broken links automatically (safe operation).

提取并验证所有链接：

bash

python .claude/skills/editing-claude/scripts/validate_links.py ./CLAUDE.md

检查内容：

内部链接（文件是否存在）
相对路径（而非绝对路径）
外部链接（HTTP 200状态，可选检查）
链接文本具有描述性（而非“点击此处”）

自动修复失效链接（安全操作）。

Step 8: Generate Health Report

步骤8：生成健康报告

Compile all analyses into comprehensive report:

bash

python .claude/skills/editing-claude/scripts/generate_report.py ./CLAUDE.md

Report format:

markdown

undefined

将所有分析结果编译为综合报告：

bash

python .claude/skills/editing-claude/scripts/generate_report.py ./CLAUDE.md

报告格式：

markdown

undefined

CLAUDE.md Health Report

CLAUDE.md健康报告

Overall Score: X/50 🟢 EXCELLENT | 🟡 GOOD | 🟠 NEEDS WORK | 🔴 CRITICAL

整体评分: X/50 🟢 优秀 | 🟡 良好 | 🟠 需要改进 | 🔴 严重

Issues Found

发现的问题

🔴 Critical (Fix Immediately)

🔴 严重（立即修复）

[Issue with line numbers and fix]

[带行号的问题及修复方案]

🟠 High Priority (Fix Soon)

🟠 高优先级（尽快修复）

[Issue with line numbers and fix]

[带行号的问题及修复方案]

🟡 Medium Priority (Improve)

🟡 中优先级（优化改进）

[Issue with line numbers and suggestion]

[带行号的问题及建议]

🟢 Low Priority (Optional)

🟢 低优先级（可选优化）

[Issue with line numbers and suggestion]

[带行号的问题及建议]

Extraction Opportunities

内容提取机会

[Section] (X lines) → [target-file.md]

[章节名称]（X行）→ [目标文件.md]

Automated Fixes Available

可用自动修复方案

Fix 1 (safe, low-risk)
Fix 2 (requires review)

修复1（安全、低风险）
修复2（需审核）

Recommendations

建议

[Priority action]
[Next action]
[Future improvement]


**Write report to `.claude/artifacts/YYYY-MM-DD/reports/claude-md-health-report.md`.**
- Use `reports/` subfolder for health reports
- If multiple reports exist for same topic, group in topic subfolder (e.g., `reports/claude-md-optimization/`)

[优先级操作]
[下一步操作]
[未来改进方向]


**将报告写入 `.claude/artifacts/YYYY-MM-DD/reports/claude-md-health-report.md`。**
- 使用`reports/`子文件夹存储健康报告
- 若同一主题存在多个报告，分组存入主题子文件夹（如`reports/claude-md-optimization/`）

Safe Automated Fixes

安全自动修复方案

The following fixes can be applied automatically (with --apply flag):

以下修复方案可自动应用（添加--apply参数）：

Fix 1: Remove Cross-File Redundancy

修复1：移除跨文件冗余

When: Same rule in global and project CLAUDE.md

Action: Replace project duplication with reference to global

markdown

undefined

适用场景： 全局和项目CLAUDE.md中存在相同规则

操作： 用全局文件的引用替换项目文件中的重复内容

markdown

undefined

Before (project CLAUDE.md)

修复前（项目CLAUDE.md）

Token Optimization (MultiEdit Required)

Token优化（需MultiEdit）

[13 lines of MultiEdit explanation]

[13行MultiEdit说明]

After

修复后

Token Optimization

Token优化

Global Rule: See ~/.claude/CLAUDE.md for MultiEdit requirement


**Validation:** Ensure global CLAUDE.md exists and contains the rule.

全局规则： 详见~/.claude/CLAUDE.md中的MultiEdit要求


**验证：** 确保全局CLAUDE.md存在且包含该规则。

Fix 2: Fix Broken Links

修复2：修复失效链接

When: Internal link points to non-existent file

Action: Update link to correct path OR remove if file truly missing

Validation: File exists at new path AND content matches expected.

适用场景： 内部链接指向不存在的文件

操作： 更新链接至正确路径，或在文件确实不存在时移除链接

验证： 新路径下的文件存在且内容符合预期。

Fix 3: Fix Orphaned Sections

修复3：修复孤立章节

When: H3 section without H2 parent

Action: Promote to H2 OR nest under appropriate existing H2

Validation: Requires semantic understanding - ASK USER for confirmation.

适用场景： 无H2父章节的H3章节

操作： 升级为H2章节，或嵌套至合适的现有H2章节下

验证： 需要语义理解 - 请用户确认。

Fix 4: Reduce Emphasis Density (>2%)

修复4：降低强调密度（>2%）

When: Too many CRITICAL/MANDATORY markers

Action: Remove redundant emphasis (e.g., heading + body both have emphasis)

Validation: Meaning preserved, emphasis still clear.

适用场景： CRITICAL/MANDATORY标记使用过多

操作： 移除冗余的强调标记（如标题和正文中都有强调）

验证： 保留原意，强调信息仍清晰。

Examples

示例

Python Examples

Python示例

analyze_structure.py - Parse headings, measure sections, detect orphans
analyze_emphasis.py - Extract MUST/NEVER/ALWAYS, calculate density
validate_links.py - Link extraction, existence checking
generate_report.py - Compile analyses into comprehensive report

analyze_structure.py - 解析标题、统计章节长度、检测孤立章节
analyze_emphasis.py - 提取MUST/NEVER/ALWAYS标记、计算密度
validate_links.py - 提取链接、检查有效性
generate_report.py - 编译分析结果生成报告

Complete Walkthroughs

完整操作流程

See examples/examples.md for:

Example 1: Quarterly Review - Full analysis workflow
Example 2: Fixing Redundancy - Cross-file duplication
Example 3: Extraction Strategy - Skills Catalog extraction
Example 4: Contradiction Resolution - Detecting conflicts
Example 5: Length Optimization - 502 → 250 lines
Example 6: Emergency Fix - Broken links and orphans

详见examples/examples.md：

示例1：季度评审 - 完整分析工作流
示例2：修复冗余 - 跨文件重复内容处理
示例3：提取策略 - 技能目录拆分
示例4：矛盾解决 - 检测冲突内容
示例5：篇幅优化 - 从502行精简至250行
示例6：紧急修复 - 失效链接与孤立章节处理

Supporting Files

支持文件

scripts/analyze_structure.py - Parse headings, measure sections, detect orphans
scripts/analyze_emphasis.py - Extract MUST/NEVER/ALWAYS, calculate density
scripts/validate_links.py - Link extraction, existence checking
scripts/generate_report.py - Compile analyses into comprehensive report
examples/examples.md - Comprehensive examples and use cases
templates/extraction-template.md - Template for creating specialized docs
templates/report-template.md - Template for health report
references/reference.md - Technical depth on algorithms and best practices

scripts/analyze_structure.py - 解析标题、统计章节长度、检测孤立章节
scripts/analyze_emphasis.py - 提取MUST/NEVER/ALWAYS标记、计算密度
scripts/validate_links.py - 提取链接、检查有效性
scripts/generate_report.py - 编译分析结果生成报告
examples/examples.md - 综合示例与使用场景
templates/extraction-template.md - 创建专业文档的模板
templates/report-template.md - 健康报告模板
references/reference.md - 算法与最佳实践的技术细节

Validation

验证

Verify skill execution:

Health score calculated: 0-50 range
All 8 analyses run: Structure, emphasis, redundancy, contradictions, extraction, links, freshness, report
Report generated: Saved to
```
.claude/artifacts/YYYY-MM-DD/reports/
```
No false positives: Reinforcement not flagged as redundancy
Safe fixes only: No destructive operations without confirmation

Expected outcomes:

✅ Report shows health score matching manual assessment
✅ Extraction suggestions align with research (e.g., 191 lines identified in Phase 2)
✅ No false positives on current CLAUDE.md (0 contradictions expected)
✅ Automated fixes apply without breaking links

验证技能执行：

1.健康评分已计算： 0-50分范围 2.所有8项分析已执行：结构、强调、冗余、矛盾、提取、链接、新鲜度、报告 3.报告已生成：保存至

.claude/artifacts/YYYY-MM-DD/reports/

4.无假阳性：未将内容强化标记为冗余 5.仅安全修复：无确认时不执行破坏性操作

预期结果：

✅ 报告中的健康评分与人工评估一致
✅ 提取建议符合研究结果（如第二阶段识别出191行可提取内容）
✅ 当前CLAUDE.md无假阳性矛盾（预期0处矛盾）
✅ 自动修复应用后未破坏链接

Integration Points

集成点

With Quality Gates:

Run before committing CLAUDE.md changes
Warn if health score <40 (FAIR threshold)

With Git Workflow:

Pre-commit hook validates CLAUDE.md
Blocks if health score <30 (POOR threshold)

With Documentation Reviews:

Quarterly review using this skill
Track health score over time

With Skill Creator:

Detects when Skills Catalog grows >40 lines
Recommends extraction to skills-index.md

与质量门禁集成：

提交CLAUDE.md修改前运行
健康评分低于40分（一般水平阈值）时发出警告

与Git工作流集成：

预提交钩子验证CLAUDE.md
健康评分低于30分（较差水平阈值）时阻止提交

与文档评审集成：

使用本技能进行季度评审
跟踪健康评分变化趋势

与技能创建工具集成：

检测到技能目录超过40行时
建议拆分至skills-index.md

Red Flags

注意事项

Common mistakes when using this skill:

❌ Auto-apply extraction without review → Always get user approval first
❌ Flag reinforcement as redundancy → Check if same info in different contexts
❌ Flag conditional fallbacks as contradictions → Validate context
❌ Break links during fix → Verify target file exists AND content matches
❌ Remove emphasis from Core Rules → Some sections SHOULD have emphasis
❌ Ignore project-specific patterns → Adapt recommendations to project needs
❌ No rollback plan → Create git commit before applying fixes
❌ Overwhelming reports → Prioritize (critical → warning → info)
❌ No A/B testing → Measure Claude adherence before/after changes
❌ Assume extraction preserves effectiveness → Test impact on adherence

使用本技能时的常见错误：

❌ 未经审核自动应用提取操作 → 始终先获得用户批准
❌ 将内容强化标记为冗余 → 检查是否为不同语境下的相同信息
❌ 将条件性回退标记为矛盾 → 验证上下文
❌ 修复时破坏链接 → 验证目标文件存在且内容匹配
❌ 移除核心规则中的强调标记 → 部分章节应保留强调
❌ 忽略项目特定模式 → 根据项目需求调整建议
❌ 无回滚计划 → 应用修复前创建Git提交
❌ 报告内容过多 → 按优先级排序（严重→警告→信息）
❌ 未进行A/B测试 → 测量修复前后Claude的遵循度
❌ 假设提取操作不影响有效性 → 测试对遵循度的影响

Troubleshooting

故障排除

Issue: Script not found

Fix: Ensure scripts/ directory exists with all Python files

Check:

ls .claude/skills/editing-claude/scripts/

Issue: False positive contradictions

Fix: Check if statements are conditional (if-then logic)
Manual review: Validate semantic analysis

Issue: Health score seems wrong

Fix: Check scoring algorithm in scripts/generate_report.py
Validate: Manual calculation vs automated

Issue: Extraction suggestions break document

Fix: Keep 80% of high-frequency content in CLAUDE.md
Test: Measure Claude adherence before/after extraction

Issue: Links break after fixes

Fix: Validate all links after applying fixes
Rollback:
```
git checkout CLAUDE.md
```
if needed

问题： 脚本未找到

解决： 确保scripts/目录存在且包含所有Python文件

检查：

ls .claude/skills/editing-claude/scripts/

问题： 假阳性矛盾

解决： 检查语句是否为条件性内容（if-then逻辑）
人工审核： 验证语义分析结果

问题： 健康评分似乎有误

解决： 检查scripts/generate_report.py中的评分算法
验证： 人工计算与自动计算结果对比

问题： 提取建议破坏文档完整性

解决： 在CLAUDE.md中保留80%的高频内容
测试： 测量提取前后Claude的遵循度

问题： 修复后链接失效

解决： 应用修复后验证所有链接
回滚： 若需要执行
```
git checkout CLAUDE.md
```

Requirements

环境要求

Python 3.8+ with standard library:

```
re
```
(regex)
```
os
```
(file operations)
```
sys
```
(arguments)
```
pathlib
```
(path handling)

Bash tools:

```
grep
```
(pattern matching)
```
wc
```
(line counting)
```
test
```
(file existence)

Claude Code tools:

Read, Write, Grep, Glob, Bash, Edit, MultiEdit

Optional:

```
git
```
(for rollback, history analysis)
```
markdownlint
```
(markdown validation)

Python 3.8+ 及标准库：

```
re
```
（正则表达式）
```
os
```
（文件操作）
```
sys
```
（参数处理）
```
pathlib
```
（路径处理）

Bash工具：

```
grep
```
（模式匹配）
```
wc
```
（行数统计）
```
test
```
（文件存在性检查）

Claude Code工具：

Read、Write、Grep、Glob、Bash、Edit、MultiEdit

可选工具：

```
git
```
（用于回滚、历史分析）
```
markdownlint
```
（Markdown验证）

另请参阅

reference.md - Anthropic best practices, algorithms, validation checklist
examples.md - Real-world usage scenarios
Anthropic Context Engineering Best Practices - Official guidance
../manage-session-workspace/references/session-workspace-guidelines.md - Where to save reports
research artifacts - Full research findings

reference.md - Anthropic最佳实践、算法、验证清单
examples.md - 实际使用场景
Anthropic上下文工程最佳实践 - 官方指南
../manage-session-workspace/references/session-workspace-guidelines.md - 报告存储位置指南
研究成果 - 完整研究发现

editing-claude

Original

Translation

editing-claude

编辑CLAUDE工具

Purpose

用途

Table of Contents

目录

Core Sections

核心章节

Advanced Topics

进阶主题

Supporting Resources

支持资源

Quick Start

快速开始

When to Use

适用场景

What This Skill Does

技能功能

Instructions

操作指南

Step 1: Discover CLAUDE.md Files

步骤1：发现CLAUDE.md文件

Global CLAUDE.md

全局CLAUDE.md

Project CLAUDE.md

项目CLAUDE.md

Get line counts

统计行数

Step 2: Analyze Structure

步骤2：分析结构

Extract all headings with line numbers

提取所有标题及行号

Count sections

统计章节数量

Step 3: Analyze Emphasis Usage

步骤3：分析强调使用情况

Find all CRITICAL/MANDATORY/MUST/NEVER/ALWAYS instances

查找所有CRITICAL/MANDATORY/MUST/NEVER/ALWAYS实例

Step 4: Detect Redundancy

步骤4：检测冗余信息

Step 5: Detect Contradictions

步骤5：检测矛盾内容

Step 6: Identify Extraction Opportunities

步骤6：识别内容提取机会

Step 7: Validate Links

步骤7：验证链接

Step 8: Generate Health Report

步骤8：生成健康报告

CLAUDE.md Health Report

CLAUDE.md健康报告

Issues Found

发现的问题

🔴 Critical (Fix Immediately)

🔴 严重（立即修复）

🟠 High Priority (Fix Soon)

🟠 高优先级（尽快修复）

🟡 Medium Priority (Improve)

🟡 中优先级（优化改进）

🟢 Low Priority (Optional)

🟢 低优先级（可选优化）

Extraction Opportunities

内容提取机会

Automated Fixes Available

可用自动修复方案

Recommendations

建议

Safe Automated Fixes

安全自动修复方案

Fix 1: Remove Cross-File Redundancy

修复1：移除跨文件冗余

Before (project CLAUDE.md)

修复前（项目CLAUDE.md）

Token Optimization (MultiEdit Required)

Token优化（需MultiEdit）

After

修复后

Token Optimization