第 2 章：项目初始化 — 让 Claude 理解你的项目 — Claude Code Geek Guide: Master Core Commands with a Pomodoro App

安装 Claude Code 并登录后，下一步是让它理解你的项目。就像新同事入职时需要项目文档一样，Claude 也需要一份"项目手册"才能高效地帮助你工作。

本章介绍的命令将帮助你：

让 Claude 自动了解你的项目结构和约定
配置个性化偏好
跨会话保持项目记忆
诊断和修复安装问题

2.1 为什么需要项目初始化

想象一下，如果你是一位新加入的开发者，第一天来到项目组，你最需要什么？

项目是用什么技术栈构建的？
如何运行开发服务器？
代码有什么约定和规范？
项目目录结构是怎样的？
特殊的命令或脚本有哪些？

Claude 就像这位新同事。虽然它能读取文件，但如果没有上下文，它可能会：

建议不合适的解决方案
违反项目的代码风格
使用错误的构建命令
重复造轮子（忽略已有的工具或组件）

CLAUDE.md 文件就是给 Claude 的"项目手册"。它包含了项目的关键信息，让 Claude 能够：

理解项目的上下文和约定
遵循项目的架构和设计模式
使用正确的命令和工具
提供符合项目风格的建议

2.2 `/init` — 生成 CLAUDE.md

语法

/init

在项目根目录下运行此命令。

功能说明

/init 命令会自动分析当前代码库并生成 CLAUDE.md 文件。它的工作流程：

扫描项目目录结构
检测包管理器（npm/yarn/pnpm）和构建配置
分析依赖和脚本命令
识别代码风格和约定
生成 CLAUDE.md 文件

实际使用示例

在项目目录中运行：

/my-pomodoro → /init

输出示例：

🔍 分析项目结构...
✓ 检测到 package.json
✓ 检测到 Vite 配置
✓ 检测到 React 项目
📝 生成 CLAUDE.md...
✓ 完成！项目文档已生成在 /my-pomodoro/CLAUDE.md

交互式初始化

设置环境变量后，/init 会进入交互式流程：

export CLAUDE_CODE_NEW_INIT=1
/init

交互式流程会询问：

Skills：是否安装推荐的技能包
Hooks：是否配置自动化行为
Memory：是否设置个人记忆文件

CLAUDE.md 的位置

项目级：/项目根目录/CLAUDE.md
- 仅在当前项目中生效
- 优先级高于全局配置
全局级：~/.claude/CLAUDE.md
- 所有项目共享
- 适合跨项目的通用约定

注意事项/技巧

首次初始化后，手动检查并补充缺失的信息
如果项目结构发生重大变化，重新运行 /init
可以手动编辑 CLAUDE.md 添加项目特定的约定
在 monorepo 中，可以为子项目创建独立的 CLAUDE.md

2.3 CLAUDE.md 结构详解

CLAUDE.md 使用 Markdown 格式，包含项目元数据和说明。以下是番茄钟项目的完整示例：

---
paths:
  - src/**
---

# 番茄钟应用

一个专注于时间管理的番茄钟 Web 应用。

## 项目概述

番茄钟应用帮助用户管理工作时间和休息时间。核心功能包括：

- 25分钟工作计时器
- 5分钟休息计时器
- 工作模式/休息模式切换
- Todo List（任务列表）
- 本地存储（localStorage）保存数据和设置

## 技术栈

- **前端框架**：React 18
- **构建工具**：Vite 5
- **状态管理**：React Hooks + Context API
- **存储**：localStorage
- **样式**：CSS Modules
- **类型检查**：TypeScript

## 构建命令

### 开发环境

```bash
npm run dev
# 或
yarn dev
# 或
pnpm dev

启动开发服务器，默认地址 http://localhost:5173

生产构建

npm run build
npm run preview

代码检查

npm run lint
npm run type-check

测试

npm run test
npm run test:watch

架构说明

目录结构

src/
├── components/      # React 组件
│   ├── Timer.tsx    # 计时器主组件
│   ├── TaskList.tsx # 任务列表组件
│   └── ...
├── hooks/           # 自定义 Hooks
│   ├── useTimer.ts  # 计时器逻辑
│   ├── useStorage.ts # localStorage 封装
│   └── ...
├── contexts/        # React Context
│   └── TimerContext.tsx
├── utils/           # 工具函数
├── types/           # TypeScript 类型定义
└── main.tsx         # 入口文件

核心组件

Timer：处理计时逻辑，包括倒计时、暂停、重置
TaskList：管理任务状态（完成/未完成）
SettingsPanel：自定义工作/休息时长

数据流

使用 Context API 管理全局状态：

TimerContext (Provider)
    ↓
Timer 组件 ←→ TaskList 组件
    ↓
localStorage (持久化)

代码约定

文件命名

React 组件：PascalCase（如 Timer.tsx）
工具函数：camelCase（如 formatTime.ts）
类型定义：*.types.ts 或放在 types/ 目录

组件结构

// 1. 导入
import React from 'react';

// 2. 类型定义
interface Props {
  // ...
}

// 3. 组件定义
export const ComponentName: React.FC<Props> = ({ ... }) => {
  // Hooks 放在顶部
  const [state, setState] = useState();

  // 事件处理函数
  const handleClick = () => { ... };

  // 渲染
  return <div>...</div>;
};

// 4. 默认导出
export default ComponentName;

样式约定

使用 CSS Modules：import styles from './Component.module.css';
命名空间：<div className={styles.container}>
避免内联样式（特殊情况除外）

性能考虑

使用 React.memo 避免不必要的重渲染
计时器使用 requestAnimationFrame 或 setInterval 时注意清理
localStorage 操作优化（批量读写）

常见任务

添加新组件

使用 Vite 创建：

npm run create-component <ComponentName>

修改计时器逻辑

编辑 src/hooks/useTimer.ts，确保更新 TimerContext

添加新功能

在 types/ 定义类型
在 contexts/ 扩展 Context
创建组件或 Hook
更新 CLAUDE.md 文档

已知限制

当前版本不支持多个计时器并发
localStorage 限制 5MB，大量数据需考虑压缩或迁移到 IndexedDB
依赖浏览器 localStorage API，不支持 SSR


### 条件规则（Frontmatter）

`CLAUDE.md` 顶部的 YAML frontmatter 可以指定文件适用范围：

```yaml
---
paths:
  - src/**
  - packages/app/**
exclude:
  - node_modules/**
  - dist/**
---

paths：此规则适用的文件路径模式
exclude：排除的路径

这样可以在多个 CLAUDE.md 文件间分配职责，避免冲突。

2.4 `/memory` — 编辑项目记忆

语法

/memory

功能说明

/memory 命令管理跨会话的持久记忆文件。与 CLAUDE.md 不同，memory 文件更像是"项目笔记"，用于：

记录项目中的特殊约定和规则
保存重要的决策和讨论
存储用户偏好设置
追踪未完成的任务

Memory 文件类型：

user：用户个人偏好和习惯
feedback：代码审查反馈和建议
project：项目特定的决策和约定
reference：外部文档和链接

实际使用示例

打开记忆编辑器：

/my-pomodoro → /memory

交互界面示例：

📝 项目记忆管理

[1] 编辑 user 记忆
[2] 编辑 project 记忆
[3] 编辑 feedback 记忆
[4] 编辑 reference 记忆
[5] 启用/禁用 auto-memory
[6] 查看自动内存条目
[7] 返回

选择操作: 2

编辑 project 记忆：

# 项目记忆

## 重要决策

- [2026-05-10] 选择 localStorage 而非 IndexedDB，因为数据量小且需要简单实现
- [2026-05-12] 拒绝使用 Redux，Context API 足够应付当前状态管理需求

## 待解决事项

- [ ] 添加番茄钟声音提醒（需处理浏览器音频权限）
- [ ] 考虑移动端响应式设计
- [ ] 研究是否添加数据导入/导出功能

## 代码风格要点

- 计时器组件避免在 useEffect 中直接调用 setState，使用 ref
- 所有 localStorage 操作封装在 useStorage Hook 中
- 测试覆盖率目标 > 80%

Auto-Memory 功能

Auto-memory 会自动记住：

用户显式标记的信息（"记住这个..."）
反复出现的代码模式
用户拒绝的建议
项目特定的上下文

启用 auto-memory：

/memory → [5] 启用 auto-memory

查看自动保存的条目：

/memory → [6] 查看自动内存条目

输出示例：

自动记忆条目：

1. 用户偏好：使用 TypeScript 严格模式
2. 项目约定：组件文件与测试文件放在同一目录
3. 决策：不使用第三方 UI 库，手写组件
4. 拒绝：不添加复杂的统计分析功能

注意事项/技巧

memory 文件与 CLAUDE.md 的区别：
- CLAUDE.md：静态的项目文档，面向所有会话
- memory：动态的学习记录，累积项目经验
定期清理 memory 中的过时信息
使用清晰的标题和日期标记
可以在 memory 中添加 @mention 指向具体文件或代码片段

2.5 `/config` — 调整偏好设置

语法

/config

别名：/settings

功能说明

/config 命令打开配置编辑器，允许你调整 Claude Code 的行为和外观。

实际使用示例

打开配置菜单：

/my-pomodoro → /config

交互界面示例：

⚙️ Claude Code 配置

[1] 主题设置
[2] 模型选择
[3] 输出样式
[4] 编辑器模式
[5] 语言设置
[6] 高级选项
[7] 保存并退出
[8] 取消

选择配置项: 1

主题设置

主题选择:

[1] Light（浅色）
[2] Dark（深色）
[3] Auto（跟随系统）
[4] High Contrast（高对比度）

当前: Dark
选择: 2

模型选择

可用模型:

[1] claude-sonnet-4-6（默认，平衡性能和速度）
[2] claude-opus-4-7（最强能力，速度较慢）
[3] claude-haiku-4-5（快速，适合简单任务）

当前: claude-sonnet-4-6
选择: 1

编辑器模式（替代 /vim）

编辑器模式:

[1] Emacs（默认）
[2] Vim
[3] Normal（普通）

当前: Normal
选择: 2

设置 Vim 模式后，可以使用 Vim 快捷键编辑消息。

语言设置

语言设置:

[1] English
[2] 简体中文
[3] 日本語

当前: English
选择: 2

注意事项/技巧

/vim 命令已被移除，现在通过 /config → 编辑器模式切换
配置保存在 ~/.claude/settings.json 中
可以直接编辑该文件进行高级配置
某些设置需要重启 Claude Code 才能生效

2.6 `/doctor` — 诊断安装问题

语法

/doctor

功能说明

/doctor 命令检查 Claude Code 的安装状态和配置，发现潜在问题并提供修复建议。

实际使用示例

运行诊断：

/my-pomodoro → /doctor

输出示例：

🔍 Claude Code 诊断

✓ 版本检查
  当前版本: 2026.05.10
  最新版本: 2026.05.10
  状态: 最新

✓ 认证状态
  已登录为: [email protected]
  Token 有效期: 2026-08-13

✓ 配置文件
  ~/.claude/settings.json 存在
  格式正确

✓ 内存文件
  user.memory: 存在
  project.memory: 存在

✗ MCP 连接
  - claude-mem: 连接失败 (超时)
  - web-reader: 连接成功

✓ 技能安装
  已安装 12 个技能

发现问题: 1 个
按 'f' 让 Claude 自动修复，或按 'q' 退出

自动修复

按 f 让 Claude 自动修复问题：

🔧 正在修复问题...

修复 claude-mem 连接问题:
  - 尝试重启 MCP 服务
  - 更新配置
  ✓ 修复成功

所有问题已解决！

常见问题类型

问题	原因	解决方案
版本过旧	未更新	运行 `npm update -g @anthropic-ai/claude-code`
认证失效	Token 过期	重新运行 `claude login`
MCP 连接失败	网络问题或配置错误	检查网络和配置文件
配置文件损坏	手动编辑错误	删除配置文件重新生成
权限不足	文件系统限制	检查 `~/.claude` 目录权限

注意事项/技巧

定期运行 /doctor 确保系统健康
如果遇到异常行为，先运行诊断
自动修复前会显示具体操作，可以手动拒绝
某些问题可能需要重启 Claude Code 才能完全解决

2.7 `/permissions` — 权限管理预览

语法

/permissions

别名：/allowed-tools

功能说明

/permissions 命令查看和管理工具访问权限。Claude Code 不会自动执行敏感操作，而是根据权限设置决定：

allow：自动允许，无需确认
ask：每次都询问（默认）
deny：禁止使用该工具

实际使用示例

查看当前权限：

/my-pomodoro → /permissions

输出示例：

🔐 工具权限管理

全局规则:

工具                    权限    说明
──────────────────────────────────────────────
Bash                    ask     执行 shell 命令
Write                   ask     写入文件
Edit                    ask     编辑文件
Read                    allow   读取文件（安全）
WebSearch               ask     搜索网络
mcp__claude-mem*        allow   记忆访问（安全）
mcp__web_reader         ask     网页读取
Git*                    ask     Git 操作

按 [A] 允许全部，[D] 拒绝全部，[E] 编辑规则，[Q] 退出

编辑规则

选择: E

选择工具编辑:
[1] Bash
[2] Write
[3] Edit
...
[Q] 返回

选择: 2

设置 Write 工具权限:
[1] Allow（自动允许）
[2] Ask（每次询问）
[3] Deny（禁止使用）

选择: 2

✓ Write 权限已设置为 Ask

注意事项/技巧

权限设置保存在 ~/.claude/settings.json
可以使用通配符匹配多个工具（如 mcp__claude-mem*）
对于高风险操作（如 Write、Git*），建议保持 ask
权限管理将在第 10 章详细讲解

2.8 动手做：初始化番茄钟项目

现在让我们将本章学到的命令应用到实际项目中。

步骤 1：创建项目目录

mkdir my-pomodoro && cd my-pomodoro

步骤 2：启动 Claude Code

claude

步骤 3：运行 `/init` 生成 CLAUDE.md

/my-pomodoro → /init

首次运行会输出：

🔍 分析项目结构...
✓ 检测到 package.json
✓ 检测到 React 项目
📝 生成 CLAUDE.md...
✓ 完成！

步骤 4：编辑 CLAUDE.md 补充项目信息

使用 /memory 或直接编辑 CLAUDE.md 文件：

---
paths:
  - src/**
---

# 番茄钟应用

一个专注于时间管理的番茄钟 Web 应用。

## 项目概述

番茄钟应用帮助用户管理工作时间和休息时间。核心功能包括：

- 25分钟工作计时器
- 5分钟休息计时器
- 工作模式/休息模式切换
- Todo List（任务列表）
- 本地存储（localStorage）保存数据和设置

## 技术栈

- **前端框架**：React 18
- **构建工具**：Vite 5
- **状态管理**：React Hooks + Context API
- **存储**：localStorage
- **样式**：CSS Modules
- **类型检查**：TypeScript

## 构建命令

### 开发环境

```bash
npm run dev

启动开发服务器，默认地址 http://localhost:5173

生产构建

npm run build
npm run preview

架构说明

目录结构

src/
├── components/      # React 组件
│   ├── Timer.tsx    # 计时器主组件
│   ├── TaskList.tsx # 任务列表组件
│   └── ...
├── hooks/           # 自定义 Hooks
│   ├── useTimer.ts  # 计时器逻辑
│   ├── useStorage.ts # localStorage 封装
│   └── ...
├── contexts/        # React Context
│   └── TimerContext.tsx
├── utils/           # 工具函数
├── types/           # TypeScript 类型定义
└── main.tsx         # 入口文件

代码约定

文件命名

React 组件：PascalCase（如 Timer.tsx）
工具函数：camelCase（如 formatTime.ts）
类型定义：*.types.ts 或放在 types/ 目录


### 步骤 5：启用 auto-memory

/my-pomodoro → /memory

📝 项目记忆管理

[1] 编辑 user 记忆 [2] 编辑 project 记忆 [3] 编辑 feedback 记忆 [4] 编辑 reference 记忆 [5] 启用/禁用 auto-memory [6] 查看自动内存条目 [7] 返回

选择操作: 5

当前状态: auto-memory 禁用是否启用? (y/N): y

✓ auto-memory 已启用


### 步骤 6：配置个人偏好

/my-pomodoro → /config

⚙️ Claude Code 配置

[1] 主题设置 [2] 模型选择 [3] 输出样式 [4] 编辑器模式 [5] 语言设置 [6] 高级选项 [7] 保存并退出 [8] 取消

选择配置项: 1

主题选择:

[1] Light（浅色） [2] Dark（深色） [3] Auto（跟随系统） [4] High Contrast（高对比度）

当前: Light 选择: 2

选择配置项: 5

语言设置:

[1] English [2] 简体中文 [3] 日本語

当前: English 选择: 2

选择配置项: 7

✓ 配置已保存


### 步骤 7：运行诊断确认一切正常

/my-pomodoro → /doctor

🔍 Claude Code 诊断

✓ 版本检查当前版本: 2026.05.10 最新版本: 2026.05.10 状态: 最新

✓ 认证状态已登录为: [email protected] Token 有效期: 2026-08-13

✓ 配置文件 ~/.claude/settings.json 存在格式正确

✓ 内存文件 user.memory: 存在 project.memory: 存在

✓ MCP 连接 claude-mem: 连接成功 web-reader: 连接成功

✓ 技能安装已安装 12 个技能

所有检查通过！系统状态良好。


### 步骤 8：验证 Claude 理解项目

现在可以让 Claude 帮你创建初始文件：

/my-pomodoro → 帮我创建一个基础的 React + Vite 项目结构


Claude 应该会：

1. 使用 `npm create vite@latest` 创建项目
2. 使用 `CLAUDE.md` 中定义的目录结构
3. 遵循你设定的代码风格约定

---

## 本章小结

本章介绍了项目初始化的核心命令：

| 命令 | 用途 |
|------|------|
| `/init` | 自动生成 `CLAUDE.md` 项目文档 |
| `/memory` | 管理跨会话的项目记忆 |
| `/config` | 调整个人偏好设置 |
| `/doctor` | 诊断和修复安装问题 |
| `/permissions` | 管理工具访问权限（预览） |

通过这些命令，你已经完成了：

1. 让 Claude 理解你的项目结构和技术栈
2. 配置了个人化的工作环境
3. 建立了跨会话的项目记忆
4. 确认系统运行正常

在下一章，我们将学习如何让 Claude 开始编写实际的代码。

第 2 章：项目初始化 — 让 Claude 理解你的项目

2.1 为什么需要项目初始化

2.2 /init — 生成 CLAUDE.md

语法

功能说明

实际使用示例

交互式初始化

CLAUDE.md 的位置

注意事项/技巧

2.3 CLAUDE.md 结构详解

生产构建

代码检查

测试

架构说明

目录结构

核心组件

数据流

代码约定

文件命名

组件结构

样式约定

性能考虑

常见任务

添加新组件

修改计时器逻辑

添加新功能

已知限制

2.4 /memory — 编辑项目记忆

语法

功能说明

实际使用示例

Auto-Memory 功能

注意事项/技巧

2.5 /config — 调整偏好设置

语法

功能说明

实际使用示例

主题设置

模型选择

编辑器模式（替代 /vim）

语言设置

注意事项/技巧

2.6 /doctor — 诊断安装问题

语法

功能说明

实际使用示例

自动修复

常见问题类型

注意事项/技巧

2.7 /permissions — 权限管理预览

语法

功能说明

实际使用示例

编辑规则

注意事项/技巧

2.8 动手做：初始化番茄钟项目

步骤 1：创建项目目录

步骤 2：启动 Claude Code

步骤 3：运行 /init 生成 CLAUDE.md

步骤 4：编辑 CLAUDE.md 补充项目信息

生产构建

架构说明

目录结构

代码约定

文件命名

2.2 `/init` — 生成 CLAUDE.md

2.4 `/memory` — 编辑项目记忆

2.5 `/config` — 调整偏好设置

2.6 `/doctor` — 诊断安装问题

2.7 `/permissions` — 权限管理预览

步骤 3：运行 `/init` 生成 CLAUDE.md