Claude Code 深度实战指南

一、理解 Claude Code 的工作原理

它不是一个聊天机器人

Claude Code 不是在"回答问题"，它在执行任务。区别在于：

聊天机器人：你问 → 它答 → 结束
Claude Code：你给任务 → 它规划 → 读文件 → 改代码 → 跑命令 → 验证 → 循环

理解这一点，你才能给它任务而不是问题。

工具调用链

用户："给项目添加用户认证"
         ↓
Claude 规划：
  1. 读 package.json 了解依赖
  2. 读 src/ 目录了解项目结构
  3. 读现有的路由文件了解代码风格
  4. 创建认证模块
  5. 写测试
  6. 运行测试验证
         ↓
每一步都会调用具体工具（Read/Edit/Write/Bash）
每一步都需要你确认（取决于权限模式）

为什么 CLAUDE.md 是最关键的

没有 CLAUDE.md 的对话，Claude 每次都要从零了解你的项目。有 CLAUDE.md，它上来就知道：

• 你的技术栈
• 你的代码规范
• 你的项目结构
• 常用命令
• 注意事项

这不只是方便，这是质量的分水岭。

二、CLAUDE.md 工程：从能用到好用

初级：基本信息

# My Project

这是一个 Next.js 项目。

有用，但不够。

中级：技术上下文

# My Project

## 技术栈
- Next.js 14 (App Router)
- TypeScript 5.3
- Tailwind CSS 3.4
- Prisma + PostgreSQL
- NextAuth.js v5

## 项目结构
src/
  app/          — 页面和路由
  components/   — React 组件
  lib/          — 工具函数和配置
  services/     — 业务逻辑
  types/        — TypeScript 类型定义
  prisma/       — 数据库 schema

## 常用命令
- dev: npm run dev
- build: npm run build
- test: npm run test
- db:push: npx prisma db push
- db:studio: npx prisma studio

高级：行为指令

# My Project

[... 技术栈和结构 ...]

## 代码规范
- 组件用函数式 + hooks，禁止 class 组件
- 命名：组件 PascalCase，变量/函数 camelCase，常量 UPPER_SNAKE_CASE
- 文件命名：组件用 PascalCase.tsx，其他用 camelCase.ts
- 导入顺序：react → 第三方 → 项目内部 → 相对路径
- 样式只用 Tailwind，不写 CSS 文件
- 错误处理：服务端用 AppError 类，客户端用 toast 通知

## 数据库
- 所有查询通过 Prisma，禁止裸 SQL
- 新增字段必须有默认值（线上 migration 安全）
- 敏感字段（password、token）永远不返回给前端

## 测试
- 核心逻辑必须有单元测试
- API 路由必须有集成测试
- 测试文件放在同目录下，命名为 xxx.test.ts
- Mock 只 mock 外部依赖，不 mock 内部逻辑

## 部署
- Vercel 自动部署
- 环境变量在 Vercel Dashboard 管理
- 数据库迁移通过 Prisma Migrate

## 已知问题
- [BUG] 上传大文件偶尔超时，正在排查
- [TODO] 支付模块还在开发中，不要动 src/services/payment.ts

专家级：动态 CLAUDE.md

# My Project

[... 基础信息 ...]

## 当前迭代 (Sprint 23)
- 目标：完成支付模块重构
- 截止：2026-07-10
- 技术债：需要把 src/utils/legacy.ts 的函数迁移到新架构

## 本周重点
1. 支付回调处理（优先级最高）
2. 订单状态机实现
3. 退款流程

## 代码地图
- src/app/api/webhooks/stripe/ — 支付回调（当前重点）
- src/services/order.ts — 订单业务逻辑
- src/services/payment.ts — 支付逻辑（正在重构）
- src/lib/stripe.ts — Stripe SDK 封装
- prisma/schema.prisma — 数据库定义

## 团队约定
- PR 标题用 Conventional Commits
- AI 生成的代码需要在 PR 描述中标注
- 重要功能需要双人 Review

子目录 CLAUDE.md

project/
├── CLAUDE.md                 # 全局
├── src/
│   ├── CLAUDE.md             # src 目录专用
│   ├── api/
│   │   └── CLAUDE.md         # API 目录专用
│   └── components/
│       └── CLAUDE.md         # 组件目录专用

子目录的 CLAUDE.md 会被合并到全局的，适合放目录特定的规范。

# src/api/CLAUDE.md

## API 路由规范
- 每个路由文件只处理一个资源
- 必须有请求验证（用 zod）
- 返回格式：{ data, error, meta }
- 分页用 cursor 而不是 offset
- 错误码参考 src/lib/errors.ts

三、Prompt 工程：官方文档不会告诉你的

原则一：任务导向而非问题导向

# 差（问题导向）
"Express.js 怎么处理 CORS？"

# 好（任务导向）
"给我的 Express 项目添加 CORS 配置，允许来自 localhost:3000 和
api.example.com 的请求，支持 credentials"

原则二：约束越具体，结果越好

# 差
"优化这个函数"

# 好
"优化 src/utils/parser.ts 的 parseCSV 函数。
当前性能：100MB 文件需要 30 秒。
目标：5 秒以内。
约束：内存使用不超过 200MB，不能引入新依赖。
可以用 worker_threads。"

原则三：给参考而非给规则

# 差
"按照项目的代码风格来写"

# 好
"参考 src/services/userService.ts 的代码风格来写，特别是：
- class 结构
- 错误处理方式
- 日志记录方式
- 返回值类型"

原则四：用否定约束控制行为

"重构 src/utils/helpers.ts
- 不要改变任何函数签名
- 不要引入新依赖
- 不要修改文件结构
- 不要添加注释（代码要自解释）
- 只优化性能"

高级 Prompt 模板

需求实现模板

实现 [功能名称]

背景：[为什么要做这个，解决什么问题]

输入：
- [输入数据格式]
- [边界条件]

输出：
- [输出格式]
- [成功/失败的返回值]

技术约束：
- [框架/库版本]
- [性能要求]
- [兼容性要求]

参考：
- [类似功能的代码位置]
- [相关文档链接]

验收标准：
- [怎么算做完了]
- [怎么验证正确性]

调试模板

症状：[什么现象]
环境：[什么条件下出现]
频率：[总是/偶现/特定条件下]

已排查：
- [已经试过什么]
- [排除了什么可能]

相关代码：
- [文件路径和行号]

日志：
[粘贴相关日志]

请：
1. 分析可能的原因
2. 给出排查步骤
3. 不要直接改代码，先分析

重构模板

重构目标：[文件/模块]

当前问题：
- [为什么要重构，是性能、可读性还是架构问题]

重构要求：
- [保持什么不变]
- [改变什么]
- [验证标准]

分步执行：
1. 先分析现有代码
2. 给出重构方案
3. 等我确认后再改
4. 每改一步都跑测试

四、工具系统深度使用

Read 工具的高效使用

# 差：让 Claude 自己找
"找到处理登录的代码"

# 好：直接给路径
"读 src/services/auth.ts 和 src/app/api/login/route.ts"

Edit 工具的精确控制

# 差
"改一下这个函数"

# 好
"把 src/services/auth.ts 第 45 行的
  const token = jwt.sign(payload, secret)
改成
  const token = jwt.sign(payload, secret, { expiresIn: '24h' })"

Bash 工具的安全使用

// .claude/settings.json
{
  "permissions": {
    "allow": [
      "Bash(npm run test)",
      "Bash(npm run lint)",
      "Bash(npx tsc --noEmit)",
      "Bash(git status)",
      "Bash(git diff)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force)",
      "Bash(curl *)"
    ]
  }
}

Agent 工具的正确使用场景

# 适合用 Agent 的场景
"找到项目中所有用了 deprecated API 的地方"
→ Agent 独立搜索，结果汇总，主对话上下文干净

"分析 src/ 下所有文件的代码质量"
→ Agent 并行读取多个文件

# 不适合用 Agent 的场景
"改一下这个函数" → 直接 Edit 就行
"跑一下测试" → 直接 Bash 就行

五、实战工作流

工作流一：Feature Branch 开发

# 1. 创建分支
"创建一个 feature/user-profile 分支"

# 2. 实现功能
"实现用户个人资料页面：
- 显示用户信息
- 支持编辑头像、昵称、简介
- 保存到数据库
- API 接口在 src/app/api/profile/route.ts"

# 3. 写测试
"为这个功能写单元测试和集成测试"

# 4. 提交
"帮我写 commit message 并提交"

# 5. 创建 PR
"创建 PR 到 main 分支，描述写清楚做了什么"

工作流二：Bug 修复

# 1. 描述问题
"用户反馈：登录后刷新页面会变成未登录状态。
复现：登录 → F5 → 显示登录按钮"

# 2. 让 Claude 排查
"帮我排查这个问题，先不要改代码，分析原因"

# 3. 确认方案
"好，按方案 A 来修，Session 用 httpOnly Cookie 存储"

# 4. 修复
"修复这个问题"

# 5. 验证
"运行测试，确保没有引入新问题"

# 6. 提交
"提交修复，commit message 描述清楚 bug 是什么、怎么修的"

工作流三：代码审查

# 审查自己的代码
"审查我当前分支和 main 的差异，指出：
1. 潜在 bug
2. 安全问题
3. 性能问题
4. 代码风格不一致"

# 审查别人的 PR
"审查 PR #42 的代码，重点关注：
- 是否符合项目架构
- 错误处理是否完整
- 是否有安全隐患"

工作流四：性能优化

# 1. 定位瓶颈
"src/services/search.ts 的 searchProducts 函数响应很慢，
帮我分析性能瓶颈"

# 2. 方案讨论
"我觉得瓶颈在数据库查询，你觉得用 Elasticsearch 还是加索引好？"

# 3. 实现优化
"按方案 B 实现，先加数据库索引，如果不够再考虑 ES"

# 4. 验证
"写一个 benchmark 脚本，对比优化前后的性能"

工作流五：技术债清理

# 1. 盘点
"分析 src/utils/legacy.ts，列出所有函数，
标注哪些还在用、哪些可以删除"

# 2. 制定计划
"先迁移最常用的 5 个函数到新架构"

# 3. 分步执行
"迁移 formatCurrency 函数，保持签名不变，
内部实现用新的 Intl.NumberFormat"

# 4. 验证
"运行所有测试，确保迁移没有破坏什么"

# 5. 清理
"把迁移后的旧函数标记为 @deprecated"

六、上下文管理专家级技巧

理解上下文窗口

Claude 的上下文窗口约 200k tokens

一个典型对话的 token 消耗：
- 系统 Prompt + CLAUDE.md：~2k tokens
- 每轮对话（你的输入 + Claude 的输出）：~1k-5k tokens
- 每次读取文件：取决于文件大小
- 工具调用结果：~500-2k tokens 每次

20 轮对话 + 读取 10 个文件 ≈ 50k-100k tokens

什么时候用 /compact

# 时机一：完成一个子任务后
"好，用户注册功能完成了，现在来做登录"
→ /compact
→ "实现登录功能"

# 时机二：对话超过 15 轮后
→ /compact

# 时机三：感觉 Claude 开始"忘记"之前说的话
→ /compact

什么时候用 /clear

# 完全切换话题
"刚才的功能做完了，现在帮我看看这个 bug"
→ /clear（如果上下文已经很乱）

# 或者直接开始新对话（关闭终端重开 claude）

用 CLAUDE.md 代替重复说明

# 差：每次对话都要说
"我的项目用 Next.js 14，TypeScript，Tailwind CSS，
数据库是 PostgreSQL，用 Prisma ORM..."

# 好：写入 CLAUDE.md，自动加载

七、Hooks 实战

自动格式化

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $CLAUDE_FILE_PATH 2>/dev/null; npx eslint --fix $CLAUDE_FILE_PATH 2>/dev/null; true"
          }
        ]
      }
    ]
  }
}

自动类型检查

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "cd $CLAUDE_PROJECT_DIR && npx tsc --noEmit 2>&1 | head -20"
          }
        ]
      }
    ]
  }
}

自动测试

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "cd $CLAUDE_PROJECT_DIR && npx vitest related $CLAUDE_FILE_PATH --run --reporter=verbose 2>&1 | tail -20"
          }
        ]
      }
    ]
  }
}

安全防护

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'rm -rf|DROP TABLE|DELETE FROM|git push --force' && echo 'BLOCKED: dangerous command detected' && exit 1 || exit 0"
          }
        ]
      }
    ]
  }
}

环境变量可用

$CLAUDE_FILE_PATH    — 被操作的文件路径
$CLAUDE_PROJECT_DIR  — 项目根目录
$CLAUDE_TOOL_NAME    — 工具名称
$CLAUDE_TOOL_INPUT   — 工具输入（JSON）

八、高级技巧

技巧一：用 Claude 做架构决策

"我在设计一个消息队列系统，需求：
- 支持 10 万 QPS
- 消息不能丢失
- 延迟 < 100ms
- 需要支持消息回溯

我在考虑：
1. Kafka
2. RabbitMQ
3. Redis Streams
4. 自研

帮我分析每个方案的优劣，给出推荐。
不要只列特点，要结合我的具体需求分析。"

技巧二：用 Claude 做代码迁移

"我要把项目从 Express 迁移到 Fastify。

请：
1. 列出两个框架的 API 差异
2. 分析迁移工作量
3. 制定迁移计划（分步骤）
4. 先迁移一个最简单的路由作为示例"

技巧三：用 Claude 写技术文档

"根据 src/services/order.ts 的代码，写一份技术文档，包括：
1. 模块职责
2. 核心流程图（用 Mermaid）
3. 接口列表
4. 数据流转
5. 已知限制
6. 后续优化方向"

技巧四：用 Claude 做 Postmortem

"今天线上出了一个事故：
- 时间：14:30-15:00
- 现象：所有 API 返回 500
- 原因：数据库连接池耗尽
- 修复：重启服务

帮我写一份 Postmortem 文档，包括：
1. 事故时间线
2. 根因分析（5 Whys）
3. 影响范围
4. 修复措施
5. 预防措施
6. Action Items"

九、实战常见问题与处理

问题：GitHub Push 超时

这是 Claude Code 用户最高频的问题之一。

症状：git push 后长时间卡住，最终报错
error: RPC failed; curl 56 GnuTLS recv error (-110)
fatal: the remote end hung up unexpectedly

原因分析：

1. 仓库太大（有大文件或历史记录多）
2. 网络不稳定（国内访问 GitHub 经常如此）
3. 代理配置不对
4. Git buffer 太小

解决步骤：

# 方案一：增大 Git buffer（最常见的解法）
git config --global http.postBuffer 524288000
# 500MB，够用了

# 方案二：配置代理
git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890

# 方案三：用 SSH 代替 HTTPS
# 先生成 SSH Key
ssh-keygen -t ed25519 -C "your@email.com"
# 把公钥添加到 GitHub Settings → SSH Keys
# 然后改 remote URL
git remote set-url origin git@github.com:user/repo.git

# 方案四：浅克隆（如果是 clone 阶段超时）
git clone --depth 1 https://github.com/user/repo.git
# 之后再 git fetch --unshallow

# 方案五：分批 push（commit 太多时）
git push origin main --force-with-lease
# 或者分批 push
git log --oneline | wc -l  # 看有多少 commit
git rebase -i HEAD~5       # 压缩最近 5 个 commit
git push

在 Claude Code 中的处理：

"push 超时了，帮我：
1. 先压缩最近的 commit（squash）
2. 配置代理
3. 用 SSH 方式 push"

问题：大仓库导致 Claude Code 卡顿

症状：Claude Code 响应很慢，启动也要很久

原因：
1. 仓库文件太多（node_modules 被索引）
2. .gitignore 没配好
3. 有大量二进制文件

# 解决：
# 1. 确保 .gitignore 完善
echo "node_modules/" >> .gitignore
echo "dist/" >> .gitignore
echo ".next/" >> .gitignore
echo "*.log" >> .gitignore

# 2. 如果仓库有大文件，用 git-lfs
git lfs install
git lfs track "*.psd"
git lfs track "*.zip"
git add .gitattributes

# 3. 清理历史中的大文件（慎重！会改写历史）
git filter-branch --force --index-filter \
  'git rm --cached --ignore-unmatch path/to/large/file' \
  --prune-empty --tag-name-filter cat -- --all

问题：npm install 在 Claude Code 中卡住

症状：Claude Code 执行 npm install 后一直等待

原因：
1. npm registry 连接慢
2. 依赖树太深
3. 有私有 registry 需要认证

# 解决：
# 1. 换淘宝源
npm config set registry https://registry.npmmirror.com

# 2. 或者用 pnpm（更快）
npm install -g pnpm
pnpm install

# 3. 如果有私有包，先登录
npm login --registry=https://npm.your-company.com

# 4. 在 CLAUDE.md 中告诉 Claude 用什么包管理器
# "使用 pnpm 而不是 npm"

问题：Claude Code 执行测试一直失败

症状：Claude 改了代码后跑测试，测试失败，然后改测试，又失败，循环...

原因：
1. 测试本身有问题（环境依赖）
2. Claude 不理解测试的意图
3. 数据库/外部服务没有 mock

# 解决：
# 1. 先让 Claude 只看错误，不要自动修
"测试失败了，先不要改代码，分析一下失败原因"

# 2. 在 CLAUDE.md 中写清楚测试规范
# "测试必须 mock 数据库和外部 API"
# "测试文件和源码文件放同一目录"

# 3. 让 Claude 先跑一次现有测试确认基线
"先跑一下现有测试，确认在你改代码之前是全过的"

问题：Claude Code 改了不该改的文件

症状：让 Claude 修一个 bug，它顺手重构了整个文件

原因：
1. 指令不够具体
2. Claude 倾向于"顺便优化"

# 解决：
# 1. 明确约束
"只修复第 45 行的 bug，不要改其他任何代码"

# 2. 用否定约束
"不要重构，不要优化，不要加注释，只修这个 bug"

# 3. 让 Claude 先说明要改什么
"先告诉我你打算改哪些文件的哪些行，我确认后再改"

问题：Windows 上 Claude Code 路径报错

症状：文件路径报错，找不到文件

原因：Windows 路径（D:\xxx）和 Unix 路径（/d/xxx）混用

# 解决：
# Claude Code 在 Git Bash 中运行，用 Unix 路径
# 如果报错，试试：
cd /d/codes/ai-api/vibecoding
# 而不是
cd D:\codes\ai-api\vibecoding

# 或者在 Windows Terminal 中直接用 Windows 路径
cd D:\codes\ai-api\vibecoding
claude

问题：对话中途提示上下文满

症状：正在工作，Claude 提示上下文接近限制

原因：对话太长 + 读取了太多文件

# 解决：
# 1. 立即 /compact
/compact

# 2. 如果还不够，把当前进度记下来，开新对话
"总结一下当前的工作进度和下一步，我要开新对话了"

# 3. 把关键信息写入 CLAUDE.md
"把刚才讨论的方案写入 CLAUDE.md 的'当前迭代'部分"

# 4. 之后在新对话中继续
"继续之前的支付模块重构，进度见 CLAUDE.md"

问题：Claude Code 生成的代码有类型错误但不自知

症状：代码看起来对，但 tsc --noEmit 报一堆类型错误

原因：Claude 不会主动跑类型检查

# 解决：
# 1. 用 Hook 自动检查（见第七章）
# 2. 在指令中明确要求
"实现完后运行 npx tsc --noEmit，确保没有类型错误"

# 3. 在 CLAUDE.md 中写
# "每次修改 TypeScript 文件后必须运行类型检查"

问题：git commit 被 Claude Code 生成了奇怪的 message

症状：commit message 是 "Update file.ts" 或 "fix stuff"

原因：Claude 没有 commit message 规范

# 解决：
# 1. 在 CLAUDE.md 中定义规范
# "Commit message 使用 Conventional Commits 格式：
#  feat: 新功能
#  fix: Bug 修复
#  refactor: 重构
#  docs: 文档
#  test: 测试
#  chore: 杂项
#  标题不超过 50 字符，空一行后写详细描述"

# 2. 或者让 Claude 先写 message，你确认后再 commit
"先写 commit message 给我看，我确认后再 commit"