Appearance
Claude Code项目结构最佳实践：5条绕不过去的底层原则
Claude Code最擅长的不是"猜你的心思"，而是在明确上下文里把事情做得又快又准。项目结构这件事，真的不是随便放放就行。
原则一：CLAUDE.md 放在根目录
CLAUDE.md不是可有可无的说明文件。它是项目级上下文入口，是给Claude Code的入职手册。Claude启动时会自动读取根目录的CLAUDE.md。
应包含的内容
| 章节 | 内容示例 |
|---|---|
| Project Overview | 项目简短介绍 |
| Architecture | 主要模块与核心架构说明 |
| Tech Stack | Next.js + TypeScript + ShadCN UI + Tailwind |
| Coding Conventions | TypeScript strict mode，函数组件，避免default export |
| Folder Structure | 目录结构说明 |
| Commands | npm run dev / npm run build |
| Important Rules | 性能要求、无障碍要求、测试策略 |
目录结构示例
my-project/
├── CLAUDE.md
├── package.json
├── src/
├── docs/
└── scripts/每当你让Claude进入项目，它不需要重新猜"这个仓库到底在干嘛"。关键背景已经说清楚了。
已有项目不用手写：/init
如果你的项目已存在代码基础，直接在Claude Code里使用 /init 命令，它会先帮你生成一版CLAUDE.md初稿。
bash
/init你要做的不是从零苦哈哈地写，而是去补充、修正、压实。CLAUDE.md写得含糊，后面的上下文就会一路含糊。
原则二：.claude/rules 做局部配置
CLAUDE.md是项目级，.claude/rules是局部配置。
| 对比 | CLAUDE.md | .claude/rules |
|---|---|---|
| 作用域 | 整个项目 | 特定目录或文件 |
| 语法 | Markdown | 纯文本 |
| 自动加载 | 是，根目录自动读取 | 否，基于当前目录向上查找 |
| 优先级 | 全局通用规则 | 局部精确覆盖 |
rules配置方式
bash
# 在项目根目录创建
mkdir -p .claude/rules在子目录里放rules文件，Claude进入该目录时会自动应用这些规则。适合：
- 不同模块有不同编码规范
- 某个目录有特殊约束
- 团队协作时的分工说明
重要规则
| 规则 | 说明 |
|---|---|
| rules文件名 | 必须带 .md 后缀 |
| 目录层级 | 按需放置，Claude自动向上查找 |
| 不要重复造轮子 | CLAUDE.md里写过的，不用在rules里再写一遍 |
原则三：Skills 统一管理
Skills是与Claude Code配合使用的功能模块，把工具、脚本、方法论打包复用。
my-project/
├── skills/
│ ├── database-schema/
│ ├── test-generator/
│ └── deployment-check/Skills的优势
| 特点 | 说明 |
|---|---|
| 模块化 | 每个Skill独立管理，便于复用 |
| 版本控制 | Skill可纳入Git管理 |
| 团队共享 | 写好一个Skill，团队都能用 |
| 方法论沉淀 | 把经验转化为可执行的流程 |
Skills禁止做的事
| ❌ 禁止 | 说明 |
|---|---|
| 不要提技术栈 | Skill应该跟项目无关 |
| 不要提目录结构 | Skill应该通用 |
| 不要加项目特定的命令 | 保持可移植性 |
原则四：保持平面目录结构
| 问题 | 解决方案 |
|---|---|
| 嵌套过深的目录 | 扁平化，最多3层 |
| 目录命名不一致 | 统一规范，统一风格 |
| 多个同类型目录 | 合并或明确区分 |
推荐结构
src/
├── components/ # UI组件
├── pages/ # 页面
├── hooks/ # 自定义hooks
├── utils/ # 工具函数
└── types/ # 类型定义原则五：CLAUDE.md和rules的合理拆分
| 场景 | 放在CLAUDE.md | 放在.claude/rules |
|---|---|---|
| 项目介绍、技术栈 | ✅ | ❌ |
| 全局编码规范 | ✅ | ❌ |
| 模块特定规范 | ❌ | ✅ |
| 目录约束 | ❌ | ✅ |
| 团队工作流 | ✅ | 可按需补充 |
常见错误
| ❌ 错误做法 | ✅ 正确做法 |
|---|---|
| CLAUDE.md写500行 | CLAUDE.md精简到核心，细节放rules |
| 所有规则堆在根目录 | 按模块分散到对应目录 |
| CLAUDE.md和rules内容重复 | 明确拆分职责，不重复 |
总结
| 原则 | 一句话 |
|---|---|
| CLAUDE.md放根目录 | 项目级上下文入口 |
| .claude/rules局部配置 | 模块级精确覆盖 |
| Skills统一管理 | 工具方法论模块化 |
| 平面目录 | 嵌套不超过3层 |
| 合理拆分 | CLAUDE.md管全局，rules管局部 |
把项目结构整理好了，Claude Code才能真正从"磨合"变成"顺手"。
关键词：Claude Code, 项目结构, CLAUDE.md, Claude Rules, Skills, 最佳实践, 编码规范
