1. 为什么你的 Claude Code 总是“失忆”从一次真实翻车说起如果你刚开始用 Claude Code大概率经历过这样的场景第一次对话里你花了十分钟解释项目结构、命名规范、测试命令AI 表现得很聪明关掉终端第二天再打开它又变回一张白纸问你“这个项目是做什么的”。这不是模型能力问题而是你还没给它建立跨会话的长期记忆。Claude Code 的配置体系本质上解决三件事记住项目CLAUDE.md、约束行为settings.json、连接外部世界MCP。这三者分别对应“知识层”“规则层”“工具层”缺一个都会让协作体验打折。我见过太多人只写了一个几十行的 CLAUDE.md 就以为配置完了结果权限没管住、MCP 没接通AI 要么畏手畏脚不敢动文件要么乱跑命令把本地环境搞乱。这篇指南面向两类人第一次搭建 Claude Code 环境的开发者以及想把团队配置统一起来的 Tech Lead。我会给出三份可以直接复制的配置文件模板——CLAUDE.md、.claude/settings.json、.mcp.json然后逐项验证加载顺序、权限是否真的生效、MCP 是否连通。全程在本地终端操作不需要任何额外账号跟着敲就能跑通。先明确一个核心概念Claude Code 的配置是分层覆盖的。项目根目录的配置优先级最高其次是项目内.claude/目录最后是家目录~/.claude/的全局配置。理解这个优先级后面所有“为什么我的设置没生效”的问题都能自己排查。2. 三份配置文件的分工与加载顺序CLAUDE.md、settings.json、.mcp.json 到底谁先谁后在动手写文件之前必须先把加载顺序搞清楚否则你会遇到“明明写了规则 AI 却不遵守”的困惑。Claude Code 启动时的加载流程大致是这样的第一步读取全局配置~/.claude/settings.json和~/.claude/CLAUDE.md。这是你的个人偏好对所有项目生效比如你习惯用 dark 主题、默认模型选哪个、哪些命令永远禁止执行。第二步读取项目配置./.claude/settings.json和./CLAUDE.md。项目级配置会覆盖全局配置中的同名项。比如全局允许Bash(git *)但项目里 deny 了Bash(git push:*)那么在这个项目里 push 就会被拦住。第三步读取本地覆盖./.claude/settings.local.json和./CLAUDE.local.md。这两个文件通常加进.gitignore用来放你个人的临时调试配置不污染团队共享的规则。第四步注册 MCP 服务器读取项目根目录的.mcp.json。注意它不在.claude/里面而是直接放在项目根目录这是官方约定的位置。第五步注入 CLAUDE.md 内容作为系统提示的一部分。这里有个细节项目级CLAUDE.md和全局~/.claude/CLAUDE.md会同时注入不是覆盖关系。所以全局 CLAUDE.md 里写“我总是用 pnpm”项目 CLAUDE.md 里写“这个项目用 npm”AI 会同时看到两条可能产生冲突。建议全局 CLAUDE.md 只放真正通用的偏好项目相关的全部下沉到项目级。关于加载顺序可以用一个简单的实验验证。在全局 settings.json 里设置model: claude-sonnet-4-20250514在项目 settings.json 里设置model: claude-opus-4-20250514启动后输入/config查看当前模型你会看到项目级生效了。这就是覆盖机制的直接证据。还有一个容易踩的坑settings.json的 JSON 格式非常严格不允许注释不允许尾随逗号。很多人从别处复制配置时带了个逗号Claude Code 启动时不会报错而是静默忽略整个文件导致你以为配置生效了其实没有。写完文件后用python -m json.tool .claude/settings.json验证一下格式能省掉大量排查时间。理解了这套加载机制接下来就可以逐个文件落地了。我会先给模板再解释每个字段的作用最后用实际命令验证。3. 可直接复制的三份配置模板CLAUDE.md 协作规则 settings.json 权限模型 .mcp.json 工具链这一节是全文的核心三份文件我都会给出完整可复制的版本并标注每一行的意图。你可以直接建一个空项目跟着做。3.1 CLAUDE.md项目说明书模板在项目根目录创建CLAUDE.md内容如下# 项目概述 这是一个基于 FastAPI 的用户管理服务提供注册、登录、资料修改接口。 架构api/ 路由层 - services/ 业务层 - models/ 数据层禁止跨层直接调用。 # 常用命令 - 安装依赖pip install -r requirements.txt - 启动开发服务uvicorn app.main:app --reload - 运行测试pytest tests/ -v - 代码格式化ruff format . # 代码风格 - 所有函数必须有类型注解 - 使用 ruff 做 lint行宽 100 - 数据库查询必须参数化禁止字符串拼接 SQL # 架构约束 - models/ 下的文件只定义 ORM 模型不写业务逻辑 - 所有 API 路由必须验证 JWT Token白名单在 config.py 中维护 - 不要修改 legacy/ 目录下的任何文件那是待迁移的旧代码 # AI 行为指引 - 修改依赖版本前必须先说明原因并等待确认 - 生成新接口时同步生成对应的 pytest 测试用例 - 遇到不确定的架构决策先提问再动手这份文件控制在 40 行左右遵循了“越短遵循度越高”的原则。注意最后一条“先提问再动手”非常关键它能显著减少 AI 自作主张改坏代码的概率。3.2 settings.json权限与模型参数模板创建.claude/settings.json注意目录要先建好{ model: claude-sonnet-4-20250514, theme: dark, permissions: { allow: [ Bash(pip install *), Bash(pytest *), Bash(ruff *), Bash(uvicorn *), Read(./**), Write(./app/**), Write(./tests/**) ], deny: [ Bash(rm -rf *), Bash(git push *), Bash(curl *), Write(./legacy/**), Write(./.env) ] }, env: { PYTHONPATH: ., APP_ENV: development }, hooks: { PostToolUse: [ { matcher: Write, command: echo \[hook] file written at $(date)\ .claude/audit.log } ] } }几个关键点解释。permissions.allow和deny支持通配符Bash(pip install *)表示允许所有 pip install 开头的命令。deny的优先级高于allow所以即使你 allow 了Bash(git *)deny 里的Bash(git push *)依然会拦住 push。env字段注入的环境变量只在 Claude Code 会话内有效不会污染你的 shell。hooks里的PostToolUse会在每次写文件后追加一条审计日志方便回溯 AI 改了什么。如果你用的是 TaoToken 这类兼容 Anthropic 接口的服务模型 ID 需要填服务商提供的名称同时通过环境变量指定 Base URL。这部分在下一节会详细说。3.3 .mcp.json接入外部工具链在项目根目录创建.mcp.json{ mcpServers: { filesystem: { command: npx, args: [ -y, modelcontextprotocol/server-filesystem, ./docs ] }, sqlite: { command: uvx, args: [ mcp-server-sqlite, --db-path, ./data/app.db ] } } }这里注册了两个 MCP 服务器filesystem 让 AI 能读取./docs下的文档sqlite 让它能查询本地数据库。注意command必须是系统 PATH 里能找到的可执行文件npx和uvx分别来自 Node.js 和 Python 的 uv 工具链用之前确认装好了。三份文件建完后目录结构应该是your-project/ ├── CLAUDE.md ├── .mcp.json ├── .claude/ │ └── settings.json ├── app/ ├── tests/ └── requirements.txt别忘了把.claude/settings.local.json和CLAUDE.local.md加进.gitignore团队共享的配置才提交。4. 验证配置是否真的生效加载顺序、权限拦截与 MCP 连通性实测配置文件写完不代表生效这一节用实际命令逐项验证。我试过跳过验证直接开发结果半小时后才发现 settings.json 因为一个尾随逗号被整个忽略了白白浪费调试时间。4.1 验证 JSON 格式python -m json.tool .claude/settings.json /dev/null echo settings.json OK python -m json.tool .mcp.json /dev/null echo .mcp.json OK两条都输出 OK 才继续。如果报错根据提示的行号去修逗号或括号。4.2 验证 CLAUDE.md 被加载启动 Claude Code 后直接问它请复述一下这个项目的架构约束和禁止修改的目录。如果它准确说出“models/ 只定义 ORM 模型”“不要修改 legacy/ 目录”说明 CLAUDE.md 注入成功。如果它答不上来检查文件名大小写——必须是全大写的CLAUDE.mdclaude.md不会被识别。4.3 验证权限拦截在 Claude Code 里让它执行一个被 deny 的命令请帮我执行 git push origin main预期结果是它拒绝执行并提示该操作被权限配置禁止。如果它真的 push 了说明 deny 规则没生效回去检查Bash(git push *)的写法——通配符位置和空格都很敏感。再测试一个 allow 的命令请运行 pytest tests/ -v这次应该正常执行。一拦一放都符合预期权限模型才算验证通过。4.4 验证 MCP 连通性在 Claude Code 里输入/mcp命令会列出当前注册的所有 MCP 服务器及其状态。正常情况应该看到 filesystem 和 sqlite 都显示 connected。如果显示 failed通常是两个原因一是npx/uvx不在 PATH 里二是包名写错了。可以先用终端单独测一下服务器能不能启动npx -y modelcontextprotocol/server-filesystem ./docs如果这个命令能跑起来会挂起等待输入CtrlC 退出即可说明 MCP 服务器本身没问题问题在 Claude Code 的配置读取。检查.mcp.json是否在项目根目录而不是.claude/里面。4.5 验证加载顺序在全局~/.claude/settings.json里设theme: light项目.claude/settings.json里设theme: dark重启后输入/config看到 dark 就说明项目级覆盖了全局级。这个实验能帮你建立对覆盖机制的直觉。全部验证通过后你的 Claude Code 环境就算真正跑通了。接下来是排障环节把最常见的几个报错一次性讲清楚。5. 常见报错排查401、local proxy failed、reading choices、OAuth 一次讲透配置过程中最容易卡住的就是这几类报错我按出现频率排序逐个给排查路径。401 Unauthorized。这个报错说明 API Key 无效或没被正确读取。如果你用的是官方 Anthropic 服务检查ANTHROPIC_API_KEY环境变量是否设置。如果你用的是 TaoToken 这类兼容服务需要同时设置两个环境变量export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY你的key注意 Base URL 不要带末尾斜杠也不要带/v1后缀具体以服务商文档为准。设置完后用echo $ANTHROPIC_BASE_URL确认变量真的在当前 shell 里。很多人是在一个终端 export在另一个终端启动 Claude Code变量根本没传过去。local proxy failed。这个报错通常出现在你配置了本地代理端口但代理没启动的情况。检查你的环境变量里有没有HTTP_PROXY或HTTPS_PROXY指向一个没运行的本地端口。如果有unset HTTP_PROXY HTTPS_PROXY清掉再试。另外确认你的网络环境能正常访问 API 端点可以用curl -I https://taotoken.net/api测一下连通性。reading choices 相关报错。这类错误一般出现在模型返回格式不符合预期时根源往往是模型 ID 写错了。比如你填了一个服务商不支持的模型名接口返回了非标准结构客户端解析时就报 reading choices 失败。解决办法是核对服务商文档里的模型 ID 列表确保settings.json里的model字段和实际可用的名称完全一致。大小写、日期后缀都不能错。OAuth 相关报错。如果你在配置 MCP 服务器时遇到 OAuth 报错通常是因为该 MCP 服务器需要额外的授权流程而你的配置里没提供凭证。检查.mcp.json里对应服务器的env字段看是否需要填入 token 或 client id。对于不需要授权的本地 MCP 服务器比如 filesystem、sqlite不应该出现 OAuth 报错如果出现了说明你注册的服务器地址指向了一个需要授权的远程服务换成本地版本即可。配置改了不生效。这是最隐蔽的一类问题。Claude Code 在启动时读取配置运行中修改文件不会热加载。改完settings.json或CLAUDE.md后必须重启会话。另外确认你没有同时存在settings.json和settings.local.json且后者覆盖了前者——settings.local.json的优先级更高。MCP 服务器显示 connected 但工具调不动。这种情况通常是 MCP 服务器启动了但初始化失败。在终端单独运行该服务器的启动命令观察有没有报错输出。常见原因是数据库文件路径不对、依赖包版本冲突。把启动命令的 stderr 重定向到文件里看npx -y modelcontextprotocol/server-sqlite --db-path ./data/app.db 2 mcp-error.log。排查这类问题的通用思路是先隔离变量。把配置简化到最小可运行状态确认基础功能通了再逐项加回复杂配置。这样任何一步出问题都能立刻定位。6. 把配置变成团队资产从个人环境到统一协作标准配置搭好只是开始真正产生复利的是把它变成团队共享的资产。我的做法是项目级CLAUDE.md、.claude/settings.json、.mcp.json全部提交到 Git本地覆盖文件加进.gitignore。新成员 clone 下来就能获得一致的 AI 协作体验不需要每个人重新踩一遍坑。CLAUDE.md 的迭代节奏建议跟着代码 review 走。每次发现 AI 犯了同一个模式错误就把它写成一条规则加进去。比如连续三次看到 AI 在 API 层直接写 SQL就在架构约束里加一条“api/ 目录禁止 import models 以外的数据库模块”。规则是长出来的不是一次写完的。settings.json 的权限列表也要定期 review。项目初期可能 allow 得比较宽随着代码稳定逐步收紧 deny 列表。特别是涉及生产配置、密钥文件、部署脚本的路径一定要显式 deny。MCP 服务器的选择上优先用本地版本而不是远程版本。本地 MCP 不依赖网络响应快也不涉及凭证管理。只有当确实需要访问远程服务时才注册远程 MCP并且把凭证放在环境变量里而不是硬编码进.mcp.json。如果你还在用官方 API 直连可以考虑通过 TaoToken 这类兼容服务统一管理密钥和用量Base URL 填https://taotoken.net/api模型 ID 按服务商文档填。这样团队里每个人不需要各自申请 key用量也能集中查看。接入文档在 https://taotoken.net/doc 有详细说明API Keys 管理在 https://taotoken.net/api-keys。想先验证模型对话效果的话https://taotoken.net/chat 可以直接试。长期做编码和 Agent 任务的团队Coding Plan 在 https://taotoken.net/coding-plan 有更划算的额度方案。最后提醒一个容易忽略的点~/.claude/下的history.jsonl、projects/、file-history/是你和 AI 协作的宝贵记录尤其是file-history/里的文件版本是“撤销修改”能力的底层支撑。建议把这些纳入个人备份策略换机器时直接迁移过去AI 对你的项目记忆就能无缝延续。配置这件事花一个下午搭好后面每次结对编程都在享受复利。