用 Claude Code 跑过项目的人，大多见过根目录里多出来的 .claude/ 文件夹，但很少有人点开看过。它不是缓存或日志目录，而是 Claude Code 的配置中心：项目指令、自定义命令、Skill、子代理、权限规则都放在这里，个人目录下的 ~/.claude/ 还存着跨会话的自动记忆。

很多人觉得 Claude Code「有时很聪明，有时又犯傻」，其中不少情况并不是模型能力问题，而是它不知道项目的规矩：用哪个测试框架、命名用 camelCase 还是 snake_case、错误怎么处理。把 .claude/ 配好，就是把这些规矩一次写清楚。

这篇适合已经在用 Claude Code、想让它更稳定地遵守团队规范的开发者。下面按文件逐个讲：两个 .claude/ 的区别、CLAUDE.md、rules、commands 与 skills、agents、settings.json 权限、自动记忆，最后给一份从零配置的推荐顺序。

先分清：项目级和全局级两个 .claude 文件夹

Claude Code 的 .claude 文件夹有两个：

项目级 ./.claude/：团队配置，提交到 git，所有人共享。规则、命令、权限策略放这里。
全局级 ~/.claude/：个人偏好，只对你生效，跨所有项目。个人命令、个人规则、会话记录和自动记忆在这里。

两个目录结构相似，职责不同：团队都该遵守的放项目级，只是你自己的习惯放全局级。

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

Claude Code 每次启动会话都会读取 CLAUDE.md，并在整个会话中保留在上下文里。你写「所有函数先写单元测试再实现」，它就会照这个顺序做；你写「错误处理只用自定义 Logger，不用 console.log」，它每次都会参考。

需要注意，官方文档说明 CLAUDE.md 是作为上下文提供的，不是强制配置，写得越具体、越简洁，遵守得越稳定。必须每次都执行的动作（比如提交前跑 lint），更适合写成 Hook。

CLAUDE.md 可以放在这几个位置：

位置	作用范围	是否提交到 git
`./CLAUDE.md` 或 `./.claude/CLAUDE.md`	当前项目，团队共享	是
`~/.claude/CLAUDE.md`	你的所有项目	否
子目录里的 `CLAUDE.md`	Claude 读写该子目录文件时才加载	是
`./CLAUDE.local.md`	当前项目，只对你生效	否，需要自己加进 `.gitignore`

各层级的 CLAUDE.md 会合并加载，不是互相覆盖。启动会话后可以运行 /context，在 Memory files 里确认哪些文件被加载了。

写多长合适

官方建议每个 CLAUDE.md 控制在 200 行以内。文件越长，占用的上下文越多，Claude 的遵守程度反而会下降。中型项目的核心规范，往往二三十行就能覆盖。

该写的：

构建、测试、lint 命令（如 npm run test、make build）
关键架构决策（如「用 Turborepo 管理 monorepo」）
不明显的坑（如「TypeScript strict 模式开着，未使用变量会报错」）
导入规范、命名风格、错误处理模式

不该写的：

linter 或 formatter 已经管住的规则
可以直接链接过去的完整文档
长篇理论解释

CLAUDE.local.md：只对自己生效的偏好

有些习惯只属于你，比如你的沙箱地址、你偏好的测试数据，不想影响团队。可以在项目根目录建 CLAUDE.local.md，它会和 CLAUDE.md 一起加载，并且排在后面读取。这个文件不会自动被 git 忽略，记得手动加进 .gitignore。

如果仓库里已经有给 Codex 等工具写的 AGENTS.md，新版 Claude Code 在没有 CLAUDE.md 时也能直接读取它，写法可以参考 AGENTS.md，把项目规范写给 Codex，看懂并就近生效。

.claude/rules/：CLAUDE.md 太长时按主题拆分

项目变大后，CLAUDE.md 很容易涨到三四百行，没人愿意维护一个巨型文件。.claude/rules/ 用来按主题拆分，里面的每个 Markdown 文件都会被发现并加载（支持子目录）：

.claude/rules/
├── api-conventions.md     # API 相关的规范
├── testing.md             # 测试标准
├── security.md            # 安全要求
└── frontend.md            # 前端组件规范

负责 API 的人改 api-conventions.md，负责测试的人改 testing.md，互不干扰。

更有用的是路径作用域。在规则文件顶部加 paths frontmatter，它就只在 Claude 读写匹配路径的文件时才加载：

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

Claude 编辑 React 组件时不会加载这份规则，只有操作 src/api/ 下的代码时才会。没有 paths 字段的规则文件每次启动都会加载。个人规则也可以放在 ~/.claude/rules/，对你的所有项目生效。

.claude/commands/ 与 .claude/skills/：自定义斜杠命令和 Skill

Claude Code 自带 /help、/compact 等命令，你也可以加自己的。按当前官方文档，自定义命令已经并入 Skill：.claude/commands/review.md 和 .claude/skills/review/SKILL.md 都会创建一个 /review 命令，用法相同。旧的 commands 文件照样能用，新写的建议直接用 Skill。

一个命令文件示例：

Review the current git diff for bugs, performance issues, and style problems.
Focus on:
1. Logic errors
2. Missing error handling
3. Performance bottlenecks

Here's the current diff:
!`git diff --staged`

!`命令` 这种写法会先执行 shell 命令，把输出替换进 prompt，所以自定义命令不只是存一段文字，还能动态注入上下文。用 $ARGUMENTS 接收参数：

Fix the GitHub issue described below:
!`gh issue view $ARGUMENTS`

保存为 fix-issue.md 后，运行 /fix-issue 234 就会把第 234 号 issue 的内容交给 Claude。项目级命令提交到 git 和团队共享，个人命令放 ~/.claude/commands/ 或 ~/.claude/skills/。

Skill 和单文件命令的区别在于两点：

Claude 可以自己判断何时调用：Skill 的 frontmatter 里写 description，对话内容匹配时 Claude 会自动加载，不必你手动输入斜杠命令。
可以打包多个文件：每个 Skill 是一个目录，SKILL.md 之外还能放详细指南、脚本等辅助文件。

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

---
description: "Review code for security vulnerabilities"
---

当你说「帮我看看这个 PR 有没有安全问题」，Claude 读到 description 匹配，就会调用这个 Skill。不过靠描述自动触发并不总是稳定，提高触发率的做法可以看 Skill 靠描述触发只有 60%，写进规则文件才更稳。

.claude/agents/：定义专职子代理

复杂任务可以交给专门的子代理。在 .claude/agents/ 里放一个 Markdown 文件，name 和 description 是必填字段：

---
name: code-reviewer
description: Reviews code for logic errors, missing tests and performance issues
model: haiku
tools: Read, Grep, Glob
---

You are a code reviewer. Focus on:
- Logic errors and edge cases
- Missing test coverage
- Performance implications

Claude 根据 description 判断什么时候把任务委派给它。子代理有独立的上下文窗口，做完后把结论返回主会话，不会把主会话的上下文撑满。

tools 限制子代理能用哪些工具。只读的审查代理没必要有写文件的权限；不写这个字段则继承全部可用工具。
model 让简单任务用更便宜的模型。只读的代码浏览用 Haiku 就够，Sonnet 和 Opus 留给需要推理的工作。

.claude/settings.json：权限控制

settings.json 决定 Claude 能做什么、不能做什么：

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

allow 里的操作不再弹确认直接执行，deny 里的操作完全禁止，两边都没写的，Claude 会先问你。还可以加 ask 列表，强制某些操作每次都确认。

个人覆盖写在 .claude/settings.local.json，不提交到仓库。另外要注意，项目 settings.json 里的 allow 规则要等团队成员信任该目录后才生效，deny 和 ask 规则则立刻生效。

~/.claude/projects/：自动记忆

Claude Code 工作时会自己记笔记：你的偏好、你纠正过它的地方、从代码里推断不出来的项目背景。这些笔记存在 ~/.claude/projects/<项目>/memory/ 下，由一个 MEMORY.md 索引和若干主题文件组成，同一个 git 仓库的不同 worktree 共用一份。

每次会话开始时会加载 MEMORY.md 的前 200 行（或前 25KB），主题文件在需要时才读。用 /memory 可以浏览、编辑这些文件，也可以在里面开关自动记忆。

如果 Claude 突然「记得」你没在本次会话里说过的事，多半就是自动记忆在起作用。想让它忘掉，直接编辑或删除对应的记忆文件即可。

从零开始配置 .claude 文件夹的推荐顺序

运行 /init：Claude 会分析项目，生成一份初始 CLAUDE.md（已有的话会给修改建议），你在上面删改即可。
创建 .claude/settings.json：至少把常用的 run 命令加进 allow，把 .env 加进 deny。
建一两个自定义命令或 Skill：代码审查和修 issue 是最好的起点。
拆分规则：CLAUDE.md 接近 200 行时，拆到 .claude/rules/，按路径设作用域。
写个人偏好：在 ~/.claude/CLAUDE.md 写上你自己的习惯，比如「总是先写类型定义再写实现」。

大多数项目做到这五步就够了。子代理和更复杂的 Skill，等有了固定的复杂工作流再加。想检查已有配置有没有过时或互相冲突的内容，较新版本的 Claude Code 还可以运行 /doctor prompt-audit。

总结

.claude/ 文件夹的作用，是把你本来要在每次对话里反复解释的项目规矩，写成 Claude Code 每次都会读的文件：CLAUDE.md 和 rules 管规范，commands 和 skills 管可复用流程，agents 管分工，settings.json 管权限，自动记忆管它自己学到的东西。花半小时把 CLAUDE.md 和权限配好，后面每次对话都能少花几分钟纠正它。

配置好之后，可以在 AIGoCode 上直接使用 Claude Code，把这套项目规范用起来。

参考链接

Claude Code 官方文档：How Claude remembers your project：https://code.claude.com/docs/en/memory
Claude Code 官方文档：Skills：https://code.claude.com/docs/en/skills
Claude Code 官方文档：Subagents：https://code.claude.com/docs/en/sub-agents
Claude Code 官方文档：Settings：https://code.claude.com/docs/en/settings