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

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秒可能不够。我习惯设成3000005分钟特别是处理大型代码库重构的时候。但注意这个值不是越大越好过长的超时会让Claude Code在死循环里空转浪费token。credentials密钥的“保险柜”但别把它当垃圾桶这个文件存储的是API认证信息格式很简单ANTHROPIC_API_KEYsk-ant-xxxxxxxxxxxx OPENAI_API_KEYsk-xxxxxxxxxxxx最致命的错误把这个文件提交到Git仓库。我见过有人把credentials写进.gitignore但忘了检查子模块里的.claude目录。更隐蔽的问题是如果你用claude init初始化项目它会自动生成一个空的credentials文件但不会自动加入.gitignore。你需要手动加。我的做法credentials文件里只放一个占位符ANTHROPIC_API_KEYYOUR_API_KEY_HERE然后在CI/CD环境变量里注入真实的key。这样即使有人误提交泄露的也只是占位符。本地开发时用export ANTHROPIC_API_KEYxxx设置环境变量Claude Code会优先读取环境变量而不是credentials文件。另一个坑credentials文件支持多行但每行只能有一个key-value对。别想着用JSON格式或者加注释——Claude Code解析这个文件的时候会直接忽略不符合KEYVALUE格式的行而且不会报错。你写了个注释# 这是生产环境的key它默默跳过你以为是配置生效了实际上根本没读到。memoryClaude Code的“短期记忆”但别指望它持久memory目录存储的是Claude Code在对话过程中积累的上下文信息。结构大概是.claude/memory/ ├── session_abc123.json ├── session_def456.json └── global.jsonsession_xxx.json——每次对话生成的临时记忆文件。包含了你在这个session里提到的关键信息、代码片段、决策记录。Claude Code用它来保持对话的连贯性。global.json——跨session的持久记忆。这里存的是你明确告诉Claude Code“记住这个”的内容。比如你让它记住项目的编码规范、数据库连接字符串、部署流程。实际使用中的问题memory文件不会自动清理。如果你每天用Claude Code一个月后memory目录里可能有上百个session文件。这些文件虽然不大但Claude Code在启动时会扫描整个memory目录文件越多启动越慢。我的建议每周清理一次memory目录只保留最近7天的session文件。写个cron job或者GitHub Actionsfind.claude/memory-namesession_*.json-mtime7-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和credentials0.2.x引入了projects和memory0.3.x开始支持hooks。如果你在团队里共享.claude目录确保大家的Claude Code版本一致否则可能出现“我配置了但你没生效”的情况。个人经验别把.claude目录当成“一次配置终身使用”我见过最典型的错误是项目初始化时配置好.claude目录然后就再也不管了。三个月后模型版本更新了API Key轮换了项目结构重构了但.claude目录还是老样子。我的维护策略每次迭代开始前检查settings.json里的model是否还是当前最优选择。Claude 3.5 Sonnet发布后我第一时间把项目从3 Sonnet切过来token成本降了40%响应质量反而提升了。每次API Key轮换不只是更新credentials文件还要检查memory里有没有缓存旧的key信息。有时候Claude Code会在memory里记住“API Key是xxx”即使你更新了credentials它可能还是用记忆里的旧值。每次项目重构清理projects目录。如果某个微服务被拆分了对应的projects子目录也要更新。别留着僵尸配置。版本锁定在settings.json里明确指定model版本号比如claude-3-sonnet-20240229而不是claude-3-sonnet。后者会指向最新版但最新版可能改变行为导致你的prompt突然不work了。最后说一句.claude目录是Claude Code的“配置文件”但它更是你和AI协作的“契约”。你花10分钟认真配置它Claude Code能帮你省下10小时。反之你随便写两行它就会在关键时刻给你挖坑。