<!-- title: Claude Code现有项目五步上手：入职到独立交付 -->

# Claude Code现有项目五步上手：从入职到独立交付

> **适用人群**：已安装 Claude Code 但面对团队现有代码库无从下手的新成员，或想用 AI 提升代码理解效率的中高级开发者
>
> **学习目标**：掌握用 Claude Code 快速理解陌生代码库、定位问题、提交首个功能修改的完整流程，在入职第一天就能产出有价值的代码

## 前置条件

| 条件 | 说明 |
|------|------|
| Node.js ≥ 18 | Claude Code 运行环境 |
| Claude Code CLI | `npm install -g @anthropic-ai/claude-code` |
| Anthropic 账户 | 需要有效的 API Key 或 Claude Pro/Max 订阅 |
| Git 基础 | clone、branch、commit、push |
| 一个现有项目 | 任何语言的 Git 仓库均可 |

本文假设你已安装 Claude Code。如果尚未安装，运行：

```bash
# macOS / Linux
npm install -g @anthropic-ai/claude-code

# 首次启动，完成 OAuth 认证
claude
```

---

## 第一步：接入代码库——用 /init 生成项目档案

### 场景

你刚 clone 了团队的仓库，面对成百上千个文件和复杂的目录结构，完全不知道从哪看起。传统方式需要花数天阅读文档和代码，而 Claude Code 可以在几分钟内帮你建立全局认知。

### 操作

```bash
# 进入项目目录
cd ~/projects/team-backend

# 启动 Claude Code
claude

# 在对话中运行初始化命令
> /init
```

`/init` 命令会扫描你的整个代码库，自动检测：

- **构建系统**：Maven、Gradle、npm、pip、Cargo 等
- **测试框架**：JUnit、pytest、Jest、Vitest 等
- **代码风格**：ESLint、Prettier、Black 配置
- **项目结构**：目录组织模式、入口文件
- **依赖关系**：核心依赖和版本

最终在项目根目录生成一个 `CLAUDE.md` 文件，这是 Claude Code 对你项目的"持久记忆"。

### 生成的 CLAUDE.md 示例

```markdown
# Project: team-backend

## Build & Run
- Build: `npm run build`
- Dev: `npm run dev`
- Test: `npm test`
- Lint: `npm run lint`

## Architecture
- Express.js REST API with TypeScript
- PostgreSQL via Prisma ORM
- Redis for session caching
- JWT authentication middleware

## Key Directories
- `src/routes/` — API route handlers
- `src/services/` — Business logic layer
- `src/models/` — Prisma schema definitions
- `src/middleware/` — Auth, logging, error handling

## Code Conventions
- Use TypeScript strict mode
- All API responses follow `{ success, data, error }` format
- Tests colocated with source: `*.test.ts`
```

### 进阶：手动补充 CLAUDE.md

`/init` 生成的文件是起点，你应该根据团队习惯补充关键信息：

```markdown
## Team Conventions
- Branch naming: `feature/TICKET-ID-description`
- Commit format: Conventional Commits (feat:, fix:, chore:)
- PR requires 2 approvals before merge
- Never push directly to main

## Known Issues
- Payment service mock in test env returns stale data
- User migration #142 is pending DBA review
```

### 常见问题

**Q: /init 扫描时间过长怎么办？**

大型项目（10万+ 文件）可能需要几分钟。你可以先创建 `.claudeignore` 文件排除不需要的目录：

```
node_modules/
dist/
build/
.git/
*.min.js
*.min.css
vendor/
__pycache__/
```

**Q: 项目没有 CLAUDE.md 也能用吗？**

可以，但没有 CLAUDE.md 时 Claude Code 每次都需要重新理解项目结构，效率显著降低。始终建议在项目根目录维护一份 CLAUDE.md。

---

## 第二步：代码库全景扫描——架构理解与关键路径定位

### 场景

你需要在 30 分钟内理解这个项目的整体架构，找出核心业务流程和关键代码路径。

### 操作

进入 Claude Code 对话后，使用一系列结构化提示词来建立认知：

```
> 请分析这个项目的整体架构，用层级方式展示模块依赖关系
```

Claude Code 会读取关键配置文件（`package.json`、`tsconfig.json`、`docker-compose.yml` 等）和源码，给出架构概览。接下来深入：

```
> 用户登录到下单支付的完整请求链路涉及哪些文件？
> 列出 src/services/ 目录下每个 service 的职责
> 哪些文件是最近一个月修改最频繁的？
```

### 用 Shift+Tab 进入 Plan 模式

在理解代码阶段，使用 Plan 模式可以避免意外修改文件：

1. 按两次 `Shift+Tab`，状态栏显示 `[plan mode]`
2. Plan 模式下 Claude Code 只读取和分析，不会编辑任何文件
3. 再次按 `Shift+Tab` 返回正常模式

```
> # 在 plan mode 下
> 分析 src/middleware/auth.ts 的认证流程，找出所有边界情况
```

### 关键提示词模板

| 目标 | 提示词 |
|------|--------|
| 理解入口 | `项目的启动入口在哪里？初始化流程是什么？` |
| 数据流 | `一个 HTTP 请求从进入到响应经过哪些层？` |
| 核心模块 | `列出最重要的 10 个文件并简述其职责` |
| 技术债务 | `代码中有哪些明显的 TODO、FIXME 或 HACK？` |
| 测试覆盖 | `哪些模块的测试覆盖率最低？` |

### 验证理解

让 Claude Code 考考你：

```
> 根据你已经分析的架构，出 5 道关于这个项目的问题来测试我的理解
```

---

## 第三步：第一个 Bug 修复——从定位到验证

### 场景

团队给你分配了第一个任务：修复一个用户报告的 Bug。这是证明自己价值的最佳机会。

### 操作流程

**3.1 获取 Bug 上下文**

```
> 用户报告：当购物车中有折扣商品时，总价计算错误，显示金额比实际多
> 请定位这个问题
```

**3.2 Claude Code 的定位过程**

Claude Code 会自动：
1. 搜索与"购物车"、"价格"、"折扣"相关的代码
2. 读取相关文件，分析计算逻辑
3. 定位到可能的 Bug 位置

**3.3 查看分析结果**

```
> 我找到了问题：在 src/services/cart.service.ts 第 47 行，折扣计算
> 在含税价格上叠加了折扣，但应该先折扣后计税。
>
> 当前逻辑（错误）：
> total = (price * quantity) * (1 + taxRate) * (1 - discountRate)
>
> 正确逻辑：
> total = (price * quantity) * (1 - discountRate) * (1 + taxRate)
```

**3.4 让 Claude Code 修复**

```
> 请修复这个问题，同时添加一个单元测试覆盖这个场景
```

**3.5 验证修复**

```bash
# 在 Claude Code 对话中
> 运行相关测试

# Claude Code 执行
npm test -- --grep "cart.*discount"
```

### 关键原则：分步确认

不要一次性让 Claude Code 做太多事。推荐的工作流程：

```
1. 先让 Claude Code 分析定位 → 你确认分析正确
2. 再让它提出修复方案 → 你审查方案
3. 最后让它实施修复 → 你验证结果
```

使用 Plan 模式（Shift+Tab）先让 Claude Code 规划修复方案，确认后再切回正常模式执行。

### 常见问题

**Q: Claude Code 的分析结果可能出错吗？**

可能。它可能定位到错误的文件或遗漏边界情况。始终用"审查"的态度看待它的分析，而不是盲目信任。运行测试是最好的验证手段。

**Q: 修复影响了其他功能怎么办？**

在修复前让 Claude Code 先运行完整的测试套件，确认修复后再次运行，对比结果：

```
> 先运行完整测试套件，记录当前状态
> （修复后）再次运行测试，确认没有回归
```

---

## 第四步：第一个功能开发——从设计到交付

### 场景

Bug 修复让你建立了信心。现在团队让你开发一个小功能：为用户添加"收藏商品"功能。

### 操作

**4.1 需求分析**

```
> 我需要为系统添加"商品收藏"功能：
> - 用户可以收藏/取消收藏商品
> - 查看收藏列表（支持分页）
> - 商品被下架时自动取消收藏
> 请先分析现有代码中哪些模块需要修改
```

**4.2 进入 Plan 模式设计**

按两次 `Shift+Tab` 进入 Plan 模式：

```
> 请给出完整的实现方案，包括：
> 1. 数据库 Schema 变更
> 2. 需要新增的文件
> 3. 需要修改的文件
> 4. API 接口设计
> 5. 测试计划
```

Claude Code 会输出详细的实现计划。仔细审查后，按 `Shift+Tab` 返回正常模式。

**4.3 分步实施**

```
> 按照计划，先实现数据库 Schema 变更
```

确认后：

```
> 现在实现收藏服务的核心逻辑
```

逐步推进，每完成一个步骤就运行测试验证：

```
> 运行测试确认 Schema 变更正确
```

**4.4 完整代码示例**

以下是一个典型的"商品收藏"功能实现，展示 Claude Code 生成代码的风格：

```typescript
// src/models/favorite.model.prisma — Schema
model Favorite {
  id         String   @id @default(uuid())
  userId     String
  productId  String
  createdAt  DateTime @default(now())

  user     User     @relation(fields: [userId], references: [id])
  product  Product  @relation(fields: [productId], references: [id])

  @@unique([userId, productId])
  @@index([userId])
}
```

```typescript
// src/services/favorite.service.ts — 核心逻辑
export class FavoriteService {
  async toggle(userId: string, productId: string): Promise<boolean> {
    const existing = await prisma.favorite.findUnique({
      where: { userId_productId: { userId, productId } }
    });

    if (existing) {
      await prisma.favorite.delete({ where: { id: existing.id } });
      return false; // 取消收藏
    }

    const product = await prisma.product.findUnique({
      where: { id: productId, status: 'ACTIVE' }
    });

    if (!product) {
      throw new NotFoundError('商品不存在或已下架');
    }

    await prisma.favorite.create({
      data: { userId, productId }
    });
    return true; // 添加收藏
  }

  async list(userId: string, page: number, pageSize: number) {
    return prisma.favorite.findMany({
      where: { userId, product: { status: 'ACTIVE' } },
      include: { product: { select: { id: true, name: true, price: true, imageUrl: true } } },
      skip: (page - 1) * pageSize,
      take: pageSize,
      orderBy: { createdAt: 'desc' }
    });
  }
}
```

```typescript
// src/services/favorite.service.test.ts — 测试
describe('FavoriteService', () => {
  it('should add favorite for active product', async () => {
    const result = await service.toggle(userId, productId);
    expect(result).toBe(true);
  });

  it('should remove existing favorite', async () => {
    await service.toggle(userId, productId); // 添加
    const result = await service.toggle(userId, productId); // 移除
    expect(result).toBe(false);
  });

  it('should reject favoriting delisted product', async () => {
    await expect(
      service.toggle(userId, delistedProductId)
    ).rejects.toThrow(NotFoundError);
  });

  it('should return paginated list excluding delisted products', async () => {
    const list = await service.list(userId, 1, 10);
    list.every(f => f.product.status !== 'DELISTED');
  });
});
```

**4.5 运行完整验证**

```
> 运行 lint 检查，然后运行完整测试套件，最后确认 build 通过
```

---

## 第五步：代码审查与提交——专业级交付

### 场景

功能开发完成，测试通过。现在需要提交代码并发起 Code Review。

### 操作

**5.1 让 Claude Code 审查自己的代码**

```
> 审查我这次的所有改动，从以下角度：
> 1. 安全性：是否有注入、XSS、权限漏洞？
> 2. 性能：是否有 N+1 查询、内存泄漏？
> 3. 边界情况：空值、并发、大数据量？
> 4. 代码风格：是否符合项目约定？
```

**5.2 查看改动范围**

```bash
# 在 Claude Code 对话中
> 查看 git diff，列出所有修改的文件和关键变更

# Claude Code 执行 git diff 并总结
git diff --stat
git diff
```

**5.3 提交代码**

```
> 请创建一个 commit，message 遵循 Conventional Commits 格式
```

Claude Code 会自动分析改动内容，生成规范的 commit message：

```
feat: add product favorites functionality

- Add Favorite model with Prisma schema
- Implement FavoriteService with toggle and list operations
- Add REST endpoints: POST /favorites, GET /favorites, DELETE /favorites/:id
- Add unit tests covering core scenarios
- Auto-exclude delisted products from favorites list
```

**5.4 创建分支和 PR**

```
> 创建 feature/TICKET-123-product-favorites 分支
> 推送到远程并创建 PR，标题和描述符合团队规范
```

Claude Code 会执行完整的 Git 工作流：

```bash
git checkout -b feature/TICKET-123-product-favorites
git add src/models/favorite.model.prisma src/services/favorite.service.ts \
        src/services/favorite.service.test.ts src/routes/favorites.ts
git commit -m "feat: add product favorites functionality

- Add Favorite model with Prisma schema
- Implement FavoriteService with toggle and list operations
- Add REST endpoints and unit tests

Co-Authored-By: Claude <noreply@anthropic.com>"
git push -u origin feature/TICKET-123-product-favorites
gh pr create --title "feat: 商品收藏功能" --body "## Summary
- 用户可收藏/取消收藏商品
- 支持分页查看收藏列表
- 自动排除已下架商品

## Test plan
- [x] 单元测试：添加/移除收藏
- [x] 单元测试：下架商品过滤
- [x] 单元测试：分页查询
- [ ] 集成测试（待 QA 确认环境）
- [ ] E2E 测试"
```

---

## 完整工作流架构图

```mermaid
flowchart TD
    A[入职第一天] --> B["Step 1: /init 生成 CLAUDE.md"]
    B --> C["Step 2: 架构理解与代码导航"]
    C --> D["Step 3: 第一个 Bug 修复"]
    D --> E["Step 4: 第一个功能开发"]
    E --> F["Step 5: 代码审查与提交"]

    B --> B1["扫描项目结构"]
    B --> B2["检测构建/测试工具"]
    B --> B3["生成项目档案"]

    C --> C1["Plan 模式分析"]
    C --> C2["关键路径定位"]
    C --> C3["模块依赖理解"]

    D --> D1["Bug 定位分析"]
    D --> D2["修复方案确认"]
    D --> D3["测试验证"]

    E --> E1["需求分析"]
    E --> E2["分步实施"]
    E --> E3["逐步测试"]

    F --> F1["自我代码审查"]
    F --> F2["规范 Commit"]
    F --> F3["创建 PR"]

    style A fill:#4A90D9,color:#fff
    style F fill:#2ECC71,color:#fff
    style B fill:#F39C12,color:#fff
    style C fill:#E67E22,color:#fff
    style D fill:#E74C3C,color:#fff
    style E fill:#9B59B6,color:#fff
```

---

## 新手避坑指南：八大常见错误

### 错误一：不写 CLAUDE.md 就开始开发

**后果**：Claude Code 每次对话都要重新理解项目，产生不一致的代码风格。

**正确做法**：

```bash
# 项目初始化后立即运行
/init

# 手动补充团队约定
# 在 CLAUDE.md 中添加 coding standards、branch rules 等
```

### 错误二：一次性给出过于宽泛的指令

```bash
# 错误示范
> 重构整个认证模块，顺便加上日志，再优化一下性能

# 正确做法：拆分为明确的步骤
> 分析 src/middleware/auth.ts 的认证流程
> # 确认分析后
> 将 token 验证逻辑提取为独立的 verifyToken 函数
> # 确认修改后
> 在 verifyToken 函数中添加请求日志
```

### 错误三：不验证直接采纳代码

**后果**：引入隐藏 Bug、安全漏洞或不一致的实现。

**正确做法**：

```
> 审查你刚才生成的代码，从安全和性能角度分析
> 运行所有相关测试
> 检查是否有潜在的类型错误
```

### 错误四：忽略 .claudeignore 文件

**后果**：Claude Code 浪费上下文窗口读取无关文件（如 `node_modules`、`dist`、`.git`），降低理解能力。

**正确做法**：

```bash
# 创建 .claudeignore
echo "node_modules/
dist/
build/
.git/
*.min.js
*.min.css
coverage/
vendor/
__pycache__/
.next/
" > .claudeignore
```

### 错误五：在主分支直接开发

**后果**：破坏主分支稳定性，团队 CI 流水线可能中断。

**正确做法**：

```
> 创建 feature 分支并切换
> # 开发完成后
> 提交到 feature 分支并创建 PR
```

### 错误六：不使用 Plan 模式

**后果**：Claude Code 在分析阶段可能意外修改文件，产生难以追踪的变更。

**正确做法**：理解代码阶段按 `Shift+Tab` 进入 Plan 模式，确认方案后再切回执行。

### 错误七：上下文过长不重启会话

**后果**：Claude Code 的响应质量随上下文增长而下降，可能出现"幻觉"。

**正确做法**：

```
# 当对话过长（超过 20-30 轮），使用 /compact 压缩上下文
/compact

# 或使用 /clear 开始新对话
/clear

# 重新加载项目记忆
/init
```

### 错误八：不利用 `@文件名` 精确引用

**后果**：Claude Code 可能分析错误的文件或遗漏关键依赖。

**正确做法**：

```
# 直接引用需要分析的文件
> 分析 @src/services/cart.service.ts 的折扣逻辑
> 对比 @src/services/cart.service.ts 和 @src/services/order.service.ts 的价格计算
```

---

## 实战案例：30 分钟上手一个陌生的 Python FastAPI 项目

### 项目背景

假设你加入了一个使用 FastAPI + SQLAlchemy + PostgreSQL 的后端团队，需要快速上手并完成第一个任务。

```bash
# 克隆项目
git clone https://github.com/example-team/fastapi-backend.git
cd fastapi-backend

# 启动 Claude Code
claude
```

**Step 1：初始化（3 分钟）**

```
> /init
```

确认生成的 CLAUDE.md 内容准确，补充遗漏信息。

**Step 2：架构理解（5 分钟）**

```
> 用表格列出所有 API 端点，包括路径、方法、认证要求
> 数据库有哪些表？表之间的关联关系是什么？
> 项目使用哪些中间件？执行顺序是什么？
```

**Step 3：运行项目（5 分钟）**

```
> 这个项目怎么启动？帮我检查依赖是否齐全
> 运行项目并确认没有启动错误
```

**Step 4：领取任务（10 分钟）**

```
> 任务：为 /api/users/{id} 端点添加返回用户的最近 10 条活动记录
> 先分析需要修改哪些文件，给出实施计划
```

**Step 5：实施与验证（7 分钟）**

```
> 按计划实施，注意遵循项目中现有的代码风格
> 运行测试确认改动正确
> 创建 feature 分支并提交
```

---

## 日常开发效率对照表

| 传统方式 | Claude Code 方式 | 节省时间 |
|----------|-----------------|---------|
| 花 2-3 天读代码理解项目 | 30 分钟获得架构概览 | ~90% |
| 逐文件搜索 Bug 位置 | 自动定位并分析根因 | ~70% |
| 手写 CRUD 接口和测试 | 描述需求自动生成 | ~60% |
| 手动编写 commit message | 自动分析 diff 生成规范消息 | ~80% |
| 手动创建 PR 描述 | 自动生成 Summary 和 Test Plan | ~75% |

---

## CLAUDE.md 分层记忆体系

理解 CLAUDE.md 的分层机制，能让 Claude Code 在不同场景下保持正确行为：

```mermaid
flowchart LR
    G["~/.claude/CLAUDE.md<br/>全局偏好"] --> P["项目根/CLAUDE.md<br/>项目规范"]
    P --> D["src/module/CLAUDE.md<br/>模块约定"]
    D --> F["CLAUDE.local.md<br/>个人配置 (不提交)"]

    G -.- G1["语言偏好<br/>Commit 规范<br/>全局规则"]
    P -.- P1["构建命令<br/>架构说明<br/>代码风格"]
    D -.- D1["模块规则<br/>特定约束<br/>依赖说明"]
    F -.- F1["个人快捷键<br/>调试偏好<br/>本地路径"]

    style G fill:#3498DB,color:#fff
    style P fill:#2ECC71,color:#fff
    style D fill:#F39C12,color:#fff
    style F fill:#E74C3C,color:#fff
```

| 层级 | 文件位置 | 作用范围 | 是否提交 Git |
|------|---------|---------|------------|
| 全局 | `~/.claude/CLAUDE.md` | 所有项目 | 否 |
| 项目 | `项目根目录/CLAUDE.md` | 当前项目 | 是 |
| 模块 | `子目录/CLAUDE.md` | 当前目录及子目录 | 是 |
| 个人 | `CLAUDE.local.md` | 当前项目（个人） | 否（加入 .gitignore） |

---

## 常用命令速查表

### 启动与配置

| 命令 | 说明 |
|------|------|
| `claude` | 启动交互式对话 |
| `claude -p "指令"` | 非交互模式，直接执行一条指令 |
| `claude --resume` | 恢复上一次对话 |
| `claude --model sonnet` | 指定使用的模型 |

### 对话内命令

| 命令 | 说明 |
|------|------|
| `/init` | 初始化项目，生成 CLAUDE.md |
| `/compact` | 压缩当前对话上下文 |
| `/clear` | 清空对话历史 |
| `/cost` | 查看当前会话的 Token 消耗 |
| `/help` | 查看所有可用命令 |
| `Shift+Tab` | 切换 Plan/Act 模式 |
| `@文件名` | 引用特定文件 |

### Git 集成

| 命令 | 说明 |
|------|------|
| `> 查看 git status` | 查看当前改动状态 |
| `> 创建 commit` | 分析改动并生成规范提交 |
| `> 创建 PR` | 自动生成 PR 标题和描述 |

---

## 延伸阅读

- **Anthropic 官方文档**：[code.claude.com/docs](https://code.claude.com/docs/en/quickstart) — Claude Code 完整使用手册，涵盖安装、配置、工作流和最佳实践
- **Claude Code Best Practices**：[code.claude.com/docs/en/best-practices](https://code.claude.com/docs/en/best-practices) — Anthropic 官方推荐的高效使用模式
- **Common Workflows**：[code.claude.com/docs/en/common-workflows](https://code.claude.com/docs/en/common-workflows) — 代码探索、Bug 修复、重构、测试等日常开发场景的分步指南
- **Claude Code Memory**：[code.claude.com/docs/en/memory](https://code.claude.com/docs/en/memory) — CLAUDE.md 分层记忆系统的完整说明

## 训练营适用性评估

| 维度 | 评估 |
|------|------|
| 适合训练营类型 | 企业新员工入职训练营、团队 AI 工具速成班、高校软件工程实践课 |
| 预计教学时长 | 3-4 小时（含实操练习） |
| 学员基础要求 | 会使用 Git 和终端，了解至少一门编程语言 |
| 实操环节占比 | 70%（每一步都有动手练习） |
| 硬件要求 | 每人一台带终端环境的笔记本，已安装 Node.js 和 Claude Code |
| 课程结构建议 | 1h 理论讲解 + 2h 跟练 + 1h 独立完成挑战任务 |

## 参考来源

1. [Quickstart - Claude Code Docs](https://code.claude.com/docs/en/quickstart) — Anthropic 官方快速上手指南，涵盖终端 CLI、桌面应用和 Web 端的安装配置
2. [Best practices for Claude Code](https://code.claude.com/docs/en/best-practices) — 官方最佳实践文档，包含 /init、上下文管理、提示词工程等核心建议
3. [Claude Code Tutorial for Beginners - Complete 2026 Guide](https://codewithmukesh.com/blog/claude-code-for-beginners/) — 面向零基础开发者的完整教程，从安装到项目开发
4. [How Claude Code works in large codebases](https://claude.com/blog/how-claude-code-works-in-large-codebases-best-practices-and-where-to-start) — Anthropic 工程博客，详解大型代码库中的 Claude Code 部署模式
5. [Common Mistakes - Claude Code Best Practices](https://muhammadusmangm.github.io/claude-code-best-practices/guides/common-mistakes/) — 社区整理的 Claude Code 常见错误和修复方法

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)