| 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: 检查是否需要渐进式披露
读取 CLAUDE.md 文件并统计行数。
如果行数超过 400 行：
- 向用户说明：CLAUDE.md 有 [N] 行，已超过推荐的 400 行限制
- 解释好处：转换为渐进式披露格式可以提高文档可读性和维护性
- 询问用户：是否要将 CLAUDE.md 转换为渐进式披露格式？
- 如果用户确认：执行步骤 2a（渐进式披露转换）
- 如果用户拒绝：直接执行步骤 3
如果行数不超过 400 行：
步骤 2a: 渐进式披露转换（简洁版）
将冗长的 CLAUDE.md 转换为简洁的导航结构：
-
创建或更新 .claude/ 目录结构
- 确保存在
.claude/ 目录用于存放详细文档
- 推荐的文档分类：
.claude/architecture.md - 项目结构、模块说明.claude/config-guide.md - 配置文件说明.claude/data-schema.md - 数据结构说明- 其他按需创建的专门文档
-
重构 CLAUDE.md
- 将详细内容移动到对应的
.claude/*.md 文件
- CLAUDE.md 只保留：
- 快速导航表：文档名称、内容描述、何时查阅
- 核心约束：必须遵守的重要规则
- 当前状态：项目当前的重要状态信息
- 开发命令：常用命令快速参考
- 使用以下格式创建导航表：
## 快速导航
需要了解更多细节时，按需查阅以下文档：
| 文档 | 内容 | 何时查阅 |
|------|------|----------|
| `.claude/architecture.md` | 项目结构、模块说明 | 理解项目布局时 |
| `.claude/config-guide.md` | 配置文件格式与字段说明 | 新增或修改配置时 |
-
验证内容完整性
- 确保所有重要信息都已迁移到对应文档
- 确保 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 是否使用渐进式披露：
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: 更新文档
根据验证结果更新文档：
- 创建新文档：如果发现项目有新的重要模块/概念但文档未覆盖
- 更新现有文档：修复路径错误、过时描述、不一致的信息
- 删除过时内容：移除不再存在的文件/功能的描述
- 补充缺失内容：添加已存在但未记录的重要信息
更新原则：
- 保持文档简洁明了
- 使用项目约定的语言（中文注释和文档）
- 技术术语使用英文（如类名、函数名、命令）
- 保持与项目 CLAUDE.md 中定义的代码风格一致
步骤 4: 报告结果
向用户报告执行结果：
## CLAUDE.md 更新报告
### 执行摘要
- CLAUDE.md 行数：[N] 行
- 验证的文档数量：[N] 个
- 发现的问题：[N] 个
- 已修复的问题：[N] 个
### 详细变更
[列出每个文档的变更内容]
### 建议
[如果发现需要用户注意的问题，在此列出]
重要原则
- 不擅自修改：如果发现文档与项目不一致，先报告问题，询问用户后再修改
- 保持简洁：CLAUDE.md 应该是快速参考，不是百科全书
- 渐进式披露优先：对于大型项目，优先使用 .claude/ 目录存放详细文档
- 可读性优先：文档应该易于阅读和理解
工具使用
- Glob: 用于收集项目文件清单
- Read: 用于读取文件内容
- Edit: 用于修改文档
- Write: 用于创建新文档
- Agent: 用于并行验证多个文档
- AskUserQuestion: 用于询问用户确认重大变更
输出格式
执行完成后，提供：
- 执行摘要
- 变更列表
- 后续建议（如有）
附录：遗漏性一致性检查详解
配置文件同步检查
目的：检测配置文件中定义但文档未说明的字段/选项。
自适应发现流程：
- 使用 Glob 自动发现配置文件：
**/*.yaml、**/*.yml、**/*.json、**/*.toml、**/*.ini 等
- 排除构建/缓存目录：
node_modules/、venv/、__pycache__/、.git/
- 根据配置文件名自动匹配相关文档：
- 精确匹配：
settings.yaml → settings.md、config.md
- 类型匹配：包含 "config" 关键词的文档
- 通用匹配：
.claude/config-guide.md、.claude/configuration.md 等
- 提取配置字段，对比文档中是否说明
代码模式：
config_files = glob("**/*.{yaml,yml,json,toml,ini,conf,cfg}",
exclude=["node_modules/**", "venv/**", "__pycache__/**", ".git/**"])
代码模式文档化检查
目的：检测源代码中使用但开发指南未说明的关键模式。
自适应发现流程：
- 使用 Glob 自动发现源代码目录：
**/*.py、**/*.js、**/*.ts、src/、lib/、core/ 等
- 查找开发指南文档：
*guide*.md、*dev*.md、*tutorial*.md、.claude/node-dev-guide.md
- 使用 Grep 扫描通用代码模式：
- 类型检查：
isinstance\(
- 错误处理：
try:\s*\n.*except
- 装饰器：
@\w+\s*\ndef
- 上下文管理：
with .+:
- 异步模式：
async def
- 统计使用频率，检测高频率但未记录的模式
代码模式：
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",
}
