Claude Code 配置文件怎么写：settings.json 与 CLAUDE.md 详细完整编写步骤指南

先说几个核心判断：Claude Code 的配置体系其实并不复杂，但很多人容易混淆三份文件的核心分工。简单来说，settings.json 负责技术层面的硬性约束——权限、环境变量、模型选择等，由客户端强制执行；CLAUDE.md 则是面向模型的“软指令”，用于引导其行为——例如编码规范、项目架构、工作流程；.mcp.json 用于对接外部工具或数据源。三者各司其职，只有理解这种分工，写配置时才不会跑偏。

举个例子，如果你要“无条件拦截某个命令”，应该写在 settings 的权限规则或 hook 里，而不是写在 CLAUDE.md 里指望模型自觉遵守。前者是铁律，后者只是建议。

一、Claude Code 有哪些配置文件

三类配置文件，分别解决三个不同层面的问题。读懂它们的定位，比死记硬背字段名更重要：

核心区别一句话概括：settings.json 是“你必须这么做”，CLAUDE.md 是“我建议你这么做”。

二、settings.json 放在哪：四个作用域与优先级

settings.json 按作用域存放在不同位置，加载时遵循固定优先级合并规则。下表列出所有存放位置：

优先级从高到低（依据 Claude Code 官方文档）：

企业托管（无法被覆盖）
命令行参数（仅当前会话）
本地 .claude/settings.local.json
项目 .claude/settings.json
用户 ~/.claude/settings.json

需要特别注意：权限规则是跨作用域“合并”而非“覆盖”。也就是说，各级的 allow 和 deny 会叠加生效，并不是你写好项目级配置就能冲掉用户级的设置。

三、settings.json 怎么写：完整示例

一个典型的 settings.json 结构如下，包含了最常用的权限、环境变量与元信息字段：

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-5",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ],
    "ask": [
      "Bash(git push *)"
    ]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1"
  },
  "cleanupPeriodDays": 20
}

常用字段速查：

• model：覆盖默认模型（修改后需重启会话生效）
• permissions：权限规则（allow / deny / ask，支持热加载）
• env：注入所有会话的环境变量
• apiKeyHelper：生成鉴权值的 shell 命令
• hooks：生命周期事件触发的自定义命令
• cleanupPeriodDays：会话文件保留天数（默认 30）

四、权限怎么配：allow / deny / ask 三类规则

权限是 settings.json 中最常用也最关键的配置项，分为三种规则，支持 * 通配符：

• allow：匹配的工具调用自动放行，例如 "Bash(npm run test *)"
• deny：匹配的工具调用始终拦截，例如 "Read(./.env)"
• ask：匹配的工具调用每次都弹窗确认，例如 "Bash(git push *)"

关键规则：deny 优先级高于 allow。当一条命令同时命中 allow 和 deny 时，以 deny 为准，始终被拦截。这也是保护敏感文件（如 .env、secrets/）的推荐做法——把它们写进 deny，即使其他规则放行也不会泄露。

五、CLAUDE.md 怎么写：位置与有效写法

CLAUDE.md 是给模型的持久化指令文件，每次会话启动时都会完整读入上下文。它同样按作用域分布：

写出高遵循度 CLAUDE.md 的四条官方建议：

• 控制长度：单文件建议 200 行以内，过长会消耗上下文并降低遵循度
• 具体可验证：“使用 2 空格缩进”比“格式化好代码”更有效；“提交前运行 npm test”比“测试你的改动”更明确
• 用结构化格式：markdown 标题 + 列表分组，比大段文字更容易被扫描
• 避免冲突指令：两条规则矛盾时模型会随机选一条，需定期清理过时内容

小技巧：在项目根目录运行 /init，Claude 会分析代码库自动生成一份初始 CLAUDE.md。

六、进阶：@path 导入与 .claude/rules 路径规则

对于大型项目，可以采用两种机制把配置拆得更清晰。

@path 导入：CLAUDE.md 支持用 @path/to/file 语法导入其他文件，启动时一并加载。相对路径基于文件自身解析，最多递归 4 层：

See @README for project overview and @package.json for a vailable commands.

# 额外指令- git 工作流
@docs/git-instructions.md

路径作用域规则：在 .claude/rules/ 放置按主题拆分的 md 文件，配合 YAML frontmatter 的 paths 字段，可让规则只在 Claude 处理匹配文件时才加载，从而节省上下文：

---
paths:
- "src/api/**/*.ts"
---

# API 开发规则
- 所有接口必须包含入参校验
- 使用统一的错误响应格式

七、团队协作：哪些配置该提交 git

团队共享配置的关键在于分清“该提交”和“不该提交”的文件，避免把个人配置或密钥混入版本库：

在接入外部模型服务时，Claude Code 兼容标准的 OpenAI SDK 与自定义网关配置，开发者可通过 env 字段或 Router 配置指向自建或第三方推理端点。例如结合七牛云的 Claude Code Router 配置，即可在国内直接访问统一的多模型推理入口，无需改动业务代码。

常见问题

Q：settings.json 和 CLAUDE.md 到底有什么区别？
settings.json 是技术配置，由客户端强制执行，用于设定权限、环境变量、模型、hooks；CLAUDE.md 是给模型的指令，属于软引导，用于编码规范、架构说明、工作流。需要“无论如何都拦截”的场景用 settings 的 permissions.deny 或 hook；需要“引导模型倾向某种做法”的场景写入 CLAUDE.md。

Q：项目配置和用户配置冲突了以谁为准？
按优先级：企业托管 > 命令行参数 > 本地 settings.local.json > 项目 settings.json > 用户 settings.json。高优先级覆盖低优先级。但权限规则例外——它是跨作用域合并叠加，而不是覆盖。

Q：怎么禁止 Claude 读取 .env 等敏感文件？
在 settings.json 的 permissions.deny 中加入对应匹配模式，例如 "Read(./.env)"、"Read(./.env.*)"、"Read(./secrets/**)"。deny 优先级高于 allow，即使其他规则放行也会被拦截。

Q：CLAUDE.md 写多长合适？
官方建议单文件控制在 200 行以内。过长会占用更多上下文并降低模型遵循度。内容较多时，可以用 .claude/rules/ 的路径作用域规则按需加载，或用 @path 导入拆分组织（注意导入文件仍会在启动时载入上下文）。

Q：settings.json 改完要重启吗？
大部分字段支持热加载，包括 permissions、hooks、apiKeyHelper；但 model、outputStyle 等字段需要重启会话才能生效。

结语

Claude Code 的配置体系可以概括为一句话：用 settings.json 做技术强制，用 CLAUDE.md 做行为引导，按作用域分层管理并区分 git 提交范围。根据 Claude Code 官方文档，权限规则跨作用域合并、deny 优先于 allow、CLAUDE.md 建议控制在 200 行内，这三条规则最容易被忽视，却对实际效果影响最大。建议团队将共享配置提交版本库，个人配置用 .local 后缀隔离，并善用 /init 生成起始文件。

延伸资源
Claude Code Router 与多模型接入配置：developer.qiniu.com/aitokenapi/13415/tools-claude-code-router-configuration-instructions