update-claude-md

name	update-claude-md
description	更新项目 CLAUDE.md 文档以保持与项目状态一致。当用户明确请求"更新CLAUDE.md"、"同步文档"、"刷新项目说明"、"检查文档一致性"或类似的明确指令时触发。也适用于项目结构发生重大变化后需要更新文档的场景。

Update CLAUDE.md

这个 skill 用于保持项目的 CLAUDE.md 文档与实际项目状态同步一致。

工作流程

按顺序执行以下步骤：

步骤 1: 检查 CLAUDE.md 是否存在

首先检查项目根目录是否存在 CLAUDE.md 文件。

如果不存在 CLAUDE.md：

• 调用 /init 生成初始的 CLAUDE.md
• 完成后继续执行步骤 2

如果存在：

• 直接执行步骤 2

步骤 2: 检查是否需要渐进式披露

读取 CLAUDE.md 文件并统计行数。

如果行数超过 400 行：

• 向用户说明：CLAUDE.md 有 [N] 行，已超过推荐的 400 行限制
• 解释好处：转换为渐进式披露格式可以提高文档可读性和维护性
• 询问用户：是否要将 CLAUDE.md 转换为渐进式披露格式？
  • 如果用户确认：执行步骤 2a（渐进式披露转换）
  • 如果用户拒绝：直接执行步骤 3

如果行数不超过 400 行：

• 直接执行步骤 3

步骤 2a: 渐进式披露转换（简洁版）

将冗长的 CLAUDE.md 转换为简洁的导航结构：

1. 创建或更新 .claude/ 目录结构

   • 确保存在 .claude/ 目录用于存放详细文档
   • 推荐的文档分类：
     • .claude/architecture.md - 项目结构、模块说明
     • .claude/config-guide.md - 配置文件说明
     • .claude/data-schema.md - 数据结构说明
     • 其他按需创建的专门文档

2. 重构 CLAUDE.md

   • 将详细内容移动到对应的 .claude/*.md 文件
   • CLAUDE.md 只保留：
     • 快速导航表：文档名称、内容描述、何时查阅
     • 核心约束：必须遵守的重要规则
     • 当前状态：项目当前的重要状态信息
     • 开发命令：常用命令快速参考
   • 使用以下格式创建导航表：

   ## 快速导航
   
   需要了解更多细节时，按需查阅以下文档：
   
   | 文档 | 内容 | 何时查阅 |
   |------|------|----------|
   | `.claude/architecture.md` | 项目结构、模块说明 | 理解项目布局时 |
   | `.claude/config-guide.md` | 配置文件格式与字段说明 | 新增或修改配置时 |
   

3. 验证内容完整性

   • 确保所有重要信息都已迁移到对应文档
   • 确保 CLAUDE.md 中的链接指向正确的文件
   • 行数应控制在 400 行以内

完成转换后继续执行步骤 3。

步骤 3: 检查内容一致性

步骤 3a: 构建项目文件清单

使用 Glob 工具收集项目的主要文件：

收集以下类型的文件：

• 项目根目录的 README.md、CLAUDE.md
• .claude/ 目录下的所有 .md 文件
• 主要源代码目录（通常为 src/、lib/、core/ 等）的源代码文件
• 配置文件（.yaml、.json、*.toml 等）
• 其他重要的文档或脚本文件

排除以下内容：

• __pycache__/、*.pyc、.git/、node_modules/ 等构建/缓存目录
• 虚拟环境目录（venv/、env/、.venv/）

步骤 3b: 执行一致性检查

1. 确定检查范围

首先判断 CLAUDE.md 是否使用渐进式披露：

• 如果使用渐进式披露（引用了 .claude/ 下的文档）：

  • 从 CLAUDE.md 中提取所有引用的 .claude/*.md 文档路径
  • 检查范围包括：CLAUDE.md + 所有引用的子文档

• 如果是单一文件（所有内容在 CLAUDE.md 中）：

  • 检查范围仅为：CLAUDE.md 本身

2. 基础一致性检查

对检查范围内的每个文档执行：

• 检查文档中提到的文件/目录/类/函数是否在项目中实际存在
• 检查文档中的路径是否正确
• 检查文档中的配置示例是否与实际配置文件匹配
• 检查文档中的代码示例是否符合项目实际代码风格

3. 遗漏性检查

• 配置文件同步检查：自动发现项目中的配置文件（YAML/JSON/TOML/INI 等），检查配置字段是否在对应文档中说明
• 代码模式文档化检查：自动识别源代码中的常见模式（如类型检查、错误处理、装饰器等），检查是否在开发指南中说明

注：遗漏性检查的具体实现方法详见文末【附录：遗漏性一致性检查详解】

4. 并行验证（仅渐进式披露）

如果使用渐进式披露，为每个 .claude/*.md 文档启动独立的 sub-agent 进行验证，提高效率。

输出格式：

{
  "document": "文档路径（如 .claude/architecture.md 或 CLAUDE.md）",
  "status": "valid" | "needs_update",
  "issues": [
    {
      "type": "missing_file" | "incorrect_path" | "outdated_content" | "missing_config_field" | "missing_code_pattern",
      "severity": "error" | "warning",
      "description": "详细描述问题",
      "suggestion": "修复建议",
      "location": "问题所在位置（可选）"
    }
  ]
}

5. 汇总验证结果

• 按严重程度排序问题（error > warning）
• 按问题类型分组展示

步骤 3c: 更新文档

根据验证结果更新文档：

1. 创建新文档：如果发现项目有新的重要模块/概念但文档未覆盖
2. 更新现有文档：修复路径错误、过时描述、不一致的信息
3. 删除过时内容：移除不再存在的文件/功能的描述
4. 补充缺失内容：添加已存在但未记录的重要信息

更新原则：

• 保持文档简洁明了
• 使用项目约定的语言（中文注释和文档）
• 技术术语使用英文（如类名、函数名、命令）
• 保持与项目 CLAUDE.md 中定义的代码风格一致

步骤 4: 报告结果

向用户报告执行结果：

## CLAUDE.md 更新报告

### 执行摘要
- CLAUDE.md 行数：[N] 行
- 验证的文档数量：[N] 个
- 发现的问题：[N] 个
- 已修复的问题：[N] 个

### 详细变更
[列出每个文档的变更内容]

### 建议
[如果发现需要用户注意的问题，在此列出]

重要原则

1. 不擅自修改：如果发现文档与项目不一致，先报告问题，询问用户后再修改
2. 保持简洁：CLAUDE.md 应该是快速参考，不是百科全书
3. 渐进式披露优先：对于大型项目，优先使用 .claude/ 目录存放详细文档
4. 可读性优先：文档应该易于阅读和理解

工具使用

• Glob: 用于收集项目文件清单
• Read: 用于读取文件内容
• Edit: 用于修改文档
• Write: 用于创建新文档
• Agent: 用于并行验证多个文档
• AskUserQuestion: 用于询问用户确认重大变更

输出格式

执行完成后，提供：

1. 执行摘要
2. 变更列表
3. 后续建议（如有）

---

附录：遗漏性一致性检查详解

配置文件同步检查

目的：检测配置文件中定义但文档未说明的字段/选项。

自适应发现流程：

1. 使用 Glob 自动发现配置文件：**/*.yaml、**/*.yml、**/*.json、**/*.toml、**/*.ini 等
2. 排除构建/缓存目录：node_modules/、venv/、__pycache__/、.git/
3. 根据配置文件名自动匹配相关文档：
   • 精确匹配：settings.yaml → settings.md、config.md
   • 类型匹配：包含 "config" 关键词的文档
   • 通用匹配：.claude/config-guide.md、.claude/configuration.md 等
4. 提取配置字段，对比文档中是否说明

代码模式：

# 使用通配符自动发现，避免硬编码特定路径
config_files = glob("**/*.{yaml,yml,json,toml,ini,conf,cfg}",
                    exclude=["node_modules/**", "venv/**", "__pycache__/**", ".git/**"])

代码模式文档化检查

目的：检测源代码中使用但开发指南未说明的关键模式。

自适应发现流程：

1. 使用 Glob 自动发现源代码目录：**/*.py、**/*.js、**/*.ts、src/、lib/、core/ 等
2. 查找开发指南文档：*guide*.md、*dev*.md、*tutorial*.md、.claude/node-dev-guide.md
3. 使用 Grep 扫描通用代码模式：
   • 类型检查：isinstance\(
   • 错误处理：try:\s*\n.*except
   • 装饰器：@\w+\s*\ndef
   • 上下文管理：with .+:
   • 异步模式：async def
4. 统计使用频率，检测高频率但未记录的模式

代码模式：

# 通用模式库，适用于多种编程语言
COMMON_PATTERNS = {
    "type_check": r"isinstance\(|typeof\s+",
    "error_handling": r"try:\s*\n.*except|try\s*{",
    "decorator": r"@\w+\s*\ndef",
    "context_manager": r"with\s+\w+\s+as",
    "async_pattern": r"async def |async\s+function",
}