你用 Claude Code 多久了？大概率用过 .claude/ 文件夹，但从没真正打开过看看。

这很正常。大多数人只知道它存在，没想过里面藏着什么。但这个文件夹，其实是整个 Claude Code 的控制中心——你的指令、自定义命令、权限规则，还有跨对话的记忆，全在这里。

一旦搞懂它的结构，你就能让 Claude Code 完全按照你的方式工作。

.claude/ 不是一个文件夹，是两个

先把一个容易忽略的事情说清楚：.claude/ 目录有两个，不是一个。

项目级： 放在你的项目根目录，跟着 git 提交。整个团队共享同一套规则、命令和权限策略。

全局级： 放在 ~/.claude/，只属于你自己。这里存的是个人偏好和机器本地状态，比如会话历史、自动记忆。

团队配置放项目，个人偏好放全局。这个分层设计让多人协作变得很清晰。

CLAUDE.md：Claude 的说明书

这是整个系统里最重要的文件，没有之一。

每次启动 Claude Code 会话，它第一件事就是读 CLAUDE.md，直接加载到系统提示里，整个对话过程都保持在上下文里。

你写什么，Claude 就遵守什么。

告诉它"写代码前先写测试"，它每次都会先写测试。说"错误处理统一用自定义 logger 模块，不用 console.log"，它会记住整个会话里的每一行代码。

这不是魔法，就是上下文注入——但用好了威力很大。

一个好用的 CLAUDE.md 应该写什么？

# Project: Acme API

## Commands
npm run dev          # 启动开发服务器
npm run test         # 运行测试（Jest）
npm run lint         # ESLint + Prettier 检查
npm run build        # 生产构建

## Architecture
- Express REST API, Node 20
- PostgreSQL via Prisma ORM
- 所有 handler 在 src/handlers/
- 共享类型在 src/types/

## Conventions
- 每个 handler 用 zod 做请求参数验证
- 返回格式统一 { data, error }
- 不向客户端暴露 stack trace
- 用 logger 模块，不用 console.log

## 注意事项
- 测试跑真实本地 DB，不是 mock。先 `npm run db:test:reset`
- TypeScript 严格模式：不允许未使用的 import

大概 20 行。给了 Claude 工作所需的全部上下文，不用每次都重复解释。

有个经验值得记住：CLAUDE.md 控制在 200 行以内。 超过这个长度，Claude 对指令的遵守度会明显下降——上下文太长，注意力稀释了。

什么不该写进去

• 应该放到 linter/formatter 配置里的规则
• 随便就能链接过去的完整文档
• 解释技术原理的长篇大论

指令文件就是指令，越精炼越好用。

CLAUDE.local.md：你自己的覆盖层

有些偏好只属于你，不适合提交给整个团队。在项目根目录创建 CLAUDE.local.md，Claude 会同时读取它和主 CLAUDE.md，而且这个文件自动被 gitignore 掉，不会进仓库。

rules/ 目录：模块化指令，随项目扩展

单个 CLAUDE.md 适合小项目。但项目一大，它就会变成一个没人维护、没人看的 300 行巨兽。

rules/ 目录解决这个问题。

.claude/rules/ 下的所有 Markdown 文件会自动和 CLAUDE.md 一起加载：

.claude/rules/
├── code-style.md
├── testing.md
├── api-conventions.md
└── security.md

每个文件只聚焦一件事，负责对应模块的人维护对应文件，互不干扰。

更强的地方是路径作用域。给规则文件加 YAML frontmatter，它就只在 Claude 处理特定路径的文件时才加载：

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

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

当 Claude 在改 React 组件时，这条规则根本不会出现。只有它进入 src/api/ 或 src/handlers/ 时才加载。

没有 paths 字段的规则文件每次会话都会加载。

这是 CLAUDE.md 开始变得拥挤之后，正确的拆分方式。

commands/ 目录：你自己的 slash 命令

Claude Code 默认有 /help、/compact 这些内置命令。commands/ 目录让你加自己的。

放一个 Markdown 文件进去，它就变成一个 slash 命令：

• review.md → /project:review
• fix-issue.md → /project:fix-issue
• deploy.md → /project:deploy

一个实用的 review 命令长这样：

---
description: 合并前检查当前分支 diff
---
## 变更文件列表

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

## 完整 Diff

!`git diff main...HEAD`

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

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

注意 ! 反引号语法——它会执行 shell 命令，把输出注入到 prompt 里。这就是自定义命令真正有用的地方：不只是保存好的文本，而是能带着真实上下文的动态指令。

运行 /project:review，Claude 自动拿到实际的 git diff 再开始工作。

给命令传参数

用 $ARGUMENTS 接收命令后面跟的文本：

---
description: 调查并修复 GitHub issue
argument-hint: [issue-number]
---
看一下这个仓库的 issue #$ARGUMENTS

!`gh issue view $ARGUMENTS`

理解这个 bug，找到根因，修复它，然后写一个能复现这个问题的测试。

运行 /project:fix-issue 234，issue 234 的内容直接注入到 prompt。

项目命令放 .claude/commands/ 提交进仓库，团队共享。个人命令放 ~/.claude/commands/，全局可用，显示为 /user:命令名。

skills/ 目录：Claude 主动触发的工作流

命令是你主动触发的，Skills 不一样——它让 Claude 在合适的时机自己决定要不要调用。

每个 skill 是一个子目录，里面有 SKILL.md：

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

SKILL.md 用 frontmatter 描述何时使用：

---
name: security-review
description: 全面安全审计。在审查代码漏洞、准备部署、或用户提到安全相关话题时使用。
allowed-tools: Read, Grep, Glob
---
分析代码库的安全漏洞：

1. SQL 注入和 XSS 风险
2. 暴露的凭证或密钥
3. 不安全的配置
4. 认证和授权缺口

报告发现的问题，附严重等级和具体修复步骤。
参考 @DETAILED_GUIDE.md 了解我们的安全标准。

你说"检查这个 PR 的安全问题"，Claude 读取 description，判断匹配，自动调用这个 skill。你也可以直接用 /security-review 显式调用。

和命令的关键区别：skills 可以打包支持文件。 @DETAILED_GUIDE.md 引用了同目录下的详细文档，commands 只是单个文件，skills 是完整的包。

agents/ 目录：专属子 agent

当一个任务复杂到值得专门的「专家」处理时，就可以在 .claude/agents/ 里定义子 agent。

.claude/agents/
├── code-reviewer.md
└── security-auditor.md

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

审查代码时：
- 发现 bug，不只是风格问题
- 给出具体修复建议，不是模糊改进
- 检查边界情况和错误处理
- 只在大规模情况下才关注性能

Claude 需要做代码审查时，它会在独立的上下文窗口里启动这个 agent。Agent 完成工作后压缩结果返回主会话——你的主对话不会被中间探索的大量 token 撑爆。

tools 字段限制 agent 能用什么工具。安全审计员只需要 Read、Grep、Glob，根本不需要写文件权限——这个限制是刻意为之的。

model 字段让你给聚焦任务使用更便宜、更快的模型。大多数只读的探索任务用 Haiku 就够了，把 Sonnet 和 Opus 留给真正需要的工作。

settings.json：权限和项目配置

.claude/settings.json 控制 Claude 能做什么、不能做什么：

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Read",
      "Write",
      "Edit"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

allow 列表里的命令不需要 Claude 每次询问确认，直接执行。通常包括：

• 你的 run 脚本（npm run *、make *）
• 只读 git 命令
• 常规文件操作

deny 列表完全封锁，不管在什么情况下。一个合理的黑名单应该包括：

• 破坏性 shell 命令（rm -rf）
• 直接网络命令（curl）
• 敏感文件（.env 及其变体）

不在任何一个列表里的命令，Claude 会在执行前询问你。 这是刻意设计的安全缓冲区，不用事先预测所有可能的命令，又有兜底保护。

settings.local.json 同样支持本地覆盖，自动 gitignore。

全局 ~/.claude/ 的几个值得知道的目录

~/.claude/CLAUDE.md 会加载进每次 Claude Code 会话，无论在哪个项目里。适合放你的个人编码原则、偏好风格，或者任何你希望 Claude 在所有项目里都记住的事。

~/.claude/projects/ 存着每个项目的会话记录和自动记忆。Claude Code 会在工作过程中自动给自己记笔记——发现的命令、观察到的模式、架构洞察——跨会话持久保存。你可以用 /memory 查看和编辑。

这就是为什么 Claude 有时候"记得"你没有显式告诉它的事情。

全局架构一览

把所有东西拼在一起：

your-project/
├── CLAUDE.md                  # 团队指令（提交进仓库）
├── CLAUDE.local.md            # 你的个人覆盖（gitignore）
│
└── .claude/
    ├── settings.json          # 权限配置（提交进仓库）
    ├── settings.local.json    # 个人权限覆盖（gitignore）
    │
    ├── commands/              # 自定义 slash 命令
    │   ├── review.md          # → /project:review
    │   ├── fix-issue.md       # → /project:fix-issue
    │   └── deploy.md          # → /project:deploy
    │
    ├── rules/                 # 模块化指令文件
    │   ├── code-style.md
    │   ├── testing.md
    │   └── api-conventions.md
    │
    ├── skills/                # 自动触发工作流
    │   ├── security-review/
    │   │   └── SKILL.md
    │   └── deploy/
    │       └── SKILL.md
    │
    └── agents/                # 专属子 agent
        ├── code-reviewer.md
        └── security-auditor.md

~/.claude/
├── CLAUDE.md                  # 全局个人指令
├── settings.json              # 全局设置
├── commands/                  # 个人命令（所有项目可用）
├── skills/                    # 个人 skills（所有项目可用）
├── agents/                    # 个人 agents（所有项目可用）
└── projects/                  # 会话历史 + 自动记忆

怎么从零开始建立这套配置

第一步： 在 Claude Code 里运行 /init，它会读取你的项目自动生成一份初始 CLAUDE.md。然后人工精简到核心内容。

第二步： 加入 .claude/settings.json，设置允许和拒绝的命令。最少要允许你的 run 命令，拒绝 .env 读取。

第三步： 把你最常做的 1-2 个工作流做成 commands。代码审查和 issue 修复是很好的起点。

第四步： 当 CLAUDE.md 开始变拥挤，把指令拆进 .claude/rules/ 目录，按路径作用域划分。

第五步： 在 ~/.claude/CLAUDE.md 里写下你的个人偏好。比如"总是先写类型再写实现"，或者"偏好函数式而非类的写法"。

95% 的项目，到第四步就够了。Skills 和 agents 是在你有反复出现的复杂工作流时才值得打包进来。

---

有一个评论我觉得说到点上了：

🦞 想一起养成你的小龙虾军团？

在公众号对话框回复「小龙虾」，加入龙虾养成群——一个专门交流如何用 OpenClaw 做自媒体、搞变现的玩家社群。

军团越强，变现越快。来一起练级 👇

参考链接

• 原始推文（Akshay Pachaar）：https://x.com/akshay_pachaar/status/2035341800739877091
• Claude Code 官方文档：https://docs.anthropic.com/en/docs/claude-code