Claude Code 的 .claude 文件夹里到底有什么，一篇讲清楚

原文：https://x.com/akshay_pachaar/status/2035341800739877091

用 Claude Code 写代码时，项目根目录会出现一个 .claude/ 文件夹。很多人知道它在那，但从来没打开看过。

这个文件夹是 Claude 在你项目里的控制中心——指令、权限、自动化脚本、甚至跨会话记忆，全都在里面。

搞懂它的结构，你就能让 Claude 按你团队的规矩干活，而不是每次都要手动纠正。

两个 .claude，不是一个

项目里有一个 .claude/，电脑根目录下还有一个 ~/.claude/。

项目级的放团队配置，提交到 git，所有人共享同一套规则。全局的放个人偏好和本地状态，比如会话历史和自动记忆。

CLAUDE.md：最重要的那个文件

Claude Code 启动时第一件事就是读 CLAUDE.md，把内容加载到系统提示里，整个会话都会遵守。

你在里面写"所有 handler 必须用 zod 做校验"，它就照做。

项目根目录放一份是最常见的做法。~/.claude/CLAUDE.md 放全局偏好，子目录里也可以放一份做更细粒度的控制，Claude 会把它们合并读取。

一份好的 CLAUDE.md 大概长这样：

# Project: Acme API

## Commands
npm run dev       # Start dev server
npm run test      # Run tests (Jest)
npm run lint      # ESLint + Prettier check

## Architecture
- Express REST API, Node 20
- PostgreSQL via Prisma ORM
- All handlers live in src/handlers/

## Conventions
- Use zod for request validation in every handler
- Return shape is always { data, error }
- Never expose stack traces to the client

## Watch out for
- Tests use a real local DB, not mocks. Run `npm run db:test:reset` first
- Strict TypeScript: no unused imports, ever

20 行左右，构建命令、架构决策、编码约定、常见坑，够了。控制在 200 行以内，太长了 Claude 反而容易漏掉指令。

不该往里写的：linter 配置能覆盖的规则、能给链接的完整文档、纯理论解释。

个人偏好放 CLAUDE.local.md，Claude 会一起读，自动 gitignore，不会进仓库。

rules/：CLAUDE.md 膨胀后的解法

CLAUDE.md 写到 300 行就没人愿意维护了。.claude/rules/ 目录里放 markdown 文件，Claude 会自动加载：

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

按职责拆，谁负责谁改，互不干扰。

更实用的是路径作用域。给规则文件加 frontmatter，它只在匹配的文件路径下生效：

---
paths:
  - "src/api/**/*.ts"
  - "src/handlers/**/*.ts"
---

编辑 React 组件时不会加载 API 规则，编辑 handler 时才会。没写 paths 的文件每次都加载。

hooks：不靠"建议"，靠代码强制执行

CLAUDE.md 的指令是建议——Claude 大多数时候遵守，但不是每次。hooks 是事件钩子，在 Claude 工作流的特定节点自动执行你的脚本，没有例外。

配置写在 .claude/settings.json 的 hooks 字段里。关键机制：exit code 2 会阻断执行，exit 0 是成功，exit 1 是错误但不阻断。安全相关的 hook 如果用了 exit 1，等于什么都没拦住。

几个最常用的事件：

PreToolUse：工具执行前触发，拿来拦危险命令
PostToolUse：工具执行后触发，比如自动跑 prettier
Stop：Claude 认为完成时触发，可以加"测试不过不准停"的门禁

一个典型配置——自动格式化 + 拦截危险命令：

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit|MultiEdit",
      "hooks": [{
        "type": "command",
        "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write 2>/dev/null"
      }]
    }],
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/bash-firewall.sh"
      }]
    }]
  }
}

firewall 脚本从 stdin 读命令，匹配到 rm -rf /、git push --force main、DROP TABLE 这类模式就 exit 2 阻断。

有个坑：Stop hook 里要检查 stop_hook_active 标志，不然会出现无限循环——hook 拦住 Claude，Claude 重试，hook 再拦，永远停不下来。

skills/：可复用的工作流包

skills 和普通指令不同，它是一个目录，里面可以放 SKILL.md 加任意辅助文件。Claude 根据对话内容自动判断是否调用，也可以用 /skill-name 手动触发。

.claude/skills/
└── security-review/
    ├── SKILL.md
    └── DETAILED_GUIDE.md

SKILL.md 用 frontmatter 声明触发条件和可用工具，正文写具体指令。辅助文件用 @文件名 引用。

个人 skills 放 ~/.claude/skills/，所有项目通用。

agents/：独立上下文的子代理

复杂任务可以派一个专门的子代理去做。每个 agent 是一个 markdown 文件，有自己的系统提示、工具权限和模型选择：

---
name: code-reviewer
model: sonnet
tools: Read, Grep, Glob
---

You are a senior code reviewer.
- Flag bugs, not style issues
- Suggest specific fixes
- Check edge cases and error handling

Claude 会在独立的上下文窗口里运行这个 agent，做完把结果压缩回来。主会话不会被大量中间探索过程污染。

model 字段可以指定便宜的模型做简单任务，tools 字段限制 agent 能做什么——只读审查的 agent 不需要写文件权限。

settings.json：权限白名单和黑名单

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

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git status)",
      "Read", "Write", "Edit"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Read(./.env)"
    ]
  }
}

allow 里的命令自动执行不需确认，deny 里的直接拦住。两边都没写的，Claude 会先问你。个人覆写放 settings.local.json，自动 gitignore。

从零开始的配置路径

跑 /init，Claude 会读项目生成一份 CLAUDE.md，你精简到 20 行左右
加 settings.json，至少 allow 你的运行命令，deny .env 读取
写一两个常用的 skill，比如 code review
CLAUDE.md 超过 100 行时，开始拆到 rules/ 里
全局偏好放 ~/.claude/CLAUDE.md

95% 的项目到这一步就够了。skills 和 agents 等你有了反复出现的复杂工作流再加。