# CLAUDE.md 主技能（创建/更新/改进）

--- name: claude-md-master description: CLAUDE.md 生命周期管理主技能，，通过仓库验证内容与多模块支持，创建、更新、改进 CLAUDE.md 文件。在创建或更新 CLAUDE.md 文件时使用。 --- # CLAUDE.md 主控（创建/更新/改进） ## 使用时机 - 用户要求创建、改进、更新或标准化 CLAUDE.md 文件时。 ## 核心规则 - 仅包含在仓库或配置中已验证的信息。 - 绝不包含机密、令牌、凭据或用户数据。 - 绝不包含任务特定或临时性指令。 - 保持简洁：根文件不超过 200 行，模块文件不超过 120 行。 - 使用项目符号；避免冗长叙述。 - 命令必须可复制粘贴，且来源于仓库文档/脚本/CI。 - 跳过空章节；避免填充内容。 ## 必需输入（生成前分析） - 与检测到的技术栈相关的构建/包配置（根模块 + 各模块）。 - 仓库中使用的静态分析配置（如存在）。 - 实际模块结构与源码模式（扫描真实目录/文件）。 - 每个模块的代表性源码根目录，用于提取： 包/功能结构、关键类型及使用的注解。 ## 发现（快速 + 定向） 1. 定位现有 CLAUDE.md 变体：`CLAUDE.md`、`.claude.md`、`.claude.local.md`。 2. 通过最小化读取识别技术栈与入口点： - `README.md`、相关 `docs/*` - 构建/包文件（参见技术栈参考） - 运行时/配置：`Dockerfile`、`docker-compose.yml`、`.env.example`、`config/*` - CI：`.github/workflows/*`、`.gitlab-ci.yml`、`.circleci/*` 3. 仅当命令存在于仓库脚本/配置/文档中时提取。 4. 检测多模块结构： - Android/Gradle：读取 `settings.gradle` 或 `settings.gradle.kts` 中的 includes。 - iOS：在 `*.xcodeproj`/`*.xcworkspace` 中检测多个目标/工作区。 - 若超过一个模块/目标包含 `src/` 或构建配置，则规划模块级 CLAUDE.md 文件。 5. 对每个候选模块，读取其构建文件及最小化文档，以捕获模块特定用途、入口点与命令。 6. 扫描源码根目录： - 顶层包/功能文件夹及分层约定。 - 使用的关键注解/类型（按技术栈参考）。 - 代码库中使用的命名约定。 7. 从文档或代码模式中捕获非显而易见的流程/陷阱。 性能： - 优先文件列表 + 定向读取。 - 当章节或符号足够时，避免完整文件读取。 - 跳过大型目录：`node_modules`、`vendor`、`build`、`dist`。 ## 技术栈特定参考（模式 2） 仅在检测到对应信号时读取相关参考： - Android/Gradle → `references/android.md` - iOS/Xcode/Swift → `references/ios.md` - PHP → `references/php.md` - Go → `references/go.md` - React（Web） → `references/react-web.md` - React Native → `references/react-native.md` - Rust → `references/rust.md` - Python → `references/python.md` - Java/JVM → `references/java.md` - Node 工具链 → `references/node.md` - .NET/C# → `references/dotnet.md` - Dart/Flutter → `references/flutter.md` - Ruby/Rails → `references/ruby.md` - Elixir/Erlang → `references/elixir.md` - C/C++/CMake → `references/cpp.md` - 其他/未知 → `references/generic.md`（无特定参考匹配时回退） 若检测到多个技术栈，读取多个参考。 若未识别技术栈，使用通用参考。 ## 多模块输出策略（检测到时强制） - 始终创建根 `CLAUDE.md`。 - 同时在每个有意义的模块/目标根目录内创建 `CLAUDE.md`。 - “有意义” = 拥有自己的构建配置和 `src/`（或等效目录）。 - 跳过纯工具目录，如 `buildSrc`、`gradle`、`scripts`、`tools`。 - 模块文件必须模块特定，避免重复： - 包含用途、关键路径、入口点、模块测试及模块命令（如有）。 - 通过 `@/CLAUDE.md` 引用共享信息。 ## 业务模块 CLAUDE.md 策略（所有技术栈） 对于 monorepo 业务逻辑目录（`src/`、`lib/`、`packages/`、`internal/`）： - 为文件数超过 5 个或拥有独立 README 的模块创建 `CLAUDE.md` - 跳过纯工具目录：`Helper`、`Utils`、`Common`、`Shared`、`Exception`、`Trait`、`Constants` - 不要求分层结构；无论架构如何，均提供模块信息 - 每个模块 CLAUDE.md 最多 120 行 - 通过 `@/CLAUDE.md` 引用根文件以获取共享架构/模式 - 包含：用途、结构、关键类、依赖、入口点 ## 强制输出章节（每个模块 CLAUDE.md） 若在代码库中检测到以下章节则包含（仅当不存在时跳过）： - **功能/组件清单**：列出源码根目录下的顶层目录 - **核心/共享模块**：工具、公共或共享代码目录 - **导航/路由结构**：导航图、路由或路由器 - **网络/API 层模式**：API 客户端、端点、响应包装器 - **DI/注入模式**：模块、容器或注入设置 - **构建/配置文件**：模块特定配置（proguard、manifest 等） 参见技术栈特定参考以获取需检测和报告的精确模式。 ## 更新流程（必须遵循） 1. 仅提出定向增补；展示每个文件的差异。 2. 在应用更新前请求批准： **Cursor IDE：** 使用 AskQuestion 工具，选项如下： - id: "approval" - prompt: "是否应用这些 CLAUDE.md 更新？" - options: [{"id": "yes", "label": "是，应用"}, {"id": "no", "label": "否，取消"}] **Claude Code（终端）：** 输出提议的更改并询问： “您是否批准这些更新？（是/否）” 在继续前停止并等待用户响应。 **其他环境（回退）：** 若无结构化提问工具可用： 1. 清晰展示提议的更改 2. 询问：“您是否批准这些更新？回复‘是’以应用或‘否’以取消。” 3. 在继续前等待用户明确确认 3. 应用更新，保留自定义内容。 若不存在 CLAUDE.md，提议新文件以供批准。 ## 内容提取规则（强制） - 仅从代码库提取： - 提取：使用的类型/类/注解名称、真实路径模式、命名约定。 - 绝不：硬编码值、机密、API 密钥、业务特定逻辑。 - 绝不：在“应做/不应做”规则中包含代码片段。 ## 写入前验证 - [ ] 每条规则引用代码库中的实际类型/路径 - [ ] “应做/不应做”章节中无代码示例 - [ ] 模式与代码库实际内容匹配（非过时） ## 内容规则 - 包含：命令、架构摘要、关键路径、测试、陷阱、工作流怪癖。 - 排除：通用最佳实践、显而易见的信息、未经验证的陈述。 - 使用 `@path/to/file` 导入以避免重复。 - “应做/不应做”格式可选；仅当文件已使用时保留。 - 避免代码示例，除非是简短的可复制粘贴命令。 ## 现有文件策略 检测： - 若存在 `<!-- Generated by claude-md-editor skill -->` → 后续运行 - 否则 → 首次运行 首次运行 + 已有文件： - 备份 `CLAUDE.md` → `CLAUDE.md.bak` - 使用 `.bak` 作为来源，仅提取可复用且项目特定的信息 - 生成新的简洁文件并添加标记 后续运行： - 保留自定义章节和措辞，除非过时或不正确 - 仅更新与当前仓库状态冲突的内容 - 仅当新增章节确实增加价值时添加 绝不修改 `.claude.local.md`。 ## 输出 更新后，打印简洁报告： ``` ## CLAUDE.md 更新报告 - /CLAUDE.md [已创建 | 已备份+创建 | 已更新] - /<module>/CLAUDE.md [已创建 | 已更新] - 备份：列出所有 `.bak` 文件 ``` ## 验证清单 - 描述具体且包含触发词 - 无占位符残留 - 无机密包含 - 命令真实且可复制粘贴 - 遵循报告优先规则 - 引用层级为一级