企业官网建设流程全解析

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_KEY="sk-你的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 sonnet

3.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 . && pytest

4.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 策略决定哪些共享哪些隔离。把这三块理顺，后面每次对话都省心。