企业官网建设流程全解析

004、.claude目录结构逐文件解析：settings.json、credentials、memory、projects

从一次诡异的API调用失败说起

上周五晚上，团队一个小伙子在CI流水线里跑Claude Code，突然报了个“401 Unauthorized”。他检查了环境变量，确认API Key没问题，重新部署了三次，问题依旧。我让他把项目根目录下的.claude目录打包发过来，打开一看——credentials文件里赫然写着另一个项目的API Key，而且settings.json里配的model是claude-3-opus，但项目实际需要的是claude-3-sonnet。

这种问题我见过不下十次。.claude目录就像Claude Code的“神经系统”，每个文件各司其职，但大多数人只把它当成一个黑盒。今天就把这个目录拆开揉碎了讲清楚。

settings.json：你的默认配置，但别让它成为枷锁

{"model":"claude-3-sonnet-20240229","maxTokens":4096,"temperature":0.7,"systemPrompt":"你是一个资深Python工程师，代码必须包含类型注解","autoExecute":false,"timeout":120000}

这个文件控制的是Claude Code的运行时行为。注意几个关键点：

model字段——这里踩过坑。如果你在settings.json里写死了model，那么无论你在命令行怎么传--model参数，都会被这个值覆盖。正确的做法是：settings.json里只写项目通用的模型，比如sonnet，需要opus的时候用命令行参数临时覆盖。别像我那个同事一样，把生产环境的model写死成opus，结果每次调用都多花三倍token费用。

autoExecute——默认是false，我建议保持这个值。设为true的话，Claude Code会直接执行它认为合适的命令，这在调试阶段可能造成意外。有一次我忘了关这个开关，它直接在生产环境的数据库上跑了个DROP TABLE——虽然它确实是在执行我之前的指令，但那个场景下我本意只是“看看表结构”。

timeout——单位是毫秒。对于复杂任务，120秒可能不够。我习惯设成300000（5分钟），特别是处理大型代码库重构的时候。但注意，这个值不是越大越好，过长的超时会让Claude Code在死循环里空转，浪费token。

credentials：密钥的“保险柜”，但别把它当垃圾桶

这个文件存储的是API认证信息，格式很简单：

ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxx OPENAI_API_KEY=sk-xxxxxxxxxxxx

最致命的错误：把这个文件提交到Git仓库。我见过有人把credentials写进.gitignore，但忘了检查子模块里的.claude目录。更隐蔽的问题是：如果你用claude init初始化项目，它会自动生成一个空的credentials文件，但不会自动加入.gitignore。你需要手动加。

我的做法：credentials文件里只放一个占位符：

ANTHROPIC_API_KEY=YOUR_API_KEY_HERE

然后在CI/CD环境变量里注入真实的key。这样即使有人误提交，泄露的也只是占位符。本地开发时，用export ANTHROPIC_API_KEY=xxx设置环境变量，Claude Code会优先读取环境变量，而不是credentials文件。

另一个坑：credentials文件支持多行，但每行只能有一个key-value对。别想着用JSON格式或者加注释——Claude Code解析这个文件的时候会直接忽略不符合KEY=VALUE格式的行，而且不会报错。你写了个注释# 这是生产环境的key，它默默跳过，你以为是配置生效了，实际上根本没读到。

memory：Claude Code的“短期记忆”，但别指望它持久

memory目录存储的是Claude Code在对话过程中积累的上下文信息。结构大概是：

.claude/memory/ ├── session_abc123.json ├── session_def456.json └── global.json

session_xxx.json——每次对话生成的临时记忆文件。包含了你在这个session里提到的关键信息、代码片段、决策记录。Claude Code用它来保持对话的连贯性。

global.json——跨session的持久记忆。这里存的是你明确告诉Claude Code“记住这个”的内容。比如你让它记住项目的编码规范、数据库连接字符串、部署流程。

实际使用中的问题：memory文件不会自动清理。如果你每天用Claude Code，一个月后memory目录里可能有上百个session文件。这些文件虽然不大，但Claude Code在启动时会扫描整个memory目录，文件越多，启动越慢。

我的建议：每周清理一次memory目录，只保留最近7天的session文件。写个cron job或者GitHub Actions：

find.claude/memory-name"session_*.json"-mtime+7-delete

更重要的：别把敏感信息写进memory。Claude Code会把memory内容作为prompt的一部分发送给API。如果你在对话里说了数据库密码，它可能被写进session文件，然后在下一次对话中被发送出去。虽然Anthropic有数据隐私保护，但多一层防护总没错。

projects：多项目管理的关键，但大多数人用错了

projects目录是Claude Code 0.2.0之后引入的功能，用于管理多个项目的独立配置。结构：

.claude/projects/ ├── project-a/ │ ├── settings.json │ └── memory/ ├── project-b/ │ ├── settings.json │ └── memory/ └── default/ ├── settings.json └── memory/

核心逻辑：当你用claude project switch project-a切换项目时，Claude Code会加载对应子目录下的配置和记忆。这解决了“一个项目一个配置”的需求。

常见错误：把projects目录当成“项目模板”来用。有人会在projects下创建一堆子目录，每个里面放不同的settings.json，然后手动复制粘贴。这完全违背了设计初衷——projects目录应该和你的实际项目一一对应，而不是配置模板库。

我的用法：每个微服务项目一个独立的projects子目录。比如：

.claude/projects/ ├── user-service/ ├── order-service/ └── gateway/

每个子目录里的settings.json配置不同的模型和system prompt。user-service用claude-3-sonnet，因为它的代码相对简单；order-service用claude-3-opus，因为涉及复杂的业务逻辑和状态机。

注意：projects目录下的memory是隔离的。你在user-service里让Claude Code记住的数据库表结构，不会泄露到order-service里。这对于多租户场景特别有用。

目录结构的“潜规则”

除了这四个核心文件/目录，.claude目录下还有一些隐藏行为：

.claudeignore——类似.gitignore，但控制的是哪些文件不会被Claude Code读取。默认情况下，Claude Code会扫描项目里所有文件，但如果你有大型的node_modules、vendor目录，或者包含敏感信息的配置文件，应该加进.claudeignore。格式和.gitignore完全一样。

.claude/hooks/——这个目录不是官方文档重点介绍的，但非常实用。你可以在这里放一些脚本，在Claude Code执行特定操作时触发。比如pre_execute.sh在每次执行命令前运行，可以用来做安全检查或者日志记录。我写了一个hook，每次Claude Code要执行git push之前，自动检查当前分支是否允许推送。

版本兼容性：不同版本的Claude Code对.claude目录的解析方式有细微差别。0.1.x版本只认settings.json和credentials，0.2.x引入了projects和memory，0.3.x开始支持hooks。如果你在团队里共享.claude目录，确保大家的Claude Code版本一致，否则可能出现“我配置了但你没生效”的情况。

个人经验：别把.claude目录当成“一次配置终身使用”

我见过最典型的错误是：项目初始化时配置好.claude目录，然后就再也不管了。三个月后，模型版本更新了，API Key轮换了，项目结构重构了，但.claude目录还是老样子。

我的维护策略：

1. 每次迭代开始前：检查settings.json里的model是否还是当前最优选择。Claude 3.5 Sonnet发布后，我第一时间把项目从3 Sonnet切过来，token成本降了40%，响应质量反而提升了。

2. 每次API Key轮换：不只是更新credentials文件，还要检查memory里有没有缓存旧的key信息。有时候Claude Code会在memory里记住“API Key是xxx”，即使你更新了credentials，它可能还是用记忆里的旧值。

3. 每次项目重构：清理projects目录。如果某个微服务被拆分了，对应的projects子目录也要更新。别留着僵尸配置。

4. 版本锁定：在settings.json里明确指定model版本号，比如claude-3-sonnet-20240229而不是claude-3-sonnet。后者会指向最新版，但最新版可能改变行为，导致你的prompt突然不work了。

最后说一句：.claude目录是Claude Code的“配置文件”，但它更是你和AI协作的“契约”。你花10分钟认真配置它，Claude Code能帮你省下10小时。反之，你随便写两行，它就会在关键时刻给你挖坑。