第 2 章项目初始化与结构深度解析

🎯 学习目标

完成本节后，你将能够：

✅ 熟练运行 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 执行初始化命令

在项目根目录下运行：

bash 复制代码

claude init

智能检测流程解析 ：

当你在终端输入该命令时，Claude Code 会在后台执行以下逻辑：

语言识别 ：扫描 package.json, requirements.txt, go.mod, Cargo.toml 等文件，判断技术栈。
框架推断 ：检测是否存在 next.config.js, manage.py, pom.xml 等，推断使用的框架。
规范建议：根据检测到的语言，自动推荐相应的 Lint 规则和测试框架。
配置生成 ：创建 .claude-code.json (或旧版本的 .claude/settings.json) 和 .claude/ 目录。

💡 高级初始化选项

bash 复制代码

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

# 2. 强制启用记忆系统（默认可能关闭）
claude init --memory-enabled

# 3. 跳过交互式问答，使用默认配置
claude init --yes

# 4. 为特定场景初始化（如仅用于代码审查）
claude init --profile code-review

2.3.3 核心配置文件详解 (`.claude-code.json`)

初始化后，项目根目录会生成配置文件。这是控制 Claude Code 行为的"大脑"。

json 复制代码

{
  "version": "1.0",
  "model": {
    "name": "claude-sonnet-4-20250514", 
    "max_tokens": 8192,
    "temperature": 0.3
  },
  "permissions": {
    "file_write": "ask",       
    "command_execute": "ask",  
    "network_access": "deny"   
  },
  "context": {
    "include_patterns": ["src/**/*", "tests/**/*"],
    "exclude_patterns": ["node_modules/**", "*.log", ".git/**"]
  },
  "custom_instructions": "始终使用 TypeScript 严格模式。优先使用函数式组件。遇到错误时先解释原因再修复。",
  "hooks": {
    "pre_task": "npm run lint",
    "post_task": "npm test"
  }
}

🔑 关键参数深度解读

| 参数类别 | 字段 | 可选值 | 作用与最佳实践 |

| :--- | :--- | :--- | : |

2.3.4 配置优先级策略

当全局配置与项目配置冲突时，遵循以下优先级（从高到低）：

命令行参数 (claude --model ...)：最高优先级，临时覆盖。
项目级配置 (.claude-code.json)：针对当前项目的特定设置。
用户级配置 (~/.claude-code/config.json)：默认设置，适用于所有未初始化的项目。
系统默认值：Anthropic 内置的兜底策略。

💡 专家提示 ：建议在 .gitignore 中添加 .claude-code/local.json（如果存在），用于存放包含 API Key 或个人偏好的本地配置，避免将敏感信息提交到 Git 仓库。但主配置文件 .claude-code.json 应该提交，以便团队成员共享相同的 AI 行为规范。

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

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

2.4.1 标准目录树

text 复制代码

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 策略：

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：多配置文件

bash 复制代码

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

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

方案 B：动态 Hook

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

json 复制代码

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

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

任务 1：初始化与观察

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

任务 2：定制"性格"

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

任务 3：验证记忆

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

任务 4：模拟回滚

让 AI 创建一个文件 test.txt 并写入内容。
查看 .claude/checkpoints 目录，确认生成了快照。
让 AI 删除该文件。
使用 /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" 的完整对话流！

第 2 章 项目初始化与结构深度解析

🎯 学习目标

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

2.3.1 为什么需要初始化？

2.3.2 执行初始化命令

💡 高级初始化选项

2.3.3 核心配置文件详解 (.claude-code.json)

🔑 关键参数深度解读

2.3.4 配置优先级策略

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

2.4.1 标准目录树

2.4.2 核心组件深度剖析

1. 记忆系统 (memory/)

2. 检查点系统 (checkpoints/)

3. 技能系统 (skills/)

2.4.3 Git 集成最佳实践

2.4.4 进阶：多环境配置管理

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

任务 1：初始化与观察

任务 2：定制"性格"

任务 3：验证记忆

任务 4：模拟回滚

❓ 常见陷阱与解答 (FAQ)

📝 本章小结

第 2 章项目初始化与结构深度解析

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

2.3.3 核心配置文件详解 (`.claude-code.json`)

1. 记忆系统 (`memory/`)

2. 检查点系统 (`checkpoints/`)

3. 技能系统 (`skills/`)