当前位置：首页 > news >正文

90% 的人从没打开过这个文件夹，但它是 Claude Code 真正的控制台

news 2026/8/20 22:52:09

你用 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/ # 会话历史 + 自动记忆