1. 为什么你的 Claude Code 一上来就“不懂你”刚装好 Claude Code 的人十有八九会经历同一个瞬间兴冲冲打开终端敲下claude然后问它“帮我看看这个项目怎么加个接口”。结果它回你一段泛泛而谈的 Node.js 示例而你的项目明明是 Python FastAPI目录里还躺着一堆自定义的 DTO 规范。问题不在模型在于它压根不知道你是谁、项目是什么。Claude Code 和普通聊天窗口最大的区别是它被设计成一个“上下文感知型代理”——但这个上下文不会凭空出现得靠初始化把它喂进去。没初始化时它不知道你的技术栈、不知道你的代码风格、不知道哪些目录碰不得初始化之后它会读取项目特征、加载专属记忆、遵守你定的规则变成一个“懂这个项目的初级工程师”。这篇就围绕claude init、.claude-code.json、.claude/目录、CLAUDE.md和checkpoints/这几个关键词把初始化流程和目录结构拆开讲清楚。适合刚接触 Claude Code、准备把它接进真实项目的人。我会给出可直接复制的配置骨架以及初始化后逐项验证配置是否生效的操作步骤照着做就能跑通。2. 前置准备把模型接入这一步先打通Claude Code 本身是个客户端真正干活的是背后的模型服务。所以初始化之前先把接入层配好否则claude init跑起来也会因为拿不到模型而卡住。我这边用的是 TaoToken 的接入方式官网在 https://taotoken.net API 入口是 https://taotoken.net/api 。它的作用是给你一个统一的模型调用入口Claude Code 通过它来发请求。你需要先去控制台拿一个 API Key地址是 https://taotoken.net/console Key 管理页面在 https://taotoken.net/api-keys 。拿到之后把它写进环境变量别硬编码进配置文件。# 写入 shell 配置按你实际用的 shell 选一个 echo export TAOTOKEN_API_KEYsk-你的key ~/.zshrc source ~/.zshrc # 验证变量是否生效 echo $TAOTOKEN_API_KEY如果你更习惯用图形界面调试模型可以先在模型对话页 https://taotoken.net/models 里发一条消息确认 Key 能正常返回内容再去配 Claude Code。这一步能帮你排除掉“到底是 Key 错了还是 Claude Code 配错了”的扯皮。注意API Key 属于敏感凭证只放环境变量或本地未提交的.env不要写进.claude-code.json这种会被提交到 Git 的文件里。3. 执行 claude init 与生成物解析3.1 init 命令到底做了什么在项目根目录下运行claude init它背后跑的逻辑大致分四步。第一是语言识别扫描package.json、requirements.txt、go.mod、Cargo.toml这类文件判断技术栈第二是框架推断看有没有next.config.js、manage.py、pom.xml来猜框架第三是规范建议根据语言推荐对应的 Lint 规则和测试框架第四是配置生成创建CLAUDE.md以及相关配置文件。在空目录里跑它会生成一套偏环境配置的骨架在已有项目里跑它会结合检测结果填充内容。你也可以指定模型覆盖默认设置claude init --model sonnet3.2 标准目录树长什么样初始化完成后项目里会多出这些东西my-project/ ├── .claude/ # Claude Code 核心工作区 │ ├── settings.json # 本地设置旧版可能链接到根配置 │ ├── memory/ # 长期记忆 │ │ ├── project_context.md # 项目背景知识AI 自动维护 │ │ └── user_preferences.md # 个人习惯记录 │ ├── checkpoints/ # 任务快照 │ │ ├── 2025-01-15-task-1.json │ │ └── ... │ ├── skills/ # 自定义技能库 │ │ └── deploy-preview.sh │ └── logs/ # 调试日志 ├── .claude-code.json # 项目主配置建议提交 Git ├── CLAUDE.md # 项目级指令与规范 ├── src/ ├── tests/ └── README.md目录名可能随版本微调比如.claude和.claude-code的取舍以你实际安装的版本为准。重点是理解每个部分的职责而不是死记名字。3.3 记忆系统 memory/这是 Claude Code 区别于普通对话的核心。project_context.md里存的是 AI 自动总结的项目架构、依赖关系和关键决策。你几天后回来继续干活它能快速“回忆”起之前的进度。工作机制是每次对话结束时AI 判断有没有新的重要信息需要写入记忆。你也可以手动编辑这个文件强行注入背景知识。比如在project_context.md里写一句“本项目数据库密码通过环境变量DB_PASS注入严禁硬编码”后续所有操作它都会遵守这条。3.4 检查点系统 checkpoints/checkpoints/保存对话历史状态和文件修改前的快照。用途有两个回滚和分支实验。如果 AI 把代码改乱了可以用/checkpoint revert恢复到之前的状态也可以基于某个检查点开新尝试不影响主线。这个目录会随时间变大建议定期清理旧快照或者用 Git 标签替代一部分功能。3.5 技能系统 skills/这里放自定义的 Shell 脚本或 Prompt 模板对话里用/skill name触发。实战里比较有用的两个一个deploy-preview.sh一键把当前分支部署到测试环境一个refactor-legacy封装一套遗留代码重构指令集。4. 可复制的配置骨架4.1 .claude-code.json 骨架下面这份可以直接拿去改字段按你项目实际情况调整{ model: claude-sonnet, custom_instructions: 你是一个资深工程师优先使用类型注解先写测试再写实现TDD。修改文件前先说明意图。, permissions: { file_write: ask, shell_exec: ask, network: deny }, exclude_patterns: [ node_modules/**, dist/**, build/**, .venv/**, *.lock ], hooks: { on_branch_main: 禁止执行任何删除操作, on_branch_feature: 允许自动创建文件 } }几个关键点解释一下。permissions.file_write设成ask意味着每次写文件前它会问你适合刚上手等你信任它了可以放宽。exclude_patterns一定要配否则它读node_modules会把 Token 烧得飞快。custom_instructions是你给它定的“性格”写清楚编码规范比每次对话重复交代省事得多。4.2 settings.json 骨架.claude/settings.json放本地设置通常不进 Git{ api_key_env: TAOTOKEN_API_KEY, api_base: https://taotoken.net/api, default_model: claude-sonnet, memory: { auto_update: true, project_context: .claude/memory/project_context.md }, checkpoints: { enabled: true, max_snapshots: 50 } }api_base指向接入入口api_key_env告诉它从哪个环境变量读 Key这样凭证就不会落到文件里。4.3 CLAUDE.md 写什么CLAUDE.md是项目级指令内容会被优先加载。建议包含项目一句话简介、技术栈、目录约定、命名规范、禁止事项。比如# 项目约定 - 技术栈Python 3.11 FastAPI PostgreSQL - 测试pytest测试文件放 tests/命名 test_*.py - 禁止直接修改 migrations/ 下的历史文件 - 提交前必须跑ruff check . pytest4.4 Git 策略哪些该提交、哪些该忽略直接给结论# 提交 .claude-code.json CLAUDE.md .claude/skills/ .claude/memory/project_context.md # 忽略 .claude/logs/ .claude/checkpoints/ .claude/memory/user_preferences.md .env共享配置和规范隔离日志和个人快照这是团队协作里比较稳的做法。5. 验证配置是否真的生效配完不算完得逐项验证。下面这套流程我实测下来能覆盖大部分坑。第一步检查 JSON 语法。配置文件少个逗号是最常见的翻车点jq . .claude-code.json /dev/null echo JSON OK第二步启动 Claude Code 并问它项目规范claude # 进入对话后输入 # 这个项目的编码规范是什么预期结果是它准确说出你在custom_instructions里写的 TDD 和类型注解要求。如果答得含糊说明配置没加载。第三步验证记忆。让它读一下project_context.md里的内容问它“数据库密码怎么注入”它应该回答通过DB_PASS环境变量。第四步验证检查点。让它创建一个文件# 对话里输入创建 test.txt 并写入 hello ls .claude/checkpoints/确认checkpoints/下生成了快照。然后让它删掉文件用/checkpoint list找到之前的快照尝试恢复。第五步验证排除规则。问它“node_modules 里有哪些包”如果它拒绝或提示被排除说明exclude_patterns生效了。6. 初始化后常见报错排查配置不生效八成是 JSON 格式错误。用上面那条jq命令先过一遍或者丢进在线校验工具。别靠肉眼找逗号。记忆混乱通常是多个项目共用了同一个全局记忆目录。确保每个项目都单独跑过claude init项目级记忆是隔离的。Token 消耗过快检查exclude_patterns有没有配。AI 一旦读了node_modules或dist一次对话就能烧掉大量额度。把大依赖目录全排掉。权限报错比如在只读目录跑 auto 模式。检查文件系统权限或者把file_write改回ask别硬上自动写入。接入层报错先确认TAOTOKEN_API_KEY环境变量在当前终端能echo出来再确认api_base写的是https://taotoken.net/api。如果还是不通去接入文档 https://taotoken.net/doc 对照一遍参数或者直接在模型对话页发条消息验证 Key 本身是否有效。如果你打算长期用 Claude Code 做编码和 Agent 任务可以看下 Coding Plan https://taotoken.net/coding-plan 比按次调用更适合高频场景。配置层面还有疑问的API Keys 页面 https://taotoken.net/api-keys 能直接管理凭证接入文档 https://taotoken.net/doc 里有完整的参数说明。初始化这件事本质是给 AI 划角色和边界。.claude-code.json是项目的宪法.claude/是它的记忆和工具箱Git 策略决定哪些共享哪些隔离。把这三块理顺后面每次对话都省心。