CLAUDE.md 完整配置指南（Android 项目版）

CLAUDE.md 完整配置指南（Android 项目实战版）

一、核心概述

1.1 什么是 CLAUDE.md

CLAUDE.md 是 Claude Code 原生支持的规则配置文件，用于向 AI 明确编码规范、项目架构约束、业务规则、个人开发偏好等内容。它采用多层作用域设计，你可以在不同目录下创建多份 CLAUDE.md，所有层级的内容拼接到一起，离工作目录越近的内容排在越后面，Claude 对其注意力权重越高。

加载机制：工作目录向上到根目录这条祖先链上的 CLAUDE.md 在会话启动时加载。工作目录之下的子目录中的 CLAUDE.md 按需加载——只有 Claude 实际读取该子目录的文件时才会被拉入上下文。

1.2 核心设计原则

• 无数量限制：支持任意目录创建配置文件，但建议克制——维护复杂度随文件数量增长
• 自动继承：子目录自动获得所有祖先目录的规则，无需重复编写
• 就近优先：离工作目录越近的 CLAUDE.md 内容在上下文中排位越靠后，Claude 注意力权重越高（不是硬覆盖，是软优先级）
• 分层加载：祖先链（CWD→根）启动时加载；子目录（CWD 之下）按需加载，只在 Claude 实际读取该目录文件时才进入上下文
• 公私分离：团队公共规则提交到项目仓库，个人私有规则通过 @import 引入本地文件，互不干扰

二、全层级体系与优先级

2.1 层级总览表

优先级从低到高排序（内容拼接顺序：先加载的在前，后加载的在后，越后面注意力权重越高）：

层级	标准路径	生效范围	共享对象	是否提交Git	核心定位
企业/组织级	macOS: /Library/Application Support/ClaudeCode/CLAUDE.md Linux/WSL: /etc/claude-code/CLAUDE.md Windows: C:\Program Files\ClaudeCode\CLAUDE.md （具体路径以企业 IT 实际部署为准）	整机所有用户、所有项目	公司全体员工	否（IT 统一部署）	公司级安全合规、强制编码底线
全局用户级	~/.claude/CLAUDE.md（用户主目录下）	本机所有项目、所有会话	仅本人	否	个人通用开发习惯、全局偏好
项目根级	项目根目录：./CLAUDE.md	整个项目	项目全体成员	是	项目技术栈、架构约束、团队协作规范
模块/子目录级	项目内任意目录，例如 ./app/CLAUDE.md、./src/main/java/com/xxx/login/CLAUDE.md	仅该目录及其子目录下的文件	随目录共享	按需提交	模块专属规则、细分业务约束

个人私有配置方案：通过项目根级 CLAUDE.md 的 @import 语法引入本地私有文件（详见 §5.2），无需在项目内单独创建本地级配置文件。

2.2 各层级详细说明

企业/组织级

由公司 IT/DevOps 统一部署，普通开发者通常无需自行维护。加载顺序最前（最先注入上下文），且不可被用户级设置排除——是保障力度最强的层级。

全局用户级

个人通用配置，一次编写，本机所有项目永久生效。适合存放通用的编码风格、输出习惯、通用工具使用规则，避免每个项目重复编写相同内容。

项目根级

整个项目的「AI 开发说明书」，是所有层级中价值最高的一层。提交到 Git 仓库，团队所有成员拉取代码后自动生效，用于统一项目技术栈、架构约束、命名规范、工作流标准，保障团队 AI 编码风格一致。

注意：官方推荐 ./CLAUDE.md 作为项目根路径。官方文档原文："A project CLAUDE.md can be stored in either ./CLAUDE.md or ./.claude/CLAUDE.md"，两者为替代关系。新项目直接用 ./CLAUDE.md 即可。

模块/子目录级

粒度最灵活的一层，任何目录都可以创建 CLAUDE.md，对其所在目录及其所有子目录下的文件生效，适合存放模块专属的业务规则、资源编写规范等细粒度约束。

Android 场景下，建议在 app/、common/ 级别和核心业务包配置即可。

三、Android 项目完整分层配置示例

以下为从全局到细粒度的全套可直接套用的配置模板，覆盖 Android 开发全场景。

3.1 全局用户级

路径：~/.claude/CLAUDE.md

# 全局 Android 开发个人偏好
## 通用语言规则
- 默认使用 Kotlin 编写代码，Java 仅用于兼容历史遗留文件
- 代码注释统一用中文，变量、类、函数名统一用英文
- 优先使用不可变（val）、纯函数，尽量减少副作用
- 所有公开类、公开方法必须加 KDoc 注释
## 编码风格
- 缩进统一 4 空格，不使用 Tab
- 每行最大长度 120 字符，超长自动换行
- 命名遵循 Android 官方驼峰规范：类大驼峰，变量/函数小驼峰，常量全大写下划线分隔
## 输出习惯
- 分析问题先给结论，再给原因和修复方案
- 写代码优先给出完整可运行的代码块，再补充关键点说明
- 涉及性能、内存、安全风险的地方必须高亮标注
## 工具使用默认规则
- 重构代码前先给出改动影响范围说明
- 执行 Gradle 命令前先确认当前项目目录
- 涉及删除文件、修改核心架构的操作，必须先二次确认

3.2 项目根级

路径：./CLAUDE.md

# 项目：XX 电商客户端 Android
## 技术栈
- 开发语言：Kotlin 2.0
- 最低兼容：Android 7.0 (API 24)
- 目标版本：Android 14 (API 34)
- UI 框架：Jetpack Compose + Material Design 3
- 架构模式：MVVM + 单向数据流
- 依赖注入：Hilt（Application 类加 `@HiltAndroidApp`，ViewModel 用 `@HiltViewModel` 注解）
- 网络请求：Retrofit + OkHttp + Kotlin Coroutine
- 本地存储：Room + DataStore
- 构建工具：Gradle 8.7 + Gradle Kotlin DSL
## 架构约束
1. 严格分层：UI 层 → ViewModel 层 → 领域层 → 数据层，禁止跨层直接调用
2. ViewModel 禁止持有任何 Context 引用，禁止直接操作 View
3. 数据层统一通过 Repository 对外暴露，禁止业务层直接访问 DAO / 网络接口
4. 所有异步操作必须使用协程，禁止直接创建线程
5. 第三方库必须经过评估后才能引入，禁止随意添加依赖
## 命名规范
- Activity 后缀：XXXActivity
- Fragment 后缀：XXXFragment
- ViewModel 后缀：XXXViewModel
- Repository 后缀：XXXRepository
- 资源文件：模块前缀_功能描述，例如 `home_item_product.xml`
- Compose 可组合函数：大驼峰命名，无后缀
## 工作流约定
- 新功能从 develop 分支切出 feature/xxx 分支
- 提交信息格式：`类型(模块): 描述`，例如 `feat(home): 新增商品卡片`，类型包括 feat/fix/refactor/docs/test/chore，模块为 app/common/login 等
- 合并代码前必须通过单元测试和 Lint 检查
- 核心业务代码必须配套单元测试
## 安全红线
- 禁止硬编码密钥、Token、接口地址，统一放到 BuildConfig 或本地 properties
- 用户敏感信息必须加密存储（推荐 AndroidKeyStore 管理加密密钥，避免密钥硬编码），禁止明文写入 SP / 数据库
- WebView 必须开启安全配置，禁止加载未知来源页面
- Release 包必须开启混淆和资源压缩

## 个人私有配置（本地生效，不提交仓库）
@~/.claude/android-project-local-config.md

3.3 模块级

3.3.1 app 主模块

路径：./app/CLAUDE.md

# app 主模块规则
## 页面路由
- 所有页面跳转统一使用 Navigation Compose，禁止直接使用 Intent 跳转
- 路由地址统一定义在 `navigation/Routes.kt` 中，禁止硬编码字符串
- 页面传参使用 Parcelable 序列化，禁止传递大数据对象
## 业务约定
- 首页、商品页、购物车、个人中心四大模块，每个模块独立包目录
- 每个页面必须单独的 ViewModel，禁止跨页面共享 ViewModel
- 埋点统一通过埋点 SDK 调用，禁止业务代码直接写埋点逻辑
## UI 规范
- 统一使用项目主题色，禁止硬编码颜色值
- 页面间距使用统一维度常量，定义在 `theme/Dimens.kt`
- 列表统一使用 LazyColumn / LazyRow；ScrollableColumn 是 Compose 早期 API 已被废弃，不要使用

3.3.2 common 公共基础模块

路径：./common/CLAUDE.md

# common 基础模块规则
## 核心原则
- 本模块只能放通用能力，禁止包含任何业务逻辑
- 禁止依赖 app 模块，只能被上层模块依赖
- 对外暴露的 API 必须稳定，修改必须向下兼容
## 包含范围
- 通用工具类（扩展函数、日期、格式化、加密）
- 通用 UI 组件（自定义按钮、标题栏、加载态、空态）
- 网络基础封装、全局异常捕获、日志工具
- 核心基类（BaseViewModel、BaseRepository）

3.4 业务包级（src 目录下）

路径：./app/src/main/java/com/你的包名/login/CLAUDE.md

# 登录模块专属规则
## 业务硬约束
1. 所有密码传输必须使用 RSA 公钥加密，禁止明文上传
2. 短信验证码有效期60秒，倒计时期间禁止重复请求发送接口
3. 登录成功必须同步刷新 Token
4. 所有登录方式（手机号/微信/Apple）必须走统一 LoginManager 入口，禁止各自实现登录逻辑
## 安全红线
- 禁止明文存储密码、验证码到 SP / DataStore
- Token 必须加密存储，禁止日志打印完整 Token 内容
- 登录错误码统一封装后再抛给 UI 层，禁止直接透传服务端原始错误码

3.5 资源目录级（可选，不推荐大多数项目使用）

注意：资源目录的 CLAUDE.md 按需加载，不操作该目录就不会进入上下文。但即便如此，资源规范建议直接写在项目根级 CLAUDE.md 中，减少文件维护负担。以下示例仅供确实需要严格管控资源规范的大型团队参考。

路径：./app/src/main/res/CLAUDE.md（合并 layout / values / drawable 规则）

# Android 资源文件编写规范
## layout 布局
1. 尺寸单位：边距/大小统一用 dp，字体统一用 sp，禁止使用 px
2. 颜色/文案：禁止硬编码，统一引用 @color/xxx、@string/xxx 主题资源
3. 控件 ID 命名：`模块_控件类型_功能`，例如 `login_btn_submit`、`home_iv_banner`
4. 传统 View 体系列表用 RecyclerView，Compose 场景用 LazyColumn/LazyRow；复杂布局优先用 ConstraintLayout 减少层级
## values 配置
1. 颜色按功能命名（`color_primary`），禁止按色值命名（`color_blue_300`）
2. 尺寸统一 `dp_数值` 命名（`dp_16`），禁止重复定义相同数值
3. 字符串按页面+功能命名（`login_btn_submit`），禁止重名
4. 新增中文文案必须同步更新 values-en 多语言条目
## drawable 图形
1. 背景 shape：`bg_形状_场景`（`bg_corner_8_white`），状态 selector：`selector_控件_场景`
2. 图标：`ic_功能_颜色`（`ic_back_white`），优先用 vector 矢量图
3. 简单圆角/渐变优先用 XML 实现，不用切图

3.6 文档目录级

路径：./docs/CLAUDE.md

# 文档写作规范
## 格式要求
- 所有文档使用 Markdown 编写
- 标题层级清晰，一级标题一个，二级标题按模块划分
- 代码块必须标注语言类型
- 接口文档必须包含：请求地址、请求方式、入参、出参、错误码说明
## 术语统一
- 统一使用「页面」而非「界面」
- 统一使用「接口」而非「API」
- 专业术语保留英文：ViewModel、Repository、Compose、Coroutine

3.7 个人本地私有配置示例（存放于用户目录，不提交仓库）

路径：~/.claude/android-project-local-config.md

# 本地私有配置
## 本地环境
- 开发测试接口地址：http://192.168.3.12:8080/api
- 本地调试账号：test_user / 123456
- 打包签名文件路径：~/keystore/debug.keystore
## 个人习惯
- 写代码时默认附带日志打印，方便本地调试
- 调试问题时优先输出 Logcat 过滤命令

四、核心运行规则

4.1 内容拼接与继承

所有 CLAUDE.md 的内容被拼接（concatenate）到一起注入上下文。Claude Code 实际是从 CWD 向上遍历收集各目录文件，再与全局/企业级合并拼接，上下文中最终的等效顺序为：企业级 → 全局用户级 → 从文件系统根到 CWD 各目录的 CLAUDE.md。后面的内容排位更靠后，注意力权重越高。

举例——CWD 在 foo/bar/ 时的上下文等效拼接顺序：

企业级 → 全局用户级 → foo/CLAUDE.md → foo/bar/CLAUDE.md

子目录会自动获得所有祖先目录的规则（因为祖先链上的文件已经在上下文中了），只需编写差异化的补充或覆盖内容。

4.2 就近优先（软优先级）

不是硬覆盖，是软优先级——离工作目录越近的 CLAUDE.md 内容在上下文中出现越晚，Claude 对其注意力更高。

底层机制：CLAUDE.md 内容作为 user message 注入（不是 system prompt 的一部分），所以它是指令上下文而非强制配置。这也解释了为什么"不保证 100% 遵循"——Claude 将其视为用户说明，而非系统级约束。

如果两条规则字面矛盾，Claude 多数情况下会跟随靠后的那条，但不保证 100%。提升遵循度的技巧：在下层规则中明确标注「覆盖上层规则：XXX」，让 Claude 明确意识到这是一条有意覆盖的指令。官方建议定期审查删除过期/冲突的指令。

4.3 加载机制

祖先链加载（启动时） ：工作目录向上到文件系统根目录这条路径上的所有 CLAUDE.md 在会话启动时一次性加载。这包括企业级、全局用户级、项目根级，以及从项目根到当前工作目录途径的各子目录级。

子目录按需加载（运行时） ：工作目录之下的子目录中的 CLAUDE.md 不会在启动时加载。只有当 Claude 实际读取该子目录中的文件时，对应的 CLAUDE.md 才会被拉入上下文。

/compact 命令影响：执行 /compact 后，项目根级 CLAUDE.md 会从磁盘自动重新读取；子目录级 CLAUDE.md 需等待下次读取该目录文件时才会重新加载。

4.4 生效范围判定

排除机制：大型 monorepo 场景下，可在 .claude/settings.json 中配置 claudeMdExcludes 字段跳过其他团队的子目录 CLAUDE.md（企业级 Managed Policy 不可被排除）。

CLAUDE.md 对其所在目录及其所有子目录下的文件均生效，仅作用于目录级，不直接支持针对单个文件单独配置。如需文件级别的精确控制，可使用 .claude/rules/ 的 paths 字段按 glob 模式匹配特定文件（见 §5.1）。如果只是临时需要，在对话中直接说明即可。

五、补充机制

5.1 .claude/rules/ 目录（路径门控规则）

官方推荐的细粒度规则方案。在 .claude/rules/ 目录下创建 .md 文件，通过 YAML frontmatter 的 paths 字段按 glob 模式匹配目标文件——只有操作匹配的文件时才加载，比散落子目录 CLAUDE.md 更可控、更透明。

---
paths:
  - "src/api/**/*.ts"
---
# API 层规则
- 所有接口调用必须带超时设置
- 错误响应统一通过 ErrorHandler 处理

• 文件命名建议：无强制要求（需 .md 后缀），官方推荐按功能/模块命名（如 api-rules.md、testing.md、ui-rules.md），提升可维护性。
• 用户级 rules：~/.claude/rules/ 目录同样支持，适用于所有项目，加载在项目级 rules 之前（项目 rules 优先级更高）。
• 注意：没有 paths frontmatter 的 rules 文件会在启动时无条件加载，优先级等同于项目根级 CLAUDE.md。如果不想规则常驻上下文，务必加上 paths 字段。

5.2 @import 语法

官方支持通过 @path/to/file 语法导入外部文件内容，是个人私有配置的官方推荐方案，完美适配多 Git worktree 场景。

核心规则：

• 递归深度：最多 4 层递归
• 加载时机：导入的文件在会话启动时全量加载（非懒加载），需控制导入文件大小
• 典型用途：引入个人本地私有配置，替代已弃用的项目本地级文件，实现单文件维护、多项目共享

示例：

# 在项目根级 CLAUDE.md 中
@~/.claude/my-shared-android-config.md

5.3 Auto Memory

Claude Code 会自动在 ~/.claude/projects/<project>/memory/ 下积累跨会话的知识（<project> 路径从 git 仓库推导）。用户角色、项目背景、工作偏好等关键信息由 Claude 自动写入，不需手动维护。

版本要求：Auto Memory 需要 Claude Code v2.1.59 或更高版本。 加载限制：MEMORY.md 的加载上限数值可能随版本调整，请以 claude --version 对应的官方文档为准。超出加载范围的内容不会被注入上下文，需定期清理过期或不再相关的记忆条目。

5.4 AGENTS.md 互操作

Claude Code 读 CLAUDE.md，不读 AGENTS.md（AGENTS.md 是 Codex/Cursor 等工具的标准）。如果团队同时使用多种 AI 编码工具，有两种桥接方案：

• 符号链接：ln -s AGENTS.md CLAUDE.md，以 AGENTS.md 为单一维护源，Claude Code 通过 CLAUDE.md symlink 读取
• @ 导入：在 CLAUDE.md 中添加 @AGENTS.md，无需文件系统特性

两种方式都能实现单文件维护、多工具共享，推荐 @ 导入（更透明）。

六、最佳实践与常见误区

6.1 最佳实践

1. 给人看的备注用 HTML 注释：CLAUDE.md 中的 <!-- 块级 HTML 注释 --> 在注入上下文前会被剥离。适合写给维护者看的说明和内部标注。
2. 粒度分层合理：通用规则往上放，差异化规则往下放；推荐核心层级：全局→项目根→大模块（如 app/common），最多到核心业务包。
3. 公私严格分离：团队公共规则放根级并提交 Git，个人私有内容通过 @import 引入本地文件，禁止把密钥、本地路径等隐私信息提交到公共仓库。
4. 控制祖先链文件长度：项目根级 CLAUDE.md 每个会话都加载，官方建议目标 < 200 行；子目录级文件按需加载，要注意维护复杂度。
5. 避免内容冗余：上层已有的规则，下层无需重复编写，只写补充和覆盖项。
6. 优先用 .claude/rules/：官方推荐的路径门控方案，通过 YAML frontmatter 的 paths 字段按 glob 模式匹配文件，比散落子目录 CLAUDE.md 更可控、更透明。
7. 善用 @import：个人私有配置统一用 @import 引入本地共享文件，不要在项目内创建本地级配置文件。

6.2 常见误区

1. ❌ 误区：CLAUDE.md 只能有 1 个
   ✅ 正确：支持多层目录、多个文件协同生效
2. ❌ 误区：子目录配置会替换（覆盖）全部上层规则
   ✅ 正确：所有层级内容拼接在一起，不是硬覆盖。离 CWD 越近的内容排位越靠后，是注意力更高的软优先级。
3. ❌ 误区：个人本地配置要提交到 Git
   ✅ 正确：私有配置通过 @import 放在用户主目录，仅本机生效，提交后会污染团队配置。
4. ❌ 误区：所有规则只能放在 CLAUDE.md 里
   ✅ 正确：官方还提供了 .claude/rules/ 目录（支持 paths 字段按 glob 匹配特定文件）和 @import 语法导入外部文件，比散落 CLAUDE.md 更灵活可控。