如果你已经把 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项目级别的 MCPModel 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用户提交消息时触发。StopClaude 停止输出时触发。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.mdClaude 在操作该目录下的文件时会自动加载对应的子目录记忆。比如project-root/ .claude/ CLAUDE.md src/ utils/ CLAUDE.md这样src/utils/CLAUDE.md里就可以写“本目录负责通用工具函数禁止引入 React 相关依赖”这类局部规范比全部堆在根目录要清晰得多。当一个项目的根目录与子目录CLAUDE.md内容冲突时子目录的记忆优先因为它更具体。4. 自定义命令与 MCP把高频操作变成一句话4.1 自定义斜杠命令 commandssettings.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 服务器配置与选型建议MCPModel 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): descriptionscope 必须填写。 # 重要注意事项 - packages/shared 里的代码会被前后端同时引用修改前务必评估影响范围。 - 构建产物目录不要手动修改。 - 新增依赖前必须先与团队确认避免引入冗余包。 - 测试相关文件统一放在 __tests__ 目录。 # 参考文档 - API 设计规范见 docs/api-design.md - 数据库设计说明见 docs/database.md这份模板的精髓在于用简短条目把事情说清楚不追求面面俱到。有了它Claude 在一个新会话里打开项目就知道“这是什么项目、怎么运行、改代码时要注意什么”省去了一大轮对话。5.3 从零到生效的四个步骤配置文件不是写完就完事的建议你按这个流程走一遍创建目录结构在项目根目录执行mkdir -p .claude确认目录已存在。写入配置文件把上面settings.json的内容按需修改后放进去。撰写 CLAUDE.md根据模板填充项目信息文档引用可以先空着之后再补。重启会话验证新建一个会话随便问一句“这个项目怎么启动”看它能否正确回答。再让它执行一个你配置了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 我的排错顺序参考遇到配置问题我一般按下面这个顺序排查效率比较高先确认文件路径和文件名完全正确。校验 JSON 合法性把文件丢进 JSON 校验工具过一遍。重启会话排除缓存和会话上下文干扰。查看会话启动时的加载日志确认配置是否被读取。如果还不行检查是否有settings.local.json或用户级配置覆盖了目标字段。最后再考虑是不是版本差异查阅当前版本对应的配置字段名是否有所调整。说实话配置系统本身不复杂绝大多数问题都出在文件路径、JSON 格式和优先级打架这三件事上。搞懂这三件事项目级配置基本就玩明白了。最后再分享一个小技巧配置写完之后可以专门用一个“测试会话”来验证。先把所有权限规则都故意触发一遍把deny、ask、allow三种情况都点一遍确认行为符合预期再放心地在日常开发中使用。我第一次配置完没有做这个验证结果在真实开发时才发现deny规则被通配覆盖了白白浪费了一下午。这个验证步骤建议你也别跳过。