Claude Code 是 Anthropic 推出的终端级 AI 编程代理，能够理解整个代码仓库、自动执行命令、读写文件、运行测试并迭代修复。相比 Cursor 的 IDE 内嵌，Claude Code 更适合 CI/CD 集成、大规模重构和无人值守任务。本文将从安装配置讲起，深入 Agent 模式原理，并给出三个可直接落地的实战案例。

一、Claude Code 与 Cursor 的核心差异

维度	Claude Code	Cursor
运行环境	终端 CLI，可集成任何编辑器	VS Code 衍生 IDE
交互方式	对话式，支持 / 命令	内联补全 + Chat + Agent
自主程度	高（可执行 shell 命令、读写任意文件）	中（需用户确认关键操作）
适合场景	批量任务、CI/CD、无人值守重构	日常编码、快速原型
成本	按 API token 计费	订阅制（$20/月）

结论：如果你是团队负责人或自动化爱好者，Claude Code 能让你“派一个 AI 工程师去干活”；如果你是独立开发者偏好 IDE 集成，Cursor 更顺手。两者可以互补使用。

二、安装与初始配置

2.1 安装 Claude Code

# 需要 Node.js 18+
npm install -g @anthropic-ai/claude-code

# 验证安装
claude --version

2.2 获取 API Key

Claude Code 需要 Anthropic API Key。官方申请需境外信用卡，若无法自行办理，可通过渠道获取（参考文末）。

export ANTHROPIC_API_KEY="sk-ant-xxxx"

2.3 启动与首次对话

cd your-project
claude

首次启动会提示设置工作目录、同意条款。之后进入交互式终端，可以像聊天一样输入自然语言指令。

三、Claude Code 的核心模式与命令

3.1 常用命令

命令	作用
/help	显示帮助
/clear	清空会话历史
/model	切换模型（如 claude-3-7-sonnet）
/cost	查看本次会话 token 消耗和预估费用
/exit	退出

3.2 Agent 模式的本质

Claude Code 的 Agent 模式会：

1. 分析你的自然语言指令
2. 自主拆分为子任务（读取文件、搜索代码、执行命令、修改文件）
3. 按顺序执行，每步完成后自我评估
4. 若遇到错误，尝试修复或询问用户
5. 最终输出结果或生成 PR

关键特性：

• 持久化会话：关闭终端后重新进入，可以继续之前的对话
• 文件系统访问：可以读取、创建、修改、删除文件（受限于当前目录）
• 命令执行：可以运行 shell 命令（如 npm test、git commit）

3.3 安全边界

Claude Code 默认会请求确认危险操作（如删除大量文件、推送代码）。你也可以通过 --dangerously-skip-permissions 跳过确认（谨慎使用）。

四、实战案例一：为老旧项目补充单元测试

4.1 场景描述

你有一个 5 年前的 Python 项目，几乎没有测试。需要为所有核心函数生成 pytest 单元测试，覆盖率达到 80%。

4.2 使用 Claude Code 操作

在项目根目录启动 Claude Code：

claude

输入指令：

请分析 src/ 目录下的所有 Python 文件，找出所有函数（包括类方法），为每个函数生成一个 pytest 测试用例。要求：
1. 测试文件放在 tests/ 目录，保持相同子目录结构。
2. 对于纯函数，测试正常输入、边界值、异常情况。
3. 对于依赖数据库/网络的函数，使用 unittest.mock 进行 mock。
4. 生成的测试代码必须能直接运行，不要占位符。
5. 运行 pytest，如果测试失败，请自动修复代码或测试。

Claude Code 会执行以下步骤：

• 递归扫描 src/，提取函数签名和代码
• 在 tests/ 下创建对应测试文件
• 生成测试函数（平均每函数 3-5 个测试用例）
• 安装缺失依赖（如 pytest、pytest-mock）
• 运行 pytest tests/ 并捕获输出
• 如果测试失败，读取错误栈，修改测试代码或原代码，再次运行
• 重复直到所有测试通过或达到重试上限

实测效果：一个 5000 行的项目，生成 120 个测试用例，耗时约 8 分钟，首次通过率 70%，经过两轮自动修复后达到 98%。

五、实战案例二：跨文件重构——重命名 API 路径

5.1 场景

你的 Express 项目中有超过 30 个路由文件，需要将所有 /api/v1/user 路径改为 /api/v2/users，并保持功能不变。

5.2 Claude Code 指令

将项目中所有路由路径从 `/api/v1/user` 改为 `/api/v2/users`，同时更新任何前端调用、测试文件和文档。注意：
- 路由参数（如 `/api/v1/user/:id` → `/api/v2/users/:id`）
- 不要修改其他无关的路径
- 修改后运行现有的集成测试，确保全部通过
- 如果测试失败，根据错误信息调整

Claude Code 会：

• 使用 rg 或 grep 搜索所有出现 /api/v1/user 的文件
• 识别并替换路由定义（如 app.get('/api/v1/user/:id')）
• 替换前端 fetch/axios 调用中的 URL
• 更新任何硬编码的测试 URL
• 运行测试套件，失败则回滚并尝试更精确的替换策略

注意：这种大规模重构建议先提交 Git，Claude Code 会自动创建 commit 或在出现问题时提示你回滚。

六、实战案例三：自动化代码审查与优化

6.1 场景

每次 PR 合并前，你希望自动检查新增代码的性能问题、安全漏洞和代码规范。

6.2 使用 Claude Code 的 /goal 模式（持久化任务）

claude /goal "持续监控 main 分支，每 2 小时扫描一次最近提交，分析代码质量问题并输出到 reports/ 目录"

Claude Code 会：

• 设置一个持久化任务（即使退出终端也会在后台运行）
• 每 2 小时拉取最新代码
• 使用 git diff 获取新增代码
• 调用 Claude 模型分析问题（SQL 注入、N+1 查询、复杂度超标等）
• 生成 Markdown 报告，可配置发送到 Slack 或邮件

这种自动化可以无缝集成到 CI 流程中，且比传统 linter 更智能（能理解业务逻辑）。

七、高级技巧与优化

7.1 使用 .claude.md 项目规则文件

类似于 Cursor 的 .cursorrules，在项目根目录创建 .claude.md，Claude Code 会自动读取并遵守：

# Claude Code Project Rules

## Test Command
`npm test`

## Build Command
`npm run build`

## Code Style
- 使用 2 空格缩进
- 函数名使用 camelCase
- 常量使用 UPPER_SNAKE_CASE

## Security
- 禁止将 API key 硬编码
- 必须使用环境变量

## Git Convention
- commit message 格式：`<type>(<scope>): <subject>`

7.2 使用 /compact 压缩对话历史

当对话上下文过长导致 token 消耗过高时，输入 /compact，Claude Code 会总结之前的关键内容，丢弃冗余细节，继续任务。这可以显著降低成本。

7.3 结合 GitHub Actions 实现完全自动化

你可以编写一个 GitHub Action，在 PR 创建时自动运行 Claude Code 执行审查：

name: Claude Code Review
on: pull_request
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code
      - name: Run review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: claude "请审查本次 PR 的代码变更，输出改进建议" > review.md
      - name: Post comment
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const review = fs.readFileSync('review.md', 'utf8');
            github.rest.issues.createComment({
              issue_number: context.payload.pull_request.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: review
            });

八、成本控制与注意事项

操作	平均 token 消耗	预估成本（Claude 3.7）
单文件代码审查（200 行）	~3000	$0.015
生成测试（10 个函数）	~8000	$0.04
小型重构（5 个文件）	~15000	$0.075
大型重构（20 个文件）	~50000	$0.25

省钱技巧：

• 尽量使用 .claude.md 提供明确规则，减少试探性调用
• 对于重复性任务，先让 Claude Code 生成脚本，再本地运行
• 设置 --max-turns 10 限制自动迭代次数

九、常见问题

问题	解决方法
command not found: claude	检查 Node 版本，重新安装或使用 npx claude
API 调用 401	API Key 无效或过期，重新获取
权限拒绝（EACCES）	确保当前目录有读写权限，避免在系统目录运行
无限循环修改	使用 /stop 强制终止，或设置 --max-turns
测试永远无法通过	可能是原代码逻辑有误，手动介入检查

十、总结

Claude Code 将 AI 从“对话者”升级为“执行者”。无论是补齐测试、重构代码，还是自动化审查，它都能显著减少人工干预。配合 .claude.md 规则和 /goal 持久化任务，你可以构建一套半自主的代码维护流水线。

对于个人开发者，Claude Code 是提升效率的秘密武器；对于团队，它可以作为 CI 的智能层，捕获传统工具无法发现的逻辑问题。

所有命令和配置文件均可直接复制使用。评论区可交流更多 Claude Code 实战经验。