当我们深入审视 Claude Code 的工作原理时，会发现其本地配置体系设计得极为精细。与传统 IDE 的简单配置文件不同，.claude目录承载了权限控制、上下文管理、MCP 服务器配置、插件系统等多维度的配置职责。这种分层设计不仅确保了团队协作时的配置共享，更为个人开发者提供了灵活的自定义空间。本文将系统性地解析 Claude Code 的文件夹结构与配置机制，为开发者提供一份可操作的工程实践指南。
四层作用域机制的设计哲学
Claude Code 采用了四层作用域系统来管理配置，这种设计在企业级工具中极为常见，但在 AI 辅助编程领域却是一项创新。四个作用域按照优先级从高到低依次为：Managed（托管）、Local（本地）、Project（项目）、User（用户）。每一层都有明确的职责边界和使用场景，理解这一机制是掌握 Claude Code 配置的关键第一步。
Managed 作用域适用于企业 IT 部门通过 MDM（移动设备管理）或组策略统一部署的安全策略。这些配置无法被用户或项目级别的设置覆盖，确保了组织级别的安全合规要求得到强制执行。例如，企业可以强制禁用某些网络权限或要求必须使用特定的 MCP 服务器。在 macOS 平台上，托管设置通过 com.anthropic.claudecode 域推送；在 Windows 上则通过注册表键 HKLM\SOFTWARE\Policies\ClaudeCode 实现。
User 作用域的配置位于用户主目录下的 ~/.claude/ 目录中，作用范围覆盖该用户的所有项目。这是最常用的个人配置层级，适合放置主题偏好、常用的 API 密钥、环境变量等跨项目生效的设置。Project 作用域则位于项目根目录的 .claude/ 文件夹，其中的 settings.json 会被提交到 Git 仓库，实现团队间的配置共享。Local 作用域通过 .claude/settings.local.json 文件实现，其独特之处在于 Claude Code 会自动将其添加到 Git 忽略列表，确保个人偏好不会意外泄露到代码仓库中。
这种分层设计的核心思想是：组织策略 > 个人偏好。当同一设置在多个层级中出现冲突时，更高优先级的配置会覆盖低优先级的配置。例如，若用户在个人设置中允许执行 Bash(curl *) 命令，但项目设置中明确禁止该操作，则项目设置会生效。这一机制确保了企业安全策略不会被个人设置所绕过。
核心配置文件的结构与功能
深入理解各个配置文件的作用，是定制 Claude Code 工作环境的基础。Claude Code 的配置文件可以分为三大类：设置文件、上下文文件、以及扩展文件。每类文件都有其特定的存在位置和生效规则。
settings.json 与 settings.local.json
settings.json 是 Claude Code 的官方配置机制，采用 JSON 格式定义层级化的设置选项。在项目层级（.claude/settings.json）中，通常包含团队共享的权限规则、MCP 服务器定义、环境变量等。在用户层级（~/.claude/settings.json）中，则放置个人偏好的设置如主题、编辑器模式等。settings.local.json 则是个人 Overrides 的专属位置，适合放置仅在当前机器上有效的配置，例如本地开发环境的特殊路径映射。
一个典型的项目级 settings.json 配置如下所示：根级别的 $schema 字段指向官方 JSON Schema，可为 IDE 提供自动补全和验证功能；permissions 对象定义了允许、询问和拒绝的权限规则；env 对象则用于设置环境变量。需要特别注意的是，某些设置项如 autoMode 和 useAutoModeDuringPlan 不会从共享的项目设置中读取，这是为了防止团队成员被迫接受可能不适合个人工作风格的配置。
权限规则采用 Tool(specifier) 的格式，其中工具名称包括 Bash、Read、Edit、WebFetch 等，限定符则用于精确匹配具体命令或文件路径。例如，Bash(npm run *) 只匹配以 npm run 开头的命令，而 Read(./.env) 则精确指向环境变量文件。这种细粒度的权限控制是 Claude Code 安全模型的重要组成部分。
CLAUDE.md 上下文文件
CLAUDE.md 文件是 Claude Code 实现持久化项目上下文的机制，其设计灵感来源于 GitHub 的 CONTRIBUTING.md 和 README.md 命名惯例，但功能更为强大。Claude Code 会主动读取项目根目录的 CLAUDE.md 文件，将其内容加载到系统提示中，从而在每次会话开始时获得项目的架构信息、编码规范、工作流程等上下文。
在用户层级（~/.claude/CLAUDE.md）中，可以放置全局性的开发规范和偏好设置，这些设置会自动应用到所有项目中。在项目层级，既可以将 CLAUDE.md 放在项目根目录，也可以放在 .claude/ 子目录中。两者的区别在于：根目录的 CLAUDE.md 会被提交到版本控制，适合团队共享的项目规范；.claude/ 内的版本则可以包含更多与特定开发环境相关的细节。
除了标准化的 CLAUDE.md，Claude Code 还支持 CLAUDE.local.md 文件，该文件专门用于个人项目笔记，同样会被自动 Git 忽略。这为开发者提供了一个记录临时想法、待办事项或项目特定决策的安全空间，无需担心这些敏感信息被意外提交。
MCP 服务器与扩展配置
MCP（Model Context Protocol）服务器的配置分布在多个位置，体现了作用域设计的精细化考量。用户级别的 MCP 配置位于 ~/.claude.json 文件中，项目级别的则位于 .mcp.json。这种分离设计使得团队可以统一管理项目依赖的 MCP 服务器（如数据库连接、GitHub 集成等），而个人可以自由添加工作流工具而不影响团队成员。
MCP 服务器的启用控制也遵循作用域优先级。通过 enabledMcpjsonServers 和 disabledMcpjsonServers 这两个设置项，团队可以指定哪些 MCP 服务器默认启用或禁用。个人用户可以在此基础上通过本地配置进行微调。值得注意的是，企业还可以通过托管设置中的 allowedMcpServers 和 deniedMcpServers 来强制推行 MCP 服务器使用策略。
本地状态管理与会话持久化
Claude Code 的本地状态管理是其区别于传统 CLI 工具的核心特色之一。除了静态的配置文件，Claude Code 还维护着动态的运行时状态，包括会话历史、内存摘要、以及各种缓存数据。理解这些状态的管理机制，有助于开发者更好地控制数据隐私和会话恢复能力。
会话内存系统
Claude Code 的会话内存系统是其状态管理的核心创新。该系统会在后台持续运行，自动将过去的工作上下文总结为结构化的记忆片段，并持久化到磁盘。当新会话启动时，这些记忆会被主动召回，帮助 Claude Code 快速恢复之前的任务上下文，而无需用户重复解释。
具体来说，会话内存的工作流程如下：系统在每次交互中分析对话内容，识别关键的任务决策、技术选型和重要上下文，并将这些信息写入项目的会话目录中。这些摘要以结构化的形式存储，便于后续快速检索。在新会话开始时，Claude Code 会显示 “Recalled X memories” 的提示，用户可以通过快捷键（Ctrl+O）查看具体被召回的记忆内容。
/remember 命令与持久化桥梁
/remember 命令建立了会话记忆与持久化配置之间的桥梁。当用户在当前会话中意识到某个决策或模式具有长期价值时，可以调用该命令来提议将其升级为永久的项目规则。Claude Code 会生成建议的更新内容，用户审核确认后，这些规则会被写入 CLAUDE.local.md 文件，从而在未来的所有会话中自动生效。
这一机制的设计体现了 Claude Code 对渐进式知识沉淀的重视。开发者无需一次性编写完整的项目规范，而是可以随着项目的演进，自然地将重要的模式和决策记录下来。这种方式是自下而上的，与传统的自上而下的文档编写方式形成鲜明对比。
存储位置与清理策略
会话数据和记忆的默认存储位置可以通过 autoMemoryDirectory 设置项自定义。该设置接受带 ~/ 展开的路径，但存在一个重要的限制：项目级别的设置不允许重定向内存目录，这是为了防止共享仓库将内存写入敏感的个人目录。内存清理策略由 cleanupPeriodDays 参数控制，默认值为 30 天，即超过此期限的非活跃会话数据会被自动删除。设置为 0 则会完全禁用会话持久化。
工程实践建议
基于以上分析，我们可以总结出一套实用的 Claude Code 配置策略。首先，对于团队项目，应将共享的权限规则、MCP 服务器配置和基本的项目规范放入 .claude/settings.json 并提交到版本控制。这些配置应当经过团队讨论，确保既能保证开发效率，又不过度限制个人灵活性。
其次，个人开发者的全局配置应集中在 ~/.claude/settings.json 中，定义跨项目生效的偏好设置，如默认模型、工作努力级别、编辑器模式等。对于特定项目的个人偏好，则应写入 .claude/settings.local.json，利用自动 Git 忽略机制保护隐私。
第三，建议充分利用 CLAUDE.md 作为项目知识的载体。新项目启动时，可以先创建一份最小化的规范文档，随着项目发展逐步补充。随着时间推移，通过 /remember 命令将重要的会话决策沉淀到文档中，形成一个活的项目知识库。
最后，企业用户应当认真评估托管设置的必要性。在安全敏感的环境中，通过托管设置强制推行权限策略是必要的；但在相对开放的工作场景中，过度严格的托管配置可能会影响开发体验。建议采用渐进式的策略部署方式，先从推荐性配置开始，再根据实际情况逐步收紧。
资料来源：本文技术细节主要参考 Claude Code 官方文档（code.claude.com/docs/en/settings）的配置参考部分，该文档详细阐述了作用域系统、权限规则和各类配置选项的完整规范。