Claude Code 从入门到实战：终端里的 AI 编程搭档完全指南

一句话总结：Claude Code 不是又一个代码补全插件——它是一个住在你终端里的 AI 程序员，能读懂整个代码库、自主编辑文件、执行命令、发起 PR，甚至同时派出多个”分身”并行干活。本文从零开始，带你完成安装 → 配置 → 日常使用 → 6 个真实场景实战，全部可复现。

一、Claude Code 是什么，凭什么火？

1.1 一句话定位

Claude Code 是 Anthropic 官方推出的终端原生 AI 编程代理（Agentic Coding Tool）。注意关键词——终端原生和代理：

• • 终端原生：不是 IDE 插件，不依赖 VS Code 或 JetBrains。打开终端，输入 claude，就是你的 AI 编程搭档。当然，它也支持 VS Code 扩展、JetBrains 插件、桌面应用和 Web 版，但终端是它的”主场”。
• • 代理（Agent）：不只是回答问题或补全代码。它能自主决定要读哪些文件、改哪些代码、运行什么命令——一个指令，它可能执行 10 步操作才返回结果。

1.2 它和 GitHub Copilot/Cursor 有什么区别？

核心差异：其他工具是”给你建议”，Claude Code 是”帮你干活”。

1.3 真实数据

• • 上下文窗口：标准 200K tokens，Opus 模型支持 1M tokens（beta）
• • 内置工具：50+ 个，涵盖文件操作、代码搜索、Shell 执行、Web 浏览、Agent 编排
• • 斜杠命令：约 101 个
• • 支持的接入方式：CLI / VS Code / JetBrains / 桌面应用 / Web / SDK / MCP Server

二、5 分钟安装与首次启动

2.1 环境要求

• • 操作系统：macOS / Linux / Windows 11（原生或 WSL）
• • Node.js：18 或更高版本（推荐使用官方安装脚本，自动处理依赖）
• • 账号：Claude Pro（月）、（100 或 $200/月）或 Anthropic Console API 账号

2.2 安装方式（选一种）

方式一：官方安装脚本（推荐，支持自动更新）

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

⚠️ Windows 原生安装需要先安装 Git for Windows

方式二：npm 安装

npm install -g @anthropic-ai/claude-code

方式三：Homebrew（macOS）

brew install --cask claude-code

2.3 验证安装

claude --version
# 输出类似：claude-code 1.x.x

2.4 首次启动

cd ~/my-project    # 进入你的项目目录
claude             # 启动 Claude Code

首次启动会引导你完成 OAuth 认证（浏览器自动打开），登录后即可使用。你会看到一个交互式的 REPL 界面：

╭──────────────────────────────────────╮
│ Claude Code                          │
│                                      │
│ /help for commands · /model to       │
│ switch model · Ctrl+C to cancel      │
╰──────────────────────────────────────╯

>

试试你的第一条指令：

> 这个项目是做什么的？帮我梳理一下目录结构和核心模块

Claude 会自动扫描项目文件，读取关键文件，然后给你一份结构化的项目概览。不需要你告诉它去看哪些文件——这就是”代理”的能力。

三、核心概念：你必须知道的 7 件事

3.1 Agentic Loop（代理循环）

Claude Code 的核心不是”你问我答”，而是一个思考 → 行动 → 观察的自主循环：

你的指令 → Claude 分析 → 决定使用什么工具
  → 读文件？执行命令？搜索代码？
    → 获得结果 → 继续分析 → 可能再调用工具
      → ... 重复直到任务完成 → 返回结果给你

真实例子：你说”修复这个 bug”，Claude 可能会：

1. 1. 搜索相关错误信息（Grep 工具）
2. 2. 读取相关代码文件（FileRead 工具）
3. 3. 分析根因
4. 4. 编辑代码（FileEdit 工具）
5. 5. 运行测试（Bash 工具）
6. 6. 如果测试失败，回到步骤 4 继续修改
7. 7. 测试通过，返回修复报告

整个过程一次指令自动完成，你只需要在关键步骤审批。

3.2 权限系统

Claude Code 不会未经允许就修改你的代码。它有三层权限控制：

你也可以设置规则，比如”允许所有只读操作”、”允许运行 npm test”。

3.3 Plan Mode（规划模式）

输入 /plan 进入规划模式。此模式下，Claude 只分析不执行：

> /plan
> 将认证系统从 session cookies 重构为 JWT tokens

Claude 会输出类似：

## 重构计划

### 影响分析
- 涉及文件：12 个
- 主要模块：auth/、middleware/、api/routes/

### 执行步骤
1. 安装 jsonwebtoken 和 cookie-parser 依赖
2. 创建 lib/jwt.ts — token 生成/验证工具函数
3. 修改 middleware/auth.ts — 从 session 切换到 JWT 验证
4. 更新 api/routes/login.ts — 返回 JWT token 而非设置 session
5. 更新 api/routes/refresh.ts — 新增 token 刷新端点
6. 修改所有受保护路由的中间件引用
7. 更新前端 API 调用层 — 在 header 中携带 Bearer token
8. 删除 session 相关配置和依赖
9. 编写并运行测试

### 风险点
- 需要处理 token 过期的优雅降级
- 旧 session 的迁移期兼容

确认执行？(y/n)

黄金法则：涉及 2 个以上文件的修改，先用 /plan。

3.4 上下文压缩（/compact）

长时间对话后，上下文窗口会被填满。输入 /compact，Claude 会智能压缩历史对话，保留关键信息，释放上下文空间。

建议：每 20-30 轮对话执行一次 /compact。

3.5 模型选择

> /model claude-sonnet-4-6      # 切换到 Sonnet 4.6（快速，性价比高）
> /model claude-opus-4-6        # 切换到 Opus 4.6（最强，适合复杂任务）

80/20 法则：

• • 80% 的日常任务用 Sonnet 4.6 — 速度快、成本低、足够胜任大部分编码工作
• • 20% 的复杂任务用 Opus 4.6 — 大规模重构、架构设计、跨模块 debug

3.6 MCP（Model Context Protocol）

MCP 让 Claude Code 连接外部工具和数据源。比如连接 Jira 读取任务、连接数据库查询数据、连接 Slack 发送通知。

# 添加一个 MCP 服务器
claude mcp add github-mcp --transport stdio -- npx @anthropic-ai/github-mcp

3.7 多 Agent 协作

对于复杂任务，Claude Code 可以启动多个子 Agent 并行工作：

• • Explore Agent：只读探索代码库，快速定位文件
• • Plan Agent：架构规划，输出实施方案
• • Verification Agent：验证实现正确性，运行测试
• • General Purpose Agent：拥有全部工具的通用 Agent

这些子 Agent 可以同时运行，主 Agent 协调它们的结果。

四、CLAUDE.md：让 AI 记住你的规矩

CLAUDE.md 是 Claude Code 最重要的配置文件——它是你和 AI 的”合作协议”。Claude 每次启动会话时自动读取它。

4.1 放在哪里？

三个层级的配置会合并，越具体的优先级越高。

4.2 一个生产级 CLAUDE.md 示例

# 项目：电商后台管理系统

## 技术栈
- 前端：React 18 + TypeScript 5 + Vite 5
- UI 框架：Ant Design 5.x
- 状态管理：Zustand
- 后端：Node.js + Express + Prisma ORM
- 数据库：PostgreSQL 15
- 测试：Vitest（单元测试）+ Playwright（E2E）

## 目录结构

src/
├── components/ # 可复用组件
├── pages/ # 页面组件，对应路由
├── hooks/ # 自定义 hooks
├── services/ # API 调用层
├── stores/ # Zustand stores
├── utils/ # 工具函数
└── types/ # TypeScript 类型定义

## 开发命令
- 启动开发：`pnpm dev`
- 构建：`pnpm build`
- 测试：`pnpm test`
- Lint：`pnpm lint`
- 类型检查：`pnpm typecheck`

## 编码规范
- 组件使用函数式组件 + hooks，禁止 class 组件
- 所有导出使用命名导出（named export），禁止默认导出
- 所有函数必须标注 TypeScript 返回类型
- 组件 props 必须定义独立的 interface，命名为 `XxxProps`
- API 调用统一使用 services/ 层，组件中禁止直接 fetch
- 错误处理：API 层使用 try-catch，组件层使用 Error Boundary
- 日志：使用项目统一的 logger 模块，禁止裸用 console.log

## Git 规范
- 提交信息使用约定式格式：feat()、fix()、refactor()、docs()、chore()
- 每个功能一个分支，命名格式：feat/xxx 或 fix/xxx
- PR 描述必须包含：改动背景、影响范围、测试情况

## 重要约束
- 不要修改 src/config/constants.ts 中的 API 地址，这些由环境变量控制
- 数据库迁移文件一旦提交，禁止修改，只能新增
- 所有新增 API 接口必须配套编写接口测试

没有 CLAUDE.md 的 Claude = 一个不了解你团队规矩的新手程序员。
有了 CLAUDE.md 的 Claude = 一个完全理解你项目规范的资深工程师。

五、高频命令速查表

启动与退出

会话内斜杠命令

管道与脚本

# 将文件内容传给 Claude 分析
cat error.log | claude -p "分析这些日志，找出根因"

# 将 git diff 传给 Claude 审查
git diff main | claude -p "审查这些代码变更，关注安全和性能问题"

# 批量处理
find . -name "*.test.ts" | claude -p "检查这些测试文件的覆盖率是否充分"

六、实战案例一：从零搭建一个 Next.js 全栈应用

场景

你要为公司内部搭建一个”会议室预约系统”，技术栈是 Next.js 14 + TypeScript + Prisma + PostgreSQL。

步骤

Step 1：创建项目

mkdir meeting-room-booking && cd meeting-room-booking
claude

输入指令：

> 帮我创建一个会议室预约系统，技术栈如下：
> - Next.js 14 App Router + TypeScript
> - Tailwind CSS + shadcn/ui
> - Prisma + PostgreSQL
> - NextAuth.js 做认证
>
> 需要以下功能：
> 1. 用户登录（支持邮箱密码）
> 2. 查看所有会议室列表（名称、容量、设备信息）
> 3. 按日期+时间段预约会议室
> 4. 查看我的预约，支持取消
> 5. 冲突检测：同一时间段已被预约的会议室不可再约
>
> 请先给我完整的方案设计，然后再开始写代码。

Step 2：Claude 的执行过程（你会看到）

Claude 会先进入规划阶段：

📋 方案设计

## 数据模型
- User: id, email, passwordHash, name
- Room: id, name, capacity, equipment[], floor
- Booking: id, userId, roomId, date, startTime, endTime, status

## 目录结构
app/
├── (auth)/login/page.tsx
├── (auth)/register/page.tsx
├── dashboard/page.tsx         # 会议室列表 + 预约入口
├── bookings/page.tsx          # 我的预约
├── api/
│   ├── auth/[...nextauth]/route.ts
│   ├── rooms/route.ts
│   └── bookings/route.ts
├── components/
│   ├── RoomCard.tsx
│   ├── BookingForm.tsx
│   ├── BookingList.tsx
│   └── TimeSlotPicker.tsx
└── lib/
    ├── prisma.ts
    └── auth.ts

## 关键逻辑：冲突检测
SQL 查询：查找同一 roomId + 同一 date 中
startTime < 新预约的 endTime AND endTime > 新预约的 startTime
的记录，有则拒绝。

开始创建项目？(y)

你确认后，Claude 会自动：

1. 1. 运行 npx create-next-app@latest 初始化项目
2. 2. 安装所有依赖（prisma、next-auth、shadcn/ui 等）
3. 3. 创建 Prisma Schema
4. 4. 编写 API 路由
5. 5. 创建前端页面和组件
6. 6. 配置认证

Step 3：验证

> 帮我运行一下项目，确认没有编译错误。然后用种子数据填充 3 个会议室。

Claude 会运行 pnpm dev，检查是否有错误，创建 prisma/seed.ts，执行 npx prisma db seed。

最终成果

一个完整可运行的会议室预约系统，包含登录注册、会议室浏览、预约/取消、冲突检测，前端使用 shadcn/ui 组件，UI 美观可用。整个过程大约 10-15 分钟，而手工编写至少需要 1-2 天。

七、实战案例二：调试一个真实的性能瓶颈

场景

你的 React 管理后台，用户反馈”订单列表页加载需要 8 秒”。你本地可以复现。

步骤

cd ~/projects/admin-dashboard
claude

输入：

> 用户反馈订单列表页（/orders）加载非常慢，大约需要 8 秒。
> 请帮我定位性能瓶颈。
> 先分析代码，然后给出优化方案。

Claude 的自主分析过程

Claude 会自动执行以下步骤（你可以在终端实时看到）：

🔍 搜索订单相关文件...
   → 找到 src/pages/Orders.tsx, src/services/orderApi.ts, src/hooks/useOrders.ts

📄 读取 Orders.tsx (245行)...
📄 读取 orderApi.ts (89行)...
📄 读取 useOrders.ts (56行)...

🔎 分析发现以下问题：

### 问题 1：N+1 查询（严重）
orderApi.ts 第 34 行：获取订单列表后，对每条订单单独调用
`fetchCustomerDetail(order.customerId)` 获取客户信息。
100 条订单 = 1 次列表查询 + 100 次客户查询 = 101 次 API 调用。

### 问题 2：无分页
useOrders.ts 第 12 行：一次性加载全部订单（数据库中有 50000+ 条）。

### 问题 3：重复渲染
Orders.tsx 第 67 行：orderList.map() 中的 <OrderRow> 组件没有 memo，
每次父组件状态变化都重新渲染所有行。

### 问题 4：未使用虚拟滚动
渲染 50000 个 DOM 节点，浏览器不堪重负。

然后 Claude 给出优化方案并询问是否执行：

## 优化方案

1. 后端：新增 /api/orders?page=1&pageSize=20&include=customer 接口
   → 在 SQL JOIN 中一次性获取客户信息，消除 N+1
2. 前端：添加分页组件，默认每页 20 条
3. 用 React.memo 包裹 OrderRow 组件
4. 引入 @tanstack/react-virtual 实现虚拟滚动

预估效果：加载时间从 8 秒降到 < 500ms

执行优化？(y)

确认后，Claude 自动修改代码，然后运行测试确认无误。

八、实战案例三：遗留代码重构——回调地狱到 async/await

场景

你接手了一个 3 年前的 Node.js 项目，核心支付模块全是回调嵌套，可读性极差，bug 频出。

步骤

> /plan
> 将 src/services/payment.js 从回调风格重构为 async/await。
> 要求：
> 1. 保持外部 API 接口不变（函数签名相同）
> 2. 所有现有测试必须通过
> 3. 改完后帮我把文件从 .js 改成 .ts，加上类型定义

Claude 的规划输出

## 重构计划

### 第一阶段：回调 → Promise
- 当前文件 468 行，包含 12 个导出函数
- 回调嵌套最深 6 层（processRefund 函数）
- 使用 util.promisify 包装数据库和第三方 SDK 调用

### 第二阶段：Promise → async/await
- 改写 12 个函数为 async 函数
- 用 try/catch 替换 .catch() 链
- 保留所有函数签名的向后兼容（仍然返回 Promise）

### 第三阶段：JS → TS
- 重命名为 payment.ts
- 为所有函数参数和返回值添加类型
- 创建 types/payment.d.ts 定义接口

### 第四阶段：验证
- 运行现有测试套件
- 检查所有引用该模块的文件

### 风险点
- processRefund 中有一个竞态条件（并发退款），重构时一并修复

确认执行？

重构前 vs 重构后的对比（Claude 自动生成）：

重构前：

function processPayment(orderId, amount, callback) {
  db.findOrder(orderId, function(err, order) {
    if (err) returncallback(err);
    validateAmount(order, amount, function(err, valid) {
      if (err) returncallback(err);
      if (!valid) returncallback(newError('Invalid amount'));
      gateway.charge(order.customerId, amount, function(err, charge) {
        if (err) returncallback(err);
        db.updateOrder(orderId, { status: 'paid', chargeId: charge.id }, function(err) {
          if (err) returncallback(err);
          notifyCustomer(order.customerId, charge, function(err) {
            if (err) console.log('Notification failed:', err);
            callback(null, charge);
          });
        });
      });
    });
  });
}

重构后：

async functionprocessPayment(orderId: string, amount: number): Promise<Charge> {
const order = await db.findOrder(orderId);
const valid = awaitvalidateAmount(order, amount);

if (!valid) {
    thrownewPaymentError('Invalid amount', { orderId, amount });
  }

const charge = await gateway.charge(order.customerId, amount);
await db.updateOrder(orderId, { status: 'paid', chargeId: charge.id });

// 通知失败不影响支付流程
try {
    awaitnotifyCustomer(order.customerId, charge);
  } catch (err) {
    logger.warn('Notification failed', { orderId, error: err });
  }

return charge;
}

12 个函数全部重构完成，测试全部通过，耗时约 5 分钟。

九、实战案例四：自动化 Git 工作流——从提交到 PR

场景

你已经完成了一个新功能的代码，想要提交并创建 PR。

步骤

> 帮我完成以下 Git 工作流：
> 1. 查看当前所有修改
> 2. 创建功能分支 feat/user-export
> 3. 将相关改动分成合理的提交（不要一个大提交）
> 4. 推送到远端
> 5. 使用 GitHub CLI 创建 PR，PR 描述要详细说明改动内容

Claude 的执行过程

🔍 检查当前修改...
   → 发现 8 个文件变更

🌿 创建分支 feat/user-export
   → git checkout -b feat/user-export

📦 将改动分为 3 个逻辑提交：

   提交 1: feat(api): add user export endpoint
   - src/api/routes/users.ts (+45 行)
   - src/services/exportService.ts (新增, 89 行)

   提交 2: feat(ui): add export button and progress dialog
   - src/pages/UserList.tsx (+23 行)
   - src/components/ExportDialog.tsx (新增, 67 行)
   - src/components/ExportProgress.tsx (新增, 34 行)

   提交 3: test: add user export tests
   - src/__tests__/exportService.test.ts (新增, 112 行)
   - src/__tests__/UserList.test.tsx (+18 行)

🚀 推送到远端...
   → git push -u origin feat/user-export

📝 创建 PR...
   → gh pr create --title "feat: 用户数据导出功能" --body "..."

✅ PR 已创建：https://github.com/your-org/repo/pull/142

PR 描述自动生成，包含改动背景、影响范围、测试情况、截图提示。整个过程约 2 分钟。

十、实战案例五：用 Hooks 打造自动化流水线

场景

你希望每次 Claude 修改文件后自动运行 Prettier 格式化，每次提交前自动运行 lint。

配置 Hooks

在 .claude/settings.json 中添加：

{
  "hooks":{
    "PostToolUse":[
      {
        "matcher":"FileEdit|FileWrite",
        "command":"npx prettier --write \"$CLAUDE_FILE_PATH\""
      }
    ],
    "PreCommit":[
      {
        "command":"npx eslint --fix . && npx tsc --noEmit"
      }
    ]
}
}

效果

• • Claude 每次编辑或创建文件后，Prettier 自动格式化
• • Claude 执行 git commit 前，ESLint + TypeScript 检查自动运行
• • 如果检查失败，Claude 会看到错误并自动修复

进阶：你还可以在 Hooks 中加入自定义脚本，比如：

• • 修改数据库 schema 后自动运行 prisma generate
• • 修改 API 路由后自动更新 OpenAPI 文档
• • 每次代码变更后自动运行相关的单元测试

十一、实战案例六：多 Agent 协作——拆分大任务并行执行

场景

你需要给项目添加国际化（i18n）支持，涉及 50+ 个页面文件。单个 Agent 串行处理太慢。

步骤

> 给整个项目添加 i18n 国际化支持，要求：
> 1. 使用 react-i18next
> 2. 支持中文和英文
> 3. 所有页面中的硬编码中文文本提取为 key
> 4. 翻译文件放在 public/locales/ 下
>
> 这是个大任务，请使用多个 Agent 并行处理。

Claude 的多 Agent 编排

🎯 任务分解：

Agent 1 (Setup)：安装依赖 + 配置 i18n 框架 + 创建语言切换组件
Agent 2 (Pages A-M)：处理 pages/ 目录 A-M 开头的 26 个文件
Agent 3 (Pages N-Z)：处理 pages/ 目录 N-Z 开头的 24 个文件
Agent 4 (Components)：处理 components/ 目录的公共组件

主 Agent：协调合并，最终验证

⏱️ 并行执行中...
   Agent 1 ✅ 完成 (1分钟)
   Agent 2 ⏳ 进行中...
   Agent 3 ⏳ 进行中...
   Agent 4 ⏳ 进行中...

   Agent 4 ✅ 完成 (3分钟)
   Agent 2 ✅ 完成 (4分钟)
   Agent 3 ✅ 完成 (4分钟)

📊 合并结果：
   - 提取文本 key：347 个
   - 中文翻译文件：public/locales/zh/translation.json
   - 英文翻译文件：public/locales/en/translation.json
   - 修改文件：52 个

🧪 运行验证...
   → pnpm build ✅
   → pnpm test ✅
   → 切换语言到 English ✅ 所有文本正确显示

总耗时：约 5 分钟（串行预计 20+ 分钟）

十二、成本控制：花最少的钱办最多的事

订阅方案对比

API 成本参考

6 条省钱策略

1. 1. 默认用 Sonnet：80% 的编码任务 Sonnet 足矣，只在复杂架构任务切 Opus
2. 2. 勤用 /compact：压缩上下文可减少后续每轮对话的 token 消耗
3. 3. 提示词要精确：模糊的指令让 Claude 多次试错，精确的指令一次到位
4. 4. 不相关任务用 /clear：切换话题时清除上下文，避免携带无用信息
5. 5. 善用 CLAUDE.md：前期投入 30 分钟写好项目规范，后续每次对话省几千 tokens
6. 6. 批量操作：”修改这 5 个文件”比分 5 次说效率高得多

十三、避坑指南：新手常犯的 8 个错误

❌ 错误 1：不写 CLAUDE.md 就开始用

后果：Claude 用自己的习惯写代码——可能和你项目风格完全不同。

正确做法：花 10 分钟创建 CLAUDE.md，写清楚技术栈、编码规范、目录结构。

❌ 错误 2：给一个巨大的需求让 Claude “一步到位”

后果：上下文爆炸，后半段质量急剧下降。

正确做法：将大任务拆成 3-5 个阶段，每阶段完成后 /compact，再进入下一阶段。

❌ 错误 3：从不看 Claude 的改动就确认

后果：可能引入隐蔽 bug，尤其是在安全相关的代码中。

正确做法：Claude 给出 diff 后，至少扫一眼关键逻辑。特别关注数据库操作、认证逻辑、金额计算。

❌ 错误 4：不用 Plan Mode 就做大型重构

后果：Claude 可能从错误的方向开始改，改了 20 个文件后你才发现方向不对，回滚成本巨大。

正确做法：/plan → 审批方案 → 再执行。

❌ 错误 5：在 Bypass Permissions 模式下操作生产环境

后果：Claude 可能误删文件或执行危险命令。

正确做法：生产环境始终使用默认权限模式，逐一审批。

❌ 错误 6：忘记 /compact，直到 Claude 开始”胡说八道”

后果：上下文窗口满了，Claude 丢失早期关键信息，输出质量大幅下降。

正确做法：设个心理计数器，每 20-30 轮对话执行 /compact。

❌ 错误 7：用自然语言描述代码改动位置

后果：描述模糊时 Claude 可能改错文件或改错位置。

正确做法：直接给出文件路径和行号范围，如”修改 src/utils/format.ts 第 45-60 行的 formatDate 函数”。

❌ 错误 8：不利用已有测试

后果：Claude 改完代码后不知道有没有破坏已有功能。

正确做法：在指令中明确说”改完后运行 pnpm test 确认所有测试通过”。Claude 会自动运行测试，如果失败会自动修复。

十四、总结与下一步

你今天学到了什么

推荐学习路径

Week 1：安装 → 配置 CLAUDE.md → 用于日常编码辅助
Week 2：掌握 /plan → 用于复杂重构和新功能开发
Week 3：配置 Hooks → 打造项目级自动化流水线
Week 4：尝试多 Agent → 处理大型跨模块任务
Week 5：集成 MCP → 连接 Jira/Slack/数据库等外部工具
Week 6：Headless 模式 → 集成到 CI/CD 流程

写在最后：Claude Code 不会取代程序员——它取代的是”没有 AI 搭档的程序员”。学会与它协作，你的生产力将提升到一个新的量级。现在，打开终端，输入 claude，开始你的第一次对话吧。

本文写于 2026 年 4 月。Claude Code 迭代速度很快，部分细节可能随版本更新而变化，请以官方文档为准。