CLAUDE.md 管理指南
核心原则
少即是多
- •控制指令数量：前沿 LLM 能可靠遵循约 150-200 条指令，Claude Code 系统提示已占用约 50 条
- •长度限制：根目录 CLAUDE.md 建议 < 300 行，越短越好（参考：HumanLayer 仅 60 行）
- •通用性优先：只包含每个会话都需要的信息，避免任务特定内容
三要素内容
| 类型 | 描述 | 示例 |
|---|---|---|
| WHAT | 技术栈、项目结构 | 框架版本、目录布局、包管理器 |
| WHY | 项目目的、设计决策 | 业务背景、架构选择原因 |
| HOW | 开发流程、验证方式 | 构建命令、测试步骤、部署流程 |
渐进式披露
将详细文档拆分到独立文件：
code
agent_docs/ ├── building.md # 构建指南 ├── testing.md # 测试规范 ├── code_conventions.md # 代码规范 └── architecture.md # 架构说明
在 CLAUDE.md 中引用：
markdown
## 扩展文档 需要时参阅： - `agent_docs/building.md` - 构建和部署 - `agent_docs/testing.md` - 测试相关
避免的反模式
- •不要用作 linter：代码风格用 ESLint/Prettier 处理
- •不要自动生成：
/init产出仅供参考，需手工精炼 - •不要堆砌命令：只保留最常用的关键命令
- •不要放代码片段：易过时，改用文件引用
file:///path#L10-20
模板
markdown
# 项目名 简短的项目描述。 ## 常用命令 - `pnpm dev` - 开发服务器 - `pnpm build` - 生产构建 - `pnpm test` - 运行测试 ## 代码规范 - ES 模块语法 (import/export) - 解构导入 - TypeScript 严格模式 ## 工作流程 - 修改代码后运行 typecheck - 提交前确保测试通过 ## 扩展文档 详细信息见 `agent_docs/` 目录。
文件位置层级
| 位置 | 范围 | 用途 |
|---|---|---|
~/.claude/CLAUDE.md | 全局 | 个人通用偏好 |
项目根/CLAUDE.md | 项目 | 团队共享配置（提交到 git） |
项目根/CLAUDE.local.md | 项目 | 个人本地配置（gitignore） |
子目录/CLAUDE.md | 模块 | 特定模块上下文 |
工作流程
- •评估现状：检查是否存在 CLAUDE.md
- •收集需求：了解用户需要记录什么
- •分类内容：区分通用 vs 任务特定信息
- •精简表达：用最少的文字传达清楚
- •迭代优化：鼓励用户使用
#快捷键实时补充规则
使用 # 快捷键
在 Claude Code 中按 # 键可快速添加指令到 CLAUDE.md：
Claude 会自动将此添加到对应的 CLAUDE.md 文件。