# 第十阶段 · 模块十 · 第一节：项目初始化实战
如何使用 Claude Code 初始化新项目？/init 命令的完整流程是什么？如何创建高效的 CLAUDE.md？
Claude Code 全局架构
┌─────────────────────────────────────────────────────────────────────┐
│ 实战案例 │
│ │
│ 项目初始化实战 ← 本节 │
│ ├── /init 命令流程 │
│ ├── CLAUDE.md 创建 │
│ └── 技能和钩子配置 │
└─────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────┐
│ 没有 CLAUDE.md： │
│ - Claude 不了解项目结构 │
│ - 不清楚构建/测试命令 │
│ - 不知道编码规范 │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 有 CLAUDE.md： │
│ - 快速理解项目 │
│ - 正确的开发命令 │
│ - 遵循团队规范 │
└─────────────────────────────────────────────────────────────────────┘
源码位置：`src/commands/init.ts`
// 初始化的三个阶段
// Phase 1: 询问用户需求
// - 项目 CLAUDE.md 还是个人 CLAUDE.local.md？
// - 需要哪些技能和钩子？
// Phase 2: 探索代码库
// - 读取 package.json、README.md
// - 检测构建命令、框架、结构
// Phase 3: 补全信息
// - 询问代码无法回答的问题
// - 生成 CLAUDE.md 提案
问 1：CLAUDE.md 和 CLAUDE.local.md 的区别？
// CLAUDE.md
// - 项目级共享
// - 提交到版本控制
// - 团队成员共享
// CLAUDE.local.md
// - 个人偏好
// - 不提交到版本控制
// - 仅自己可见
# 在项目根目录运行
claude /init
# 或使用 --init 标志
claude --init
源码位置：`src/commands/init.ts`
┌─────────────────────────────────────────────────────────────────────┐
│ /init 选项 │
│ │
│ CLAUDE.md 文件： │
│ ├─ Project CLAUDE.md ──> 团队共享 │
│ ├─ Personal CLAUDE.local.md ──> 个人偏好 │
│ └─ Both ──> 两者都要 │
│ │
│ 额外配置： │
│ ├─ Skills + Hooks ──> 完整配置 │
│ ├─ Skills only ──> 只创建技能 │
│ ├─ Hooks only ──> 只创建钩子 │
│ └─ Neither ──> 只创建 CLAUDE.md │
└─────────────────────────────────────────────────────────────────────┘
问 1：应该选择哪些选项？
// 建议：
// 1. 新项目
// - 选择 "Both" 和 "Skills + Hooks"
// - 全面配置
// 2. 现有项目
// - 选择 "Project CLAUDE.md"
// - 团队共享规范
// 3. 个人使用
// - 选择 "Personal CLAUDE.local.md"
// - 只配置个人偏好
源码位置：`src/commands/init.ts`
// 问题 1：设置哪些 CLAUDE.md 文件？
"Which CLAUDE.md files should /init set up?"
- "Project CLAUDE.md" — 团队共享指令
- "Personal CLAUDE.local.md" — 你的私人偏好
- "Both project + personal"
// 问题 2：需要技能和钩子吗？
"Also set up skills and hooks?"
- "Skills + hooks" — 完整配置
- "Skills only" — 只创建技能
- "Hooks only" — 只创建钩子
- "Neither, just CLAUDE.md"
// Claude 只问代码无法回答的问题
// 例如：
// - 你的角色是什么？（后端/前端/数据科学家）
// - 你对这个代码库熟悉吗？
// - 有没有个人沙箱 URL 或测试账号？
// Claude 不会问：
// - package.json 中已有的信息
// - README 中已有的信息
问 1：为什么 Claude 要询问而不是直接创建？
// 因为有些信息代码无法获取：
// 1. 个人偏好
// - 工作风格
// - 通信习惯
// 2. 团队流程
// - 分支命名规范
// - PR 合并规范
// 3. 特殊要求
// - 沙箱 URL
// - 测试账号
源码位置：`src/commands/init.ts`
// Claude 会读取这些文件：
// 清单文件
package.json, Cargo.toml, pyproject.toml, go.mod, pom.xml
// 文档
README.md, CLAUDE.md
// 构建配置
Makefile, build.gradle, CMakeLists.txt
// CI 配置
.github/workflows/, .gitlab-ci.yml
// 编辑器规则
.claude/rules/, .cursor/rules/, .cursorrules
.github/copilot-instructions.md
.windsurfrules, .clinerules
// MCP 配置
.mcp.json
// Claude 从代码中检测：
// 1. 构建/测试/林挺命令
// - npm run build, npm test
// - cargo build, cargo test
// 2. 语言和框架
// - TypeScript, React
// - Python, Django
// 3. 项目结构
// - Monorepo (workspaces)
// - Multi-module
// 4. 代码风格
// - prettier, eslint
// - rustfmt, gofmt
// 5. 现有的 skills 和 hooks
// - .claude/skills/
// - .claude/commands/
问 1：Claude 能自动检测所有内容吗？
// 不能
// Claude 能检测：
// - 已有文件中的信息
// - 显式的配置
// Claude 不能检测：
// - 隐式的团队规范
// - 文档中没有的 gotchas
// - 个人偏好
源码位置：`src/commands/init.ts`
// Claude 生成配置提案，包括：
// 1. Hook（严格）
// - 格式化钩子：PostToolUse 后自动格式化
// - 示例：ruff format <file>
// 2. Skill（按需）
// - /verify 技能：运行完整验证
// - 示例：make lint && make typecheck && make test
// 3. CLAUDE.md 笔记（宽松）
// - 行为准则：plan before coding
// - 示例："每次编码前先提出计划"
// Claude 根据 Phase 1 选择过滤提案：
// 如果选择 "Skills only"：
// - 所有 Hook 降级为 Skill 或 Note
// 如果选择 "Hooks only"：
// - 所有 Skill 降级为 Hook 或 Note
// 如果选择 "Neither"：
// - 一切都成为 Note
问 1：Hook 和 Skill 有什么区别？
// Hook = 工具事件触发，Claude 无法跳过
// - 示例：PostToolUse 后自动运行 prettier
// - 适用：格式化、linting、快速测试
// Skill = 按需调用，Claude 可以选择
// - 示例：/verify 运行完整验证
// - 适用：深度验证、部署、报告
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## 项目结构
- `/src` — 源代码
- `/tests` — 测试文件
- `/docs` — 文档
## 构建命令
- `npm run build` — 构建项目
- `npm run test` — 运行测试
- `npm run lint` — 运行 linter
## 架构
本项目使用 React + TypeScript，采用模块化架构...
源码位置：`src/commands/init.ts`
// 每个文件都要通过这个测试：
// "Would removing this cause Claude to make mistakes?"
// 如果答案是 "否"，就删除它
// 避免：
// - 显而易见的说明
// - 可以从代码中轻松发现的信息
// - 过于详细的文件列表
问 1：CLAUDE.md 应该多详细？
// 原则：最小化
// 应该包含：
// - Claude 会弄错的
// - 非显而易见的
// - 团队特定的规范
// 不应该包含：
// - package.json 中已有的命令
// - 可以从代码中发现的信息
// - 显而易见的最佳实践
# 进入项目目录
cd my-node-project
# 运行初始化
claude /init
🤖 Claude: 我来帮你设置 CLAUDE.md
首先，我需要了解你的需求：
1. 哪些 CLAUDE.md 文件？
- Project CLAUDE.md（团队共享）
- Personal CLAUDE.local.md（个人偏好）
- Both
2. 需要技能和钩子吗？
- Skills + hooks（完整配置）
- ...
我正在分析你的代码库...
.claude/
├── CLAUDE.md # 项目级配置
├── skills/ # 技能目录
│ └── verify.ts # 验证技能
└── hooks/
└── format-hook.ts # 格式化钩子
问 1：如何验证初始化是否成功？
// 方法：
// 1. 检查文件存在
ls -la CLAUDE.md
// 2. 测试 Claude 理解
claude "这个项目的构建命令是什么？"
// 3. 测试 Hook
# 修改文件，看是否自动格式化
// Claude 会：
// 1. 读取现有的 CLAUDE.md
// 2. 提出改进建议
// 3. 不覆盖现有内容，除非你同意
// Claude 会询问：
// 1. Monorepo？
// 2. Multi-module？
// 3. 特殊目录结构？
问 1：初始化可以多次运行吗？
// 可以
// 每次运行 /init：
// - 可以添加新的技能和钩子
// - 可以更新 CLAUDE.md
// - 不会删除已有内容
答案：
// 使用 Project CLAUDE.md：
// - 团队共享的规范
// - 架构说明
// - 构建命令
// 使用 Personal CLAUDE.local.md：
// - 个人偏好
// - 沙箱 URL
// - 通信习惯
// 建议：大多数项目使用 Project
// 个人偏好只在多个项目间共享时使用 Personal
答案：
// 精简原则：
// 1. 每行都要回答这个问题：
// "删除这行会让 Claude 犯错吗？"
// 2. 不要包含：
// - 显而易见的说明
// - 可以从代码中发现的信息
// 3. 只包含：
// - 非显而易见的
// - Claude 会弄错的
答案：
// 维护策略：
// 1. 项目结构大改时更新
// 2. 添加新的 gotchas
// 3. 移除过时的信息
// 定期检查：
// - CLAUDE.md 是否还有效
// - 是否有未记录的规范
// - 是否有可以删除的冗余内容
| 资源 | 说明 |
| Claude Code 文档 | https://docs.anthropic.com/claude-code |
| CLAUDE.md 指南 | https://docs.anthropic.com/claude-code/initialize |
下一节我们将深入 代码重构实战：
- 重构前的分析
- 安全的重构步骤
- 重构验证
*- 第一轮：□ 事实准确性*
*- 第二轮：□ 深度与洞见*
*- 第三轮：□ 可读性与价值*