Claude Code(二)环境配置

配置体系概览

Claude Code 内置了一套多层级配置架构，目的是为了平衡”个人开发习惯”与”团队项目规范”。通过全局设置、项目级配置及环境变量的组合，我可以控制 Agent 的行为、权限以及它对项目的理解。

配置作用域

配置项会按照特定的优先级生效。这种设计确保了团队规范的统一性，同时允许我在本地进行个性化调整。

作用域	配置文件位置	逻辑定义	是否同步 (Git)	典型应用场景
Managed (管理级)	系统级目录	强制约束	是 (IT 部署)	企业统一的安全红线。例如：强制禁止访问生产数据库，强制开启审计日志。此层级普通用户无法修改。
User (用户级)	~/.claude/	个人偏好	否	跨项目的通用习惯。例如：我默认开启了思维链模式，配置了个人的 GitHub Token，并安装了常用的辅助插件。
Project (项目级)	项目根目录 .claude/	团队规范	是	团队共享的规范。例如：统一的代码格式化命令，项目专属的 MCP 服务器配置，团队共用的 Lint 规则。
Local (本地级)	.claude/*.local.*	临时环境	否 (Git 忽略)	仅针对当前机器的特定配置。例如：本地数据库的连接串，临时调试用的 API Key。

配置隔离: 我始终遵循”配置隔离”原则。将涉及机密凭证的配置严格限制在 User 或 Local 作用域；将涉及工程规范的配置显式提交到 Project 作用域。

优先级与覆盖

当同一个配置项在多个作用域中同时存在时，优先级如下：

Managed (最高) > Command Line Flags > Local > Project > User (最低)

这意味着：

1. 我在命令行指定的参数（如 --model）优先级极高，适合临时测试。
2. 我的 Local 配置可以覆盖团队的 Project 配置（例如团队要求用 Python 3.9，但我可以在本地测试 Python 3.10）。
3. 任何配置都无法突破 Managed 层的限制。

功能模块分布

配置系统不仅管理键值对，还管理着 Agent 的扩展能力和记忆：

功能模块	用户级 (User)	项目级 (Project)	本地级 (Local)
Settings (行为)	~/.claude/settings.json	.claude/settings.json	.claude/settings.local.json
Subagents (能力)	~/.claude/agents/	.claude/agents/	—
MCP Servers (连接)	~/.claude.json	.mcp.json	~/.claude.json (项目状态缓存)
Memory (记忆)	~/.claude/CLAUDE.md	CLAUDE.md 或 .claude/CLAUDE.md	CLAUDE.local.md

核心配置文件详解

Claude Code 的”大脑”由三个核心部分组成：Settings (控制中枢)、Memory (项目记忆) 和 MCP (外部连接)。

Settings.json：行为控制

settings.json 定义了 Claude Code 的运行规则。它不关心我的代码业务逻辑，只关心 Agent 本身如何运作。

• Permissions (权限模型): 采用”最小权限原则 (Least Privilege)”。
  • allow: 明确放行的命令白名单。
  • deny: 绝对禁止的操作（如读取 .env，上传私钥）。
  • ask: 需要人工审批的敏感操作（默认策略）。
• Sandbox (沙箱环境): 我默认开启了沙箱模式。启用后，Bash 工具在隔离的容器化环境中运行，防止误操作影响系统文件，同时保证了环境一致性。
• Hooks (生命周期钩子): 类似于 Git Hooks。
  • PreToolUse: 在工具执行前拦截，可用于强制 Lint 检查。
  • PostToolUse: 工具执行后触发，可用于自动化测试反馈。

实际配置参考

{
  "permissions": {
    "allow": ["Bash(npm run *)", "Bash(git status)", "Bash(ls)"],
    "deny": ["Read(.env)", "Bash(curl -X POST *)"],
    "ask": ["Edit(package.json)"]
  },
  "sandbox": {
    "enabled": true,
    "timeout": 300
  },
  "autoUpdater": {
    "enabled": false
  }
}

权限合并逻辑：权限系统的合并策略是 “收敛合并” (Restrictive Merge)。如果在 User 层允许了 curl，但在 Project 层禁止了 curl，最终结果是禁止。安全限制总是优先于许可。

CLAUDE.md：项目记忆

如果说 settings.json 是大脑的结构，那么 CLAUDE.md 就是大脑中的知识。它是 Claude Code 最独特的特性之一，充当了项目级系统提示词的角色。

它与传统文档的区别在于：它主要是写给 AI 看的，而用户也可以随机动态优化。

• 构建指令: 我可以明确告诉它：”在这个项目里，运行测试必须用 make test-unit，而不是 npm test。”
• 架构约束: 明确”负面约束”。例如：”禁止引入新的 npm 依赖，除非经过批准”、”UI 组件必须与逻辑 Hook 分离”。
• 风格指南: 统一代码风格，减少 Code Review 的摩擦。

MCP Servers：外部能力

通过 .mcp.json，Claude Code 利用 Model Context Protocol (MCP) 协议连接外部工具。它允许 Claude 连接到：

• GitHub/GitLab: 直接读取 Issue 内容或 PR 评论。
• PostgreSQL/MySQL: 在只读权限下查询数据库 Schema，辅助编写 SQL。
• Browser: 实时抓取网页文档库。

记忆系统工作原理

Memory 机制是 Claude Code 区别于普通 Copilot 的核心。它通过结构化上下文注入，让 AI 理解项目结构。

上下文加载机制

Claude Code 通过 CLAUDE.md 文件来获取项目上下文。它不会一次性读取所有文件，而是根据我当前的工作目录 (CWD) 动态加载相关的 CLAUDE.md 文件。

加载逻辑：

1. 定位: 确定当前 Shell 所在的路径。
2. 回溯: 从当前路径向上查找至根目录，收集沿途所有的 CLAUDE.md。
3. 合并: 将收集到的 Markdown 文件按”子目录优先”的顺序合并。
4. 注入: 将合并后的文本作为 System Context 的一部分发送给模型。

场景演示：

/workspace/
├── CLAUDE.md              # [Layer 1] 全局规范：Java 项目通用配置
└── services/
    ├── payment-service/
    │   ├── CLAUDE.md      # [Layer 2] 服务规范：支付网关接口定义
    │   └── src/
    └── user-service/
        └── CLAUDE.md      # [Layer 2] 服务规范：用户数据隐私标准

当我 cd services/payment-service 后，Claude 加载的是 Layer 1 + Layer 2 (Payment)，不会触及 User Service 的配置，有效避免了跨服务的上下文污染，也减少了不必要的 Token 消耗。

动态维护

记忆不是静态的。

• /init: 初始化项目记忆文件。分析 package.json 等元数据，自动生成”第一份记忆”。
• /memory: 热更新记忆文件。当我在对话中纠正了 Claude 的一个错误（比如”不要用 Log4j，用 SLF4J”），我会立即使用 /memory 将这条规则写入文件，让下次会话不再重蹈覆辙。

环境变量与模型调优

环境变量 (Env Vars)

环境变量不仅用于鉴权，还用于微调 Runtime 行为：

• ANTHROPIC_API_KEY: 必须。
• BASH_DEFAULT_TIMEOUT_MS: 调整 Shell 命令的”耐心值”。对于大型编译任务，我通常会调大此值。
• CLAUDE_LOG_LEVEL: 设置为 debug 可查看详细的 Prompt 交互日志，用于排查为何 Claude “不听话”。

Thinking Mode

Claude 3.7+ 引入的 Thinking Mode 通过增加推理时间来提高输出质量。

• 原理: 模型在输出最终代码前，会进行一段内部推理，检查逻辑漏洞。
• 适用场景: 复杂的重构、算法设计、涉及多个文件联动的修改。
• 不适用场景: 简单的语法修正、文档补全（耗时且消耗 Token）。

高效协作技巧

结构化需求 (Structured Prompting)

我把 Claude 当作一名高级工程师。使用 DOD (Definition of Done) 清单：

“请实现用户登录功能。” (❌ 弱指令)

“请实现用户登录 API，要求如下：

1. 接口: POST /api/login，接收 JSON。
2. 验证: 使用 Zod 进行 Schema 校验。
3. 安全: 密码必须使用 Argon2 哈希。
4. 测试: 编写对应的 Vitest 单元测试。
5. 规范: 遵循 @docs/api-guide.md 中的错误码定义。” (✅ 强指令)

模块化引用 (@References)

CLAUDE.md 的 @ 语法支持引用文件，这实际上构建了一个知识索引。

• @package.json: 告诉 Claude 当前项目的依赖版本。
• @src/types.ts: 告诉 Claude 全局的数据结构定义。

我发现这种引用方式能让 Claude 在不加载完整文件的情况下，精准获取关键上下文。

结语

在实践中，我对配置系统的理解经历了一个转变：最初我把它当成”选项清单”来填写，后来才意识到它更像是在给 Claude 建立项目认知。CLAUDE.md 写得越清晰，我在每次会话里花在”解释背景”上的时间就越少。

目前我的工作流程是：用 /init 生成基础骨架，每当发现 Claude 因缺少上下文而犯错，就立刻用 /memory 把这条经验固化进 CLAUDE.md；权限控制则通过 settings.json 按需逐步放开。

下一篇预告：Claude Code(三)核心解密：揭秘上下文引擎与提示词系统-了解Claude Code如何管理上下文，了解如何节省token