Claude Code 真正的玩法：.claude文件夹使用指南

大多数人知道 .claude 文件夹存在，看着它出现在项目根目录，但从来不会打开看里面有什么。

这太浪费了。Akshay Pachaar 的千万浏览好文分享了有关它的一切。

.claude 是 Claude Code 的控制中心。你的指令、自定义命令、权限规则、甚至跨会话的记忆，都放在这里。搞明白每个文件的作用，配置好它，Claude 就能完全按你和团队的需求来工作。

先说一个关键点：其实有 两个 .claude 目录。

一个是项目级的，放在你的仓库里，整个团队共享，同一套规则，同一套命令，同一套权限策略——提交到 git。

另一个是全局的，放在 ~/.claude/，存的是你个人的偏好和机器本地的状态，比如会话历史和自动记忆。每次会话，这两个都会加载。

CLAUDE.md：最重要的文件

Claude Code 每次启动，第一个读取的就是 CLAUDE.md。它直接加载进系统提示，全程生效。

简单说：你写什么，Claude 就听什么。

让它先写测试再写实现，它照做。告诉它「永远别用 console.log 处理错误，必须用自定义 logger」，它每次都遵守。

项目根目录的 CLAUDE.md 是最常见的用法。但你也可以在 ~/.claude/CLAUDE.md 放全局偏好，甚至在子目录里放针对特定文件夹的规则。Claude 会全部读取并合并。

写什么，别写什么

该写：

• 构建、测试、lint 命令（npm run test, make build 之类）
• 关键的架构决策（「我们用 Turborepo 做 monorepo」）
• 不明显的坑（「TypeScript strict 模式开了，未使用变量会报错」）
• 导入规范、命名模式、错误处理风格
• 主要模块的文件和文件夹结构

别写：

• linter 或 formatter 配置（那属于配置文件）
• 可以直接链接的完整文档
• 解释理论的长段落

CLAUDE.md 最好控制在 200 行以内。超过这个长度，消耗的 context 太多，Claude 遵循指令的能力反而会下降。

rules/：变大的 CLAUDE.md 的解法

CLAUDE.md 刚开始用着挺好。但团队一大，很快就变成 300 行没人维护的怪物，大家都当它不存在。

rules/ 就是来解决这个的。

.claude/rules/ 里的每个 markdown 文件会自动和 CLAUDE.md 一起加载。把指令按关注点拆开：api-conventions.md 给负责 API 的人改，testing.md 给负责测试标准的人改，谁也不碍谁的事。

更狠的是路径限定规则。在文件开头加一段 YAML frontmatter，规定这规则只在特定路径下才激活：

---
paths:
  - src/api/**
  - src/handlers/**
---

这样 Claude 编辑 React 组件时不会加载这个规则，只有在 src/api/ 或 src/handlers/ 目录下才触发。

hooks：让行为变得确定

CLAUDE.md 里的指令是「建议」，Claude 大部分时候听，但不是每次都听。你没法指望一个语言模型每次都跑 linter、永远不执行危险命令、或者每次完成后都通知你。

hooks 让这些行为变得确定。事件处理器会在 Claude 工作流的特定节点自动触发，你的 shell 脚本每次都会运行，没例外。

所有 hooks 配置都放在 settings.json 的 hooks 键下面。

常用事件

• PreToolUse：任何工具运行前触发，安全门
• PostToolUse：工具成功后触发，用来格式化输出
• Stop：Claude 结束时触发，质量门槛（比如「测试必须通过才能算完成」）
• UserPromptSubmit：你按回车时触发，做 prompt 验证
• Notification：桌面通知
• SessionStart/SessionEnd：上下文注入和清理

一个常见的坑

Exit code 2 是唯一能阻止执行的那个。Exit 0 是成功，Exit 1 是报错但不阻止。很多人把安全 hook 设为 exit 1，结果只是记了个日志，操作还是执行了。

skills/：需要时自动调用的工作流

skills 是 Claude 可以根据上下文自动调用的工作流。

每个 skill 放在自己的子目录里，里面有个 SKILL.md：

---
name: security-review
description: Comprehensive security audit. Use when reviewing code for
  vulnerabilities, before deployments, or when the user mentions security.
allowed-tools: Read, Grep, Glob
---
Analyze the codebase for security vulnerabilities:

1. SQL injection and XSS risks
2. Exposed credentials or secrets
3. Insecure configurations
4. Authentication and authorization gaps

Report findings with severity ratings and specific remediation steps.
Reference @DETAILED_GUIDE.md for our security standards.

你说「review this PR for security issues」，Claude 读到描述，发现匹配，就自动调用这个 skill。也可以直接用 /security-review 手动触发。

和 commands 的区别：commands 是单个文件，skills 可以附带一堆支持文件。上面那个 @DETAILED_GUIDE.md 就是和 SKILL.md 放在一起的。

agents/：专门的子代理人格

任务复杂到需要个专门的专家时，可以在 .claude/agents/ 定义一个子代理人格。每个 agent 是个 markdown 文件，有自己的系统提示、工具访问权限和模型偏好：

---
name: code-reviewer
description: Expert code reviewer. Use PROACTIVELY when reviewing PRs,
  checking for bugs, or validating implementations before merging.
model: sonnet
tools: Read, Grep, Glob
---
You are a senior code reviewer with a focus on correctness and maintainability.

When reviewing code:
- Flag bugs, not just style issues
- Suggest specific fixes, not vague improvements
- Check for edge cases and error handling gaps
- Note performance concerns only when they matter at scale

需要代码审查时，Claude 在独立的上下文窗口里唤醒这个 agent。它干完活，把发现压缩后报告回来，你的主会话不会被成千上万的中间 token 污染。

tools 字段限制 agent 能做什么。安全审计 agent 只需要 Read、Grep、Glob，写文件跟它没关系。这个限制是故意的，明确比较好。

model 字段让你用更便宜更快的模型做专注的任务。Haiku 处理大多数只读探索够用了。Sonnet 和 Opus 留给真正需要它们的活。

settings.json：权限和项目配置

.claude/settings.json 控制 Claude 能做什么、不能做什么。hooks 在这里，你的白名单黑名单也在这里——哪些工具能跑，哪些文件能读，哪些命令需要先问你。

{
  "$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.*)"
    ]
  }
}

白名单

放那些不需要确认就能执行的命令。大多数项目通常包括：

• Bash(npm run ) 或 Bash(make )——让 Claude 自由跑脚本
• Bash(git *)——只读 git 命令
• Read, Write, Edit, Glob, Grep——文件操作

黑名单

完全封掉的命令：

• 破坏性 shell 命令 like rm -rf
• 直接网络命令 like curl
• 敏感文件 like .env 和 secrets/ 下的任何东西

中间地带

不在白名单也不在黑名单里的，Claude 会问你。这个设计是故意的——给你留个安全网，不用提前预料每一种可能的命令。

~/.claude/：全局那个

你不太经常跟这个文件夹打交道，但知道里面有什么会有用：

• ~/.claude/CLAUDE.md：加载到每个 Claude Code 会话，无论你在哪个项目。放你的个人编码原则、偏好风格，或者不管在哪个仓库都想让 Claude 记住的东西。
• ~/.claude/projects/：每个项目的会话记录和自动记忆。Claude 工作时会自动给自己记笔记：它发现的命令、观察到的模式、架构洞察。这些跨会话持久化。你可以用 /memory 浏览和编辑。
• ~/.claude/commands/ 和 ~/.claude/skills/：个人命令和 skills，所有项目可用。

有时候 Claude「记得」一些你明明没告诉它的事，就是这些自动记忆在起作用。想清空某个项目的记忆重新开始，也在这里操作。

怎么上手

从头开始的话，一个实用的渐进路线：

第一步。 在 Claude Code 里跑 /init。它会读取你的项目生成一个起步的 CLAUDE.md。把它精简到 essentials。

第二步。 添加 .claude/settings.json，写上适合你技术栈的 allow/deny 规则。至少allow 你的 run 命令，deny .env 读取。

第三步。 创建一两个 commands，做你最常跑的工作流。代码审查和 issue 修复是很好的起点。

第四步。 项目变大、CLAUDE.md 变拥挤了，开始拆到 .claude/rules/ 文件里。路径限定用起来。

第五步。 加一个 ~/.claude/CLAUDE.md 放个人偏好。比如「实现前先写类型」「喜欢函数式而不是类」。

这就覆盖了 95% 的项目需求。skills 和 agents 是当你有反复出现的复杂工作流值得封装的时候才用的。

小结

.claude 文件夹本质上是一个协议——告诉 Claude 你是谁、你的项目做什么、它应该遵循什么规则。定义得越清楚，你花在纠正 Claude 的时间越少，它花在干活的时间越多。

CLAUDE.md 是杠杆最高的文件。先把这玩意儿弄对。其他都是优化。

不止如此，懂了它，很多Agent设计的原理也都理解了，包括Openclaw的一系列巧妙设计，本质都在于对于一系列prompt文件的组织和运转流程的控制，而它们也正是harness设计的关键。