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

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

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

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

# 启动 Claude Code
claude

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

# 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`

## 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

// 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])
}

// 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' }
    });
  }
}

// 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');
  });
});

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

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

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

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

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

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

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

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 <[email protected]>"
git push -u origin feature/TICKET-123-product-favorites
gh pr create --title "feat: 商品收藏功能" --body "## Summary
- 用户可收藏/取消收藏商品
- 支持分页查看收藏列表
- 自动排除已下架商品

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

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

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

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

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

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

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

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

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

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

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

# 重新加载项目记忆
/init

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

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

# 启动 Claude Code
claude

> /init

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

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

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

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

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