Claude Code 三个月实战：用 CLAUDE.md 与 settings.json 把效率提升 3 倍的最佳实践

1. 为什么你的 Claude Code 用了一个月还是「不听话」先说结论Claude Code 本身不慢慢的是每次都要重新交代一遍项目背景。我接手过一个中途换人的项目代码没文档、测试跑不起来、目录结构靠猜。第一周我几乎在重复同一件事告诉它构建命令是什么、哪个目录别乱动、提交信息按什么格式写。等到第三周我把这些内容沉淀进CLAUDE.md和settings.json同样的任务量来回沟通次数肉眼可见地掉下来。这篇聚焦的是长期使用中的配置沉淀不是「怎么装 Claude Code」。适合已经能跑起来、但每次开新会话都要重新解释项目的人也适合同时维护三四个仓库、经常在项目之间切换的人。核心就两条主线CLAUDE.md负责项目记忆settings.json负责权限与环境骨架。再配合一个统一的 API 通道把 Key 管理这件事从每个项目里抽出来。我试过最笨的办法把项目说明写在聊天框里每次粘贴。结果是上下文一满就被挤掉AI 该忘还是忘。后来改成文件沉淀重启会话后它自己就能读到这才是长期可用的做法。2. 前置准备用 TaoToken 统一 Key 与 API 通道在写配置文件之前先把「请求往哪发、用哪个 Key」这件事定下来。多项目切换时最烦的就是每个仓库一套环境变量改来改去还容易把 Key 提交上去。我的做法是走一个统一通道项目里只引用环境变量名不写死值。TaoToken 在这里扮演的是统一入口官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。你需要先去控制台拿一个 Key然后把它配到环境变量里Claude Code 通过ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN两个变量识别。拿 Key 的入口在控制台接入细节看文档这两处配合着看最省事控制台创建/管理 Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite接入文档环境变量写法https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite如果你只是想先验证模型通不通可以用模型对话页面发一条测试消息https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。长期编码和 Agent 场景建议直接看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。环境变量建议写在 shell 的 profile 里而不是项目文件里。这样切项目时不用改也不会误提交# ~/.zshrc 或 ~/.bashrc export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的Key改完执行source ~/.zshrc再用echo $ANTHROPIC_BASE_URL确认生效。这一步做完后面所有项目共用同一个通道settings.json里就不用再碰 Key 了。3. 可复制配置CLAUDE.md 模板与 settings.json 骨架3.1 CLAUDE.md 要写「可执行的事实」不是口号很多人写CLAUDE.md没效果问题出在写的是愿望而不是事实。「代码要写好」「遵循最佳实践」这种句子AI 没法翻译成动作。换成具体命令、具体路径、具体命名规则它执行得就很干脆。下面是我现在用的项目级模板可以直接抄把命令和路径换成你自己的# 项目规范 ## 开发环境 - Node.js 18包管理器 pnpm 8 - 安装依赖: pnpm install - 启动开发: pnpm dev - 构建: pnpm build ## 代码风格 - 缩进 2 空格不用 Tab - 组件名 PascalCase函数名 camelCase - 常量 UPPER_SNAKE_CASE - 导入顺序: 内置模块 - 第三方 - 本地 ## 提交规范 - 提交前必须运行 pnpm test - 提交信息格式: type: description - type 可选: feat / fix / docs / style / refactor / test ## 目录结构 - src/api 接口路由 - src/components 通用组件 - src/hooks 自定义 Hook - src/utils 工具函数 - 不要修改 src/generated 下的文件那是自动生成的注意最后一条「不要修改」这类负向约束非常有用。AI 默认会「顺手帮你优化」明确划出禁区能省掉很多回滚。3.2 文件放哪作用域对照CLAUDE.md可以放在不同位置作用范围不一样。放错地方是「写了没反应」的头号原因。位置作用域典型用途./CLAUDE.md当前项目团队共享规范提交到 Git~/.claude/CLAUDE.md所有项目个人偏好比如回复语言、注释风格./CLAUDE.local.md当前项目本地个人临时配置加进.gitignore推荐结构是这样团队规范和个人偏好分开互不干扰my-project/ ├── CLAUDE.md # 团队规范提交 ├── CLAUDE.local.md # 本地配置不提交 └── src/3.3 规则太长就拆.claude/rules/ 按需加载单个CLAUDE.md建议控制在 200 行以内。我早期写过 400 多行结果后面的内容基本被忽略。拆成多个文件后效果好很多尤其是前后端规范差异大的项目my-project/ ├── CLAUDE.md └── .claude/ └── rules/ ├── frontend.md ├── backend.md └── testing.mdrules还支持条件加载用 frontmatter 里的paths指定触发范围。只有 AI 处理匹配文件时这段规则才会进上下文既省 token 又不互相干扰--- paths: - src/api/**/*.ts - routes/**/*.js --- # API 开发规范 - 遵循 RESTful 风格 - 错误响应统一为 { code, message, data } - 每个接口补 OpenAPI 注释3.4 settings.json权限与环境骨架CLAUDE.md管「怎么做」settings.json管「能做什么」。把常用命令加进允许列表能减少大量确认弹窗把危险操作挡在外面能避免误删。项目级配置放在.claude/settings.json本地覆盖放.claude/settings.local.json{ permissions: { allow: [ Bash(pnpm test:*), Bash(pnpm lint:*), Bash(pnpm build:*), Bash(git status), Bash(git diff:*) ], deny: [ Bash(rm -rf:*), Bash(git push --force:*), Read(./.env), Read(./secrets/**) ] }, env: { NODE_ENV: development } }deny里的Read(./.env)很关键。哪怕 Key 走的是环境变量也建议把敏感文件读权限关掉多一层保险。多项目切换时如果发现规则串了可以在本地配置里排除其他项目的记忆文件{ claudeMdExcludes: [ ../other-project/CLAUDE.md ] }4. 验证重启会话确认记忆生效、请求走通配置写完不验证等于没写。我固定做两步检查。第一步确认记忆被加载。重启 Claude Code 会话直接问它你看到了哪些项目规则把构建命令和提交格式复述一遍。如果它能准确说出pnpm build和type: description说明CLAUDE.md生效了。如果答得含糊八成是文件位置不对或者被别的规则覆盖了。第二步确认请求走通。在会话里让它跑一个只读命令比如运行 git status然后告诉我当前分支。能正常返回分支名说明 API 通道和权限配置都没问题。如果卡在鉴权先回到第 2 节检查ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN是否在当前 shell 生效。想单独验证模型连通性用模型对话页面发一条消息最快https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。第三步验证条件规则。让 AI 改一个src/api/下的文件观察它是否按backend.md里的错误响应格式来写。这一步能确认paths触发是否正常。5. 本篇常见错排查问题一CLAUDE.md 写了但 AI 不遵守。先查指令是否具体再看文件位置。放在项目根目录的./CLAUDE.md才会被当前项目读取放到子目录里通常不生效。最后检查有没有和~/.claude/CLAUDE.md里的规则冲突冲突时以更具体的那条为准。问题二规则太多AI 记不全。这是上下文预算问题不是 AI 笨。分层处理核心规范放CLAUDE.md专业规范放.claude/rules/按需加载可复用的工作流单独抽出来手动触发。别把所有东西塞进一个文件。问题三不同项目的规则串了。典型症状是在 A 项目里 AI 提到 B 项目的目录。用claudeMdExcludes排除或者检查是不是把规则写进了~/.claude/CLAUDE.md这个全局位置。问题四权限弹窗太多打断节奏。把高频只读命令加进allow比如git status、pnpm lint。但rm -rf、git push --force这类一定要留在deny里别图省事放开。问题五改了 settings.json 没反应。配置文件是会话启动时读取的改完要重启会话。另外确认改的是.claude/settings.json而不是别的路径JSON 语法错误也会导致整份配置被忽略可以用编辑器校验一下。问题六请求报鉴权失败。九成是环境变量没生效。新开一个终端窗口执行echo $ANTHROPIC_AUTH_TOKEN如果为空说明 profile 没加载或者写错了文件。注意别把 Key 写进settings.json提交到仓库。6. 把配置沉淀成习惯三个月下来最大的体会是Claude Code 的效率不取决于模型多强而取决于你愿不愿意花半小时把项目事实写清楚。CLAUDE.md是给 AI 的项目说明书settings.json是安全边界统一 API 通道是省掉重复配置的底座。三者配齐新会话开局就能干活多项目切换也不用重新交代。如果你还在每个项目里单独配 Key建议先把环境变量统一到 TaoToken 通道再去控制台建 Key、对照文档接入控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。长期编码场景直接上 Coding Plan 更省心https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。最后留一个我一直在用的习惯每次踩到新坑顺手往CLAUDE.md或对应rules文件里补一条具体规则。配置不是一次写完的是跟着项目一起长出来的。