你用 Claude Code 多久了大概率用过.claude/文件夹但从没真正打开过看看。这很正常。大多数人只知道它存在没想过里面藏着什么。但这个文件夹其实是整个 Claude Code 的控制中心——你的指令、自定义命令、权限规则还有跨对话的记忆全在这里。一旦搞懂它的结构你就能让 Claude Code 完全按照你的方式工作。.claude/ 不是一个文件夹是两个先把一个容易忽略的事情说清楚.claude/目录有两个不是一个。项目级放在你的项目根目录跟着 git 提交。整个团队共享同一套规则、命令和权限策略。全局级放在~/.claude/只属于你自己。这里存的是个人偏好和机器本地状态比如会话历史、自动记忆。团队配置放项目个人偏好放全局。这个分层设计让多人协作变得很清晰。CLAUDE.mdClaude 的说明书这是整个系统里最重要的文件没有之一。每次启动 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.mdClaude 会同时读取它和主 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:reviewfix-issue.md→/project:fix-issuedeploy.md→/project:deploy一个实用的 review 命令长这样--- description: 合并前检查当前分支 diff --- ## 变更文件列表 !git diff --name-only main...HEAD ## 完整 Diff !git diff main...HEAD 检查以上变更关注 1. 代码质量问题 2. 安全漏洞 3. 缺失的测试覆盖 4. 性能问题 按文件给出具体可操作的反馈。注意!反引号语法——它会执行 shell 命令把输出注入到 prompt 里。这就是自定义命令真正有用的地方不只是保存好的文本而是能带着真实上下文的动态指令。运行/project:reviewClaude 自动拿到实际的 git diff 再开始工作。给命令传参数用$ARGUMENTS接收命令后面跟的文本--- description: 调查并修复 GitHub issue argument-hint: [issue-number] --- 看一下这个仓库的 issue #$ARGUMENTS !gh issue view $ARGUMENTS 理解这个 bug找到根因修复它然后写一个能复现这个问题的测试。运行/project:fix-issue 234issue 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.mdSKILL.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 Pachaarhttps://x.com/akshay_pachaar/status/2035341800739877091Claude Code 官方文档https://docs.anthropic.com/en/docs/claude-code