姜姜姜的blog

CLAUDE.md 优化

7分钟阅读

claude version: 2.1.133 · #meta

Info

本文参考: https://claudefa.st/blog/guide/mechanics/claude-md-mastery

大多数关于 Claude.md 的指导都存在误解, 常见的建议是将 claude.md 视为项目文档 --- 一个描述技术栈, 列出命令和解释目录结构的地方. 这种方法存在的问题:

  1. 优先级饱和: claude.md 的内容在 Claude 的上下文窗口中享有极高的优先级. 当你把所有内容都塞进一个文件中时, 它们会争夺这种高优先级, 处处高优先级意味着处处没有优先级

  2. 上下文浪费: 如果你的 claude.md 描述了 react 项目的 react 设计模式, 则该上下文会在每个会话中加载 --- 即使你正在处理数据库迁移或部署脚本

  3. 没有行为控制: 列出技术栈并不能告诉 claude 如何解决问题、何时委派任务或如何管理复杂的多步骤工作

  4. 项目间的重复: 每个新项目都需要一个新的 claude.md 来解释类似的模式, 导致 AI在你的工作中行为不一致

  5. 静态知识: 项目文档会过时.

更优方案: 编排层

claude.md 应该定义:

  1. 操作流程: cluade 处理每个请求所遵循的步骤
  2. 上下文管理策略: 如何有效保存和分配上下文
  3. 委托模式: 何时使用子代理, 何时直接处理
  4. 质量标准: 编码规范、错误处理、安全要求
  5. 协调协议: 如何管理并行工作与串行工作

项目相关的知识 — 例如: 技术栈, 模式和约定 存储在 skills 中, 这些 skill 会在需要时按需加载. 这种分离模式有如下好处:

  • 所有项目中AI行为一致
  • 高效的上下文利用 — 按需加载
  • 可移植的专业知识 — 项目间 skills 可共享
  • 可维护的知识 — 只需要更新一次 skill, 即可终身受益

构建你的claude.md

核心原则部分

明确希望 AI 具备的基本行为, 无论进行什么项目或任务, 这些基本行为都普遍适用

## 核心原则
 
### 以 skill 为优先的工作流
 
**每个用户请求都遵循以下顺序：**
 
请求 → 加载 skill → 收集上下文 → 执行
 
skill 包含基础上下文中不包含的关键工作流和协议。
 
优先加载 skill 可避免遗漏关键指令。
 
### 上下文管理策略
 
**中央 AI 应节约上下文资源以扩展预压缩处理能力**：
 
- 将文件探索和低复杂度任务委托给子代理
 
- 保留上下文资源用于协调、用户沟通及战略决策
 
- 对于范围明确的简单任务：跳过繁重的协调过程，直接执行
 
**子代理应最大限度地收集上下文**：
 
- 子代理的上下文窗口是临时性的
 
- 执行后，未使用的容量即意味着错失机会
 
- 指示子代理读取所有相关文件、加载技能并收集示例

路由和委托逻辑

明确 claude 何时应该直接处理工作, 何时应该委派给专家. 确保 claude 能够就工作分配做出明智的决定, 而不是事事亲力亲为或不必要地委派任务

### 路由决策
 
**直接执行**：
 
- 范围明确的简单/有限任务
 
- 单组件变更
 
- 快速修复和微小修改
 
**子代理委托**：
 
- 复杂/多阶段的实现
 
- 需要专业领域知识的任务
 
- 受益于隔离上下文的工作
 
**主协调器**：
 
- 需要调研的模糊需求
 
- 影响广泛的架构决策
 
- 需要会话管理的多日功能开发

编码标准

## 编码最佳实践
 
**优先级顺序**（当需要权衡取舍时）：
 
正确性 > 可维护性 > 性能 > 简洁性
 
### 任务复杂度评估
 
开始之前，先进行分类：
 
- **简单**（单个文件，显而易见的修复）→ 直接执行
 
- **中等**（2-5 个文件，范围明确）→ 简要规划后执行
 
- **复杂**（影响架构，需求模糊）→ 先进行全面调研
 
工作量应与复杂度相匹配。不要对简单任务过度设计，也不要对复杂任务规划不足。
 
### 集成安全性
 
在修改任何功能之前：
 
- 通过代码库搜索识别所有下游调用者
 
- 针对所有调用者验证更改
 
- 测试集成点以防止功能中断

从附加目录加载 claude.md

从 claude code v2.1.20 开始, 你可以通过 —add-dir 从当前项目之外的目录加载 claude.md. 这对于单体仓库, 共享团队标准或多项目工作流程尤为有用

案例:

company/
├── shared-standards/
│   └── CLAUDE.md          # Company coding guidelines
├── apps/
│   ├── web/
│   │   └── CLAUDE.md      # Web-specific rules
│   └── api/
│       └── CLAUDE.md      # API-specific rules

在 web/ 目录中, 挂载 shared-standards/ 目录

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../../shared-standards
  • 跨项目一致性: 将你的个人开发标准保存在一个中心位置, 并将其加载到任何项目汇总, 而无需复制文件
  • 团队入职: 新成员可以指向包含团队约定的共享目录, 从而消除 “每个鲜蘑菇都有略微不同的 claude.md” 的问题

关系图谱