🎯 学习目标

完成本节后，你将能够：

• ✅ 熟练运行 claude init 并理解其背后的智能检测逻辑。
• ✅ 解读 .claude-code.json 配置文件中的每一个关键参数。
• ✅ 清晰区分“全局配置”与“项目配置”的优先级关系。
• ✅ 掌握 .claude/ 目录（记忆、检查点、技能）的内部运作机制。
• ✅ 自定义项目结构以适应团队协作或个人偏好。

---

2.3 Claude Code 项目初始化：init 命令与配置文件

2.3.1 为什么需要初始化？

Claude Code 不仅仅是一个聊天机器人，它是一个上下文感知型代理。

• 无初始化状态：它不知道你的项目是用 Python 还是 Node.js，不知道你的代码规范是 Airbnb 还是 Google Style，也不知道你希望它如何命名变量。
• 初始化后状态：它读取项目特征，加载专属记忆，遵循特定规则，成为该项目的“专属初级工程师”。

2.3.2 执行初始化命令

在项目根目录下运行：

claude init

智能检测流程解析：
当你在终端输入该命令时，Claude Code 会在后台执行以下逻辑：

1. 语言识别：扫描 package.json, requirements.txt, go.mod, Cargo.toml 等文件，判断技术栈。
2. 框架推断：检测是否存在 next.config.js, manage.py, pom.xml 等，推断使用的框架。
3. 规范建议：根据检测到的语言，自动推荐相应的 Lint 规则和测试框架。
4. 配置生成：创建 CLAUDE.md 文件。

如下图：

这是在一个我自己的项目的中执行/init，生成了CLAUDE.md文件。也可以在空的项目文件夹中执行/init,会生成一些环境配置。如下图：

💡 高级初始化选项

# 1. 指定模型（覆盖默认设置）
claude init --model sonnet

2.4 Claude Code 项目结构：生成的文件与目录说明

初始化不仅生成了一个配置文件，还构建了一个完整的AI 工作空间。

2.4.1 标准目录树

my-project/
├── .claude/                  # 🤖 Claude Code 的核心工作区 (Git 需保留)
│   ├── settings.json         # (旧版) 或链接到根目录的配置
│   ├── memory/               # 🧠 长期记忆存储
│   │   ├── project_context.md # 项目背景知识（由 AI 自动维护）
│   │   └── user_preferences.md # 用户习惯记录
│   ├── checkpoints/          # 💾 任务快照
│   │   ├── 2023-10-27-task-1.json
│   │   └── ...
│   ├── skills/               # 🛠️ 自定义技能库
│   │   └── my-custom-skill.sh
│   └── logs/                 # 📝 调试日志
├── .claude-code.json         # ⚙️ 项目主配置文件 (建议提交 Git)
├── src/                      # 源代码
├── tests/                    # 测试代码
└── README.md

(注：具体目录名可能随版本更新微调，如 .claude 或 .claude-code，请以实际安装版本为准)

2.4.2 核心组件深度剖析

1. 记忆系统 (memory/)

这是 Claude Code 区别于普通 Chat 的核心。

• project_context.md：AI 会自动总结项目的架构、依赖关系和关键决策。当你几天后回来继续工作时，它能迅速“回忆”起之前的进度。
• 工作机制：每次对话结束时，AI 会判断是否有新的重要信息需要写入记忆。
• 手动干预：你可以直接编辑此文件，强行注入背景知识。

  示例：在文件中写入“本项目数据库密码通过环境变量 DB_PASS 注入，严禁硬编码”，AI 将在所有后续操作中严格遵守。

2. 检查点系统 (checkpoints/)

• 功能：保存对话的历史状态、文件修改前的快照。
• 用途：
  • 回滚：如果 AI 改乱了代码，可以使用 /checkpoint revert 恢复到之前的状态。
  • 分支实验：基于某个检查点开启新的尝试，而不影响主线。
• 清理策略：该目录可能会随时间变大，建议定期清理旧的检查点，或使用 Git 标签代替部分功能。

3. 技能系统 (skills/)

• 定义：存放用户自定义的 Shell 脚本或 Prompt 模板。
• 调用方式：在对话中输入 /skill <name> 即可触发。
• 实战案例：
  • 创建一个 deploy-preview.sh 技能，一键部署当前分支到测试环境。
  • 创建一个 refactor-legacy 技能，包含一套复杂的遗留代码重构指令集。

2.4.3 Git 集成最佳实践

如何管理这些生成的文件？以下是推荐的 .gitignore 策略：

# ✅ 应该提交 (Commit)
.claude-code.json       # 共享配置规范
.claude/memory/project_context.md # 共享项目知识库 (可选，视团队习惯)
.claude/skills/         # 共享技能库

# ❌ 应该忽略 (Ignore)
.claude/logs/           # 本地调试日志，无需共享
.claude/checkpoints/    # 个人历史快照，体积大且含本地路径
.claude/memory/user_preferences.md # 个人习惯，不应强加给团队
.env                    # 永远不要提交环境变量

2.4.4 进阶：多环境配置管理

对于需要在不同环境（开发、测试、生产）下使用不同 AI 策略的项目，可以利用配置继承或条件加载。

方案 A：多配置文件

# 开发环境
claude start --config .claude-code.dev.json

# 生产环境（更严格的权限）
claude start --config .claude-code.prod.json

方案 B：动态 Hook
在 hooks 中根据分支名称动态调整行为：

"custom_instructions": "如果当前分支是 main，禁止执行任何删除操作；如果是 feature/*，允许自动创建文件。"

---

🧪 动手练习：构建你的第一个“智能项目”

任务 1：初始化与观察

1. 新建一个空文件夹 demo-project。
2. 运行 claude init。
3. 观察：查看生成的 .claude-code.json，记录下它自动识别出的技术栈（即使现在是空的，看它预设了什么）。

任务 2：定制“性格”

1. 打开 .claude-code.json。
2. 在 custom_instructions 中加入：“你是一个资深 Python 专家，喜欢使用 Type Hints，并且总是先写单元测试再写实现代码（TDD）。”
3. 保存文件。

任务 3：验证记忆

1. 启动 Claude Code：claude。
2. 询问：“这个项目的编码规范是什么？”
3. 预期结果：AI 应准确回答你刚才配置的 TDD 和 Type Hints 要求，证明配置已生效。

任务 4：模拟回滚

1. 让 AI 创建一个文件 test.txt 并写入内容。
2. 查看 .claude/checkpoints 目录，确认生成了快照。
3. 让 AI 删除该文件。
4. 使用 /checkpoint list 找到之前的快照，并尝试恢复。

---

❓ 常见陷阱与解答 (FAQ)

问题	原因分析	解决方案
配置不生效	修改了 JSON 但格式错误（如少了逗号）	使用 jq 或在线 JSON 校验工具检查语法。
记忆混乱	多个项目共用同一个全局记忆目录	确保每个项目都运行了 init，隔离项目级记忆。
Token 消耗过快	exclude_patterns 未配置，AI 读取了 node_modules	立即在配置文件中添加大规模依赖目录的排除规则。
权限报错	试图在只读目录运行 auto 模式	检查文件系统权限，或将 file_write 改回 ask。

---

📝 本章小结

• 初始化不仅是创建文件，更是定义 AI 的角色和行为边界。
• .claude-code.json 是项目的宪法，决定了 AI 的模型、权限和规范。
• .claude/ 目录 是 AI 的“海马体”和“工具箱”，合理利用记忆和检查点能大幅提升开发连续性。
• Git 策略 至关重要：共享配置与规范，隔离日志与个人快照。

🚀 下一步预告：
环境已就绪，配置已完善。下一章 第 3 章：第一次交互，我们将正式发出第一个指令，体验从 “Hello World” 到 “Complex Refactoring” 的完整对话流！