Claude Code的免费层级是初学者和轻度使用者的重要入口点，但也存在一定的限制。本文将深入解析2026年免费层级的具体限制、福利对比，以及帮助用户做出明智选择的实用建议。

免费层级概览

什么是Claude Code免费层级？

Claude Code免费层级允许用户：

• 在Web界面使用Claude的强大模型进行聊天
• 获得一定量的免费代码生成能力
• 体验Claude Code的核心功能

访问方式

• Web聊天：通过claude.ai访问
• VS Code集成：通过Claude Code插件
• 终端CLI：通过命令行工具
• Slack集成：在Slack中使用Claude

第一部分：详细限制解析

1. 消息限额

核心限制

实战案例：消息限制如何影响实际使用

案例1：数据科学家的工作流

“我使用免费层级分析数据集，但消息限制让我无法完成复杂的分析流程。通常在第30-40条消息左右，我就达到了每日限额。这意味着我必须精心规划每次会话，避免浪费宝贵的消息额度。”

案例2：学习新框架

“作为一名初学者，我经常需要在Claude Code中反复提问来理解新的概念。消息限制让我无法进行深入的多轮对话。我学会了先在搜索引擎中查找资料，整理好问题后，再一次性提出多个相关问题，这样可以节省大量消息额度。”

案例3：代码生成和调试

“我主要用Claude Code来生成和修改代码。通常一个中等大小的任务需要30-50轮对话。当接近每日限额时，我必须做出选择：要么今天完成这个任务，要么留到明天继续。合理规划消息使用对于免费用户来说是关键技能。”

2. 模型访问

可用模型

免费层级通常可以访问Claude的最新模型，但可能存在以下限制：

模型版本：

• Claude 3.5 Sonnet（2025年主力模型）
• Claude 3.5 Opus（最强推理模型）
• Claude 4.0系列（2026年最新）

使用场景：

| 场景 | 可用模型 | 限制 |
|——–|———–|———|——-|
| 简单聊天 | Sonnet 3.5 | 默认选择，平衡速度和质量 |
| 复杂推理 | Opus 3.5 | 可能需要特别请求或有限访问 |
| 长上下文 | 上下文窗口 | 可能受限，不适用于大型项目 |
| 代码生成 | Sonnet 3.5 | 主要用例，适合日常开发 |

注意：免费用户可能无法获得最新模型的优先访问，付费用户在高负载时期享有优先权。

3. 功能限制

Claude Code特定功能

| 功能 | 免费层级状态 | 说明 |
|——–|—————|——|———-|
| Agent Teams | 限制或不可用 | 实验性功能，主要为付费用户设计 |
| MCP服务器 | 基础MCP | 可使用官方和社区MCP，企业级MCP可能限制 |
| 上下文窗口 | 200K tokens | 标准大小，但1M tokens为付费功能 |
| 自定义命令 | 有限 | 可创建简单命令，高级自动化受限 |
| Director Mode | 不可用 | 需要Pro或Max计划 |

4. 使用场景限制

不推荐的用法

第二部分：福利对比

1. 消息福利对比

2. 上下文管理

| 福利 | 免费层级 | Pro/Max |
|——–|———–|———-|———-|
| 上下文窗口 | 200K tokens | 200K tokens | 1M tokens（beta） |
| 长期记忆 | 会话级 | 会话级 | 会话级 + 项目级记忆 |
| 项目上下文 | CLAUDE.md | CLAUDE.md | CLAUDE.md + 智能总结 |
| 文件访问 | 基础 | 基础 | 所有功能 |

3. 模型特性

| 特性 | 免费层级 | Pro计划 | Max计划 |
|——–|———–|———-|———-|———-|
| 模型选择 | 自动Sonnet 3.5 | Sonnet/Opus可切换 | 最高优先级最新模型 |
| 高负载访问 | 限制 | 标准 | 优先 | 最高优先级 |
| 优先级提升 | 无 | Pro/Max可设置 | 所有用户可设置 |
| API访问 | 无 | 有限 | 按用量计费，需Pro |

第三部分：定价分析

1. 订阅计划对比

Claude Code官方定价（2026年3月）

2. 性价比分析

对于不同使用场景

场景1：轻量使用（每周几次）

• 推荐计划：免费层级
• 理由：成本最低，功能满足需求
• 月度成本：$0

场景2：学习和小项目（每周10-20次使用）

• 推荐计划：免费层级
• 理由：充分利用免费额度，无需付费
• 月度成本：$0
• 建议：合理规划消息使用，避免浪费

场景3：专业开发（每周20-40次使用）

• 推荐计划：Claude Pro ($20/月）
• 理由：5倍容量，支持日常开发和一些代码生成
• 月度成本：$20
• 建议：对于专业开发者来说，Pro计划是性价比最高的选择

场景4：重度使用或团队协作（每周40+次使用）

• 推荐计划：Claude Max ($100/月）或Claude Max 200 ($200/月）
• 理由：1,000-4,000条月度消息，支持团队工作流
• 月度成本：$100-$200
• 建议：对于团队或企业用户，Max计划是必要投资

场景5：企业级应用

• 推荐计划：Claude Max 200 ($200/月）
• 理由：4,000条消息，最高优先级，所有模型访问
• 月度成本：$200
• 建议：联系销售团队获取企业折扣

3. 免费使用技巧

最大化免费价值

1. 消息效率：

• 合并相关问题，一次提出多个相关查询
• 使用清晰的上下文，减少来回沟通
• 利用CLAUDE.md提供项目信息，避免重复解释

2. 时间管理：

• 集中在工作时间使用，避免分散使用
• 记住重置时间（通常是UTC 00:00），在重置前完成重要任务
• 使用会话历史回顾，避免重复询问相同问题

3. 功能优先使用：

• 专注于核心功能：聊天、简单代码生成、内容分析
• 避免使用需要高资源的功能（如长上下文）
• 使用web搜索获取信息，减少消息使用

4. 学习策略：

• 优先掌握基础功能，再探索高级特性
• 阅读官方文档和社区最佳实践
• 参与GitHub开源项目和教程

5. 模型选择技巧：

• 默认使用Sonnet 3.5，它速度快且成本低
• 只在需要复杂推理时才使用Opus
• 避免频繁切换模型，消耗消息额度

第四部分：替代方案补充

1. 其他AI编码工具

| 工具 | 免费层级 | 付费情况 | 特点 |
|——–|———–|———-|———-|———-|
| GitHub Copilot | 有免费层级 | 按仓库收费 | IDE集成，代码补全强大 |
| Cursor | 有免费层级 | 按订阅收费 | IDE深度集成，AI能力强 |
| Windsurf | 完全免费 | 完全免费 | 基于Fork的VS Code，AI生成能力 |
| Replit | 有免费层级 | 按使用量计费 | 在线IDE，支持项目构建 |
| Aider | 完全免费（CLI） | 完全免费 | 命令行AI编码代理 |

2. 学习资源

官方资源

• Claude Code文档：https://claude.com/docs
• Claude Code教程：https://claude.com/resources/use-cases
• API文档：https://platform.claude.com/docs
• 博客：https://claude.com/blog

社区资源

• r/ClaudeAI：免费用户讨论和技巧分享
• r/ClaudeCode：Claude Code专项讨论
• r/ClaudeCodeLearning：学习路径和经验分享

教程和课程

• Claude Code Beginner Guide：官方入门指南
• Real-World Claude Code Examples：实战案例集合
• Claude Code Best Practices：最佳实践合集

第五部分：决策指南

选择合适计划的关键问题

1. 你如何使用Claude Code？

• 主要用于聊天和文本处理
• 偶尔用于代码生成和调试
• 每周使用2-3次
• 主要在工作日使用

2. 你的预算是多少？

• 没有明确预算，希望使用免费层级
• 愿意每月花费$20以内
• 成本敏感型用户

3. 你需要什么级别的服务？

轻度使用：免费层级完全满足

• 日常开发**：Claude Pro提供足够容量
• 专业开发**：Claude Max提供所需容量和优先级
• 企业团队**：Claude Max 200提供企业级支持

4. 你是否需要特定功能？

决策树

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

开始
  │
  ├─ 是轻度使用者？
  │   ├─ 否 → 每周<10次使用？
  │   │   ├─ 否 → 每周10-40次使用？
  │   │   ├─ 否 → 每周40+次使用？
  │   │   ├─ 否 → 团队协作？
  │   └─ 是 → 推荐 Max或Max 200
  │       │
  │       ├─ 是企业？
  │       │   ├─ 否 → 推荐 Max（$100）
  │       │   └─ 是 → 推荐 Max 200（$200）
  │
  └─ 推荐免费层级
      （每天40-50条消息足够）

推荐方案

阶段1：初学者和轻度使用者

推荐：从免费层级开始
理由：

• 成本最低，无付费压力
• 功能满足日常学习和轻度开发需求
• 消息限额足够用于学习和实验
• 可随时升级到付费计划

行动建议：

1. 注册免费账号，熟悉界面和功能
2. 学习核心功能：聊天、简单代码生成
3. 善用消息，不要浪费在无意义的对话上
4. 阅读文档和教程，了解最佳实践
5. 使用web搜索获取信息，减少消息使用

阶段2：专业开发者和重度使用者

推荐：Claude Pro ($20/月）
理由：

• 5倍消息容量（每月约1,000条）
• 访问所有模型
• 支持日常开发和复杂项目
• 性价比高，月度成本合理
• 适合独立开发者和小团队

行动建议：

1. 评估你的实际使用量，确保Pro计划物有所值
2. 利用上下文管理功能，保持会话清晰
3. 设置使用量提醒，避免意外超限
4. 考虑批量购买（年付折扣）

阶段3：企业团队和重度生产环境

推荐：Claude Max 200 ($200/月）
理由：

• 20倍消息容量（每月4,000条）
• 最高优先级支持
• 1M上下文窗口
• 所有模型访问
• 支持企业级协作和大规模项目

行动建议：

1. 联系销售团队获取企业定制方案
2. 建立团队使用规范，确保资源合理分配
3. 使用项目级记忆功能（CLAUDE.md）提高效率
4. 设置预算和监控，控制成本

阶段4：混合策略

推荐：免费层级 + 按需升级到Pro/Max
理由：

• 免费层级处理日常和突发任务
• 付费层级处理重要和复杂项目
• 根据任务类型选择合适的计划，优化成本

行动建议：

1. 分析你的工作负载，识别哪些任务可以在免费层级完成
2. 对于需要大量资源或高优先级的任务，临时升级到付费计划
3. 定期评估使用情况，调整订阅策略

总结

核心洞察

1. 免费层级价值巨大：为初学者和轻度使用者提供了零成本的入门点
2. 限制是现实存在的：消息、上下文、高级功能都有合理限制
3. 升级路径清晰：从免费 → Pro → Max → Max 200
4. 免费使用技巧可以极大提升价值：效率管理、消息优化、功能优先使用
5. 决策应基于实际需求：不要盲目追求最高计划，而是选择最适合你的使用场景

给新手的建议

1. 从免费开始：注册免费账号，熟悉界面和功能，评估你的使用需求
2. 合理使用消息：合并问题，善用CLAUDE.md，避免浪费
3. 设置使用提醒：记住重置时间，在限额前完成重要任务
4. 学习文档：充分利用官方文档、教程和社区资源
5. 保持现实预期：免费层级不是为重度使用或生产环境设计的，不要因为它有限制而感到挫败

下一步行动

如果你正在考虑升级到付费计划，建议：

1. 先在免费层级尝试1-2周，了解你的实际使用模式
2. 记录消息使用量、功能使用频率、遇到的限制
3. 评估付费计划的ROI（投资回报），选择最适合你的计划
4. 关注优惠活动，年付通常有折扣

Claude Code的免费层级为用户提供了强大的起点。通过明智使用和按需升级，你可以获得最佳的价值/成本比，同时避免不必要的付费。记住，最贵的计划不一定最适合你，选择正确比选择最贵更重要。

Claude Code 教程：从零开始掌握 AI 编程的完整指南

在 2026 年，Claude Code 已经成为 AI 编程领域的领导者，从零到排名第一工具只用了八个月时间。本文将带你从零开始，系统性地掌握 Claude Code，并通过实际案例展示其强大功能。

为什么选择 Claude Code

在深入教程之前，让我们先了解一下为什么 Claude Code 值得学习：

• 性能优势：根据最新测试数据，Claude 4 平均响应时间为 60ms，而 GitHub Copilot 的 p99 响应时间为 43ms。在实际使用场景中，两者的性能差异几乎可以忽略不计。
• 代理式执行：Claude Code 不仅能提供建议，还能独立执行完整任务。对于需要多个步骤的复杂重构或功能实现，Claude Code 表现尤为出色。
• 深度理解能力：相比简单的代码补全，Claude Code 能够理解项目结构、代码上下文和开发意图。

安装与配置

系统要求

在使用 Claude Code 之前，请确保你的系统满足以下最低要求：

• 操作系统：Linux、macOS 或 Windows 10+（推荐使用类 Unix 系统）
• 终端：支持 ANSI 转义序列的现代终端
• 网络：稳定的互联网连接

快速安装

1
2
3
4
5
6
7
8

# 使用 npm 安装（推荐）
npm install -g @anthropic/claude-code

# 或使用 pip 安装
pip install claude-code

# 验证安装
claude --version

配置文件设置

创建配置文件 ~/.claude/CLAUDE.md 来定制你的工作流程：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# 我的工作规则

## 项目上下文
- 项目使用 Next.js 14 + TypeScript
- 状态管理使用 Zustand
- 样式使用 Tailwind CSS

## 代码风格
- 遵循 ESLint 规则
- 使用 2 空格缩进
- 单行长度不超过 100 字符

## 测试要求
- 所有新功能必须有单元测试
- 测试覆盖率至少 80%
- 使用 Vitest 作为测试框架

## Git 工作流
- 功能分支从 `develop` 分出
- Pull Request 必须经过至少一人 Code Review
- 合并前必须通过 CI 检查

核心命令详解

1. Plan 模式：智能规划

Plan 模式是 Claude Code 的杀手级功能。它能让你用自然语言描述目标，然后自动生成详细的实施计划。

1
2
3
4
5
6
7
8
9
10

# 启动 Plan 模式
claude plan "实现用户认证功能，包括登录、注册和密码重置"

# Claude 会生成详细的任务清单
# 1. 创建用户模型和接口定义
# 2. 实现登录表单和验证逻辑
# 3. 实现注册表单和验证逻辑
# 4. 实现密码重置流程
# 5. 添加单元测试
# 6. 更新 API 文档

最佳实践：

• 在 Plan 模式中尽量一次性描述完整的业务需求
• 使用具体的文件路径和函数名称
• 生成计划后，先审查再执行

2. Director 模式：并行执行

Director 模式让你能够同时管理多个并行的开发会话，极大提升团队协作效率。

1
2
3
4
5
6
7

# 启动 Director 模式
claude director

# 然后创建多个并行会话
claude director --session frontend "优化前端性能"
claude director --session backend "重构 API 层"
claude director --session tests "补充测试用例"

使用场景：

• 团队开发：不同成员可以并行处理不同模块
• 个人工作：同时进行编码、测试、文档编写
• 迭代优化：在修复 Bug 的同时进行性能优化

3. Agent 工作流：自动化复杂任务

Agent 工作流让你能够创建自动化的代理来处理重复性或复杂任务。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# 在 CLAUDE.md 中定义代理
@agent testing {
  description: "自动化测试用例生成和执行"
  triggers: ["src/发生变化", "提交代码"]
  workflow: [
    "分析变更的代码",
    "生成对应的测试用例",
    "执行测试并报告结果"
  ]
}

@agent documentation {
  description: "自动更新 API 文档"
  triggers: ["接口发生变化"]
  workflow: [
    "提取新的接口定义",
    "生成文档草稿",
    "提交到文档仓库"
  ]
}

实战案例：构建完整功能

让我们通过一个完整的例子来展示如何在实际项目中使用 Claude Code。

案例：实现博客文章的搜索和筛选功能

第一步：使用 Plan 模式规划

1
2
3
4
5
6
7

claude plan "为博客系统实现搜索功能，包括：
1. 全文搜索（基于标题和内容）
2. 标签筛选
3. 日期范围筛选
4. 分页和排序
5. 搜索结果高亮
技术栈：Next.js 14 + TypeScript + Prisma"

生成的计划包括：

• 创建搜索 API 路由
• 实现 Prisma 查询逻辑
• 添加前端搜索组件
• 实现搜索结果高亮
• 添加标签和日期筛选组件
• 编写集成测试

第二步：逐个执行任务

创建 API 路由：

1

claude "创建 src/app/api/posts/search/route.ts，实现搜索接口"

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79

// src/app/api/posts/search/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { prisma } from '@/lib/prisma';

interface SearchParams {
  q?: string;
  tags?: string;
  startDate?: string;
  endDate?: string;
  page?: number;
  limit?: number;
}

export async function GET(request: NextRequest) {
  const { searchParams } = new URL(request.url);
  const { q, tags, startDate, endDate, page = 1, limit = 10 } = searchParams as SearchParams;

  try {
    const where: any = {};

    // 全文搜索
    if (q) {
      where.OR = [
        { title: { contains: q, mode: 'insensitive' } },
        { content: { contains: q, mode: 'insensitive' } }
      ];
    }

    // 标签筛选
    if (tags) {
      const tagList = tags.split(',');
      where.tags = { hasSome: tagList };
    }

    // 日期范围筛选
    if (startDate || endDate) {
      where.publishedAt = {};
      if (startDate) {
        where.publishedAt.gte = new Date(startDate);
      }
      if (endDate) {
        where.publishedAt.lte = new Date(endDate);
      }
    }

    const skip = (Number(page) - 1) * Number(limit);
    const [posts, total] = await Promise.all([
      prisma.post.findMany({
        where,
        orderBy: { publishedAt: 'desc' },
        skip,
        take: Number(limit),
        include: {
          tags: true,
          author: {
            select: { name: true, avatar: true }
          }
        }
      }),
      prisma.post.count({ where })
    ]);

    return NextResponse.json({
      posts,
      pagination: {
        page: Number(page),
        limit: Number(limit),
        total,
        totalPages: Math.ceil(total / Number(limit))
      }
    });
  } catch (error) {
    console.error('Search error:', error);
    return NextResponse.json(
      { error: '搜索失败，请稍后重试' },
      { status: 500 }
    );
  }
}

实现搜索组件：

1

claude "创建 src/components/SearchBar.tsx，实现搜索输入框和筛选器"

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

'use client';

import { useState, useEffect } from 'react';
import { useRouter, useSearchParams } from 'next/navigation';

export default function SearchBar() {
  const router = useRouter();
  const searchParams = useSearchParams();
  const [query, setQuery] = useState(searchParams.get('q') || '');
  const [tags, setTags] = useState(searchParams.get('tags') || '');
  const [debouncedQuery, setDebouncedQuery] = useState(query);

  // 防抖处理
  useEffect(() => {
    const timer = setTimeout(() => {
      setDebouncedQuery(query);
    }, 300);
    return () => clearTimeout(timer);
  }, [query]);

  // 执行搜索
  useEffect(() => {
    if (debouncedQuery || tags) {
      const params = new URLSearchParams();
      if (debouncedQuery) params.set('q', debouncedQuery);
      if (tags) params.set('tags', tags);
      router.push(`/blog/search?${params}`);
    }
  }, [debouncedQuery, tags, router]);

  const handleSearch = (e: React.FormEvent) => {
    e.preventDefault();
    const formData = new FormData(e.currentTarget);
    const searchValue = formData.get('search') as string;
    const tagsValue = formData.get('tags') as string;
    setQuery(searchValue);
    setTags(tagsValue);
  };

  return (
    <form onSubmit={handleSearch} className="flex gap-2 mb-4">
      <input
        type="text"
        name="search"
        placeholder="搜索文章..."
        defaultValue={query}
        className="flex-1 px-4 py-2 border rounded-lg focus:ring-2 focus:ring-blue-500"
      />
      <input
        type="text"
        name="tags"
        placeholder="标签（逗号分隔）"
        defaultValue={tags}
        className="w-48 px-3 py-2 border rounded-lg"
      />
      <button
        type="submit"
        className="px-6 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700"
      >
        搜索
      </button>
    </form>
  );
}

编写单元测试：

1

claude "创建 src/__tests__/api/search.test.ts，为搜索接口编写测试"

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

import { GET } from '@/app/api/posts/search/route';
import { createMocks } from 'node-mocks-http';

describe('搜索 API', () => {
  beforeEach(async () => {
    // 清空测试数据
  });

  it('应该返回搜索结果', async () => {
    const mockRequest = createMocks({
      url: 'http://localhost:3000/api/posts/search?q=test',
      method: 'GET'
    });

    const response = await GET(mockRequest as any);
    const data = await response.json();

    expect(response.status).toBe(200);
    expect(data).toHaveProperty('posts');
    expect(data.posts).toBeInstanceOf(Array);
  });

  it('应该处理标签筛选', async () => {
    const mockRequest = createMocks({
      url: 'http://localhost:3000/api/posts/search?tags=react,nextjs',
      method: 'GET'
    });

    const response = await GET(mockRequest as any);
    const data = await response.json();

    expect(response.status).toBe(200);
    expect(data.posts.every((post: any) => 
      post.tags.some((tag: any) => ['react', 'nextjs'].includes(tag))
    )).toBe(true);
  });

  it('应该返回 500 错误当数据库出错时', async () => {
    // Mock prisma 错误
    const mockRequest = createMocks({
      url: 'http://localhost:3000/api/posts/search',
      method: 'GET'
    });

    const response = await GET(mockRequest as any);
    expect(response.status).toBe(500);
  });
});

第三步：验证和优化

1
2
3
4
5
6
7
8

# 运行测试
npm test

# 使用 Lighthouse 检查性能
npm run lighthouse

# 让 Claude Code 优化代码
claude "优化搜索 API 性能，添加数据库索引建议"

Claude Code 可能会建议：

• 为 title 和 content 字段添加数据库索引
• 实现查询结果缓存
• 使用连接池优化数据库连接
• 添加限流机制防止滥用

高级技巧与最佳实践

1. 高效的上下文传递

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# 在项目中创建 .claude/context.md

## 当前任务
我们正在实现博客搜索功能，当前阶段是 API 开发。

## 相关文件
- src/app/api/posts/search/route.ts
- src/components/SearchBar.tsx
- src/lib/prisma.ts

## 数据模型
Post {
  id: String
  title: String
  content: String
  tags: Tag[]
  publishedAt: DateTime
  author: User
}

## 约束条件
- 搜索结果最多返回 100 条
- 每个标签必须有至少一篇文章
- 已删除的文章不参与搜索

2. 安全的 Hook 使用

在 CLAUDE.md 中配置 PostToolUse hooks：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

## 安全 Hook 规则

@posttooluse validate-inputs {
  description: "验证所有输入参数",
  priority: 1,
  rules: [
    "对用户输入进行验证",
    "对文件路径进行验证",
    "对 API 密钥进行保护"
  ]
}

@posttooluse check-path-traversal {
  description: "防止路径遍历攻击",
  rules: [
    "禁止使用 ..",
    "使用绝对路径",
    "验证文件扩展名"
  ]
}

3. 团队协作模式

代码审查工作流

1
2
3
4
5
6
7
8
9
10
11
12
13

# 创建审查分支
git checkout -b feature/blog-search

# 开发完成后，创建 PR
git push origin feature/blog-search
# 在 GitHub 上创建 Pull Request

# 让 Claude Code 辅助审查
claude "审查这个 PR 的代码变更，关注：
1. 代码风格是否符合规范
2. 是否有潜在的安全问题
3. 测试覆盖率是否足够
4. 性能是否有优化空间"

知识共享

创建项目级知识库：

1
2
3
4
5
6
7
8

# .claude/knowledge/team-guidelines.md

## 代码风格指南
- 使用 TypeScript 严格模式
- 遵循 Airbnb TypeScript 风格指南
- 所有函数必须有 JSDoc 注释

## 项目结构约定

src/
├── app/ # Next.js 应用路由
├── components/ # 可复用组件
├── lib/ # 工具库
├── types/ # TypeScript 类型定义
├── tests/ # 测试文件
└── public/ # 静态资源

1
2
3
4

## 常见问题解决方案
- 如何处理 Prisma 连接池：参考 docs/prisma-connection-pool.md
- 如何优化图片上传：参考 docs/image-upload-optimization.md

性能优化实战

1. 识别性能瓶颈

1
2
3
4
5
6
7
8
9
10
11

# 使用 Claude Code 分析性能问题
claude "分析这个搜索接口的性能问题，并提供优化方案：
当前实现：
- 全文搜索使用 OR 条件
- 每次查询都进行完整数据库访问
- 没有使用缓存

请提供：
1. 性能瓶颈分析
2. 优化建议
3. 预期性能提升"

Claude Code 可能会建议：

• 使用全文搜索引擎（如 Elasticsearch 或 MeiliSearch）
• 实现查询结果缓存（Redis 或内存缓存）
• 优化数据库查询（添加索引、减少 JOIN）
• 实现分页和虚拟滚动

2. 实施缓存策略

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

// src/lib/cache.ts
import { LRUCache } from 'lru-cache';

export interface CacheEntry<T> {
  data: T;
  timestamp: number;
}

class SearchCache {
  private cache: LRUCache<string, CacheEntry<any>>;
  private readonly ttl = 5 * 60 * 1000; // 5分钟缓存

  constructor() {
    this.cache = new LRUCache({
      max: 500,
      ttl: this.ttl,
      calcSize: (value) => 1
    });
  }

  async get<T>(key: string): Promise<T | null> {
    const entry = this.cache.get(key);
    if (!entry) return null;
    
    // 检查是否过期
    if (Date.now() - entry.timestamp > this.ttl) {
      this.cache.del(key);
      return null;
    }
    
    return entry.data;
  }

  async set<T>(key: string, data: T): Promise<void> {
    this.cache.set(key, {
      data,
      timestamp: Date.now()
    });
  }

  clear(): void {
    this.cache.clear();
  }
}

export const searchCache = new SearchCache();

3. 数据库查询优化

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

// src/lib/prisma-extensions.ts
import { PrismaClient } from '@prisma/client';

const prisma = new PrismaClient();

// 创建扩展方法
prisma.$extends({
  query: {
    posts: {
      searchByTitle: async (query: string) => {
        return prisma.post.findMany({
          where: {
            title: {
              contains: query,
              mode: 'insensitive'
            }
          },
          select: {
            id: true,
            title: true,
            publishedAt: true
          }
        });
      },
      
      searchByContent: async (query: string) => {
        return prisma.post.findMany({
          where: {
            content: {
              contains: query,
              mode: 'insensitive'
            }
          },
          select: {
            id: true,
            content: true,
            publishedAt: true
          }
        });
      }
    }
  }
});

export { prisma };

故障排查指南

常见问题及解决方案

1. 安装问题

问题：command not found: claude

解决方案：

1
2
3
4
5
6
7
8

# 检查 PATH
echo $PATH

# 重新加载 shell 配置
source ~/.zshrc

# 或使用 npx 运行
npx @anthropic/claude-code --version

2. API 认证失败

问题：AuthenticationError: Invalid API key

解决方案：

1
2
3
4
5
6
7
8

# 检查 API key 配置
claude auth show

# 重新设置 API key
claude auth set sk-ant-xxxx

# 验证配置
claude auth test

3. 上下文丢失

问题：Claude Code 不记得之前的对话

解决方案：

1
2
3
4
5
6
7
8

# 保存当前会话
claude session save my-work

# 列出所有会话
claude session list

# 恢复会话
claude session load my-work

调试技巧

1
2
3
4
5
6
7
8

# 启用详细日志
claude config set log.level debug

# 查看 Claude Code 日志
claude logs tail

# 测试配置
claude config validate

最佳实践总结

✅ DO（推荐做法）

1. 始终使用 Plan 模式开始新任务

   • 这样可以确保目标的清晰理解
   • 避免后续的反复修改

2. 保持 CLAUDE.md 文件的更新

   • 项目规则需要变更时及时更新
   • 上下文信息要保持准确

3. 编写充分的测试

   • 单元测试覆盖率至少 80%
   • 集成测试覆盖主要用户流程

4. 使用版本控制

   • 每个功能分支对应一个明确的任务
   • 提交信息要清晰描述变更内容

5. 定期审查代码

   • 让 Claude Code 辅助代码审查
   • 关注安全性、性能和可维护性

❌ DON’T（避免做法）

1. 不要盲目信任 Claude 的输出

   • 总是验证生成的代码
   • 测试关键功能

2. 不要在 Plan 模式中生成过多细节

   • 保持计划的高层抽象
   • 细节在执行阶段确定

3. 不要忽略错误信息

   • 及时处理警告和错误
   • 记录问题的解决方案

4. 不要在没有配置的情况下直接运行

   • 确保环境变量设置正确
   • 验证依赖版本兼容性

5. 不要在生产环境使用实验性功能

   • 先在开发环境充分测试
   • 使用 feature flags 控制新功能

进阶学习资源

官方文档

• Claude Code 官方文档
• 最佳实践指南
• API 参考

社区资源

• Claude Code 最佳实践 GitHub 仓库
• ClaudeLog - 教程和指南
• Claude Code 完整指南 2026
• Florian Bruniaux 的终极指南

推荐阅读顺序

1. 新手入门：先阅读官方文档的 Getting Started 部分
2. 最佳实践：理解官方最佳实践指南
3. 实战案例：通过实际项目练习所学
4. 进阶技巧：学习高级工作流和 Agent 配置
5. 社区贡献：参与开源项目，分享你的经验

结语

Claude Code 是一个强大的 AI 编程工具，但掌握它需要时间和实践。本文涵盖了从安装到高级技巧的完整流程，并通过实际的博客搜索案例展示了如何在实际项目中应用这些知识。

记住：

• 循序渐进：不要急于求成，逐步掌握每个功能
• 持续学习：AI 编程领域发展迅速，保持关注最新动态
• 实践为王：理论结合实践才能真正掌握
• 分享经验：与团队和社区分享你的经验和教训

开始你的 Claude Code 之旅吧，它将成为你开发过程中不可或缺的伙伴！

参考资源：

• Claude Code 官方文档：https://code.claude.com/docs/en/overview
• 最佳实践指南：https://code.claude.com/docs/en/best-practices
• ClaudeLog 社区：https://claudelog.com/
• Claude Code 2026 完整指南：https://claude-world.com/articles/claude-code-complete-guide-2026/

一、引言：企业80%的真实场景

新项目从0到1的开发只占企业开发工作的20%，剩下80%是存量产品的迭代开发：大版本升级、平台迁移、新增模块、功能改造。这些场景的核心挑战不是”如何写代码”，而是”如何让AI理解你的项目”。

Claude Code（以下简称CC）默认状态下，它不认识你的项目、不知道你的技术约束、不了解你的业务规则。如果直接问”帮我重构这个模块”，CC会：

• 按自己的偏好选择技术栈
• 无视已有的组件封装
• 改动一处影响三处

本文的核心思路：把散落的上下文工程化，让CC从”猜”变成”遵守”。通过系统化的方法论，将项目背景、技术约束、业务规则显性化，让AI成为真正懂你的协作者。

七大痛点分析

二、五阶段SOP总览

流程全景图

1
2
3
4
5
6
7
8

graph TD
    A[阶段一：项目上下文建设<br/>一次性投入] --> B[阶段二：需求对齐<br/>每次迭代]
    B --> C[阶段三：约束建立<br/>一次性投入+持续更新]
    C --> D[阶段四：开发执行<br/>每次迭代]
    D --> E[阶段五：验证与沉淀<br/>每次迭代]
    E -.-> A
    C -.-> C
    E -.-> C

痛点×阶段映射矩阵

标注：★=主要解决，○=辅助解决

三、阶段一：项目上下文建设

目标

建立项目的”百科全书”，让CC在第一句话就知道：这是什么项目、用啥技术、有什么约束。

具体步骤

步骤1：扫描项目生成CLAUDE.md

使用CC的扫描能力生成根级和模块级CLAUDE.md：

1
2

# 根级CLAUDE.md（项目整体信息）
claude @. --init-project --output CLAUDE.md

生成的CLAUDE.md包含：

• 项目名称、用途、业务领域
• 技术栈（语言、框架、数据库、中间件）
• 目录结构说明
• 关键模块职责

对于多模块项目，还要生成模块级CLAUDE.md：

1
2
3

# 模块级CLAUDE.md（模块特定信息）
claude @modules/user-service --init-project --output modules/user-service/CLAUDE.md
claude @modules/order-service --init-project --output modules/order-service/CLAUDE.md

步骤2：写入业务术语表和软硬件约束

在CLAUDE.md中手动补充（CC无法自动识别）：

1
2
3
4

## 业务术语表
- SKU: Stock Keeping Unit，商品最小库存单元
- GMV: Gross Merchandise Volume，成交总额
- ...

1
2
3
4
5

## 软硬件约束
- 数据库: MySQL 8.0，必须使用MyBatis Plus
- 缓存: Redis 5.0，禁止使用@Cacheable注解
- 第三方: 必须走公司统一网关
- 性能要求: 接口响应时间<500ms

步骤3：多组件项目的全局索引策略

Monorepo场景：在根目录CLAUDE.md中添加模块索引

1
2
3
4

## 模块索引
- `@modules/user-service`: 用户服务，负责用户认证、资料管理
- `@modules/order-service`: 订单服务，负责订单创建、状态流转
- `@modules/payment-service`: 支付服务，对接支付宝、微信

多仓场景：在每个仓库根目录建立CLAUDE.md，并在关键依赖中添加外部引用

1
2
3

## 外部依赖
- 用户服务API: https://git.corp.com/user-api
- 支付SDK: https://git.corp.com/payment-sdk

流程图

1
2
3
4
5
6
7
8
9
10
11

graph TD
    A[项目扫描] --> B{项目类型?}
    B -->|单模块| C[生成根级CLAUDE.md]
    B -->|多模块| D[生成根级+模块级CLAUDE.md]
    C --> E[补充业务术语表]
    C --> F[补充软硬件约束]
    D --> E
    D --> F
    E --> G[建立模块索引]
    F --> G
    G --> H[验证: 用CLAUDE.md回答项目问题]

检查清单

• CLAUDE.md包含项目基本信息
• 技术栈版本明确标注
• 业务术语表完整
• 软硬件约束无遗漏
• 多模块项目建立索引
• 测试：询问CC”这个项目用什么数据库”，能从CLAUDE.md得到正确答案

四、阶段二：需求对齐

目标

从散落的代码中”逆向”出完整的PRD，消除需求黑箱。

具体步骤

步骤1：多维度扫描生成PRD初稿

关键原则：四个维度分别扫描，不要用一个大prompt。

维度一：从API入口追踪完整调用链

1
2
3

claude @controllers/OrderController.java @services/OrderService.java \
  "分析订单创建的完整调用链，从Controller到Service到Repository到数据库操作。
  输出到 docs/order-create-flow.md，不要修改任何代码。"

维度二：从数据模型反推业务规则

1
2
3

claude @entities/Order.java @migrations/V2__create_order.sql \
  "分析订单表结构和字段约束，反推业务规则（如订单状态机、金额精度要求）。
  输出到 docs/order-business-rules.md。"

维度三：从异常处理和校验逻辑挖掘边界条件

1
2
3

claude @services/OrderService.java \
  "提取所有异常处理和参数校验逻辑，总结边界条件和异常场景。
  输出到 docs/order-edge-cases.md。"

维度四：从配置文件和外部依赖发现隐藏行为

1
2
3

claude @application.yml @resources/config/payment.properties \
  "分析配置项和外部依赖，总结隐藏的开关、限流、降级等行为。
  输出到 docs/order-hidden-behaviors.md。"

步骤2：合并去重 + 生成覆盖度自检表

1
2
3

claude @docs/order-*.md \
  "合并四个维度的扫描结果，生成完整的订单功能PRD，并生成覆盖度自检表（已识别/待确认）。
  输出到 docs/order-prd-complete.md。"

覆盖度自检表示例：

步骤3：用Git历史和已有测试交叉补充

1
2
3
4
5
6
7
8
9

# 从Git提交历史补充隐性需求
claude --git-history 20 \
  "分析最近20次提交，总结新增的需求和Bug修复，补充到PRD。
  输出到 docs/order-prd-history.md。"

# 从测试用例补充边界条件
claude @tests/OrderServiceTest.java \
  "分析测试用例，提取隐含的业务规则和边界条件，补充到PRD。
  输出到 docs/order-prd-test-coverage.md。"

步骤4：用PRD反向生成测试，跑测试验证PRD准确性

1
2
3
4

claude @docs/order-prd-complete.md @src/ \
  "基于PRD生成测试用例（使用JUnit 5），然后运行这些测试。
  如果测试通过，说明PRD准确；如果失败，说明PRD有误或代码有bug。
  输出到 tests/generated/OrderServicePrdTest.java。"

这是最关键的验证机制：测试通过=PRD准确，测试失败=需要修正PRD或代码。

步骤5：人工补充隐性规则

5类典型隐性规则：

将这些规则写入@docs/implicit-rules.md。

流程图（三角验证）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

graph TD
    A[现有代码] --> B[维度一: API调用链]
    A --> C[维度二: 数据模型]
    A --> D[维度三: 异常处理]
    A --> E[维度四: 配置依赖]
    B --> F[合并生成PRD初稿]
    C --> F
    D --> F
    E --> F
    F --> G[Git历史补充]
    F --> H[测试用例补充]
    G --> I[完整PRD]
    H --> I
    I --> J[反向生成测试]
    J --> K{测试通过?}
    K -->|是| L[✅ PRD准确]
    K -->|否| M[❌ 修正PRD或代码]
    M --> J

检查清单

• 四个维度分别扫描，非单一prompt
• 覆盖度自检表已生成
• Git历史已分析
• 测试用例已补充
• PRD反向生成测试并验证通过
• 隐性规则已文档化

五、阶段三：约束建立

目标

建立三层防线，确保CC遵守项目规范。

具体步骤

三层防线架构

1
2
3

graph LR
    A[CLAUDE.md<br/>告知层] --> B[.claude/rules/<br/>禁止层]
    B --> C[Hooks<br/>拦截层]

第一层：CLAUDE.md（告知层）

• 作用：告诉CC项目的基本约束
• 示例：

1
2
3
4

## 技术约束
- 必须使用MyBatis Plus，禁止直接写SQL
- 所有接口返回统一格式Result<T>
- 禁止使用@Cacheable，必须用RedisTemplate

第二层：.claude/rules/（禁止层）

• 作用：明确的禁止性规则，CC违反时直接拒绝
• 规则文件格式：

1
2
3
4
5

## 规则: 禁止直接写SQL

### ✅ 正确做法
```java
userMapper.selectById(id);

❌ 禁止做法

1
2

@Select("SELECT * FROM user WHERE id = #{id}")
User findById(Long id);

使用示例

错误示范会自动被拦截

1
2
3
4
5
6
7
8
9
10

**第三层：Hooks（拦截层）**
- 作用：在代码提交前自动检查
- 示例`.claude/hooks/pre-commit.md`：
```markdown
## 检查项1: SQL注入风险
运行grep -r "SELECT \* FROM" src/，如果发现直接拼接SQL，拒绝提交。

## 检查项2: 未使用的导入
运行mvn checkstyle:check，如果有未使用的导入，警告但允许提交。

流程图

1
2
3
4
5
6
7
8
9
10

graph TD
    A[CLAUDE.md] --> B{违反告知?}
    B -->|否| C[生成代码]
    B -->|是| D[提示遵循CLAUDE.md]
    C --> E{违反Rules?}
    E -->|否| F[生成代码]
    E -->|是| G[拒绝生成]
    F --> H{违反Hooks?}
    H -->|否| I[✅ 允许]
    H -->|是| J[拒绝提交]

检查清单

• CLAUDE.md包含技术约束
• .claude/rules/目录已创建
• 关键规则已写成Rules文件（格式：✅做法+❌做法+示例）
• Hooks已配置（pre-commit）
• 测试：故意违反规则，验证CC能拦截

六、阶段四：开发执行

目标

在约束下安全开发，控制风险。

具体步骤

步骤1：计划先行，人工批准

推荐使用Plan模式或workflow skill：

1
2
3
4
5
6

# Plan模式
claude --permission-mode plan
"重构订单状态机，从5个状态扩展到8个状态。先生成详细计划。"

# 或使用workflow skill
/workflow refactor-order-state-machine

CC会生成详细的实施计划，人工批准后再执行。

步骤2：小步快跑，每步验证

1
2
3
4
5
6
7
8
9
10

graph TD
    A[拆分任务] --> B[实现第一步]
    B --> C[运行测试]
    C --> D{测试通过?}
    D -->|是| E[提交代码]
    D -->|否| F[修复代码]
    F --> C
    E --> G{还有步骤?}
    G -->|是| B
    G -->|否| H[✅ 完成]

决策循环图：

• 每次改动后立即运行测试
• 测试通过才进入下一步
• 失败则立即回滚或修复

步骤3：多组件协同策略

策略一：接口契约先行

1
2
3
4

# 先定义接口
claude @order-service @payment-service \
  "定义订单支付接口契约（方法签名、参数、返回值、异常），
  输出到 docs/payment-contract.md。"

策略二：按依赖方向执行

依赖链条：order-service → payment-service → bank-service

执行顺序：

1. 先改最下游的bank-service
2. 测试通过后再改payment-service
3. 最后改order-service

策略三：Agent Team并行

1
2
3
4
5
6
7
8
9
10

# 定义Agent Team
claude --agent-team
"需求分析师：分析需求，生成PRD
Architect：设计架构
java-dev：开发支付模块
web-dev：开发前端支付页
QA：生成测试用例并验证"

# 并行执行
claude --agent-team "执行订单支付功能开发"

步骤4：大范围改动用Worktree隔离

1
2
3
4
5
6
7
8

# 创建Worktree
git worktree add ../order-service-v2-refactor refactor/branch

# 在Worktree中开发
claude @../order-service-v2-refactor "重构订单服务"

# 测试通过后再合并
git worktree remove ../order-service-v2-refactor

检查清单

• 已使用Plan模式或workflow skill
• 任务已拆分为小步骤
• 每步都有测试验证
• 多组件协同按依赖顺序执行
• 大范围改动使用Worktree隔离

七、阶段五：验证与沉淀

目标

验证功能正确性，沉淀经验避免下次重复踩坑。

具体步骤

流程图

1
2
3
4
5
6
7
8
9
10

graph TD
    A[开发完成] --> B[系统级QA验证]
    B --> C{验证通过?}
    C -->|否| D[修复问题]
    D --> B
    C -->|是| E[代码审查]
    E --> F[更新CLAUDE.md]
    E --> G[沉淀错误到Memory]
    E --> H[生成工程文档]
    H --> I[下次迭代复用]

步骤1：系统级QA验证

1
2
3
4

# QA Agent运行完整测试
claude --agent qa
"运行完整测试套件（单元测试+集成测试+端到端测试），
生成测试报告，输出到 docs/test-report.md。"

步骤2：代码审查

1
2
3

# 生成代码审查清单
claude @src/ "生成代码审查清单，关注点：性能、安全、可维护性，
输出到 docs/code-review-checklist.md。"

步骤3：更新CLAUDE.md

将新发现的技术约束和业务规则补充到CLAUDE.md：

1
2

claude @docs/test-report.md @CLAUDE.md
"将测试报告中发现的约束补充到CLAUDE.md。"

步骤4：沉淀错误到Memory

1
2
3
4

# 记录本次迭代遇到的问题和解决方案
claude --memory "订单状态机重构过程中，
遇到的bug：状态流转时未加锁导致并发问题。
解决方案：使用数据库乐观锁。"

步骤5：生成/更新工程基线文档

• 架构设计文档：docs/architecture.md
• 详细设计文档：docs/design/order-state-machine.md
• 数据库设计文档：docs/database/order-schema.md
• 接口文档：docs/api/payment-api.md

步骤6：数据库变更用Flyway管理

1
2
3
4

# 生成Flyway迁移脚本
claude @entities/Order.java @migrations/
"生成Flyway迁移脚本V3__update_order_state_machine.sql，
使用ALTER TABLE语法，避免DROP TABLE。"

检查清单

• 系统级QA验证通过
• 代码审查完成
• CLAUDE.md已更新
• 错误已沉淀到Memory
• 工程文档已生成
• 数据库变更已用Flyway管理

八、实战演示

项目背景

一个三端应用的v2.0版本迭代：

• 后端：Java + Spring Boot + MyBatis Plus
• 前端：Next.js + TypeScript + Ant Design
• 移动端：Flutter

迭代目标：从v1.0的单店模式升级到v2.0的多店模式。

阶段一：项目上下文建设

1
2

# 扫描后端项目
claude @backend/ --init-project --output backend/CLAUDE.md

生成的backend/CLAUDE.md关键内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

## 项目信息
项目名称：电商订单系统
业务领域：B2C电商

## 技术栈
- Java 17
- Spring Boot 2.7
- MyBatis Plus 3.5
- MySQL 8.0
- Redis 6.0

## 关键模块
- `@backend/modules/order`: 订单服务
- `@backend/modules/user`: 用户服务
- `@backend/modules/product`: 商品服务

补充业务术语：

1
2
3
4

## 业务术语表
- 单店模式：一个账号只能管理一个店铺
- 多店模式：一个账号可以管理多个店铺
- 店铺ID (shop_id): 店铺的唯一标识，v2.0新增字段

阶段二：需求对齐

维度一：API调用链扫描

1
2

claude @backend/modules/order/src/main/java/controller/OrderController.java \
  "分析订单创建API的完整调用链，输出到 docs/order-create-flow.md。"

生成的docs/order-create-flow.md：

1
2
3
4
5
6
7
8

## 订单创建调用链

1. OrderController.createOrder()
2. → OrderService.createOrder()
3. → ProductClient.checkStock() (RPC调用)
4. → UserClient.checkUserStatus() (RPC调用)
5. → OrderMapper.insert()
6. → PaymentClient.createPayment() (RPC调用)

维度二：数据模型反推业务规则

1
2

claude @backend/modules/order/src/main/java/entity/Order.java \
  "分析订单实体，反推业务规则，输出到 docs/order-business-rules.md。"

发现的问题：

1
2

## 发现的问题
当前订单表没有shop_id字段，无法支持多店模式。

维度三：异常处理挖掘边界条件

1
2

claude @backend/modules/order/src/main/java/service/OrderService.java \
  "提取异常处理逻辑，输出到 docs/order-edge-cases.md。"

维度四：配置文件发现隐藏行为

1
2

claude @backend/application.yml \
  "分析配置项，输出到 docs/order-hidden-behaviors.md。"

逆向PRD生成

1
2

claude @backend/docs/order-*.md \
  "合并生成订单功能PRD，输出到 docs/order-prd-v1.md。"

生成的PRD关键内容：

1
2
3
4
5
6
7
8
9
10
11
12

# 订单功能PRD (v1.0单店模式)

## 功能描述
用户可以创建订单，系统会检查库存和用户状态，然后创建订单记录。

## 业务规则
1. 一个用户只能有一个店铺（隐含规则）
2. 订单金额必须大于0
3. 库存不足时订单创建失败

## 数据模型
订单表包含字段：id, user_id, product_id, amount, status, created_at

人工补充隐性规则

创建docs/implicit-rules.md：

1
2
3
4
5
6
7
8
9

## 业务潜规则
- v1.0版本中，user_id等同于shop_id（一个用户一个店）
- v2.0需要解耦：一个用户可以有多个shop

## 历史决策
- 订单状态使用字符串存储，不是枚举（历史遗留）

## 性能红线
- 批量创建订单单次不超过1000条

PRD反向生成测试验证

1
2
3

claude @backend/docs/order-prd-v1.md @backend/modules/order/src/main/java/ \
  "基于PRD生成测试用例，使用JUnit 5，输出到 backend/modules/order/src/test/java/OrderPrdTest.java。
  然后运行测试，验证PRD准确性。"

测试结果：✅ 通过（说明PRD准确）

阶段三：约束建立

创建Rules文件

.claude/rules/database-rule.md：

1
2
3
4
5
6

## 规则: 数据库变更必须使用Flyway

### ✅ 正确做法
```bash
# 创建Flyway迁移脚本
claude @entities/Order.java @migrations/ "生成Flyway脚本V2__add_shop_id.sql"

❌ 禁止做法

1
2

-- 禁止直接修改数据库
ALTER TABLE `order` ADD COLUMN `shop_id` BIGINT;

使用示例

所有数据库变更必须生成Flyway迁移脚本

1
2
3
4
5
6
7
8
9
10

`.claude/rules/mybatis-rule.md`：

```markdown
## 规则: 禁止直接写SQL

### ✅ 正确做法
```java
userMapper.selectById(id);
userMapper.insert(user);

❌ 禁止做法

1
2

@Select("SELECT * FROM user WHERE id = #{id}")
User findById(Long id);

使用示例

所有数据库操作必须使用MyBatis Plus方法

1
2
3
4
5
6
7
8
9
10
11

#### 配置Hooks

`.claude/hooks/pre-commit.md`：

```markdown
## 检查项1: Flyway脚本命名规范
运行grep -r "^--" migrations/，检查脚本以V开头。

## 检查项2: 未使用的导入
运行mvn checkstyle:check，如果有未使用的导入，警告。

阶段四：开发执行

步骤1：Plan模式生成实施计划

1
2
3

claude --permission-mode plan
"实施订单表添加shop_id字段，支持多店模式。
生成详细计划，包括：数据库迁移、后端代码修改、前端代码修改。"

CC生成的计划：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

# 实施计划：订单表添加shop_id字段

## 阶段1：数据库迁移
1. 生成Flyway脚本V2__add_shop_id.sql
2. 添加shop_id字段，默认值为user_id
3. 为shop_id创建索引

## 阶段2：后端代码修改
1. 修改Order实体，添加shopId字段
2. 修改OrderMapper的查询方法，支持shopId过滤
3. 修改OrderService，支持多店订单查询
4. 修改OrderController，添加shopId参数

## 阶段3：前端代码修改
1. 修改订单创建页面，添加店铺选择器
2. 修改订单列表页面，添加店铺筛选
3. 修改API调用，传递shopId参数

## 阶段4：测试
1. 单元测试
2. 集成测试
3. 端到端测试

人工审查计划后，批准执行。

步骤2：小步快跑实现

步骤2.1：数据库迁移

1
2
3

claude @backend/modules/order/src/main/java/entity/Order.java @backend/migrations/ \
  "生成Flyway脚本V2__add_shop_id.sql，使用ALTER TABLE语法，添加shop_id字段。
  输出到 backend/migrations/V2__add_shop_id.sql。"

生成的V2__add_shop_id.sql：

1
2
3
4
5
6
7
8

-- 添加shop_id字段
ALTER TABLE `order` ADD COLUMN `shop_id` BIGINT NOT NULL DEFAULT 0 COMMENT '店铺ID';

-- 为shop_id创建索引
CREATE INDEX idx_shop_id ON `order`(`shop_id`);

-- 为现有数据填充shop_id（等于user_id）
UPDATE `order` SET shop_id = user_id WHERE shop_id = 0;

运行迁移脚本：

1

mvn flyway:migrate

✅ 迁移成功。

步骤2.2：后端代码修改

1
2
3

claude @backend/modules/order/src/main/java/entity/Order.java \
  "添加shopId字段，使用Long类型，添加字段注释。
  不要修改其他代码。"

1
2
3

claude @backend/modules/order/src/main/java/mapper/OrderMapper.java \
  "添加selectByShopId方法，使用MyBatis Plus的QueryWrapper。
  输出示例代码。"

1
2
3

claude @backend/modules/order/src/main/java/service/OrderService.java \
  "修改createOrder方法，添加shopId参数，并保存到订单记录。
  修改queryOrders方法，支持shopId过滤。"

运行测试：

1

mvn test

✅ 测试通过。

步骤2.3：前端代码修改

1
2
3

claude @frontend/src/pages/order/create.tsx \
  "添加店铺选择器，使用Select组件，数据来源：/api/shops。
  将选中的shopId传递给订单创建接口。"

1
2

claude @frontend/src/pages/order/list.tsx \
  "添加店铺筛选器，使用Select组件，支持筛选不同店铺的订单。"

运行前端测试：

1

npm test

✅ 测试通过。

步骤3：多组件协同

后端多服务协同

后端有3个微服务：order-service, product-service, user-service。

按依赖顺序执行：

1. 先改product-service（添加shopId检查）
2. 再改user-service（添加shop列表查询）
3. 最后改order-service（使用shopId）

1
2
3
4
5
6
7
8

# 先改product-service
claude @product-service/ "修改商品查询接口，支持shopId过滤"

# 测试通过后，改user-service
claude @user-service/ "添加shop列表查询接口"

# 测试通过后，改order-service
claude @order-service/ "修改订单创建接口，使用shopId"

步骤4：Agent Team并行开发

1
2
3
4
5
6
7

claude --agent-team
"需求分析师：分析多店模式需求，生成PRD
Architect：设计多店模式架构
java-dev-order：开发订单服务
java-dev-product：开发商品服务
web-dev：开发前端页面
QA：生成测试用例并验证"

并行执行：

• 需求分析师生成PRD
• Architect设计架构
• java-dev-order开发订单服务
• java-dev-product开发商品服务
• web-dev开发前端页面
• QA生成测试用例并验证

阶段五：验证与沉淀

系统级QA验证

1
2
3

claude --agent qa
"运行完整测试套件：单元测试+集成测试+端到端测试。
生成测试报告，输出到 docs/test-report-v2.md。"

测试结果：

• 单元测试：✅ 通过（120个用例）
• 集成测试：✅ 通过（35个用例）
• 端到端测试：✅ 通过（10个用例）

代码审查

1
2
3

claude @backend/src/ @frontend/src/
"生成代码审查清单，关注点：性能、安全、可维护性。
输出到 docs/code-review-checklist.md。"

审查发现：

• ⚠️ 订单查询接口缺少分页参数（性能问题）
• ✅ SQL注入防护到位
• ✅ 权限检查完善

修复性能问题：

1
2

claude @backend/modules/order/src/main/java/service/OrderService.java \
  "添加分页参数，使用MyBatis Plus的Page对象。"

更新CLAUDE.md

1
2

claude @docs/test-report-v2.md @backend/CLAUDE.md
"将测试报告中发现的约束补充到CLAUDE.md。"

更新的CLAUDE.md：

1
2
3
4
5

## 技术约束
- 必须使用MyBatis Plus，禁止直接写SQL
- 所有接口返回统一格式Result<T>
- 禁止使用@Cacheable，必须用RedisTemplate
- **所有列表查询接口必须支持分页** (新增)

沉淀错误到Memory

1
2
3
4
5
6

claude --memory "多店模式开发过程中，
遇到的bug1：订单查询接口缺少分页，导致大量数据时性能问题。
解决方案：使用MyBatis Plus的Page对象。

遇到的bug2：shop_id字段初始值为0，导致查询错误。
解决方案：Flyway脚本中UPDATE现有数据，shop_id = user_id。"

生成工程文档

1
2
3

claude @backend/ "生成多店模式架构文档，输出到 docs/architecture/multi-shop.md"
claude @backend/modules/order/ "生成订单服务详细设计，输出到 docs/design/order-service.md"
claude @frontend/ "生成前端API文档，输出到 docs/api/frontend-api.md"

数据库变更用Flyway管理

验证Flyway脚本已生成：

• ✅ V1__init_schema.sql
• ✅ V2__add_shop_id.sql

本次迭代解决的痛点

九、CC工具箱速查

分层约束体系表

命令/技能/代理速查表

工作流分级表

十、结语：4条关键原则

1. 上下文先行：在开发前，先建设CLAUDE.md和Rules，让AI”懂”项目。
2. 逆向工程：从代码逆向PRD，用测试验证PRD，消除需求黑箱。
3. 小步快跑：拆分任务，每步验证，控制风险。
4. 持续沉淀：每次迭代后更新CLAUDE.md和Memory，避免重复踩坑。

存量产品的迭代开发不是靠AI”猜”出来的，而是靠系统化的方法论”造”出来的。建立好工程化体系，CC才能真正成为你的AI协作者。

附录：CC Prompt编写规范

所有prompt示例必须遵守以下CC最佳实践：

1. 用 @路径 引用具体文件/目录，不用 [模块路径] 占位符
2. 指定输出文件位置（如 输出到 docs/xxx.md）
3. 分析类prompt必须加 不要修改任何代码 或 只描述现有行为
4. 测试类prompt必须指定测试框架
5. 优先推荐使用skill/Plan模式，手动prompt作为备选
6. 收窄扫描范围（核心代码 而非 所有代码）

数据可视化最佳实践：从原始数据到洞察呈现

数据可视化是将复杂数据转化为直观、易懂的图形表示的过程。良好的可视化能够帮助发现数据中的模式、趋势和异常，从而支持更好的决策制定。

数据可视化的价值

加速理解：

• 人脑处理图像的速度比文本快6万倍
• 快速识别数据中的模式和异常
• 提高信息传递效率

增强洞察：

• 发现隐藏在数据中的关系
• 识别数据分布和趋势
• 支持数据驱动的决策

促进沟通：

• 简化复杂数据的呈现
• 支持跨部门的数据交流
• 建立共同的数据理解

可视化设计原则

1. 简洁性原则

减少认知负担：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 数据准备示例
import pandas as pd
import matplotlib.pyplot as plt

# 简化数据，聚焦关键指标
def simplify_data(df):
    # 选择关键维度
    key_dimensions = ['date', 'category', 'metric']
    simplified_df = df[key_dimensions]
    
    # 聚合计数
    summary_df = simplified_df.groupby(['date', 'category']).sum().reset_index()
    
    return summary_df

2. 一致性原则

保持视觉连贯：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# 颜色方案管理
class ColorScheme:
    # 主色调
    PRIMARY = '#3498db'
    
    # 辅助色
    SECONDARY = ['#e74c3c', '#f1c40f', '#2ecc71', '#9b59b6']
    
    # 灰度等级
    GRAYSCALE = ['#f7f7f7', '#dcdcdc', '#999999', '#666666', '#333333']
    
    @staticmethod
    def get_color(index, scheme='primary'):
        if scheme == 'primary':
            return ColorScheme.PRIMARY
        elif scheme == 'secondary':
            return ColorScheme.SECONDARY[index % len(ColorScheme.SECONDARY)]
        elif scheme == 'grayscale':
            return ColorScheme.GRAYSCALE[index % len(ColorScheme.GRAYSCALE)]

图表类型选择

1. 趋势分析

折线图：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

import matplotlib.pyplot as plt
import seaborn as sns

def plot_trend(data, x_col, y_col, title="Trend Analysis"):
    plt.figure(figsize=(12, 6))
    
    # 绘制趋势线
    sns.lineplot(data=data, x=x_col, y=y_col, 
                color=ColorScheme.PRIMARY, linewidth=2)
    
    # 添加置信区间
    if 'std' in data.columns:
        plt.fill_between(data[x_col], 
                        data[y_col] - data['std'],
                        data[y_col] + data['std'],
                        color=ColorScheme.PRIMARY, alpha=0.2)
    
    plt.title(title, fontsize=16, fontweight='bold')
    plt.xlabel(x_col.capitalize(), fontsize=12)
    plt.ylabel(y_col.capitalize(), fontsize=12)
    plt.grid(True, alpha=0.3, linestyle='--')
    
    return plt

2. 分布分析

直方图与箱线图：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

def plot_distribution(data, value_col, title="Distribution Analysis"):
    fig, axes = plt.subplots(1, 2, figsize=(15, 5))
    
    # 直方图
    axes[0].hist(data[value_col], bins=30, 
                    color=ColorScheme.PRIMARY, 
                    edgecolor='black', alpha=0.7)
    axes[0].set_title(f'Histogram of {value_col}', fontweight='bold')
    axes[0].set_xlabel(value_col.capitalize())
    axes[0].set_ylabel('Frequency')
    
    # 箱线图
    axes[1].boxplot(data[value_col], 
                     patch_artist=True,
                     boxprops=dict(facecolor=ColorScheme.PRIMARY, alpha=0.7),
                     medianprops=dict(color='red', linewidth=2))
    axes[1].set_title(f'Boxplot of {value_col}', fontweight='bold')
    axes[1].set_ylabel(value_col.capitalize())
    
    plt.suptitle(title, fontsize=16, fontweight='bold')
    plt.tight_layout()
    
    return plt

3. 比较分析

柱状图与条形图：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

def plot_comparison(data, category_col, value_col, 
                     title="Comparison Analysis"):
    plt.figure(figsize=(12, 6))
    
    # 计算均值并排序
    summary_data = data.groupby(category_col)[value_col].mean().sort_values(ascending=False)
    
    # 绘制柱状图
    bars = plt.bar(range(len(summary_data)), summary_data.values,
                   color=ColorScheme.SECONDARY[:len(summary_data)])
    
    # 添加数值标签
    for i, bar in enumerate(bars):
        height = bar.get_height()
        plt.text(bar.get_x() + bar.get_width()/2., height,
                f'{height:.2f}',
                ha='center', va='bottom', fontweight='bold')
    
    plt.title(title, fontsize=16, fontweight='bold')
    plt.xlabel(category_col.capitalize(), fontsize=12)
    plt.ylabel(value_col.capitalize(), fontsize=12)
    plt.xticks(range(len(summary_data)), summary_data.index, rotation=45, ha='right')
    plt.grid(axis='y', alpha=0.3, linestyle='--')
    
    return plt

4. 关系分析

散点图与相关矩阵：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

def plot_relationship(data, x_col, y_col, title="Relationship Analysis"):
    fig, axes = plt.subplots(1, 2, figsize=(15, 5))
    
    # 散点图
    axes[0].scatter(data[x_col], data[y_col], 
                    alpha=0.6, color=ColorScheme.PRIMARY)
    axes[0].set_title(f'Scatter Plot: {x_col} vs {y_col}', fontweight='bold')
    axes[0].set_xlabel(x_col.capitalize())
    axes[0].set_ylabel(y_col.capitalize())
    
    # 计算相关系数
    correlation = data[[x_col, y_col]].corr().iloc[0, 1]
    
    # 添加趋势线
    z = np.polyfit(data[x_col], data[y_col], 1)
    p = np.poly1d(z)
    axes[0].plot(data[x_col], p(data[x_col]), 
                 "r--", alpha=0.8, label=f'Correlation: {correlation:.2f}')
    axes[0].legend()
    
    # 相关系数热力图
    sns.heatmap(data[[x_col, y_col]].corr(), 
                annot=True, cmap='coolwarm', center=0,
                ax=axes[1], cbar_kws={'label': 'Correlation'})
    axes[1].set_title('Correlation Matrix', fontweight='bold')
    
    plt.suptitle(title, fontsize=16, fontweight='bold')
    plt.tight_layout()
    
    return plt

交互式可视化

1. Plotly 示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

import plotly.express as px
import plotly.graph_objects as go

def create_interactive_dashboard(data):
    # 创建交互式图表
    fig = go.Figure()
    
    # 添加折线图
    fig.add_trace(go.Scatter(
        x=data['date'],
        y=data['value'],
        mode='lines+markers',
        name='Trend',
        line=dict(color=ColorScheme.PRIMARY, width=2),
        marker=dict(size=8)
    ))
    
    # 更新布局
    fig.update_layout(
        title="Interactive Dashboard",
        xaxis_title="Date",
        yaxis_title="Value",
        hovermode='x unified',
        template='plotly_white'
    )
    
    return fig

2. Bokeh 示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

from bokeh.plotting import figure, show
from bokeh.models import ColumnDataSource, HoverTool
from bokeh.io import output_notebook

def create_bokeh_dashboard(data):
    # 创建数据源
    source = ColumnDataSource(data)
    
    # 创建图形
    p = figure(x_axis_type='datetime', title="Bokeh Dashboard",
              tools='pan,wheel_zoom,box_zoom,reset,hover,save',
              width=900, height=400)
    
    # 添加折线
    p.line('date', 'value', source=source, 
          line_width=2, color=ColorScheme.PRIMARY)
    
    # 添加点
    p.circle('date', 'value', source=source,
            size=8, color=ColorScheme.PRIMARY, alpha=0.7)
    
    # 添加悬停工具
    hover = HoverTool()
    hover.tooltips = [
        ("Date", "@date{%F %Y-%m-%d}"),
        ("Value", "@value{0.2f}"),
    ]
    p.add_tools(hover)
    
    return p

可视化工作流程

1. 数据探索

初步分析：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

def data_exploration(df):
    # 基本信息
    print("数据形状:", df.shape)
    print("\n数据类型:")
    print(df.dtypes)
    
    # 缺失值检查
    print("\n缺失值:")
    print(df.isnull().sum())
    
    # 统计摘要
    print("\n统计摘要:")
    print(df.describe())
    
    # 相关性分析（仅数值列）
    numeric_cols = df.select_dtypes(include=[np.number]).columns
    if len(numeric_cols) > 1:
        print("\n相关性矩阵:")
        print(df[numeric_cols].corr())
    
    return df

2. 图形生成

批量生成图表：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28