Claude Code 完整使用指南：从入门到自动化工作流

AI 编程工具已经进入”第二阶段”——不再是单纯的代码补全，而是可以理解上下文、执行多步任务、甚至自主管理文件和运行测试的 Agent 级别助手。Claude Code 就是这个阶段最具代表性的工具之一。

本文不是功能罗列，而是一份可以直接上手的实战指南，覆盖安装配置、核心工作流、自动化钩子，以及与 Cursor 等同类工具的横向对比。

一、什么是 Claude Code，它和其他工具有什么不同

Claude Code 是 Anthropic 推出的终端原生 AI 编程助手，以 CLI 形式运行，核心定位是”在你的代码库里工作的 Agent”，而不是编辑器插件。

与 Cursor 的核心差异

维度	Claude Code	Cursor
运行方式	终端 CLI / IDE 扩展	独立编辑器
上下文管理	全局 CLAUDE.md + 项目级配置	规则文件（.cursorrules）
任务执行	可直接运行 shell 命令、测试、git	主要聚焦编辑操作
自动化支持	Hooks 机制，事件驱动	有限
适用场景	多步骤 Agent 任务、CI 集成	编辑器内快速迭代

一句话总结：Cursor 是”更智能的编辑器”，Claude Code 是”会写代码的队友”。如果你需要让 AI 帮你跑测试、提交 PR、修复 CI 流水线，Claude Code 更合适。

---

二、安装与初始配置

安装

# 通过 npm 全局安装
npm install -g @anthropic-ai/claude-code

# 验证安装
claude --version

# 首次登录（OAuth 认证，无需手动配置 API Key）
claude

项目级配置：CLAUDE.md

在项目根目录创建 CLAUDE.md，Claude Code 每次启动时会自动读取，作为”项目说明书”：

# 项目说明

## 技术栈
- Node.js 20 + TypeScript 5
- PostgreSQL 16，ORM 使用 Prisma
- 测试框架：Vitest

## 开发规范
- 所有新增函数必须有 JSDoc 注释
- 提交信息遵循 Conventional Commits
- 禁止直接修改 `dist/` 目录下的文件

## 常用命令
- `npm run dev`：启动开发服务器
- `npm run test`：运行单元测试
- `npm run lint`：代码风格检查

这份文件直接决定了 Claude Code 对项目的”理解深度”，越详细，输出质量越高。

---

三、核心使用场景

场景一：理解陌生代码库

接手一个新项目，先让 Claude Code 帮你建立地图：

claude "分析这个项目的整体架构，重点说明数据流向和核心模块之间的依赖关系"

它会自动读取文件树、关键源码、package.json，然后给出结构性分析——这比手动翻代码快 10 倍。

场景二：实现一个完整功能

claude "在 src/api/ 下新增一个用户积分查询接口，需要：
1. GET /users/:id/points
2. 从 PostgreSQL 的 user_points 表查询
3. 加上请求频率限制（每分钟最多 60 次）
4. 编写对应的单元测试"

Claude Code 会依次创建路由文件、编写测试、甚至检查现有代码风格来保持一致性。

场景三：代码审查与重构

# 审查最近的改动
claude "review 一下我刚才修改的文件，重点关注潜在的安全漏洞和性能问题"

# 针对特定文件重构
claude "重构 src/utils/auth.ts，把重复的 JWT 验证逻辑抽取成独立函数，保持对外 API 不变"

场景四：调试难以复现的 Bug

claude "线上报了一个 UnhandledPromiseRejection 错误，堆栈如下：
[粘贴错误日志]
帮我定位根因，并给出修复方案"

---

四、自动化工作流：Hooks 机制

这是 Claude Code 区别于其他工具的核心能力。通过 settings.json 配置 Hooks，可以在特定事件触发时自动执行 shell 命令。

配置文件位置

~/.claude/settings.json          # 全局配置
.claude/settings.json            # 项目级配置（优先级更高）

典型配置示例

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint --fix 2>&1 | head -50"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo '[Hook] 即将执行 shell 命令，请注意风险'"
          }
        ]
      }
    ]
  }
}

这个配置的效果：每次 Claude Code 修改文件后，自动运行 lint 修复——无需你手动干预，代码风格始终保持整洁。

进阶：自动代码审查 Hook

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "git diff --staged | head -200"
          }
        ]
      }
    ]
  }
}

在 Claude Code 完成一轮任务后，自动输出 diff 供你确认，防止意外改动漏网。

---

五、上下文管理技巧

使用 /clear 控制上下文窗口

长会话中，历史对话会消耗大量 token 并引入噪声：

/clear          # 清空当前会话历史，保留 CLAUDE.md 配置

在切换到新任务时养成 /clear 的习惯，响应质量会明显提升。

精准引用文件

# 直接指向具体文件，避免 Claude 自行猜测
claude "解释一下 @src/core/scheduler.ts 的调度逻辑"

# 多文件关联分析
claude "对比 @src/v1/parser.ts 和 @src/v2/parser.ts 的差异，说明 v2 的改进点"

使用 /compact 压缩上下文

/compact        # 保留关键信息，压缩对话历史，节省 token

适合进行长时间、多步骤的重构任务时使用。

---

六、与 CI/CD 集成

Claude Code 可以在无人值守模式下运行，适合集成到 GitHub Actions：

# .github/workflows/claude-review.yml
name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Run AI Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          git diff origin/main...HEAD > changes.diff
          claude --print "请审查以下代码变更，输出结构化的审查报告，重点关注安全性、性能和可维护性：$(cat changes.diff)"

注意：在 CI 环境中使用 --print 参数让 Claude Code 以非交互模式运行，直接输出结果到 stdout。

---

七、常见问题与最佳实践

Q：Claude Code 会不会乱改代码？
通过 CLAUDE.md 明确禁止修改的目录/文件，配合 Hooks 在每次修改后自动 diff 确认，风险可控。

Q：如何让输出更稳定、更符合项目风格？
CLAUDE.md 写得越具体越好。把编码规范、禁止事项、常用命令都写进去，比在对话里反复提醒有效得多。

Q：token 消耗太快怎么办？

• 用 /compact 压缩上下文
• 任务切换时用 /clear
• 指向具体文件而不是让 Claude 自行扫描整个代码库

---

八、总结

Claude Code 的价值不在于”它能写代码”——大多数 AI 工具都能做到。它真正的差异化在于：

1. Agent 级别的任务执行：不只是生成代码片段，而是完成端到端的开发任务
2. 可编程的自动化：Hooks 机制让它真正融入工程流程，而不是孤立的对话工具
3. 上下文持久化：CLAUDE.md 让每次会话都有项目背景，无需反复解释

对于个人开发者，Claude Code 能让你以”一个人的效率干两个人的活”；对于技术团队，它可以标准化代码审查、自动化重复性工程任务，让工程师专注在更有创造力的工作上。

---

延伸阅读

• Claude Code 官方文档 — Hooks 配置的完整字段参考
• CLAUDE.md 最佳实践社区讨论 — 看看其他团队怎么写项目说明书
• Claude Code + GitHub Actions 深度集成 — 官方 Action 的源码和用法
• 本站相关文章：《AI 辅助代码审查：让 PR Review 不再是团队瓶颈》