Claude Code项目级配置详解：用settings.json与CLAUDE.md管好AI助手

如果你已经把 Claude Code 跑起来了，大概率会遇到一个尴尬：每次开新会话都要重新叮嘱它“我们项目用 pnpm，别用 npm”“有个生成脚本要先跑一下”“改代码之前先看架构文档”。说得多了，AI 还是偶尔犯浑，明明上一轮说好的事，换个会话就忘得干干净净。这时候你就需要项目级配置文件了。

Claude Code 的项目级配置文件，说白了就是放在项目里的.claude目录和对应文件，用来告诉 Claude 这个项目的基本规则、可用权限、常用命令、环境变量，甚至给它挂上一些自动执行的钩子脚本。它解决的核心问题有两个：一是减少重复沟通，让 Claude 一进来就“懂规矩”；二是把权限和行为边界钉死，防止它乱跑命令、乱改文件。适合所有用过 Claude Code 但觉得它“不够听话”的人，不管你是前端、后端还是做运维的，这套配置思路都通用。

这篇文章我会从配置文件的存放位置、加载优先级讲起，然后逐个拆解settings.json里的字段，再重点说说CLAUDE.md怎么写才真正有用，最后给一份可以直接抄的完整示例。全程以我实际踩过的坑和验证过的方案为准，不整虚的。

1. 配置文件都藏在哪：先搞懂三个文件与加载优先级

1.1 三个常用位置：全局、项目、本地

首次接触 Claude Code 配置的人最容易懵的就是：到底往哪个文件里写配置？

实际上，Claude Code 的配置体系是分层的，主要涉及三个位置：

• 用户级全局配置：位于~/.claude/settings.json。这是你个人的默认偏好，相当于“我这个人习惯怎么用 AI”，对所有项目生效。比如你希望所有项目默认模型都是某一个大模型版本，或者你在所有项目里都禁止 Claude 执行rm -rf这类高危命令，就可以写在这里。
• 项目级共享配置：位于项目根目录的.claude/settings.json。这个文件通常建议提交到 Git 仓库里，让所有协作的同事共享同一套规则。它适合放项目相关的约定，比如统一用 pnpm、测试命令是什么、哪些目录不允许 AI 乱动等。
• 本地私有配置：位于.claude/settings.local.json。这个文件不提交到 Git，是开发者在本地单独覆盖或补充的配置。比如你本人的 API Key、个人环境变量、你自己想额外加的一些权限规则，都可以放这里。

除了这三个settings.json，还有两个容易一起出现的文件：

• .claude/CLAUDE.md：项目级“记忆”文件，用来给 Claude 写项目背景、架构说明、开发规范。也可以直接放在项目根目录，名为CLAUDE.md，两者都会被读取。
• .mcp.json：项目级别的 MCP（Model Context Protocol）服务器配置，放项目需要用到的外部工具连接信息。

我的建议是：如果只有一个文件要重视，那就是.claude/settings.json和.claude/CLAUDE.md。前者管“能做什么”，后者管“该怎么做”。

1.2 合并顺序与常见误区

多层配置同时存在时，它们的优先级从高到低大致是：

.claude/settings.local.json>.claude/settings.json>~/.claude/settings.json

也就是说，settings.local.json里写的配置会覆盖项目配置和用户配置里同名字段。这个设计很合理：全局配置定基线，项目配置做统一约束，本地配置允许个人微调。

实际使用中有几个误区很常见：

误区一：改了配置不重启会话。Claude Code 的配置主要在会话启动时读取。你改了settings.json，正在运行的会话不会立即感知。要么重启会话，要么至少重新加载一次。部分配置项确实可以热更新，但我实测下来，重启最稳妥。

误区二：把项目专用配置写到用户级。比如有个项目要求 Claude 必须使用某个内部镜像源，这个需求只对这个项目有意义，写进~/.claude/settings.json会导致其他项目也被影响。正确的做法是写进.claude/settings.json。

误区三：混淆CLAUDE.md和settings.json的职责。这俩是互补关系：CLAUDE.md提供的是上下文和规则，适合写“我们项目是什么、怎么构建、有什么约定”；settings.json提供的是机制和权限，适合写“允许执行哪些命令、用什么模型、注入什么环境变量”。把项目背景写进 settings.json，或把权限规则写进 CLAUDE.md，都会让配置变得一团乱。

提示：如果你和团队共享项目，.claude/settings.json和.claude/CLAUDE.md建议入库；settings.local.json务必加进.gitignore，避免把个人偏好带到别人环境里。

2. settings.json 核心字段逐个拆解

2.1 permissions：把“能做什么”管起来

permissions是settings.json里最重要的字段，没有之一。它决定了 Claude 在执行操作前需不需要征得你同意。

一个典型的 permissions 配置长这样：

{ "permissions": { "defaultMode": "acceptEdits", "allow": [ "Read(**)", "Edit(**)" ], "deny": [ "Bash(rm -rf *)", "Bash(git push *)" ], "ask": [ "Bash(pnpm install)", "WebFetch(domain:example.com)" ], "additionalDirectories": [ "../shared-lib" ] } }

几个关键点逐一说：

defaultMode可取"acceptEdits"或"plan"。acceptEdits表示文件编辑类操作默认直接接受，不会每次弹出确认；plan表示更保守，倾向于先出方案再执行。大多数开发者日常用acceptEdits就够，如果你在维护一个特别核心的仓库，再考虑plan。

allow/deny/ask这三组是规则列表，支持的通配规则包括：

• Read(**)：允许读取任意文件。
• Edit(...)：带路径过滤的编辑权限。
• Bash(pnpm run build)：精确匹配某条命令。
• WebFetch(domain:example.com)：限制网页抓取的域名范围。
• WebSearch：允许网络搜索。

规则的匹配有优先级，deny 最高，其次是精确规则，最后才是默认模式。这意味着即使你defaultMode设了acceptEdits，如果某条规则出现在deny里，该操作依然会被拒绝。

additionalDirectories是一个很容易被忽略但相当实用的字段。默认情况下 Claude Code 只能访问项目根目录内的文件。如果你有个 monorepo，里面多个子包需要互相读取，或者你要让 AI 访问某个共享目录，就把这些外部路径加进来。

注意：权限规则不是越多越好。规则写得太宽，等于没设防；写得太细，比如把每条命令都列进去，Claude 会因为反复弹授权而变得难以使用。我一般遵循“宽读、严写、关键命令单独确认”的原则：读取放开，编辑看情况，删除和推送类命令必须逐个确认。

2.2 model / env / outputStyle：日常高频小开关

除了权限，settings.json里还有几个日常最常用到的小开关。

model用于指定该项目的默认模型。比如：

{ "model": "claude-sonnet-4-5" }

如果你的项目比较复杂，需要更强的推理能力，可以在项目级指定某个高配模型；简单脚本类项目则可以用更快的轻量模型，节省等待时间。

env用来注入环境变量。这个功能很实用，比如项目需要读取某些配置才能让 Claude 正确执行构建命令：

{ "env": { "NODE_ENV": "development", "MY_PROJECT_API_HOST": "http://localhost:8080" } }

要注意的是，env里写入的变量会出现在 Claude 的执行环境中，千万别把密钥直接写进配置文件。密钥应该通过环境变量本身注入，或者放在settings.local.json里并且不入库。

outputStyle控制 AI 响应输出的格式，可取值主要是"default"和"xml"。xml模式会以更结构化的 XML 形式返回内容，方便程序化解析。如果你只是把 Claude Code 当日常编码助手用，default就够了；如果你在写自动化流水线、希望输出能被脚本处理，再考虑xml。

includeCoAuthoredBy设置为true时，Claude 会在生成代码的提交信息中自动追加Co-Authored-By署名。对开源项目来说这个选项比较友好，能留下 AI 辅助的记录。不需要就直接删掉或设false。

cleanupPeriodDays用来控制会话记录的清理周期。默认情况下 Claude Code 会保留一段时间内的会话记录，这个字段可以按天数调整清理频率。如果你的磁盘空间紧张，可以调小这个值。

2.3 hooks：给关键动作挂上自动脚本

如果说permissions是防守，那hooks就是进攻——它让你在特定事件发生时自动执行脚本或让 Claude 执行子任务。这对于规范工作流非常有用。

支持的事件类型包括：

• PreToolUse：在某个工具被调用之前触发。
• PostToolUse：在某个工具执行完毕之后触发。
• SessionStart：会话开始的时候触发。
• SessionEnd：会话结束的时候触发。
• UserPromptSubmit：用户提交消息时触发。
• Stop：Claude 停止输出时触发。
• Notification：需要通知用户时触发。
• SubagentStop：子代理停止时触发。

举个最实用的例子：我想确保每次 Claude 准备运行pnpm test时，都会先自动执行一遍 lint，可以这样配置：

{ "hooks": { "PreToolUse": [ { "matcher": "Bash(pnpm test)", "hooks": [ { "type": "command", "command": "pnpm lint" } ] } ], "PostToolUse": [ { "matcher": "Edit(**)", "hooks": [ { "type": "command", "command": "node scripts/check-format.js" } ] } ] } }

hooks里的每个钩子对象都有两个核心属性：matcher用来匹配工具调用，hooks数组里是具体要执行的动作。type目前主要用command，也就是执行 shell 命令；也可以配置为task，让 Claude 去处理一个子任务。

需要特别提醒的是：hook 里执行的命令会占用执行时间，写得太重会拖慢整个交互流程。我见过有人把每次Edit后的类型检查都挂在PostToolUse上，结果改一行代码要等十几秒。建议只在关键动作上挂 hook，且命令要尽量轻量。

3. CLAUDE.md：给 AI 写一份“项目说明书”

3.1 该放什么、不该放什么

settings.json明白之后，重头戏来了：CLAUDE.md。这个名字看起来只是一个 Markdown 文件，实际上它是 Claude 的“项目级长期记忆”，重要性远超想象。

Claude 本身没有跨会话的记忆能力，每个新会话都像第一天入职的新人。CLAUDE.md就是它的“入职手册”，每次会话开始时会自动加载，帮它快速进入状态。

那么这份“入职手册”该写什么？基于几个真实项目的配置经验，我总结了一份清单：

该放的内容：

• 项目一句话简介：这个项目是做什么的、给谁用的。别小看这句话，它决定了 Claude 后续做技术判断时的大方向。
• 技术栈与依赖管理工具：比如“React + TypeScript 项目，包管理统一用 pnpm，禁止使用 npm”。
• 常用命令速查：开发启动命令、测试命令、构建命令、Lint 命令，每条用一行写清楚。
• 目录结构说明：哪些目录是源码、哪些是构建产物、哪些是配置文件。最好附一张简化版的目录树。
• 代码风格与约定：比如“组件命名用 PascalCase，工具函数用 camelCase，样式文件统一放同目录styles.ts”。
• 禁止事项：比如“不要修改generated/目录下的文件”“不要随便升级依赖”。

不该放的内容：

• 频繁变动的内容：比如当前正在开发的某个功能的进度、前两天的 bug 临时解决方案。这些内容写进去只会混淆重点。
• 超大文档：完整的架构设计文档几十页，全塞进CLAUDE.md会导致上下文被占用。正确的做法是用引用语法把文档链接进来，按需加载。
• 敏感信息：API key、数据库密码、内网地址，一个都别写。Claude 的上下文可能被日志记录，泄露风险不值得冒。

CLAUDE.md的长度没有硬性标准，但经验法则是：让一个新工程师读一遍就能上手开始改代码，就合格了。

3.2 Frontmatter 与引用语法

CLAUDE.md支持两级结构，用起来很顺手。

首先，文件顶部可以加 YAML Frontmatter，用来指定一些元信息，比如默认模型：

--- model: claude-sonnet-4-5 --- # 项目说明 ...

Frontmatter 里能配置什么、什么格式最合适，官方文档迭代得比较快，建议以你当前版本的提示为准。但有一点是确定的：如果 Frontmatter 里的设置和settings.json冲突，settings.json的配置优先，别指望靠CLAUDE.md去覆盖权限设置。

其次，CLAUDE.md支持引用其他文件，用@语法：

# API 设计约定 详见 @docs/api-design.md

这个功能非常强大。你可以把详细文档拆分成多个独立文件放在docs/下，然后在CLAUDE.md里按需引用。Claude 遇到@引用时会自动读取对应文件内容，相当于按需加载，不浪费上下文窗口。

还有一个容易被忽略的玩法：子目录记忆文件。你可以在任意子目录下放一个CLAUDE.md，Claude 在操作该目录下的文件时会自动加载对应的子目录记忆。比如：

project-root/ .claude/ CLAUDE.md src/ utils/ CLAUDE.md

这样src/utils/CLAUDE.md里就可以写“本目录负责通用工具函数，禁止引入 React 相关依赖”这类局部规范，比全部堆在根目录要清晰得多。当一个项目的根目录与子目录CLAUDE.md内容冲突时，子目录的记忆优先，因为它更具体。

4. 自定义命令与 MCP：把高频操作变成一句话

4.1 自定义斜杠命令 commands

settings.json里还有一个容易被低估的功能：commands。它允许你自定义斜杠命令，把一串复杂的提示词封装成一条快捷指令。

配置格式如下：

{ "commands": { "review": { "description": "对当前改动进行代码评审", "args": [ { "name": "scope", "description": "评审范围，可选：staged / all", "required": false } ], "prompt": "请对当前改动进行代码评审。重点关注：1. 潜在的 bug 和边界条件；2. 性能隐患；3. 代码风格是否与项目一致。评审范围：{{scope}}" } } }

配置完成并重启会话后，你就可以在对话框里输入/review或/review all来触发对应的提示词流程。args里定义的参数会通过模板变量{{scope}}注入到 prompt 中。

这个功能的实际价值在于：把团队里反复要说的评审标准、提交规范、重构要求沉淀成指令。比如你可以定义一个/commit命令，让 Claude 按项目规范生成提交信息；再定义一个/docs命令，让它为新写的函数自动补注释。

提示：commands的prompt写的是“给 Claude 的指令”，不是“给用户的说明”。要用第二人称明确告诉 Claude 该做什么、按什么标准做，而不是写“这个命令用于”。

4.2 MCP 服务器配置与选型建议

MCP（Model Context Protocol）是让 Claude Code 能访问外部数据源和工具服务的桥梁。你可以在项目级配置 MCP 服务器，让 Claude 具备查询内部文档、操作数据库等能力。

项目级 MCP 配置一般写在.mcp.json里，格式如下：

{ "mcpServers": { "internal-docs": { "type": "http", "url": "http://localhost:8080/mcp" }, "local-db": { "type": "stdio", "command": "node", "args": ["mcp-server-db.js"] } } }

type: "http"走远程 MCP 服务，适合团队共用的知识库、接口平台；type: "stdio"启动本地进程，适合个人本地数据库读取、文件解析这类工具。选型上没有绝对标准，我的建议是：如果只是你自己用，优先 stdio，启动快、调试方便；如果整个团队要共用，上 HTTP 服务。

配置好之后，Claude 会在对话中自动发现并使用这些工具。注意：MCP 工具同样受permissions管控，如果你发现 Claude 明明已经连接了 MCP 却不肯调用，多半是权限配置把它拦住了。这时候去settings.json里把对应工具加入allow规则即可。

5. 实操：从零搭建一份可复用的项目配置

5.1 完整示例：一个全栈项目的 settings.json

理论讲再多，不如直接给一份能用的。下面这个示例是一个典型的全栈项目（前端 React + 后端 Node.js，包管理器用 pnpm）的.claude/settings.json，基本覆盖了日常所需：

{ "model": "claude-sonnet-4-5", "permissions": { "defaultMode": "acceptEdits", "allow": [ "Read(**)", "Edit(**)", "Bash(pnpm dev)", "Bash(pnpm build)", "Bash(pnpm test)", "Bash(git status)", "Bash(git diff *)", "WebSearch" ], "deny": [ "Bash(rm -rf *)", "Bash(git push *)", "Bash(pnpm add *)", "Bash(pnpm remove *)" ], "ask": [ "Bash(pnpm install)", "Bash(git commit *)" ], "additionalDirectories": [ "../shared-packages" ] }, "hooks": { "PreToolUse": [ { "matcher": "Bash(pnpm test *)", "hooks": [ { "type": "command", "command": "pnpm lint" } ] } ] }, "env": { "NODE_ENV": "development" }, "commands": { "review": { "description": "评审当前分支的改动", "args": [ { "name": "base", "description": "对比分支", "required": false } ], "prompt": "请对当前分支相对 {{base}} 分支的改动做一次完整的代码评审，重点检查逻辑正确性、潜在 bug、性能问题和项目规范符合度，并逐条给出修改建议。" } }, "includeCoAuthoredBy": true, "cleanupPeriodDays": 30 }

这套配置的模式很清晰：

• 读取和编辑全部放行，保证日常开发流畅；
• 删除、推送、安装依赖这些“有副作用”的命令，要么 deny 要么 ask；
• 测试之前强制跑一遍 lint，用 hook 保证规范；
• monorepo 场景下通过additionalDirectories让 Claude 能访问共享包目录；
• 内置一个最常用的代码评审命令，减少重复输入。

建议你拿到这份配置后不要直接照抄，先把你自己的测试命令、构建命令、禁止的命令列表替换进去，再跑一个会话验证一下。

5.2 CLAUDE.md 模板参考

配合上面的settings.json，下面是一份CLAUDE.md模板，你可以按项目情况增删：

--- model: claude-sonnet-4-5 --- # 项目简介 这是一个面向中小团队的全栈项目，前端使用 React + TypeScript，后端使用 Node.js + Express，数据库使用 PostgreSQL。项目目标是提供轻量级的内部协作工具。 # 常用命令 - 安装依赖：`pnpm install` - 启动前端开发服务：`pnpm dev:web` - 启动后端开发服务：`pnpm dev:api` - 运行全部测试：`pnpm test` - 代码检查：`pnpm lint` - 构建生产包：`pnpm build` # 目录结构 - `apps/web`：前端应用源码 - `apps/api`：后端 API 服务 - `packages/shared`：前后端共享的类型定义与工具函数 - `docs`：项目文档，按需阅读 # 代码规范与约定 1. 前端组件使用函数组件 + Hooks，禁止使用 Class 组件。 2. 状态管理统一使用现有 store 方案，避免引入新依赖。 3. 所有后端接口必须包含基础参数校验。 4. 数据库表结构变更必须先写迁移脚本，不允许直接修改表结构。 5. 提交信息格式：`feat(scope): description`，scope 必须填写。 # 重要注意事项 - `packages/shared` 里的代码会被前后端同时引用，修改前务必评估影响范围。 - 构建产物目录不要手动修改。 - 新增依赖前必须先与团队确认，避免引入冗余包。 - 测试相关文件统一放在 `__tests__` 目录。 # 参考文档 - API 设计规范：见 @docs/api-design.md - 数据库设计说明：见 @docs/database.md

这份模板的精髓在于，用简短条目把事情说清楚，不追求面面俱到。有了它，Claude 在一个新会话里打开项目就知道“这是什么项目、怎么运行、改代码时要注意什么”，省去了一大轮对话。

5.3 从零到生效的四个步骤

配置文件不是写完就完事的，建议你按这个流程走一遍：

1. 创建目录结构：在项目根目录执行mkdir -p .claude，确认目录已存在。
2. 写入配置文件：把上面settings.json的内容按需修改后放进去。
3. 撰写 CLAUDE.md：根据模板填充项目信息，文档引用可以先空着，之后再补。
4. 重启会话验证：新建一个会话，随便问一句“这个项目怎么启动？”，看它能否正确回答。再让它执行一个你配置了deny的命令，确认权限拦截生效。

我在第一次按这个流程操作时的经验是：别追求一步到位。配置这东西，一定是在真实使用中逐步调整出来的。比如一开始你可能没意识到需要禁止pnpm add，直到 Claude 自作主张装了个依赖，才想起来补上。

6. 常见问题与排查实录

6.1 配置不生效怎么办

配置写了，权限没拦住，模型没切换……这类“不生效”的问题，九成是下面几个原因：

原因一：会话没重启。最普遍的情况。Claude Code 的配置在会话启动时读取，修改后没重启会话，当然不生效。

原因二：文件放错了位置。有人把.claude/settings.json写成了.claude/settings.local.json，或者把用户级配置直接放到了项目根目录。检查一下文件路径是不是严格匹配上面说的那三个位置。

原因三：JSON 格式错误。settings.json不支持注释，也不能有尾逗号。很多编辑器默认不校验 JSON 格式，写错了一个逗号整个文件就静默失效。改完配置后用jq . settings.json或者任意 JSON 工具跑一遍校验。

原因四：大小写不一致。权限规则里的工具名是区分大小写的，比如Bash(pnpm TEST)和Bash(pnpm test)是两条完全不同的规则。写规则时务必和你实际使用的命令保持一致。

原因五：多条配置合并时被覆盖。settings.local.json会覆盖settings.json，如果你在本地配置里写了同名字段，项目配置就会被顶掉。排查时先看看本地配置里有没有覆盖项。

6.2 权限与钩子的坑

权限配置踩过的坑比较多，我挑几个典型的：

坑一：allow 规则太宽，AI 绕过限制。比如你配置了allow: ["Bash(git *)"]，然后 deny 了Bash(git push *)，在实际匹配时，因为git *这个通配可能已经覆盖了 push，导致 deny 不生效。解决方式是 deny 规则要写在更精确的层面，并且尽量缩小 allow 的通配范围。

坑二：hook 命令挂载点不对。PreToolUse里匹配的是“工具调用”，不是“终端命令”。如果 Claude 通过其他方式触发了同样的操作，你的 hook 可能不会触发。排查 hook 问题时，不要只盯着终端输出，要打开调试日志确认工具调用事件是否真的发生。

坑三：钩子命令本身要消耗 token 或时间。特别是PostToolUse里挂重型命令，每次编辑都要等半天。我的建议是：只挂轻量的、不会修改文件状态的命令，比如提示、日志，不要把完整的构建流程挂上去。

坑四：权限拦截了 MCP 工具。接入了 MCP 服务器但 AI 不用，多半是 MCP 工具的权限没放开。MCP 工具会被当作独立的工具调用，你需要把对应的工具名加入allow规则，或者在会话里手动允许一次。

6.3 我的排错顺序参考

遇到配置问题，我一般按下面这个顺序排查，效率比较高：

1. 先确认文件路径和文件名完全正确。
2. 校验 JSON 合法性，把文件丢进 JSON 校验工具过一遍。
3. 重启会话，排除缓存和会话上下文干扰。
4. 查看会话启动时的加载日志，确认配置是否被读取。
5. 如果还不行，检查是否有settings.local.json或用户级配置覆盖了目标字段。
6. 最后再考虑是不是版本差异，查阅当前版本对应的配置字段名是否有所调整。

说实话，配置系统本身不复杂，绝大多数问题都出在文件路径、JSON 格式和优先级打架这三件事上。搞懂这三件事，项目级配置基本就玩明白了。

最后再分享一个小技巧：配置写完之后，可以专门用一个“测试会话”来验证。先把所有权限规则都故意触发一遍，把deny、ask、allow三种情况都点一遍，确认行为符合预期，再放心地在日常开发中使用。我第一次配置完没有做这个验证，结果在真实开发时才发现deny规则被通配覆盖了，白白浪费了一下午。这个验证步骤，建议你也别跳过。