AI智能体

【AI智能体】高效使用 Claude Code 之目录详解

讲解如何通过配置.claude目录更高效使用Claude Code为你工作

soragui
· 7 min read
【AI智能体】高效使用 Claude Code 之目录详解
讲解如何通过配置.claude目录更高效使用Claude Code为你工作

很多人把 Claude Code 当"高级自动补全"用，却不知道它藏着一个强大的配置系统。在项目根目录创建 .claude 文件夹，你就能解锁自定义命令、权限控制、记忆系统等一系列高级功能。

本文带你逐一拆解 .claude 目录下的每个配置文件，手把手教你搭建一套高效的 Claude Code 工作环境。

.claude 文件夹是 Claude 在您项目中的控制中心。它存放着您的指令、自定义命令、权限规则，甚至包括 Claude 跨会话的记忆功能。一旦了解其中文件的分布与作用原理，您就能将 Claude Code 配置成完全符合团队需求的工作模式。
本指南将全面解析该文件夹的结构——从日常使用的文件到一次性设置即可长期生效的配置文件。

区分两个 .claude 目录

和大多数配置一样，.claude 也有两个目录。一个是项目下的，一个是用户Home文件夹的目录，知道这两个目录的区分也是很重要的。

用户Home目录里面相关配置相当于全局配置，每个项目都可以使用和加载；这里你就可以存放通用的配置；项目相关的配置可以单独存放再项目目录里面，这样可以更好的方便claude code加载。

1┌─────────────────────────┐         ┌─────────────────────────┐
2│ your-project/.claude/   │◄───────►│      ~/.claude/         │
3│       [项目]            │  same   │         [全局]           │
4│                         │  tool,  │                         │
5│  ├─ settings.json       │different│  ├─ CLAUDE.md           │
6│  ├─ commands/           │ scope   │  ├─ projects/           │
7│  └─ CLAUDE.md           │         │  └─ commands/           │
8│                         │         │                         │
9│  ✅ committed to git    │         │  ❌ never committed     │
10└─────────────────────────┘         └─────────────────────────┘
11
12       两个文件夹，每次会话都会加载
13

CLAUDE.md文件编写规范

当使用claude code进入一个项目文件时，可以使用/init命令来生成一个 claude.md文件，后面在每次使用claude code的时候，都会把文件内容加载到上下文。所以，这个文件不适宜过长，把关于项目最关键、最重要的信息放进去即可。也就是一些大局观整体性的规范和描述。

可写：

  1. 构建、测试和代码检查命令（如 npm run test, make build 等）
  2. 关键架构决策（例如“我们采用 Turborepo 管理的单体仓库模式”）
  3. 易忽略的注意事项（例如“TypeScript 严格模式已启用，未使用变量将报错”）
  4. 导入规范、命名模式、错误处理风格
  5. 核心模块的文件与文件夹结构

不要写：

  1. 应归属于代码检查或格式化工具配置的内容
  2. 已有完整文档可链接的说明性内容
  3. 解释理论的长篇段落

rules/ 文件夹：模块化指令，轻松扩展

通俗来说，rules文件夹是claude.md文件的扩展。里面编写的文件也会加载到上下文中，那为什么不都写到claude.md文件里面呢。你可以理解成claude.md是无条件加载，而rules文件夹里面可以指定规则有条件的加载生效，这也就是模块化指令。

如下示例中指定了 paths 过滤，只有涉及相关路径文件的时候才需要加载这个规则，不难看出这是一个指定如何设计API的规范。

---
paths:
  - "src/api/**/*.ts"
  - "src/handlers/**/*.ts"
---
# API 设计规则

- 所有 handler 返回 { data, error } 格式
- 使用 zod 验证请求体
- 绝不向客户端暴露内部错误详情

commands/ 文件夹：你的自定义斜杠命令

Claude Code 自带一些内置斜杠命令，比如 /help 和 /compact。而 commands/ 文件夹让你能添加自己的命令。.claude/commands/ 的每个 Markdown 文件都会变成一个斜杠命令。

比如 review.md 会生成 /project:review，fix-issue.md 会生成 /project:fix-issue。文件名就是命令名。可以使用 $ARGUMENTS 来传递命令后面的参数。

来看个简单例子。创建 .claude/commands/review.md：

---
description: 在合并前审查当前分支的差异
---
## 待审查的变更

!`git diff --name-only main...HEAD`

## 详细差异

!`git diff main...HEAD`

请审查以上变更，重点关注：
1. 代码质量问题
2. 安全漏洞
3. 缺失的测试覆盖
4. 性能隐患

请按文件给出具体、可操作的反馈。

skills/文件夹：按需调用的可复用工作流

这个应该是claude code很火的原因之一吧，当然其他的AI编码工具也有这个功能。这个和commands很相似，但不同的是命令是自己主动调用的，而skills是通过关键词或流程由claude code自己触发的工作流。代码review、软件编码规范、如何获取使用API接口、如何浏览网页、如何写PPT都可以当成一个技能。

每个技能也是一个单独的文件夹，文件夹下面使用skill.md描述了技能的名称、描述和执行步骤，你还可以编写代码脚本供该技能调用。毫无疑问这个让技能更加强大了。

.claude/skills/
├── security-review/
│   ├── SKILL.md
│   └── DETAILED_GUIDE.md
└── deploy/
    ├── SKILL.md
    └── templates/
        └── release-notes.md

关于如何编写技能，这个以后单独介绍，大家也可以去clawhub上寻找你项目相关和需要的技能。

agents/ 文件夹：专门的子代理角色

你可以在 .claude/agents/ 里定义一个子代理角色。每个 agent 是一个 Markdown 文件，带有自己的系统提示词、工具权限和模型偏好。这个对于我们来说也是一个好消息。因为，不是所有的任务都需要最强模型。有的模型善于编码，要求不那么高的任务可以使用便宜的模型，来节约成本。
来看看 code-reviewer.md 长什么样：

---
name: code-reviewer
description: 资深代码审查专家。在审查 PR、检查 bug 或合并前验证实现时主动使用。
model: sonnet
tools: Read, Grep, Glob
---
你是一位资深代码审查专家，专注于正确性和可维护性。

审查代码时：
- 标记 bug，而不是仅仅关注风格问题
- 给出具体的修复建议，而不是笼统的改进方向
- 检查边界情况和错误处理的遗漏
- 只有在确实影响规模时才指出性能问题

总结

.claude/ 文件夹本质上是一个协议，用来告诉 Claude：你是谁、你的项目是干什么的、它应该遵守哪些规则。你把这些定义得越清楚，花在纠正 Claude 上的时间就越少，它花在帮你干活上的时间就越多。

CLAUDE.md 是你杠杆率最高的文件。先把它搞定。其他都是优化。

从小处着手，边用边改进，把它当成项目中其他基础设施一样对待——一旦设置得当，编码效率必定有所提高。

祝大家编码愉快。