CLAUDE.md Master

---
name: claude-md-master
description: 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` 中检测多个 target/workspace。
   - 如果多个模块/target 拥有 `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 tooling → `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`。
- 在每个有意义的模块/target 根目录中也创建 `CLAUDE.md`。
  - “有意义” = 拥有独立的构建配置和 `src/`（或等效目录）。
  - 跳过仅用于工具的目录，如 `buildSrc`、`gradle`、`scripts`、`tools`。
- 模块文件必须为模块特定内容，避免重复：
  - 包含目的、关键路径、入口点、模块测试及模块命令（如有）。
  - 通过 `@/CLAUDE.md` 引用共享信息。

## 业务模块 CLAUDE.md 策略（所有技术栈）
针对单体仓库中的业务逻辑目录（`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、manifests 等）

参见技术栈特定参考，了解需检测和报告的具体模式。

## 更新工作流（必须遵循）
1. 仅提出有针对性的增补内容；按文件显示差异。

2. 应用更新前需请求批准：

**Cursor IDE：**
使用 AskQuestion 工具并配置以下选项：
- id: "approval"
- prompt: "应用这些 CLAUDE.md 更新吗？"
- options: [{"id": "yes", "label": "是，应用"}, {"id": "no", "label": "否，取消"}]

**Claude Code（终端）：**
输出建议的更改并询问：
“您是否批准这些更新？（yes/no）”
在继续之前停止并等待用户回复。

**其他环境（备用方案）：**
若无可用的结构化提问工具：
1. 清晰显示建议的更改
2. 询问：“您是否批准这些更新？回复 'yes' 以应用或 'no' 以取消。”
3. 在继续之前等待用户的明确确认

3. 应用更新时，保留自定义内容。

若不存在 CLAUDE.md 文件，则提出新文件供审批。

## 内容提取规则（强制）
- 仅从代码库中提取：
  - 提取：使用的类型/类/注解名称、真实路径模式、命名约定。
  - 禁止：硬编码值、密钥、API 密钥、业务特定逻辑。
  - 禁止：在“Do/Do Not”规则中包含代码片段。

## 写入前验证
- [ ] 每条规则均引用代码库中的实际类型/路径
- [ ] “Do/Do Not”部分不含代码示例
- [ ] 模式与代码库中实际内容一致（非过时内容）

## 内容规则
- 包含：命令、架构摘要、关键路径、测试、陷阱、工作流异常。
- 排除：通用最佳实践、显而易见的信息、未经验证的陈述。
- 使用 `@path/to/file` 导入以避免重复。
- “Do/Do Not”格式为可选；仅当文件中已使用时才保留。
- 避免代码示例，除非是简短的可复制粘贴命令。

## 现有文件策略
检测：
- 若存在 `<!-- Generated by claude-md-editor skill -->` → 后续运行
- 否则 → 首次运行

首次运行 + 存在现有文件：
- 备份 `CLAUDE.md` → `CLAUDE.md.bak`
- 使用 `.bak` 作为源，并仅提取可复用的、项目特定的信息
- 生成新的简洁文件并添加标记

后续运行：
- 除非内容过时或错误，否则保留自定义章节和措辞
- 仅更新与当前仓库状态冲突的内容
- 仅当新增章节具有实际价值时才添加

切勿修改 `.claude.local.md`。

## 输出
更新后打印简洁报告：
```
## CLAUDE.md Update Report
- /CLAUDE.md [CREATED | BACKED_UP+CREATED | UPDATED]
- /<module>/CLAUDE.md [CREATED | UPDATED]
- Backups: list any `.bak` files
```
# C / C++

## 检测信号
- `CMakeLists.txt`
- `meson.build`
- `Makefile`
- `conanfile.*`, `vcpkg.json`
- `compile_commands.json`
- `src/`, `include/`

## 多模块信号
- `CMakeLists.txt` 中包含 `add_subdirectory(...)` 
- 子目录中存在多个 `CMakeLists.txt` 或 `meson.build`
- 包含各自构建文件的 `libs/`、`apps/` 或 `modules/`

## 生成前需分析的源文件
- `CMakeLists.txt` / `meson.build` / `Makefile`
- `conanfile.*`、`vcpkg.json`（如存在）
- `compile_commands.json`（如存在）
- `src/`、`include/`、`tests/`、`libs/`

## 代码库扫描（C/C++ 特定）
- 源码根目录：`src/`、`include/`、`tests/`、`libs/`
- 库/应用拆分（仅在存在时记录）：
  `src/lib`、`src/app`、`src/bin`
- 命名空间和类前缀（仅在存在时记录）
- CMake 目标（仅在存在时记录）：
  `add_library`、`add_executable`

## 必备输出（C/C++ 模块 CLAUDE.md）
如检测到则包含以下内容（列出实际找到的名称）：
- **库**：列出库目标
- **可执行文件**：列出可执行目标
- **头文件**：列出公共头文件目录
- **模块/组件**：列出包含构建文件的子目录
- **依赖项**：列出 Conan/vcpkg 依赖项（如有）

## 命令来源
- README/文档或 CI 中调用 `cmake`、`ninja`、`make` 或 `meson` 的命令
- 调用构建工具的仓库脚本
- 仅包含仓库中存在的命令

## 需提及的关键路径（仅在存在时）
- `src/`、`include/`
- `tests/`、`libs/`
- 入口点（仅在存在时记录）：`lib/main.dart`
- 层级文件夹（仅在存在时记录）：
  `features/`, `core/`, `data/`, `domain/`, `presentation/`
- 状态管理（仅在存在时记录）：
  `Bloc`, `Cubit`, `ChangeNotifier`, `Provider`, `Riverpod`
- 组件命名（仅在存在时记录）：
  `*Screen`, `*Page`

## 必需输出（Flutter 模块 CLAUDE.md）
若检测到则包含以下内容（列出实际找到的名称）：
- **Features**：列出 `features/` 或 `lib/` 下的目录
- **Core modules**：列出 `core/` 下的目录（若存在）
- **State management**：列出 Bloc/Cubit/Provider 的配置
- **Repositories**：列出仓库类
- **Data sources**：列出远程/本地数据源类
- **Widgets**：列出共享组件的目录

## 命令来源
- README/docs 或 CI 中调用 `flutter` 的命令
- 调用 `flutter` 或 `dart` 的仓库脚本
- 文档/脚本中使用的 `flutter run`、`flutter test`、`flutter pub get`
- 仅包含仓库中存在的命令

## 需提及的关键路径（仅在存在时）
- `lib/`, `test/`
- `android/`, `ios/`
- `fastlane/Fastfile`（若存在）
- 目标的 `Sources/` 和 `Tests/` 目录结构

## 代码库扫描（iOS 特定）
- 源码根目录：`Sources/`、`Tests/`、`ios/`（若存在）
- 功能/层级文件夹（仅在存在时记录）：
  `Features/`、`Core/`、`Services/`、`Networking/`、`UI/`、`Domain/`、`Data/`
- SwiftUI 使用情况（仅在存在时记录）：
  `@main`、`App`、`@State`、`@StateObject`、`@ObservedObject`、
  `@Environment`、`@EnvironmentObject`、`@Binding`
- UIKit/生命周期（仅在存在时记录）：
  `UIApplicationDelegate`、`SceneDelegate`、`UIViewController`
- Combine/并发（仅在存在时记录）：
  `@Published`、`Publisher`、`AnyCancellable`、`@MainActor`、`Task`

## 必备输出（iOS 模块 CLAUDE.md）
若检测到则包含以下内容（列出实际找到的名称）：
- **功能清单**：列出 `Features/` 下的目录或功能目标
- **核心模块**：列出 `Core/`、`Services/`、`Networking/` 下的目录
- **导航**：列出协调器、路由器或 SwiftUI 导航文件
- **DI 容器**：列出 DI 配置（Swinject、Factory、手动容器）
- **网络层**：列出 API 客户端或网络服务
- **持久化**：列出 CoreData 模型或其他存储类

## 命令来源
- 调用 Xcode 或 Swift 工具的 README/文档或 CI
- 调用 Xcode/Swift 工具的仓库脚本
- 文档/脚本中使用的 `xcodebuild`、`swift build`、`swift test`
- 仅包含仓库中存在的命令

## 需提及的关键路径（仅在存在时）
- `Sources/`、`Tests/`
- `fastlane/`
- `ios/`（React Native 或多平台仓库）
- `routes`, `controllers`, `services`, `middlewares`, `handlers`,
  `utils`, `config`, `models`, `schemas`
- 框架标记（仅在存在时记录）：
  Express (`express()`、`Router`)、Koa (`new Koa()`)、
  Fastify (`fastify()`)、Nest (`@Controller`、`@Module`、`@Injectable`)
- 全栈布局（仅在存在时记录）：
  Next/Nuxt (`pages/`、`app/`、`server/`)

## 必需输出（Node 模块 CLAUDE.md）
若检测到则包含以下内容（列出实际找到的名称）：
- **路由/页面**：列出路由文件或页面组件
- **控制器/处理器**：列出控制器或处理器文件
- **服务**：列出服务类或模块
- **中间件**：列出中间件文件
- **模型/模式**：列出数据模型或验证模式
- **状态管理**：列出状态存储设置（Redux、Zustand 等）
- **API 客户端**：列出外部 API 客户端模块

## 命令来源
- `package.json` 脚本
- README/文档或 CI
- 文档/脚本中 `npm|yarn|pnpm` 脚本的使用情况
- 仅包含仓库中存在的命令

## 需提及的关键路径（仅在存在时）
- `src/`、`lib/`
- `tests/`
- `apps/`、`packages/`（单体仓库）
- `pages/`、`app/`、`server/`、`api/`
- `controllers/`、`services/`
## Detection signals
- `package.json`
- `src/`, `public/`

## Multi-module signals
- `pnpm-workspace.yaml`, `lerna.json`, `nx.json`, `turbo.json`
- Root `package.json` with `workspaces`
- `packages/` or `apps/` each with `package.json`

## Before generating, analyze these sources
- Root `package.json` and workspace config (`pnpm-workspace.yaml`, `lerna.json`,
  `nx.json`, `turbo.json`)
- `webpack.config.js`, `vite.config.js`, `next.config.js`, `gatsby-config.js`
- `public/`, `static/`, `assets/`
- `src/`, `app/`, `pages/`, `components/`

## Codebase scan (React Web-specific)
- Source roots: `src/`, `app/`
- Entry points (record only if present):
  `index.js`, `index.ts`, `main.tsx`, `_app.tsx`, `App.tsx`
- Framework markers (record only if present):
  `Next.js`: `next.config.js`, `getServerSideProps`, `getStaticProps`, `pages/`, `app/`
  `Gatsby`: `gatsby-config.js`, `createPage`, `useStaticQuery`
  `Remix`: `remix.config.js`, `loader`, `action`, `routes/`
  `Create React App`: `react-scripts`, `App.test.js`
- State management (record only if present):
  `redux`, `@reduxjs/toolkit`, `zustand`, `jotai`, `mobx`
- Styling patterns (record only if present):
  `CSS modules`, `styled-components`, `emotion`, `tailwind`, `sass`, `less`
- Component patterns (record only if present):
  `components/`, `ui/`, `hooks/`, `layouts/`, `pages/`

## Mandatory output (React Web module CLAUDE.md)
Include these if detected (list actual names found):
- **Pages/Routes**: list page components and routing files
- **Components**: list shared component directories
- **Hooks**: list custom hook files
- **Services/API**: list API client modules
- **State management**: list store setup
- **Layouts**: list layout components
- **Styling**: mention styling approach used

## Command sources
- `package.json` scripts
- README/docs or CI
- Build config: `webpack.config.js`, `vite.config.js`, `next.config.js`, `gatsby-config.js`
- Only include commands present in repo

## Key paths to mention (only if present)
- `src/`, `app/`
- `public/`, `static/`, `assets/`
- `pages/`, `components/`, `hooks/`, `layouts/`
- `styles/`, `theme/`, `ui/`
- `vite.config.*`, `next.config.*`, `webpack.config.*`
- `tsconfig.json`
- `turbo.json`
- `app/` 或 `pages/` (Next.js)

## 多模块信号
- `pnpm-workspace.yaml`, `lerna.json`, `nx.json`, `turbo.json`
- 根目录 `package.json` 包含 `workspaces`
- `apps/` 和 `packages/` 各自包含 `package.json`

## 生成前需分析的源文件
- 根目录 `package.json` 和工作区配置 (`pnpm-workspace.yaml`, `lerna.json`,
  `nx.json`, `turbo.json`)
- `apps/*/package.json`, `packages/*/package.json` (如果是单体仓库)
- `vite.config.*`, `next.config.*`, `webpack.config.*`
- `tsconfig.json` / `jsconfig.json`

## 代码库扫描（React Web 专用）
- 源码根目录：`src/`, `app/`, `pages/`, `components/`, `hooks/`, `services/`
- 文件夹模式（仅在存在时记录）：
  `routes`, `store`, `state`, `api`, `utils`, `assets`
- 路由标记（仅在存在时记录）：
  React Router (`Routes`, `Route`)，Next (`app/`, `pages/`)
- 状态管理（仅在存在时记录）：
  `redux`, `zustand`, `recoil`
- 命名规范（仅在存在时记录）：
  hooks 以 `use*` 开头，组件使用 PascalCase

## 必备输出（React Web 模块 CLAUDE.md）
若检测到则包含以下内容（列出实际找到的名称）：
- **Pages/routes**：列出页面组件或路由文件
- **Components**：列出共享组件目录
- **Hooks**：列出自定义 hooks
- **Services/API**：列出 API 客户端模块
- **State management**：列出状态管理设置（Redux、Zustand 等）
- **Utils**：列出工具模块

## 命令来源
- `package.json` 中的 scripts
- README/文档或 CI
- 仅包含仓库中存在的命令

## 需提及的关键路径（仅在存在时）
- `src/`, `public/`
- `app/`, `pages/`, `components/`
- `hooks/`, `services/`
- `apps/`, `packages/` (单体仓库)