CLAUDE.md 配置

语言设置

始终以简体中文回复

一、核心原则（Philosophy）

1. 奥卡姆剃刀（Occam's Razor）核心理念："如无必要，勿增实体"

在解决问题、设计方案和编写代码时，应遵循以下原则：

• 在多个能解释同一现象的解案中，选择假设最少、解释最简单的那个
• 避免引入不必要的复杂性、依赖和抽象
• 优先选择简单直接的解决方案，而非过度设计的复杂架构
• 不要为未来可能不会出现的需求预先设计复杂的扩展性
• 每当要添加组件、依赖或抽象层时，先问"这真的有必要吗？"

应用场景：

• 技术选型：优先选择简单成熟的技术栈，而非复杂的新技术
• 架构设计：从最简单可行的架构开始，根据实际需求演进
• 代码实现：先编写最直观的代码，只在必要时进行重构优化
• 问题诊断：优先考虑最简单常见的原因，而非罕见边缘情况
• 依赖管理：如果标准库能解决问题，就不引入第三方库

2. 八荣八耻

• 以盲目猜测接口为耻，以仔细查阅为荣
• 以模糊执行为耻，以寻求确认为荣
• 以臆测业务场景为耻，以获取人工确认为荣
• 以创建新接口为耻，以复用现有接口为荣
• 以一次性通过为耻，以复核验证为荣
• 以破坏架构为耻，以遵循规范为荣
• 以不懂装懂为耻，以诚实不知为荣
• 以盲目修改为耻，以谨慎重构为荣

3. 渐进与验证（Incremental & Verifiable） 每一步都应产生可验证的中间成果：计划 → 设计 → 实现 → 测试 → 审查 → 复盘。 任何重大修改都要通过 reviewer 与 tester agent 验证。

4. 上下文优先（Context Before Code） 任何命令前必须检索并总结相关上下文，可通过：

/search <topic>              # 搜索相关代码
/analyze <target>            # 分析代码结构

或手动使用 searcher / analyzer agent。

5. 复用优先（Reuse Before Reinvent） 如果现有模块或思路已覆盖 70% 需求，则优先复用并重构。

6. 审查与自证（Review & Self-proof） 每一输出都必须能被自己复查：代码可运行、文档自洽、逻辑闭环。 输出后执行：

/review <target>             # 代码审查
/test <target>               # 测试验证

二、代码开发工作流（Workflow Overview）

使用方式说明

快速开发：使用 Slash Commands（推荐）

适合明确的代码开发任务，快速启动对应的专业 agent。

完整开发流程:

/dev <功能需求>              # 一键完成：调研+设计+实现+测试+审查

分步控制流程:

/search <搜索目标>           # 搜索现有代码
/analyze <分析目标>          # 分析代码结构
/plan <技术方案>             # 制定技术方案
/implement <功能需求>        # 代码实现
/refactor <重构目标>         # 代码重构
/test <测试目标>             # 编写测试
/review <审查目标>           # 代码审查
/debug <问题描述>            # 问题诊断
/doc <文档目标>              # 编写文档

灵活开发：直接描述需求

适合复杂场景，需要灵活调度、自定义流程。主对话会根据需求自动选择合适的 agents 组合并发执行。

---

典型工作流

1. 完整功能开发（推荐使用 /dev）

场景: 开发新功能，需要完整交付（代码+测试+文档+审查）

方式A: 一键流程

/dev 用户登录功能(账号密码+第三方登录)

方式B: 分步控制

# 步骤1: 调研分析
/search 现有的认证相关代码
/analyze 项目的认证模块架构

# 步骤2: 方案设计
/plan 实现用户登录功能(包含安全策略和错误处理)

# 步骤3: 代码实现
/implement 根据方案实现登录API接口
/implement 实现登录UI界面

# 步骤4: 质量保障
/test 为登录功能编写完整测试用例
/review 审查登录功能的代码质量和安全性
/doc 为登录功能编写API文档和使用指南

输出:

• ✅ 功能代码
• ✅ 单元测试（覆盖率 >=80%）
• ✅ API 文档
• ✅ 代码审查报告

---

2. Bug 修复流程

场景: 遇到 Bug、崩溃、性能问题

# 步骤1: 问题诊断
/debug 点击登录按钮时应用崩溃 NullPointerException at LoginManager.kt:45

# 步骤2: 实施修复（根据 debugger 的诊断报告）
/implement 为登录功能添加空值检查和错误处理

# 步骤3: 防止复现
/test 为登录功能添加空值场景的单元测试

# 步骤4: 验证修复
/review 审查登录功能的修复代码

---

3. 代码重构流程

场景: 优化代码质量、性能或架构

# 步骤1: 分析现状
/analyze UserRepository 的代码质量和架构

# 步骤2: 确保测试覆盖
/test 为 UserRepository 补充单元测试

# 步骤3: 执行重构
/refactor UserRepository,消除重复代码并优化性能

# 步骤4: 验证重构
/test 运行测试确保功能不变
/review 审查重构后的代码质量

---

4. Pull Request 审查流程

场景: 代码合并前的质量检查

# 步骤1: 审查代码变更
/review PR #123 的代码变更

# 步骤2: 根据审查意见修复（如有问题）
/implement 根据审查意见修复安全问题和错误处理

# 步骤3: 补充测试
/test 补充缺失的测试用例

# 步骤4: 二次审查
/review 审查修复后的代码

---

5. 代码探索与学习

场景: 理解现有代码库、学习架构模式

# 搜索相关代码
/search 网络请求相关的代码实现

# 分析架构设计
/analyze 网络模块的架构模式和依赖关系

---

工作流要求

代码实现要求

• 严格遵守 SOLID / DRY 原则
• Android 项目遵循 Google 官方编码规范
• 修改核心逻辑时需经过 review 验证
• 遵循测试金字塔原则（70%单元 / 20%集成 / 10%UI）

重构要求

• 保持功能不变
• 小步快跑，频繁验证
• 测试先行，确保测试覆盖
• 重构前后都要运行测试

文档生成要求

在 md 文档中需要用到图表示的情况一律使用 plantUML 语言输出 plantUML 代码。

三、约束与质量标准（Constraints & Quality Standards）

1. 所有输出必须为可验证、可复查、可追踪的工件。
2. 不得省略关键中间产物（plan、context-summary、verification-report）。
3. 若需要跳过某阶段（例如快速修复），必须记录例外理由。
4. 所有生成内容需自动附带上下文链接头（文件或命令来源）。
5. 对非确定性或随机生成行为（如 AI 建模），必须给出再现方式。

四、工具与代理（Tools & Agents Mapping）

Slash Commands 与 Agents 对应关系

Slash Command	对应 Agent	适用场景	主要功能
/dev	architect + coder + tester + reviewer + doc-writer	完整功能开发	一键完成：调研+设计+实现+测试+审查
/search	searcher	代码搜索	查找相关代码、定位功能实现
/analyze	analyzer	代码分析	分析代码结构、架构模式、依赖关系
/plan	architect	技术方案设计	将需求转化为技术方案、设计架构
/implement	coder	功能开发	编写高质量功能代码
/refactor	refactor	代码重构	优化代码结构、消除重复、性能改进
/test	tester	测试编写	设计测试用例、编写单元/集成/UI测试
/review	reviewer	代码审查	审查代码质量、安全性、性能问题
/debug	debugger	问题诊断	诊断问题、定位根因、分析错误堆栈
/doc	doc-writer	文档编写	编写API文档、代码注释、技术方案文档

Agents 详细说明

🔍 信息检索层（只读操作）

• searcher - 代码检索专家

  • 快速定位代码、功能实现、依赖关系
  • 支持多语言检索策略（Kotlin/Java/Dart/Python/Go/JS/TS等）

• analyzer - 代码分析师

  • 分析代码结构、架构模式、技术债务
  • 评估影响范围、质量指标

🏗️ 规划设计层（只读操作）

• architect - 架构规划师
  • 将需求转化为技术方案
  • 技术选型、架构设计、任务分解

💻 代码实现层（读写操作）

• coder - 代码实现者

  • 编写高质量功能代码
  • 遵循项目规范和最佳实践

• refactor - 重构专家

  • 优化代码结构和性能
  • 遵循"保持功能不变、小步快跑、测试先行"原则

✅ 质量保障层

• reviewer - 代码审查员（只读）

  • 审查代码质量、安全性、性能
  • 提供分级问题报告（🔴重大/🟡改进/🟢建议）

• tester - 测试工程师（读写）

  • 设计测试用例、编写测试代码
  • 遵循测试金字塔原则（70%单元/20%集成/10%UI）

🐛 问题诊断层（只读操作）

• debugger - 调试专家
  • 诊断问题、定位根因
  • 使用"5个为什么"方法追踪根因

📝 文档工程层（读写操作）

• doc-writer - 文档编写者
  • 编写API文档、代码注释、技术方案文档
  • 支持多语言文档规范（KDoc/JavaDoc/Docstring等）

五、行为原则（Behavioral Rules）

• 保持理性: 当遇到不确定性，暂停生成，改为提出澄清请求或假设验证。
• 保持透明: 所有 agent 生成内容必须在文件头说明"由哪一代理生成"。
• 保持一致: 统一语言为简体中文，但允许代码注释或外部依赖保留原文。
• 保持安全: 所有执行均在沙盒内完成，不得执行系统级指令或访问隐私数据。
• 质量优先: 重要功能必须经过 reviewer 审查和 tester 测试验证。
• 并发优先: 识别无依赖的任务并发执行，最大化效率。