CLAUDE.md Master（创建/更新/改进）

何时使用

• 用户要求创建、改进、更新或标准化 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 工具链 → 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: "Apply these CLAUDE.md updates?"
• options: [{"id": "yes", "label": "Yes, apply"}, {"id": "no", "label": "No, cancel"}]

Claude Code（终端）： 输出拟议的更改并询问： "Do you approve these updates? (yes/no)" 停止并等待用户回复后再继续。

其他环境（回退方案）： 如果没有可用的结构化提问工具：

1. 清晰地展示拟议的更改

2. 询问："Do you approve these updates? Reply 'yes' to apply or 'no' to cancel."

3. 在继续之前等待用户明确确认

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

如果不存在 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

验证清单

• 描述具体且包含触发词
• 没有残留占位符
• 没有包含机密信息
• 命令真实且可复制粘贴
• 遵守报告优先规则
• 引用只有一层深度 FILE:README.md

claude-md-master

用于 CLAUDE.md 生命周期的精通技能：使用经仓库验证的数据创建、更新和改进文件， 支持多模块和特定技术栈规则。

概述

• 目标：从真实仓库数据生成准确、简洁的 CLAUDE.md 文件
• 范围：根目录 + 有意义的模块，并进行特定技术栈检测
• 保障措施：无机密信息、无填充内容、写入前需明确批准

AI 如何发现并使用此技能

• 发现：该工具之所以学习此技能，是因为它存在于 仓库技能目录中（已在环境中安装/可用）
• 自动使用：当请求包含“创建/更新/改进 CLAUDE.md”时，该工具会选择此技能作为最佳匹配
• 手动使用：操作员可以显式调用 /claude-md-master 以强制使用此工作流
• 运行行为：它会扫描仓库文档/配置/源代码，提出更改， 并在写入文件前等待明确批准

受众

• 在 Cursor/Claude Code 中使用技能的 AI 操作员
• 维护规则和引用的维护者

它的作用

• 使用经过验证、源自仓库的内容生成或更新 CLAUDE.md
• 强制执行严格的安全和简洁规则（无机密信息、无填充内容）
• 检测多模块仓库并生成模块级 CLAUDE.md
• 使用特定技术栈的引用以捕获准确的模式

何时使用

• 用户要求创建、改进、更新或标准化 CLAUDE.md
• 仓库需要一致、经过验证的指导以支持 AI 工作流

所需输入（必须分析）

• 仓库文档：README.md、docs/*（如果存在）
• 与检测到的技术栈相关的构建/配置文件
• 运行时/配置：Dockerfile、.env.example、config/*（如果存在）
• CI：.github/workflows/*、.gitlab-ci.yml、.circleci/*（如果存在）
• 用于提取真实结构、类型、注解、命名的源代码根目录

输出

• 根 CLAUDE.md（始终）
• 有意义模块的模块级 CLAUDE.md（构建配置 + src/）
• 简洁的更新报告，列出已创建/更新的文件和备份

工作流程（高层）

1. 定位现有的 CLAUDE.md 变体，并检测是首次运行还是后续运行
2. 识别技术栈和多模块结构
3. 阅读相关文档/配置/CI，以获取真实命令和工作流程
4. 扫描源码根目录，了解结构、关键类型、注解、模式
5. 生成根级 + 模块级文件，通过 @/CLAUDE.md 避免重复
6. 在应用更新前请求明确批准
7. 应用更改并打印更新报告

核心规则与约束

• 只包含已在仓库中验证的信息；绝不添加机密
• 保持简洁：根级 <= 200 行，模块级 <= 120 行
• 命令必须是真实的，且可从仓库文档/脚本/CI 中复制粘贴
• 跳过空章节；避免通用性指导
• 绝不修改 .claude.local.md
• 在 Do/Do Not 章节中避免代码示例

多模块策略（摘要）

• 始终创建根级 CLAUDE.md
• 只为有意义的模块创建模块级文件
• 跳过仅含工具链的目录（例如 buildSrc、gradle、scripts、tools）
• 业务模块在文件数 >5 或有自己的 README 时拥有自己的文件

参考（技术栈专属指南）

每个参考定义了检测信号、生成前来源、代码库扫描 目标、强制输出项、命令来源和关键路径。

• references/android.md — Android/Gradle
• references/ios.md — iOS/Xcode/Swift
• references/react-web.md — React Web 应用
• references/react-native.md — React Native
• references/node.md — Node 工具链（通用）
• references/python.md — Python
• references/java.md — Java/JVM
• references/dotnet.md — .NET（C#/F#）
• references/go.md — Go
• references/rust.md — Rust
• references/flutter.md — Dart/Flutter
• references/ruby.md — Ruby/Rails
• references/php.md — PHP（Laravel/Symfony/CI/Phalcon）
• references/elixir.md — Elixir/Erlang
• references/cpp.md — C/C++
• references/generic.md — 无匹配技术栈时的回退方案

扩展该技能

• 使用相同模板新增 references/<stack>.md
• 保持检测信号和强制输出具体且可验证
• 不要引入未经验证的命令或泛泛的建议

质量检查清单

• 每条规则都引用仓库中实际的类型/路径
• 不残留任何占位符
• 不包含任何密钥
• 命令真实且可复制粘贴
• 遵守报告优先规则；引用仅一层深度 FILE:references/android.md

Android (Gradle)

检测信号

• settings.gradle 或 settings.gradle.kts
• build.gradle 或 build.gradle.kts
• gradle.properties
• gradle/libs.versions.toml
• gradlew
• gradle/wrapper/gradle-wrapper.properties
• app/src/main/AndroidManifest.xml

多模块信号

• settings.gradle* 中有多个 include(...) 或 includeBuild(...) 条目
• 有多个包含 build.gradle* 和 src/ 的模块目录
• 常见的模块根目录，如 feature/、core/、library/（如果存在）

生成之前，分析这些来源

• settings.gradle 或 settings.gradle.kts
• build.gradle 或 build.gradle.kts（根目录和模块）
• gradle/libs.versions.toml
• gradle.properties
• config/detekt/detekt.yml（如果存在）
• app/src/main/AndroidManifest.xml（或模块清单）

代码库扫描（Android 专用）

• 每个模块的源码根目录：*/src/main/java/、*/src/main/kotlin/
• 功能/分层文件夹的包树（仅在存在时记录）： features/、core/、common/、data/、domain/、presentation/、 ui/、di/、navigation/、network/
• 注解使用情况（仅在存在时记录）： Hilt（@HiltAndroidApp、@AndroidEntryPoint、@HiltViewModel、 @Module、@InstallIn、@Provides、@Binds）、 Compose（@Composable、@Preview）、 Room（@Entity、@Dao、@Database）、 WorkManager（@HiltWorker、ListenableWorker、CoroutineWorker）、 Serialization（@Serializable、@Parcelize）、 Retrofit（@GET、@POST、@PUT、@DELETE、@Body、@Query）
• 导航模式（仅在存在时记录）：NavHost、composable

强制输出（Android 模块 CLAUDE.md）

如果检测到以下内容，请包含它们（列出实际找到的名称）：

• 功能清单：列出 features/ 下的目录（例如 homepage、payment、auth）
• 核心模块：列出 core/ 下的目录（例如 data、network、localization）
• 导航图：列出 *Graph.kt 或 *Navigator*.kt 文件
• Hilt 模块：列出 @Module 类或 di/ 包内容
• Retrofit API：列出 *Api.kt 接口
• Room 数据库：列出 @Database 类
• Worker：列出 @HiltWorker 类
• Proguard：如果存在，提及 proguard-rules.pro

命令来源

• README/文档或调用 Gradle wrapper 的 CI
• 调用 ./gradlew 的仓库脚本
• 文档/脚本中使用的 ./gradlew assemble、./gradlew test、./gradlew lint
• 仅包含仓库中存在的命令

需要提及的关键路径（仅在存在时）

• app/src/main/、app/src/main/res/
• app/src/main/java/、app/src/main/kotlin/
• app/src/test/、app/src/androidTest/ FILE:references/cpp.md

C / C++

检测信号

• CMakeLists.txt
• meson.build
• Makefile
• conanfile.*、vcpkg.json
• compile_commands.json
• src/、include/

多模块信号

• 带有 add_subdirectory(...) 的 CMakeLists.txt
• 子目录中存在多个 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/文档或调用 cmake、ninja、make 或 meson 的 CI
• 调用构建工具的仓库脚本
• 仅包含仓库中存在的命令

需要提及的关键路径（仅在存在时）

• src/、include/
• tests/、libs/ FILE:references/dotnet.md

.NET (C# / F#)

检测信号

• *.sln
• *.csproj、*.fsproj、*.vbproj
• global.json
• Directory.Build.props、Directory.Build.targets
• nuget.config
• Program.cs
• Startup.cs
• appsettings*.json

多模块信号

• 包含多个项目条目的 *.sln
• src/ 和 tests/ 下的多个 *.*proj 文件
• 跨项目管理共享设置的 Directory.Build.*

生成前，分析这些来源

• *.sln、*.csproj / *.fsproj / *.vbproj
• Directory.Build.props、Directory.Build.targets
• global.json、nuget.config
• Program.cs / Startup.cs
• appsettings*.json

代码库扫描（.NET 专用）

• 源码根目录：src/、tests/、包含 *.csproj 的项目文件夹
• 分层文件夹（仅在存在时记录）： Controllers、Services、Repositories、Domain、Infrastructure
• ASP.NET 特性（仅在存在时记录）： [ApiController]、[Route]、[HttpGet]、[HttpPost]、[Authorize]
• EF Core 用法（仅在存在时记录）： DbContext、Migrations、[Key]、[Table]

强制输出（.NET 模块 CLAUDE.md）

如果检测到以下内容，请包含（列出实际找到的名称）：

• 控制器：列出 [ApiController] 类
• 服务：列出服务类
• 仓储：列出仓储类
• 实体：列出 EF Core 实体类
• DbContext：列出数据库上下文类
• 中间件：列出自定义中间件
• 配置：列出配置节或选项类

命令来源

• README/文档或 CI 中调用 dotnet
• 仓库脚本，如 build.ps1、build.sh
• 文档/脚本中的 dotnet run、dotnet test 用法
• 仅包含仓库中存在的命令

需要提及的关键路径（仅在存在时）

• src/、tests/
• appsettings*.json
• Controllers/、Models/、Views/、wwwroot/ FILE:references/elixir.md

Elixir / Erlang

检测信号

• mix.exs、mix.lock
• config/config.exs
• lib/、test/
• apps/（umbrella）
• rel/

多模块信号

• Umbrella 的 apps/ 中包含多个 mix.exs
• 根目录 mix.exs 带有 apps_path

生成前，分析以下来源

• 根目录 mix.exs、mix.lock
• config/config.exs
• apps/*/mix.exs（umbrella）
• lib/、test/、rel/

代码库扫描（Elixir 专用）

• 源码根目录：lib/、test/、apps/*/lib（umbrella）
• Phoenix 结构（仅在存在时记录）： lib/*_web/、controllers、views、channels、routers
• Ecto 用法（仅在存在时记录）： schema、Repo、migrations
• Context/模块（仅在存在时记录）： lib/*/ context 模块和 *_context.ex

强制输出（Elixir 模块 CLAUDE.md）

若检测到则包含以下内容（列出实际找到的名称）：

• Context：列出 context 模块
• Schema：列出 Ecto schema 模块
• Controller：列出 Phoenix controller 模块
• Channel：列出 Phoenix channel 模块
• Worker：列出后台任务模块（Oban 等）
• Umbrella 应用：列出 umbrella 下的应用（若有）

命令来源

• README/文档或 CI 中调用 mix
• 调用 mix 的仓库脚本
• 仅包含仓库中存在的命令

需要提及的关键路径（仅在存在时）

• lib/、test/、config/
• apps/、rel/ FILE:references/flutter.md

Dart / Flutter

检测信号

• pubspec.yaml、pubspec.lock
• analysis_options.yaml
• lib/
• android/、ios/、web/、macos/、windows/、linux/

多模块信号

• melos.yaml（Flutter monorepo）
• packages/、apps/ 或 plugins/ 下的多个 pubspec.yaml

生成前，分析这些来源

• pubspec.yaml、pubspec.lock
• analysis_options.yaml
• melos.yaml（如果是 monorepo）
• lib/、test/ 以及平台文件夹（android/、ios/ 等）

代码库扫描（Flutter 专用）

• 源码根目录：lib/、test/
• 入口点（仅在存在时记录）：lib/main.dart
• 分层文件夹（仅在存在时记录）： features/、core/、data/、domain/、presentation/
• 状态管理（仅在存在时记录）： Bloc、Cubit、ChangeNotifier、Provider、Riverpod
• Widget 命名（仅在存在时记录）： *Screen、*Page

强制输出（Flutter 模块 CLAUDE.md）

如果检测到以下内容，请包含它们（列出实际找到的名称）：

• 功能模块：列出 features/ 或 lib/ 下的目录
• 核心模块：列出 core/ 下的目录（如果存在）
• 状态管理：列出 Bloc/Cubit/Provider 的设置
• 仓库：列出仓库类
• 数据源：列出远程/本地数据源类
• Widget：列出共享 widget 目录

命令来源

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

需要提及的关键路径（仅在存在时）

• lib/、test/
• android/、ios/ FILE:references/generic.md

通用 / 未知技术栈

当没有匹配的特定技术栈参考时，使用此参考。

检测信号（常见模式）

• README.md、CONTRIBUTING.md
• Makefile、Taskfile.yml、justfile
• Dockerfile、docker-compose.yml
• .env.example、config/
• CI 文件：.github/workflows/、.gitlab-ci.yml、.circleci/

生成前，分析这些来源

• README.md - 项目概览、设置说明、命令
• 根目录下的构建/包文件（任何可识别的格式）
• Makefile、Taskfile.yml、justfile、scripts/（如果存在）
• 用于构建/测试命令的 CI/CD 配置
• 用于运行时信息的 Dockerfile

代码库扫描（通用）

• 确定源码根目录：src/、lib/、app/、pkg/ 或根目录
• 分层文件夹（仅在存在时记录）： controllers、services、models、handlers、utils、config
• 入口点：main.*、index.*、app.*、server.*
• 测试位置：tests/、test/、spec/、__tests__/ 或与源码同目录

强制输出（通用 CLAUDE.md）

若检测到以下内容则包含（列出实际找到的名称）：

• 入口点：主文件、启动脚本
• 源码结构：源码根目录下的顶层目录
• 配置文件：环境、设置、密钥模板
• 构建系统：检测到的构建工具及配置位置
• 测试设置：测试框架及运行命令

命令来源

• README 的安装/使用章节
• Makefile 目标、Taskfile.yml 任务、justfile 配方
• CI 工作流步骤（构建、测试、lint）
• scripts/ 目录
• 仅包含仓库中实际存在的命令

需要提及的关键路径（仅在存在时）

• 源码根目录及其顶层结构
• 配置/环境文件
• 测试目录
• 文档位置
• 构建输出目录 FILE:references/go.md

Go

检测信号

• go.mod、go.sum、go.work
• cmd/、internal/
• main.go
• magefile.go
• Taskfile.yml

多模块信号

• 包含多个模块路径的 go.work
• 子目录中存在多个 go.mod 文件
• apps/ 或 services/ 各自拥有自己的 go.mod

生成前，分析以下来源

• go.work、go.mod、go.sum
• cmd/、internal/、pkg/ 布局
• Makefile、Taskfile.yml、magefile.go（若存在）

代码库扫描（Go 专用）

• 源码根目录：cmd/、internal/、pkg/、api/
• 分层文件夹（仅在存在时记录）： handler、service、repository、store、config
• 框架标记（仅在存在时记录）： gin、echo、fiber、chi 导入
• 入口点（仅在存在时记录）： cmd/*/main.go、main.go

强制输出（Go 模块 CLAUDE.md）

如果检测到以下内容，请包含它们（列出实际找到的名称）：

• 命令：列出 cmd/ 下的二进制文件
• 处理器：列出 HTTP 处理器包
• 服务：列出服务包
• 仓库：列出仓库或存储包
• 模型：列出领域模型包
• 配置：列出配置加载包

命令来源

• README/文档或 CI
• Makefile、Taskfile.yml 或调用 Go 工具的仓库脚本
• 文档/脚本中的 go test ./...、go run 用法
• 仅包含仓库中存在的命令

需要提及的关键路径（仅在存在时）

• cmd/、internal/、pkg/、api/
• tests/ 或 *_test.go 布局 FILE:references/ios.md

iOS (Xcode/Swift)

检测信号

• Package.swift
• *.xcodeproj 或 *.xcworkspace
• Podfile、Cartfile
• Project.swift、Tuist/
• fastlane/Fastfile
• *.xcconfig
• Sources/ 或 Tests/（SPM 布局）

多模块信号

• *.xcworkspace 或 *.xcodeproj 中的多个 target/project
• 包含多个 target/product 的 Package.swift
• Sources/<TargetName> 和 Tests/<TargetName> 布局
• 定义多个 target 的 Project.swift（Tuist）

生成前，分析这些来源

• Package.swift（SPM）
• *.xcodeproj/project.pbxproj 或 *.xcworkspace/contents.xcworkspacedata
• Podfile、Cartfile（如果存在）
• Project.swift / Tuist/（如果存在）
• fastlane/Fastfile（如果存在）
• 用于 target 的 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/ 下的目录或功能 target
• 核心模块：列出 Core/、Services/、Networking/ 下的目录
• 导航：列出 coordinator、router 或 SwiftUI 导航文件
• DI 容器：列出 DI 设置（Swinject、Factory、手动容器）
• 网络层：列出 API client 或网络服务
• 持久化：列出 CoreData 模型或其他存储类

命令来源

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

需要提及的关键路径（仅在存在时）

• Sources/、Tests/
• fastlane/
• ios/（React Native 或多平台仓库） FILE:references/java.md

Java / JVM

检测信号

• pom.xml 或 build.gradle*
• settings.gradle、gradle.properties
• mvnw、gradlew
• gradle/wrapper/gradle-wrapper.properties
• src/main/java、src/test/java、src/main/kotlin
• src/main/resources/application.yml、src/main/resources/application.properties

多模块信号

• settings.gradle* 包含多个模块
• 父 pom.xml 带有 <modules>（packaging 为 pom）
• 子目录中存在多个 build.gradle* 或 pom.xml 文件

生成前，分析这些来源

• settings.gradle* 和 build.gradle*（如果是 Gradle）
• 父级和模块的 pom.xml（如果是 Maven）
• gradle/libs.versions.toml（如果存在）
• gradle.properties / mvnw / gradlew
• src/main/resources/application.yml|application.properties（如果存在）

代码库扫描（Java/JVM 专用）

• 源码根目录：src/main/java、src/main/kotlin、src/test/java、src/test/kotlin
• 包/分层文件夹（仅在存在时记录）： controller、service、repository、domain、model、dto、config、client
• 框架注解（仅在存在时记录）： @SpringBootApplication、@RestController、@Controller、@Service、 @Repository、@Component、@Configuration、@Bean、@Transactional
• 持久化/校验（仅在存在时记录）： @Entity、@Table、@Id、@OneToMany、@ManyToOne、@Valid、@NotNull
• 入口点（仅在存在时记录）： 带有 main 的 *Application 类

强制输出（Java/JVM 模块 CLAUDE.md）

如果检测到以下内容，请包含它们（列出实际找到的名称）：

• Controllers：列出 @RestController 或 @Controller 类
• Services：列出 @Service 类
• Repositories：列出 @Repository 类或 JPA 接口
• Entities：列出 @Entity 类
• Configuration：列出 @Configuration 类
• Security：列出安全配置或认证过滤器
• Profiles：列出正在使用的 Spring profiles

命令来源

• Maven/Gradle wrapper 脚本
• README/文档或 CI
• 文档/脚本中使用的 ./mvnw spring-boot:run、./gradlew bootRun
• 只包含仓库中存在的命令

需要提及的关键路径（仅在存在时）

• src/main/java、src/test/java
• src/main/kotlin、src/test/kotlin
• src/main/resources、src/test/resources
• src/main/java/**/controller、src/main/java/**/service、src/main/java/**/repository FILE:references/node.md

Node 工具链（通用）

检测信号

• package.json
• package-lock.json、pnpm-lock.yaml、yarn.lock
• .nvmrc、.node-version
• tsconfig.json
• .npmrc、.yarnrc.yml
• next.config.*、nuxt.config.*
• nest-cli.json、svelte.config.*、astro.config.*

多模块信号

• pnpm-workspace.yaml、lerna.json、nx.json、turbo.json、rush.json
• 根目录 package.json 中包含 workspaces
• apps/、packages/ 下有多个 package.json

生成之前，分析这些来源

• 根目录 package.json 和工作区配置（pnpm-workspace.yaml、lerna.json、 nx.json、turbo.json、rush.json）
• apps/*/package.json、packages/*/package.json（如果是 monorepo）
• tsconfig.json 或 jsconfig.json
• 框架配置：next.config.*、nuxt.config.*、nest-cli.json、 svelte.config.*、astro.config.*（如果存在）

代码库扫描（Node 专用）

• 源码根目录：src/、lib/、apps/、packages/
• 文件夹模式（仅在存在时记录）： 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）

如果检测到以下内容，请包含它们（列出实际找到的名称）：

• 路由/页面：列出路由文件或页面组件
• 控制器/处理器：列出控制器或处理器文件
• 服务：列出服务类或模块
• 中间件：列出中间件文件
• 模型/schema：列出数据模型或验证 schema
• 状态管理：列出 store 设置（Redux、Zustand 等）
• API 客户端：列出外部 API 客户端模块

命令来源

• package.json scripts
• README/docs 或 CI
• 文档/脚本中的 npm|yarn|pnpm script 用法
• 仅包含仓库中存在的命令

需要提及的关键路径（仅在存在时）

• src/、lib/
• tests/
• apps/、packages/（monorepo）
• pages/、app/、server/、api/
• controllers/、services/ FILE:references/php.md

PHP

检测信号

• composer.json、composer.lock
• public/index.php
• artisan、spark、bin/console（框架入口点）
• phpunit.xml、phpstan.neon、phpstan.neon.dist、psalm.xml
• config/app.php
• routes/web.php、routes/api.php
• config/packages/（Symfony）
• app/Config/（CI4）
• composer.json 中的 ext-phalcon（Phalcon）
• phalcon/ide-stubs、phalcon/devtools（Phalcon）

多模块信号

• modules/ 或 app/Modules/（HMVC 风格）
• app/Config/Modules.php、app/Config/Autoload.php（CI4）
• composer.json 中的多个 PSR-4 根
• packages/ 或 apps/ 下的多个 composer.json
• apps/ 下包含 Module.php 或 controllers/ 的子目录

生成前，分析这些来源

• composer.json、composer.lock
• config/ 和 routes/（框架配置）
• app/Config/*（CI4）
• modules/ 或 app/Modules/（如果是 HMVC）
• phpunit.xml、phpstan.neon*、psalm.xml（如果存在）
• bin/worker.php、bin/console.php（CLI 入口点）

代码库扫描（PHP 专用）

• 源码根目录：app/、src/、modules/、packages/、apps/
• Laravel 结构（仅在存在时记录）： app/Http/Controllers、app/Models、database/migrations、 routes/*.php、resources/views
• Symfony 结构（仅在存在时记录）： src/Controller、src/Entity、config/packages、templates
• CodeIgniter 结构（仅在存在时记录）： app/Controllers、app/Models、app/Views、app/Config/Routes.php、 app/Database/Migrations
• Phalcon 结构（仅在存在时记录）： apps/*/controllers/、apps/*/Module.php、models/
• 属性/注解（仅在存在时记录）： #[Route]、#[Entity]、#[ORM\\Column]

业务模块发现

根据检测到的框架扫描以下路径：

• Laravel：app/Services/、app/Domains/、app/Modules/、packages/
• Symfony：src/ 顶层目录
• CodeIgniter：app/Modules/、modules/
• Phalcon：src/、apps/*/
• 通用：src/、lib/

对于每个路径：

• 按文件数量列出前 5-10 个最大的模块
• 对于每个重要模块（>5 个文件），如果可从名称推断，注明其用途
• 识别分层模式（如果存在）：*/Repository/、*/Service/、*/Controller/、*/Action/

模块级 CLAUDE.md 信号

扫描以下路径以查找重要模块（框架特定）：

• src/ - Symfony、Phalcon、自定义框架
• app/Services/、app/Domains/ - Laravel 领域驱动
• app/Modules/、modules/ - Laravel/CI4 HMVC
• packages/ - Laravel 内部包
• apps/ - Phalcon 多应用

在以下情况下创建 <path>/<Module>/CLAUDE.md：

• 阈值：模块有 >5 个文件 或 有自己的 README.md
• 跳过工具目录：Helper/、Exception/、Trait/、Contract/、Interface/、Constants/、Support/
• 不要求分层结构；无论架构如何都提供模块信息

模块 CLAUDE.md 内容（最多 120 行）

• 用途：1-2 句话描述模块
• 结构：列出子目录（Service/、Repository/ 等）
• 关键类：主要的 service/manager/action 类
• 依赖：本模块依赖的其他模块（通过 use 语句）
• 入口点：主要的公共接口/门面
• 框架特定：ServiceProvider（Laravel）、Module.php（Phalcon/CI4）

Worker/Job 检测

• bin/worker.php 或类似的 worker 入口点
• */Job/、*/Jobs/、*/Worker/ 目录
• 队列配置文件（queue.php、rabbitmq.php、amqp.php）
• 如果存在，列出 job 类

API 版本检测

• routes_v*.php 或 routes/v*/ 模式
• controllers/v*/ 目录结构
• 从路由文件或配置中注明当前/活跃的 API 版本

强制输出（PHP 模块 CLAUDE.md）

如果检测到，请包含以下内容（列出实际找到的名称）：

• Controllers：列出 controller 目录/类
• Models：列出 model/entity 类或目录
• Services：列出 service 类或目录
• Repositories：列出 repository 类或目录
• Routes：列出路由文件和版本模式
• Migrations：提及 migrations 目录及文件数量
• Middleware：列出 middleware 类
• Views/templates：提及视图引擎和布局
• Workers/Jobs：如果存在，列出 job 类
• Business modules：按大小列出从检测到的源码路径中提取的顶级模块

命令来源

• composer.json scripts
• README/docs 或 CI
• 文档/脚本中的 php artisan、bin/console 用法
• bin/worker.php 命令
• 仅包含仓库中存在的命令

需要提及的关键路径（仅在存在时）

• app/、src/、apps/
• public/、routes/、config/、database/
• app/Http/、resources/、storage/（Laravel）
• templates/（Symfony）
• app/Controllers/、app/Views/（CI4）
• apps/*/controllers/、models/（Phalcon）
• tests/、tests/acceptance/、tests/unit/ FILE:references/python.md

Python

检测信号

• pyproject.toml
• requirements.txt、requirements-dev.txt、Pipfile、poetry.lock
• tox.ini、pytest.ini
• manage.py
• setup.py、setup.cfg
• settings.py、urls.py（Django）

多模块信号

• 子目录中存在多个 pyproject.toml/setup.py/setup.cfg
• packages/ 或 apps/ 各自带有自己的包配置
• Django 风格的 apps/，包含多个 apps.py（如果存在）

生成之前，分析这些来源

• pyproject.toml 或 setup.py / setup.cfg
• requirements*.txt、Pipfile、poetry.lock
• tox.ini、pytest.ini
• manage.py、settings.py、urls.py（如果是 Django）
• src/、app/、packages/ 下的包根目录（如果存在）

代码库扫描（Python 专用）

• 源码根目录：src/、app/、packages/、tests/
• 文件夹模式（仅在存在时记录）： api、routers、views、services、repositories、 models、schemas、utils、config
• Django 结构（仅在存在时记录）： apps.py、models.py、views.py、urls.py、migrations/、settings.py
• FastAPI/Flask 标记（仅在存在时记录）： FastAPI()、APIRouter、@app.get、@router.post、 Flask(__name__)、Blueprint
• 类型模型用法（仅在存在时记录）： pydantic.BaseModel、TypedDict、dataclass

强制输出（Python 模块 CLAUDE.md）

如果检测到，则包含以下内容（列出实际找到的名称）：

• 路由/视图：列出 API 路由或视图文件
• 服务：列出服务模块
• 模型/schema：列出数据模型（Pydantic、SQLAlchemy、Django）
• 仓库：列出仓库或 DAO 模块
• 迁移：提及 migrations 目录
• 中间件：列出中间件类
• Django 应用：列出已安装的应用（如果是 Django）

命令来源

• pyproject.toml 的 tool 配置段
• README/文档或 CI
• 调用 Python 工具的仓库脚本
• 文档/脚本中使用的 python manage.py、pytest、tox
• 仅包含仓库中存在的命令

需要提及的关键路径（仅在存在时）

• src/、app/、scripts/
• templates/、static/
• tests/ FILE:references/react-native.md

React Native

检测信号

• 包含 react-native 的 package.json
• react-native.config.js
• metro.config.js
• ios/、android/
• babel.config.js、app.json、app.config.*
• eas.json、package.json 中的 expo

多模块信号

• pnpm-workspace.yaml、lerna.json、nx.json、turbo.json
• 根目录 package.json 包含 workspaces
• packages/ 或 apps/ 各自包含 package.json

生成之前，分析这些来源

• 根目录 package.json 和工作区配置（pnpm-workspace.yaml、lerna.json、 nx.json、turbo.json）
• react-native.config.js、metro.config.js
• ios/ 和 android/ 原生文件夹
• app.json / app.config.* / eas.json（如果是 Expo）

代码库扫描（React Native 专用）

• 源码根目录：src/、app/
• 入口点（仅在存在时记录）： index.js、index.ts、App.tsx
• 原生文件夹（仅在存在时记录）：ios/、android/
• 导航/状态（仅在存在时记录）： react-navigation、redux、mobx
• 原生模块模式（仅在存在时记录）： NativeModules、TurboModule

强制输出（React Native 模块 CLAUDE.md）

如果检测到则包含这些（列出找到的实际名称）：

• 屏幕/导航器：列出屏幕组件和导航器
• 组件：列出共享组件目录
• 服务/API：列出 API 客户端模块
• 状态管理：列出 store 设置
• 原生模块：列出自定义原生模块
• 平台文件夹：提及 ios/ 和 android/ 设置

命令来源

• package.json 脚本
• README/文档或 CI
• ios/ 和 android/ 中的原生构建文件
• 文档/脚本中的 expo 脚本用法（如果是 Expo）
• 仅包含仓库中存在的命令

需要提及的关键路径（仅在存在时）

• ios/、android/
• src/、app/ FILE:references/react-web.md

React（Web）

检测信号

• package.json
• src/、public/
• 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（如果是 monorepo）
• 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）

如果检测到则包含这些（列出实际找到的名称）：

• 页面/路由：列出页面组件或路由文件
• 组件：列出共享组件目录
• Hooks：列出自定义 hooks
• 服务/API：列出 API 客户端模块
• 状态管理：列出 store 设置（Redux、Zustand 等）
• 工具：列出工具模块

命令来源

• package.json scripts
• README/文档或 CI
• 仅包含仓库中存在的命令

需要提及的关键路径（仅在存在时）

• src/、public/
• app/、pages/、components/
• hooks/、services/
• apps/、packages/（monorepo） FILE:references/ruby.md

Ruby / Rails

检测信号

• Gemfile、Gemfile.lock
• Rakefile
• config.ru
• bin/rails 或 bin/rake
• config/application.rb
• config/routes.rb

多模块信号

• 子目录中存在多个 Gemfile 或 .gemspec 文件
• gems/、packages/ 或 engines/ 中包含独立的 gem 规格
• apps/ 下存在多个 Rails 应用（每个都带有 config/application.rb）

生成之前，分析这些来源

• Gemfile、Gemfile.lock 以及任何 .gemspec
• config/application.rb、config/routes.rb
• Rakefile / bin/rails（如果存在）
• engines/、gems/、apps/（如果是多应用/引擎结构）

代码库扫描（Ruby/Rails 专用）

• 源码根目录：app/、lib/、engines/、gems/
• Rails 分层（仅在存在时记录）： app/models、app/controllers、app/views、app/jobs、app/services
• 配置与初始化器（仅在存在时记录）： config/routes.rb、config/application.rb、config/initializers/
• ActiveRecord/迁移（仅在存在时记录）： db/migrate、ActiveRecord::Base
• 测试（仅在存在时记录）：spec/、test/

强制输出（Ruby 模块 CLAUDE.md）

如果检测到以下内容，请包含（列出实际找到的名称）：

• Controllers：列出控制器类
• Models：列出 ActiveRecord 模型
• Services：列出服务对象
• Jobs：列出后台任务类
• Routes：概述关键路由命名空间
• Migrations：说明 db/migrate 的数量
• Engines：列出已挂载的引擎（如果有）

命令来源

• README/文档或 CI 中调用 bundle、rails、rake
• Rakefile 任务
• 文档/脚本中的 bundle exec 用法
• 仅包含仓库中实际存在的命令

需要提及的关键路径（仅在存在时）

• app/、config/、db/
• app/controllers/、app/models/、app/views/
• spec/ 或 test/ FILE:references/rust.md

Rust

检测信号

• Cargo.toml、Cargo.lock
• rust-toolchain.toml
• src/main.rs、src/lib.rs
• Cargo.toml 中的工作区成员、crates/

多模块信号

• Cargo.toml 中带 members 的 [workspace]
• crates/ 或 apps/ 下的多个 Cargo.toml

生成前，分析这些来源

• 根目录 Cargo.toml、Cargo.lock
• rust-toolchain.toml（如果存在）
• crates/ 或 apps/ 中的工作区 Cargo.toml
• src/main.rs / src/lib.rs

代码库扫描（Rust 专用）

• 源码根目录：src/、crates/、tests/、examples/
• 模块布局（仅在存在时记录）： lib.rs、main.rs、mod.rs、src/bin/*
• Serde 用法（仅在存在时记录）： #[derive(Serialize, Deserialize)]
• 异步/运行时（仅在存在时记录）： tokio、async-std
• Web 框架（仅在存在时记录）： axum、actix-web、warp

强制输出（Rust 模块 CLAUDE.md）

如果检测到，则包含以下内容（列出找到的实际名称）：

• Crates：列出工作区 crate 及其用途
• Binaries：列出 src/bin/* 或 [[bin]] 目标
• Modules：列出顶层 mod 声明
• Handlers/routes：列出 Web 处理器模块（如果是 Web 应用）
• Models：列出领域模型模块
• Config：列出配置加载模块

命令来源

• README/文档或 CI
• 调用 cargo 的仓库脚本
• 文档/脚本中 cargo test、cargo run 的用法
• 仅包含仓库中存在的命令

需要提及的关键路径（仅在存在时）

• src/、crates/
• tests/、examples/、benches/

CLAUDE.md Master (Create/Update/Improver)

When to use

• User asks to create, improve, update, or standardize CLAUDE.md files.

Core rules

• Only include info verified in repo or config.
• Never include secrets, tokens, credentials, or user data.
• Never include task-specific or temporary instructions.
• Keep concise: root <= 200 lines, module <= 120 lines.
• Use bullets; avoid long prose.
• Commands must be copy-pasteable and sourced from repo docs/scripts/CI.
• Skip empty sections; avoid filler.

Mandatory inputs (analyze before generating)

• Build/package config relevant to detected stack (root + modules).
• Static analysis config used in repo (if present).
• Actual module structure and source patterns (scan real dirs/files).
• Representative source roots per module to extract: package/feature structure, key types, and annotations in use.

Discovery (fast + targeted)

1. Locate existing CLAUDE.md variants: CLAUDE.md, .claude.md, .claude.local.md.
2. Identify stack and entry points via minimal reads:
   • README.md, relevant docs/*
   • Build/package files (see stack references)
   • Runtime/config: Dockerfile, docker-compose.yml, .env.example, config/*
   • CI: .github/workflows/*, .gitlab-ci.yml, .circleci/*
3. Extract commands only if they exist in repo scripts/config/docs.
4. Detect multi-module structure:
   • Android/Gradle: read settings.gradle or settings.gradle.kts includes.
   • iOS: detect multiple targets/workspaces in *.xcodeproj/*.xcworkspace.
   • If more than one module/target has src/ or build config, plan module CLAUDE.md files.
5. For each module candidate, read its build file + minimal docs to capture module-specific purpose, entry points, and commands.
6. Scan source roots for:
   • Top-level package/feature folders and layer conventions.
   • Key annotations/types in use (per stack reference).
   • Naming conventions used in the codebase.
7. Capture non-obvious workflows/gotchas from docs or code patterns.

Performance:

• Prefer file listing + targeted reads.
• Avoid full-file reads when a section or symbol is enough.
• Skip large dirs: node_modules, vendor, build, dist.

Stack-specific references (Pattern 2)

Read the relevant reference only when detection signals appear:

• 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
• Other/Unknown → references/generic.md (fallback when no specific reference matches)

If multiple stacks are detected, read multiple references. If no stack is recognized, use the generic reference.

Multi-module output policy (mandatory when detected)

• Always create a root CLAUDE.md.
• Also create CLAUDE.md inside each meaningful module/target root.
  • "Meaningful" = has its own build config and src/ (or equivalent).
  • Skip tooling-only dirs like buildSrc, gradle, scripts, tools.
• Module file must be module-specific and avoid duplication:
  • Include purpose, key paths, entry points, module tests, and module commands (if any).
  • Reference shared info via @/CLAUDE.md.

Business module CLAUDE.md policy (all stacks)

For monorepo business logic directories (src/, lib/, packages/, internal/):

• Create CLAUDE.md for modules with >5 files OR own README
• Skip utility-only dirs: Helper, Utils, Common, Shared, Exception, Trait, Constants
• Layered structure not required; provide module info regardless of architecture
• Max 120 lines per module CLAUDE.md
• Reference root via @/CLAUDE.md for shared architecture/patterns
• Include: purpose, structure, key classes, dependencies, entry points

Mandatory output sections (per module CLAUDE.md)

Include these sections if detected in codebase (skip only if not present):

• Feature/component inventory: list top-level dirs under source root
• Core/shared modules: utility, common, or shared code directories
• Navigation/routing structure: navigation graphs, routes, or routers
• Network/API layer pattern: API clients, endpoints, response wrappers
• DI/injection pattern: modules, containers, or injection setup
• Build/config files: module-specific configs (proguard, manifests, etc.)

See stack-specific references for exact patterns to detect and report.

Update workflow (must follow)

1. Propose targeted additions only; show diffs per file.

2. Ask for approval before applying updates:

Cursor IDE: Use the AskQuestion tool with these options:

• id: "approval"
• prompt: "Apply these CLAUDE.md updates?"
• options: [{"id": "yes", "label": "Yes, apply"}, {"id": "no", "label": "No, cancel"}]

Claude Code (Terminal): Output the proposed changes and ask: "Do you approve these updates? (yes/no)" Stop and wait for user response before proceeding.

Other Environments (Fallback): If no structured question tool is available:

1. Display proposed changes clearly

2. Ask: "Do you approve these updates? Reply 'yes' to apply or 'no' to cancel."

3. Wait for explicit user confirmation before proceeding

4. Apply updates, preserving custom content.

If no CLAUDE.md exists, propose a new file for approval.

Content extraction rules (mandatory)

• From codebase only:
  • Extract: type/class/annotation names used, real path patterns, naming conventions.
  • Never: hardcoded values, secrets, API keys, business-specific logic.
  • Never: code snippets in Do/Do Not rules.

Verification before writing

• Every rule references actual types/paths from codebase
• No code examples in Do/Do Not sections
• Patterns match what's actually in the codebase (not outdated)

Content rules

• Include: commands, architecture summary, key paths, testing, gotchas, workflow quirks.
• Exclude: generic best practices, obvious info, unverified statements.
• Use @path/to/file imports to avoid duplication.
• Do/Do Not format is optional; keep only if already used in the file.
• Avoid code examples except short copy-paste commands.

Existing file strategy

Detection:

• If <!-- Generated by claude-md-editor skill --> exists → subsequent run
• Else → first run

First run + existing file:

• Backup CLAUDE.md → CLAUDE.md.bak
• Use .bak as a source and extract only reusable, project-specific info
• Generate a new concise file and add the marker

Subsequent run:

• Preserve custom sections and wording unless outdated or incorrect
• Update only what conflicts with current repo state
• Add missing sections only if they add real value

Never modify .claude.local.md.

Output

After updates, print a concise report:

## CLAUDE.md Update Report
- /CLAUDE.md [CREATED | BACKED_UP+CREATED | UPDATED]
- /<module>/CLAUDE.md [CREATED | UPDATED]
- Backups: list any `.bak` files

Validation checklist

• Description is specific and includes trigger terms
• No placeholders remain
• No secrets included
• Commands are real and copy-pasteable
• Report-first rule respected
• References are one level deep FILE:README.md

claude-md-master

Master skill for the CLAUDE.md lifecycle: create, update, and improve files using repo-verified data, with multi-module support and stack-specific rules.

Overview

• Goal: produce accurate, concise CLAUDE.md files from real repo data
• Scope: root + meaningful modules, with stack-specific detection
• Safeguards: no secrets, no filler, explicit approval before writes

How the AI discovers and uses this skill

• Discovery: the tool learns this skill because it exists in the repo skills catalog (installed/available in the environment)
• Automatic use: when a request includes "create/update/improve CLAUDE.md", the tool selects this skill as the best match
• Manual use: the operator can explicitly invoke /claude-md-master to force this workflow
• Run behavior: it scans repo docs/config/source, proposes changes, and waits for explicit approval before writing files

Audience

• AI operators using skills in Cursor/Claude Code
• Maintainers who evolve the rules and references

What it does

• Generates or updates CLAUDE.md with verified, repo-derived content
• Enforces strict safety and concision rules (no secrets, no filler)
• Detects multi-module repos and produces module-level CLAUDE.md
• Uses stack-specific references to capture accurate patterns

When to use

• A user asks to create, improve, update, or standardize CLAUDE.md
• A repo needs consistent, verified guidance for AI workflows

Inputs required (must be analyzed)

• Repo docs: README.md, docs/* (if present)
• Build/config files relevant to detected stack(s)
• Runtime/config: Dockerfile, .env.example, config/* (if present)
• CI: .github/workflows/*, .gitlab-ci.yml, .circleci/* (if present)
• Source roots to extract real structure, types, annotations, naming

Output

• Root CLAUDE.md (always)
• Module CLAUDE.md for meaningful modules (build config + src/)
• Concise update report listing created/updated files and backups

Workflow (high level)

1. Locate existing CLAUDE.md variants and detect first vs. subsequent run
2. Identify stack(s) and multi-module structure
3. Read relevant docs/configs/CI for real commands and workflow
4. Scan source roots for structure, key types, annotations, patterns
5. Generate root + module files, avoiding duplication via @/CLAUDE.md
6. Request explicit approval before applying updates
7. Apply changes and print the update report

Core rules and constraints

• Only include info verified in repo; never add secrets
• Keep concise: root <= 200 lines, module <= 120 lines
• Commands must be real and copy-pasteable from repo docs/scripts/CI
• Skip empty sections; avoid generic guidance
• Never modify .claude.local.md
• Avoid code examples in Do/Do Not sections

Multi-module policy (summary)

• Always create root CLAUDE.md
• Create module-level files only for meaningful modules
• Skip tooling-only dirs (e.g., buildSrc, gradle, scripts, tools)
• Business modules get their own file when >5 files or own README

References (stack-specific guides)

Each reference defines detection signals, pre-gen sources, codebase scan targets, mandatory output items, command sources, and key paths.

• references/android.md — Android/Gradle
• references/ios.md — iOS/Xcode/Swift
• references/react-web.md — React web apps
• references/react-native.md — React Native
• references/node.md — Node tooling (generic)
• references/python.md — Python
• references/java.md — Java/JVM
• references/dotnet.md — .NET (C#/F#)
• references/go.md — Go
• references/rust.md — Rust
• references/flutter.md — Dart/Flutter
• references/ruby.md — Ruby/Rails
• references/php.md — PHP (Laravel/Symfony/CI/Phalcon)
• references/elixir.md — Elixir/Erlang
• references/cpp.md — C/C++
• references/generic.md — Fallback when no stack matches

Extending the skill

• Add a new references/<stack>.md using the same template
• Keep detection signals and mandatory outputs specific and verifiable
• Do not introduce unverified commands or generic advice

Quality checklist

• Every rule references actual types/paths from the repo
• No placeholders remain
• No secrets included
• Commands are real and copy-pasteable
• Report-first rule respected; references are one level deep FILE:references/android.md

Android (Gradle)

Detection signals

• settings.gradle or settings.gradle.kts
• build.gradle or build.gradle.kts
• gradle.properties
• gradle/libs.versions.toml
• gradlew
• gradle/wrapper/gradle-wrapper.properties
• app/src/main/AndroidManifest.xml

Multi-module signals

• Multiple include(...) or includeBuild(...) entries in settings.gradle*
• More than one module dir with build.gradle* and src/
• Common module roots like feature/, core/, library/ (if present)

Before generating, analyze these sources

• settings.gradle or settings.gradle.kts
• build.gradle or build.gradle.kts (root and modules)
• gradle/libs.versions.toml
• gradle.properties
• config/detekt/detekt.yml (if present)
• app/src/main/AndroidManifest.xml (or module manifests)

Codebase scan (Android-specific)

• Source roots per module: */src/main/java/, */src/main/kotlin/
• Package tree for feature/layer folders (record only if present): features/, core/, common/, data/, domain/, presentation/, ui/, di/, navigation/, network/
• Annotation usage (record only if present): Hilt (@HiltAndroidApp, @AndroidEntryPoint, @HiltViewModel, @Module, @InstallIn, @Provides, @Binds), Compose (@Composable, @Preview), Room (@Entity, @Dao, @Database), WorkManager (@HiltWorker, ListenableWorker, CoroutineWorker), Serialization (@Serializable, @Parcelize), Retrofit (@GET, @POST, @PUT, @DELETE, @Body, @Query)
• Navigation patterns (record only if present): NavHost, composable

Mandatory output (Android module CLAUDE.md)

Include these if detected (list actual names found):

• Features inventory: list dirs under features/ (e.g., homepage, payment, auth)
• Core modules: list dirs under core/ (e.g., data, network, localization)
• Navigation graphs: list *Graph.kt or *Navigator*.kt files
• Hilt modules: list @Module classes or di/ package contents
• Retrofit APIs: list *Api.kt interfaces
• Room databases: list @Database classes
• Workers: list @HiltWorker classes
• Proguard: mention proguard-rules.pro if present

Command sources

• README/docs or CI invoking Gradle wrapper
• Repo scripts that call ./gradlew
• ./gradlew assemble, ./gradlew test, ./gradlew lint usage in docs/scripts
• Only include commands present in repo

Key paths to mention (only if present)

• app/src/main/, app/src/main/res/
• app/src/main/java/, app/src/main/kotlin/
• app/src/test/, app/src/androidTest/ FILE:references/cpp.md

C / C++

Detection signals

• CMakeLists.txt
• meson.build
• Makefile
• conanfile.*, vcpkg.json
• compile_commands.json
• src/, include/

Multi-module signals

• CMakeLists.txt with add_subdirectory(...)
• Multiple CMakeLists.txt or meson.build in subdirs
• libs/, apps/, or modules/ with their own build files

Before generating, analyze these sources

• CMakeLists.txt / meson.build / Makefile
• conanfile.*, vcpkg.json (if present)
• compile_commands.json (if present)
• src/, include/, tests/, libs/

Codebase scan (C/C++-specific)

• Source roots: src/, include/, tests/, libs/
• Library/app split (record only if present): src/lib, src/app, src/bin
• Namespaces and class prefixes (record only if present)
• CMake targets (record only if present): add_library, add_executable

Mandatory output (C/C++ module CLAUDE.md)

Include these if detected (list actual names found):

• Libraries: list library targets
• Executables: list executable targets
• Headers: list public header directories
• Modules/components: list subdirectories with build files
• Dependencies: list Conan/vcpkg dependencies (if any)

Command sources

• README/docs or CI invoking cmake, ninja, make, or meson
• Repo scripts that call build tools
• Only include commands present in repo

Key paths to mention (only if present)

• src/, include/
• tests/, libs/ FILE:references/dotnet.md

.NET (C# / F#)

Detection signals

• *.sln
• *.csproj, *.fsproj, *.vbproj
• global.json
• Directory.Build.props, Directory.Build.targets
• nuget.config
• Program.cs
• Startup.cs
• appsettings*.json

Multi-module signals

• *.sln with multiple project entries
• Multiple *.*proj files under src/ and tests/
• Directory.Build.* managing shared settings across projects

Before generating, analyze these sources

• *.sln, *.csproj / *.fsproj / *.vbproj
• Directory.Build.props, Directory.Build.targets
• global.json, nuget.config
• Program.cs / Startup.cs
• appsettings*.json

Codebase scan (.NET-specific)

• Source roots: src/, tests/, project folders with *.csproj
• Layer folders (record only if present): Controllers, Services, Repositories, Domain, Infrastructure
• ASP.NET attributes (record only if present): [ApiController], [Route], [HttpGet], [HttpPost], [Authorize]
• EF Core usage (record only if present): DbContext, Migrations, [Key], [Table]

Mandatory output (.NET module CLAUDE.md)

Include these if detected (list actual names found):

• Controllers: list [ApiController] classes
• Services: list service classes
• Repositories: list repository classes
• Entities: list EF Core entity classes
• DbContext: list database context classes
• Middleware: list custom middleware
• Configuration: list config sections or options classes

Command sources

• README/docs or CI invoking dotnet
• Repo scripts like build.ps1, build.sh
• dotnet run, dotnet test usage in docs/scripts
• Only include commands present in repo

Key paths to mention (only if present)

• src/, tests/
• appsettings*.json
• Controllers/, Models/, Views/, wwwroot/ FILE:references/elixir.md

Elixir / Erlang

Detection signals

• mix.exs, mix.lock
• config/config.exs
• lib/, test/
• apps/ (umbrella)
• rel/

Multi-module signals

• Umbrella with apps/ containing multiple mix.exs
• Root mix.exs with apps_path

Before generating, analyze these sources

• Root mix.exs, mix.lock
• config/config.exs
• apps/*/mix.exs (umbrella)
• lib/, test/, rel/

Codebase scan (Elixir-specific)

• Source roots: lib/, test/, apps/*/lib (umbrella)
• Phoenix structure (record only if present): lib/*_web/, controllers, views, channels, routers
• Ecto usage (record only if present): schema, Repo, migrations
• Contexts/modules (record only if present): lib/*/ context modules and *_context.ex

Mandatory output (Elixir module CLAUDE.md)

Include these if detected (list actual names found):

• Contexts: list context modules
• Schemas: list Ecto schema modules
• Controllers: list Phoenix controller modules
• Channels: list Phoenix channel modules
• Workers: list background job modules (Oban, etc.)
• Umbrella apps: list apps under umbrella (if any)

Command sources

• README/docs or CI invoking mix
• Repo scripts that call mix
• Only include commands present in repo

Key paths to mention (only if present)

• lib/, test/, config/
• apps/, rel/ FILE:references/flutter.md

Dart / Flutter

Detection signals

• pubspec.yaml, pubspec.lock
• analysis_options.yaml
• lib/
• android/, ios/, web/, macos/, windows/, linux/

Multi-module signals

• melos.yaml (Flutter monorepo)
• Multiple pubspec.yaml under packages/, apps/, or plugins/

Before generating, analyze these sources

• pubspec.yaml, pubspec.lock
• analysis_options.yaml
• melos.yaml (if monorepo)
• lib/, test/, and platform folders (android/, ios/, etc.)

Codebase scan (Flutter-specific)

• Source roots: lib/, test/
• Entry point (record only if present): lib/main.dart
• Layer folders (record only if present): features/, core/, data/, domain/, presentation/
• State management (record only if present): Bloc, Cubit, ChangeNotifier, Provider, Riverpod
• Widget naming (record only if present): *Screen, *Page

Mandatory output (Flutter module CLAUDE.md)

Include these if detected (list actual names found):

• Features: list dirs under features/ or lib/
• Core modules: list dirs under core/ (if present)
• State management: list Bloc/Cubit/Provider setup
• Repositories: list repository classes
• Data sources: list remote/local data source classes
• Widgets: list shared widget directories

Command sources

• README/docs or CI invoking flutter
• Repo scripts that call flutter or dart
• flutter run, flutter test, flutter pub get usage in docs/scripts
• Only include commands present in repo

Key paths to mention (only if present)

• lib/, test/
• android/, ios/ FILE:references/generic.md

Generic / Unknown Stack

Use this reference when no specific stack reference matches.

Detection signals (common patterns)

• README.md, CONTRIBUTING.md
• Makefile, Taskfile.yml, justfile
• Dockerfile, docker-compose.yml
• .env.example, config/
• CI files: .github/workflows/, .gitlab-ci.yml, .circleci/

Before generating, analyze these sources

• README.md - project overview, setup instructions, commands
• Build/package files in root (any recognizable format)
• Makefile, Taskfile.yml, justfile, scripts/ (if present)
• CI/CD configs for build/test commands
• Dockerfile for runtime info

Codebase scan (generic)

• Identify source root: src/, lib/, app/, pkg/, or root
• Layer folders (record only if present): controllers, services, models, handlers, utils, config
• Entry points: main.*, index.*, app.*, server.*
• Test location: tests/, test/, spec/, __tests__/, or co-located

Mandatory output (generic CLAUDE.md)

Include these if detected (list actual names found):

• Entry points: main files, startup scripts
• Source structure: top-level dirs under source root
• Config files: environment, settings, secrets template
• Build system: detected build tool and config location
• Test setup: test framework and run command

Command sources

• README setup/usage sections
• Makefile targets, Taskfile.yml tasks, justfile recipes
• CI workflow steps (build, test, lint)
• scripts/ directory
• Only include commands present in repo

Key paths to mention (only if present)

• Source root and its top-level structure
• Config/environment files
• Test directory
• Documentation location
• Build output directory FILE:references/go.md

Go

Detection signals

• go.mod, go.sum, go.work
• cmd/, internal/
• main.go
• magefile.go
• Taskfile.yml

Multi-module signals

• go.work with multiple module paths
• Multiple go.mod files in subdirs
• apps/ or services/ each with its own go.mod

Before generating, analyze these sources

• go.work, go.mod, go.sum
• cmd/, internal/, pkg/ layout
• Makefile, Taskfile.yml, magefile.go (if present)

Codebase scan (Go-specific)

• Source roots: cmd/, internal/, pkg/, api/
• Layer folders (record only if present): handler, service, repository, store, config
• Framework markers (record only if present): gin, echo, fiber, chi imports
• Entry points (record only if present): cmd/*/main.go, main.go

Mandatory output (Go module CLAUDE.md)

Include these if detected (list actual names found):

• Commands: list binaries under cmd/
• Handlers: list HTTP handler packages
• Services: list service packages
• Repositories: list repository or store packages
• Models: list domain model packages
• Config: list config loading packages

Command sources

• README/docs or CI
• Makefile, Taskfile.yml, or repo scripts invoking Go tools
• go test ./..., go run usage in docs/scripts
• Only include commands present in repo

Key paths to mention (only if present)

• cmd/, internal/, pkg/, api/
• tests/ or *_test.go layout FILE:references/ios.md

iOS (Xcode/Swift)

Detection signals

• Package.swift
• *.xcodeproj or *.xcworkspace
• Podfile, Cartfile
• Project.swift, Tuist/
• fastlane/Fastfile
• *.xcconfig
• Sources/ or Tests/ (SPM layouts)

Multi-module signals

• Multiple targets/projects in *.xcworkspace or *.xcodeproj
• Package.swift with multiple targets/products
• Sources/<TargetName> and Tests/<TargetName> layout
• Project.swift defining multiple targets (Tuist)

Before generating, analyze these sources

• Package.swift (SPM)
• *.xcodeproj/project.pbxproj or *.xcworkspace/contents.xcworkspacedata
• Podfile, Cartfile (if present)
• Project.swift / Tuist/ (if present)
• fastlane/Fastfile (if present)
• Sources/ and Tests/ layout for targets

Codebase scan (iOS-specific)

• Source roots: Sources/, Tests/, ios/ (if present)
• Feature/layer folders (record only if present): Features/, Core/, Services/, Networking/, UI/, Domain/, Data/
• SwiftUI usage (record only if present): @main, App, @State, @StateObject, @ObservedObject, @Environment, @EnvironmentObject, @Binding
• UIKit/lifecycle (record only if present): UIApplicationDelegate, SceneDelegate, UIViewController
• Combine/concurrency (record only if present): @Published, Publisher, AnyCancellable, @MainActor, Task

Mandatory output (iOS module CLAUDE.md)

Include these if detected (list actual names found):

• Features inventory: list dirs under Features/ or feature targets
• Core modules: list dirs under Core/, Services/, Networking/
• Navigation: list coordinators, routers, or SwiftUI navigation files
• DI container: list DI setup (Swinject, Factory, manual containers)
• Network layer: list API clients or networking services
• Persistence: list CoreData models or other storage classes

Command sources

• README/docs or CI invoking Xcode or Swift tooling
• Repo scripts that call Xcode/Swift tools
• xcodebuild, swift build, swift test usage in docs/scripts
• Only include commands present in repo

Key paths to mention (only if present)

• Sources/, Tests/
• fastlane/
• ios/ (React Native or multi-platform repos) FILE:references/java.md

Java / JVM

Detection signals

• pom.xml or build.gradle*
• settings.gradle, gradle.properties
• mvnw, gradlew
• gradle/wrapper/gradle-wrapper.properties
• src/main/java, src/test/java, src/main/kotlin
• src/main/resources/application.yml, src/main/resources/application.properties

Multi-module signals

• settings.gradle* includes multiple modules
• Parent pom.xml with <modules> (packaging pom)
• Multiple build.gradle* or pom.xml files in subdirs

Before generating, analyze these sources

• settings.gradle* and build.gradle* (if Gradle)
• Parent and module pom.xml (if Maven)
• gradle/libs.versions.toml (if present)
• gradle.properties / mvnw / gradlew
• src/main/resources/application.yml|application.properties (if present)

Codebase scan (Java/JVM-specific)

• Source roots: src/main/java, src/main/kotlin, src/test/java, src/test/kotlin
• Package/layer folders (record only if present): controller, service, repository, domain, model, dto, config, client
• Framework annotations (record only if present): @SpringBootApplication, @RestController, @Controller, @Service, @Repository, @Component, @Configuration, @Bean, @Transactional
• Persistence/validation (record only if present): @Entity, @Table, @Id, @OneToMany, @ManyToOne, @Valid, @NotNull
• Entry points (record only if present): *Application classes with main

Mandatory output (Java/JVM module CLAUDE.md)

Include these if detected (list actual names found):

• Controllers: list @RestController or @Controller classes
• Services: list @Service classes
• Repositories: list @Repository classes or JPA interfaces
• Entities: list @Entity classes
• Configuration: list @Configuration classes
• Security: list security config or auth filters
• Profiles: list Spring profiles in use

Command sources

• Maven/Gradle wrapper scripts
• README/docs or CI
• ./mvnw spring-boot:run, ./gradlew bootRun usage in docs/scripts
• Only include commands present in repo

Key paths to mention (only if present)

• src/main/java, src/test/java
• src/main/kotlin, src/test/kotlin
• src/main/resources, src/test/resources
• src/main/java/**/controller, src/main/java/**/service, src/main/java/**/repository FILE:references/node.md

Node Tooling (generic)

Detection signals

• package.json
• package-lock.json, pnpm-lock.yaml, yarn.lock
• .nvmrc, .node-version
• tsconfig.json
• .npmrc, .yarnrc.yml
• next.config.*, nuxt.config.*
• nest-cli.json, svelte.config.*, astro.config.*

Multi-module signals

• pnpm-workspace.yaml, lerna.json, nx.json, turbo.json, rush.json
• Root package.json with workspaces
• Multiple package.json under apps/, packages/

Before generating, analyze these sources

• Root package.json and workspace config (pnpm-workspace.yaml, lerna.json, nx.json, turbo.json, rush.json)
• apps/*/package.json, packages/*/package.json (if monorepo)
• tsconfig.json or jsconfig.json
• Framework config: next.config.*, nuxt.config.*, nest-cli.json, svelte.config.*, astro.config.* (if present)

Codebase scan (Node-specific)

• Source roots: src/, lib/, apps/, packages/
• Folder patterns (record only if present): routes, controllers, services, middlewares, handlers, utils, config, models, schemas
• Framework markers (record only if present): Express (express(), Router), Koa (new Koa()), Fastify (fastify()), Nest (@Controller, @Module, @Injectable)
• Full-stack layouts (record only if present): Next/Nuxt (pages/, app/, server/)

Mandatory output (Node module CLAUDE.md)

Include these if detected (list actual names found):

• Routes/pages: list route files or page components
• Controllers/handlers: list controller or handler files
• Services: list service classes or modules
• Middlewares: list middleware files
• Models/schemas: list data models or validation schemas
• State management: list store setup (Redux, Zustand, etc.)
• API clients: list external API client modules

Command sources

• package.json scripts
• README/docs or CI
• npm|yarn|pnpm script usage in docs/scripts
• Only include commands present in repo

Key paths to mention (only if present)

• src/, lib/
• tests/
• apps/, packages/ (monorepos)
• pages/, app/, server/, api/
• controllers/, services/ FILE:references/php.md

PHP

Detection signals

• composer.json, composer.lock
• public/index.php
• artisan, spark, bin/console (framework entry points)
• phpunit.xml, phpstan.neon, phpstan.neon.dist, psalm.xml
• config/app.php
• routes/web.php, routes/api.php
• config/packages/ (Symfony)
• app/Config/ (CI4)
• ext-phalcon in composer.json (Phalcon)
• phalcon/ide-stubs, phalcon/devtools (Phalcon)

Multi-module signals

• modules/ or app/Modules/ (HMVC style)
• app/Config/Modules.php, app/Config/Autoload.php (CI4)
• Multiple PSR-4 roots in composer.json
• Multiple composer.json under packages/ or apps/
• apps/ with subdirectories containing Module.php or controllers/

Before generating, analyze these sources

• composer.json, composer.lock
• config/ and routes/ (framework configs)
• app/Config/* (CI4)
• modules/ or app/Modules/ (if HMVC)
• phpunit.xml, phpstan.neon*, psalm.xml (if present)
• bin/worker.php, bin/console.php (CLI entry points)

Codebase scan (PHP-specific)

• Source roots: app/, src/, modules/, packages/, apps/
• Laravel structure (record only if present): app/Http/Controllers, app/Models, database/migrations, routes/*.php, resources/views
• Symfony structure (record only if present): src/Controller, src/Entity, config/packages, templates
• CodeIgniter structure (record only if present): app/Controllers, app/Models, app/Views, app/Config/Routes.php, app/Database/Migrations
• Phalcon structure (record only if present): apps/*/controllers/, apps/*/Module.php, models/
• Attributes/annotations (record only if present): #[Route], #[Entity], #[ORM\\Column]

Business module discovery

Scan these paths based on detected framework:

• Laravel: app/Services/, app/Domains/, app/Modules/, packages/
• Symfony: src/ top-level directories
• CodeIgniter: app/Modules/, modules/
• Phalcon: src/, apps/*/
• Generic: src/, lib/

For each path:

• List top 5-10 largest modules by file count
• For each significant module (>5 files), note its purpose if inferable from name
• Identify layered patterns if present: */Repository/, */Service/, */Controller/, */Action/

Module-level CLAUDE.md signals

Scan these paths for significant modules (framework-specific):

• src/ - Symfony, Phalcon, custom frameworks
• app/Services/, app/Domains/ - Laravel domain-driven
• app/Modules/, modules/ - Laravel/CI4 HMVC
• packages/ - Laravel internal packages
• apps/ - Phalcon multi-app

Create <path>/<Module>/CLAUDE.md when:

• Threshold: module has >5 files OR has own README.md
• Skip utility dirs: Helper/, Exception/, Trait/, Contract/, Interface/, Constants/, Support/
• Layered structure not required; provide module info regardless of architecture

Module CLAUDE.md content (max 120 lines)

• Purpose: 1-2 sentence module description
• Structure: list subdirectories (Service/, Repository/, etc.)
• Key classes: main service/manager/action classes
• Dependencies: other modules this depends on (via use statements)
• Entry points: main public interfaces/facades
• Framework-specific: ServiceProvider (Laravel), Module.php (Phalcon/CI4)

Worker/Job detection

• bin/worker.php or similar worker entry points
• */Job/, */Jobs/, */Worker/ directories
• Queue config files (queue.php, rabbitmq.php, amqp.php)
• List job classes if present

API versioning detection

• routes_v*.php or routes/v*/ patterns
• controllers/v*/ directory structure
• Note current/active API version from route files or config

Mandatory output (PHP module CLAUDE.md)

Include these if detected (list actual names found):

• Controllers: list controller directories/classes
• Models: list model/entity classes or directory
• Services: list service classes or directory
• Repositories: list repository classes or directory
• Routes: list route files and versioning pattern
• Migrations: mention migrations dir and file count
• Middleware: list middleware classes
• Views/templates: mention view engine and layout
• Workers/Jobs: list job classes if present
• Business modules: list top modules from detected source paths by size

Command sources

• composer.json scripts
• README/docs or CI
• php artisan, bin/console usage in docs/scripts
• bin/worker.php commands
• Only include commands present in repo

Key paths to mention (only if present)

• app/, src/, apps/
• public/, routes/, config/, database/
• app/Http/, resources/, storage/ (Laravel)
• templates/ (Symfony)
• app/Controllers/, app/Views/ (CI4)
• apps/*/controllers/, models/ (Phalcon)
• tests/, tests/acceptance/, tests/unit/ FILE:references/python.md

Python

Detection signals

• pyproject.toml
• requirements.txt, requirements-dev.txt, Pipfile, poetry.lock
• tox.ini, pytest.ini
• manage.py
• setup.py, setup.cfg
• settings.py, urls.py (Django)

Multi-module signals

• Multiple pyproject.toml/setup.py/setup.cfg in subdirs
• packages/ or apps/ each with its own package config
• Django-style apps/ with multiple apps.py (if present)

Before generating, analyze these sources

• pyproject.toml or setup.py / setup.cfg
• requirements*.txt, Pipfile, poetry.lock
• tox.ini, pytest.ini
• manage.py, settings.py, urls.py (if Django)
• Package roots under src/, app/, packages/ (if present)

Codebase scan (Python-specific)

• Source roots: src/, app/, packages/, tests/
• Folder patterns (record only if present): api, routers, views, services, repositories, models, schemas, utils, config
• Django structure (record only if present): apps.py, models.py, views.py, urls.py, migrations/, settings.py
• FastAPI/Flask markers (record only if present): FastAPI(), APIRouter, @app.get, @router.post, Flask(__name__), Blueprint
• Type model usage (record only if present): pydantic.BaseModel, TypedDict, dataclass

Mandatory output (Python module CLAUDE.md)

Include these if detected (list actual names found):

• Routers/views: list API router or view files
• Services: list service modules
• Models/schemas: list data models (Pydantic, SQLAlchemy, Django)
• Repositories: list repository or DAO modules
• Migrations: mention migrations dir
• Middleware: list middleware classes
• Django apps: list installed apps (if Django)

Command sources

• pyproject.toml tool sections
• README/docs or CI
• Repo scripts invoking Python tools
• python manage.py, pytest, tox usage in docs/scripts
• Only include commands present in repo

Key paths to mention (only if present)

• src/, app/, scripts/
• templates/, static/
• tests/ FILE:references/react-native.md

React Native

Detection signals

• package.json with react-native
• react-native.config.js
• metro.config.js
• ios/, android/
• babel.config.js, app.json, app.config.*
• eas.json, expo in package.json

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)
• react-native.config.js, metro.config.js
• ios/ and android/ native folders
• app.json / app.config.* / eas.json (if Expo)

Codebase scan (React Native-specific)

• Source roots: src/, app/
• Entry points (record only if present): index.js, index.ts, App.tsx
• Native folders (record only if present): ios/, android/
• Navigation/state (record only if present): react-navigation, redux, mobx
• Native module patterns (record only if present): NativeModules, TurboModule

Mandatory output (React Native module CLAUDE.md)

Include these if detected (list actual names found):

• Screens/navigators: list screen components and navigators
• Components: list shared component directories
• Services/API: list API client modules
• State management: list store setup
• Native modules: list custom native modules
• Platform folders: mention ios/ and android/ setup

Command sources

• package.json scripts
• README/docs or CI
• Native build files in ios/ and android/
• expo script usage in docs/scripts (if Expo)
• Only include commands present in repo

Key paths to mention (only if present)

• ios/, android/
• src/, app/ FILE:references/react-web.md

React (Web)

Detection signals

• package.json
• src/, public/
• vite.config.*, next.config.*, webpack.config.*
• tsconfig.json
• turbo.json
• app/ or pages/ (Next.js)

Multi-module signals

• pnpm-workspace.yaml, lerna.json, nx.json, turbo.json
• Root package.json with workspaces
• apps/ and packages/ each with package.json

Before generating, analyze these sources

• Root package.json and workspace config (pnpm-workspace.yaml, lerna.json, nx.json, turbo.json)
• apps/*/package.json, packages/*/package.json (if monorepo)
• vite.config.*, next.config.*, webpack.config.*
• tsconfig.json / jsconfig.json

Codebase scan (React web-specific)

• Source roots: src/, app/, pages/, components/, hooks/, services/
• Folder patterns (record only if present): routes, store, state, api, utils, assets
• Routing markers (record only if present): React Router (Routes, Route), Next (app/, pages/)
• State management (record only if present): redux, zustand, recoil
• Naming conventions (record only if present): hooks use*, components PascalCase

Mandatory output (React web module CLAUDE.md)

Include these if detected (list actual names found):

• Pages/routes: list page components or route files
• Components: list shared component directories
• Hooks: list custom hooks
• Services/API: list API client modules
• State management: list store setup (Redux, Zustand, etc.)
• Utils: list utility modules

Command sources

• package.json scripts
• README/docs or CI
• Only include commands present in repo

Key paths to mention (only if present)

• src/, public/
• app/, pages/, components/
• hooks/, services/
• apps/, packages/ (monorepos) FILE:references/ruby.md

Ruby / Rails

Detection signals

• Gemfile, Gemfile.lock
• Rakefile
• config.ru
• bin/rails or bin/rake
• config/application.rb
• config/routes.rb

Multi-module signals

• Multiple Gemfile or .gemspec files in subdirs
• gems/, packages/, or engines/ with separate gem specs
• Multiple Rails apps under apps/ (each with config/application.rb)

Before generating, analyze these sources

• Gemfile, Gemfile.lock, and any .gemspec
• config/application.rb, config/routes.rb
• Rakefile / bin/rails (if present)
• engines/, gems/, apps/ (if multi-app/engine setup)

Codebase scan (Ruby/Rails-specific)

• Source roots: app/, lib/, engines/, gems/
• Rails layers (record only if present): app/models, app/controllers, app/views, app/jobs, app/services
• Config and initializers (record only if present): config/routes.rb, config/application.rb, config/initializers/
• ActiveRecord/migrations (record only if present): db/migrate, ActiveRecord::Base
• Tests (record only if present): spec/, test/

Mandatory output (Ruby module CLAUDE.md)

Include these if detected (list actual names found):

• Controllers: list controller classes
• Models: list ActiveRecord models
• Services: list service objects
• Jobs: list background job classes
• Routes: summarize key route namespaces
• Migrations: mention db/migrate count
• Engines: list mounted engines (if any)

Command sources

• README/docs or CI invoking bundle, rails, rake
• Rakefile tasks
• bundle exec usage in docs/scripts
• Only include commands present in repo

Key paths to mention (only if present)

• app/, config/, db/
• app/controllers/, app/models/, app/views/
• spec/ or test/ FILE:references/rust.md

Rust

Detection signals

• Cargo.toml, Cargo.lock
• rust-toolchain.toml
• src/main.rs, src/lib.rs
• Workspace members in Cargo.toml, crates/

Multi-module signals

• [workspace] with members in Cargo.toml
• Multiple Cargo.toml under crates/ or apps/

Before generating, analyze these sources

• Root Cargo.toml, Cargo.lock
• rust-toolchain.toml (if present)
• Workspace Cargo.toml in crates/ or apps/
• src/main.rs / src/lib.rs

Codebase scan (Rust-specific)

• Source roots: src/, crates/, tests/, examples/
• Module layout (record only if present): lib.rs, main.rs, mod.rs, src/bin/*
• Serde usage (record only if present): #[derive(Serialize, Deserialize)]
• Async/runtime (record only if present): tokio, async-std
• Web frameworks (record only if present): axum, actix-web, warp

Mandatory output (Rust module CLAUDE.md)

Include these if detected (list actual names found):

• Crates: list workspace crates with purpose
• Binaries: list src/bin/* or [[bin]] targets
• Modules: list top-level mod declarations
• Handlers/routes: list web handler modules (if web app)
• Models: list domain model modules
• Config: list config loading modules

Command sources

• README/docs or CI
• Repo scripts invoking cargo
• cargo test, cargo run usage in docs/scripts
• Only include commands present in repo

Key paths to mention (only if present)

• src/, crates/
• tests/, examples/, benches/