wwsun CLAUDE.md 管理指南
核心原则
少即是多
- 控制指令数量：前沿 LLM 能可靠遵循约 150-200 条指令，Claude Code 系统提示已占用约 50 条
- 长度限制：根目录 CLAUDE.md 建议 < 300 行，越短越好（参考：HumanLayer 仅 60 行）
- 通用性优先：只包含每个会话都需要的信息，避免任务特定内容
三要素内容
| 类型 | 描述 | 示例 |
|---|---|---|
| WHAT | 技术栈、项目结构 | 框架版本、目录布局、包管理器 |
| WHY | 项目目的、设计决策 | 业务背景、架构选择原因 |
| HOW | 开发流程、验证方式 | 构建命令、测试步骤、部署流程 |
渐进式披露
将详细文档拆分到独立文件：
agent_docs/
├── building.md # 构建指南
├── testing.md # 测试规范
├── code_conventions.md # 代码规范
└── architecture.md # 架构说明
在 CLAUDE.md 中引用：
## 扩展文档
需要时参阅：
- `agent_docs/building.md` - 构建和部署
- `agent_docs/testing.md` - 测试相关
避免的反模式
- 不要用作 linter：代码风格用 ESLint/Prettier 处理
- 不要自动生成：
/init产出仅供参考，需手工精炼 - 不要堆砌命令：只保留最常用的关键命令
- 不要放代码片段：易过时，改用文件引用
file:///path#L10-20
模板
# 项目名
简短的项目描述。
## 常用命令
- `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 文件。