系列文章

本篇是 Claude Code 系列的第 1 篇。系列将从安装入门到高级实战，由浅入深地拆解这个终端原生 Coding Agent 的每一个能力。

入门篇

  1. Claude Code 是什么？从安装到第一次对话（本文）
  2. 日常开发工作流：用 Claude Code 重塑你的编码习惯

核心篇
3. 内置命令全解：从 /compact 到 /doctor 的实战指南
4. CLAUDE.md：项目上下文工程的艺术

进阶篇
5. 多文件重构与复杂任务实战
6. Hooks、MCP 与能力扩展

高级篇
7. Headless 模式与 CI/CD 集成
8. 多 Agent 协作：从 Claude Code 到 Codex

一、开篇：为什么又一个 AI 编程工具？

2024 年，AI 编程工具遍地开花。GitHub Copilot 补全代码、Cursor 重写 IDE、ChatGPT 回答技术问题。每个工具都在解决”写代码”的某个环节，但它们有一个共同的局限：你是工具的使用者，而不是指挥者。

你打开 IDE，等 Copilot 补全一行代码；你切到浏览器，在 ChatGPT 里粘贴报错信息；你回到 IDE，手动复制粘贴解决方案。整个过程中，你在适应工具，而不是工具在适应你。

2025 年 2 月，Anthropic 发布了 Claude Code——一个运行在终端里的自主编程 Agent。它不是 IDE 插件，不是代码补全，而是一个能理解你的整个代码库、自己读文件、写代码、跑测试、提交 Git 的自主代理。

你只需要用自然语言告诉它要做什么，剩下的它自己搞定。

到 2026 年 6 月，Claude Code 已经迭代到 v2.1.185，经历了 441 个版本更新，默认模型从 Claude 3.5 Sonnet 一路升级到 Claude Opus 4.8。它已经从一个”有趣的实验”变成了很多开发者的主力生产力工具。

这篇文章，我们从零开始。

二、Claude Code 到底是什么？

一句话：Claude Code 是一个住在你终端里的 AI 程序员。

它不是帮你补全代码的 Copilot，不是帮你回答问题的 ChatGPT，而是一个能自主完成整个开发任务的 Agent。你告诉它”给用户模块加一个分页查询接口”，它会：

  1. 读你的项目结构，理解分层架构
  2. 找到现有的 Controller、Service、Mapper 模板
  3. 写出新的接口代码（Controller + Service + Mapper + 单元测试）
  4. 跑测试，看是否通过
  5. 如果测试失败，自己修 bug 再跑
  6. 最终帮你 commit

整个过程，你只需要下达指令和审批关键操作。

它的定位矩阵

工具 定位 交互方式 自主程度
GitHub Copilot 代码补全 IDE 内联 低（逐行建议）
Cursor AI IDE 对话 + 编辑 中（需要确认）
ChatGPT 通用问答 浏览器 无（不操作你的代码）
Codex CLI 终端 Agent 终端 高（OpenAI 出品）
Claude Code 终端 Agent 终端/IDE/桌面/Web 高（Anthropic 出品）

Claude Code 的独特之处在于它的终端原生设计。它不是从 IDE 里”长出来”的，而是从终端”长出来”的。这意味着它天然理解 shell 环境、Git 工作流、CI/CD 流水线——这些恰恰是真实开发中最核心的基础设施。

它能做什么？

代码理解与编辑：读取整个项目代码库，理解架构和依赖关系，跨多个文件进行编辑。

终端命令执行：运行测试、安装依赖、执行构建脚本——任何你在终端里能做的事。

Git 工作流：创建分支、提交代码、发起 PR、解决冲突。

多文件重构：同时修改 10 个文件的重构操作，它能保持一致性。

自主迭代：写代码 → 跑测试 → 发现失败 → 修改 → 再跑——直到通过。

代码审查：/ultrareview 命令可以启动多 Agent 并行代码审查。

计算机操控（研究预览）：打开原生应用、点击 UI、验证视觉变化。

三、安装：三种方式任选

方式一：官方安装脚本（推荐）

macOS / Linux：

1
curl -fsSL https://claude.ai/install.sh | bash

Windows（PowerShell）：

1
irm https://claude.ai/install.ps1 | iex

这是官方推荐的方式，会自动处理依赖和 PATH 配置。

方式二：包管理器

Homebrew（macOS / Linux）：

1
brew install --cask claude-code

WinGet（Windows）：

1
winget install Anthropic.ClaudeCode

Homebrew 在过去 30 天有约 9 万次安装，说明它在开发者中已经非常普及。

方式三：npm（已废弃）

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

⚠️ 注意：npm 安装方式已被官方标记为废弃（deprecated）。虽然还能用，但推荐使用上面两种方式。

系统要求

  • Node.js：18 或更高版本
  • 操作系统：macOS、Linux、Windows 全平台支持
  • Git：推荐安装（Windows 上 Git for Windows 不再是必须的，Claude Code 会使用 PowerShell 作为替代）

安装完成后，终端输入 claude 就能启动。

四、认证：四种方式连接你的大脑

Claude Code 本身不带模型，它需要连接到 Claude 模型才能工作。认证方式决定了它通过什么渠道访问模型。

方式一：Anthropic API Key（最直接）

到 console.anthropic.com 注册账号，创建 API Key。

首次启动 claude 时，它会提示你输入 API Key。输入后自动保存，后续使用无需重复配置。

计费方式：按 token 用量计费（输入/输出分别计价）。Opus 4.8 的快速模式价格约为 $10/$50 每百万 token（输入/输出）。

适合：个人开发者、想精确控制成本的团队。

方式二：Claude Pro / Max 订阅（最省心）

如果你已经订阅了 Claude Pro（$20/月）或 Max（$100/月），可以直接用 OAuth 登录：

1
2
claude
# 首次启动会弹出浏览器进行 OAuth 认证

Pro 计划：包含 Claude Code 访问权限，有使用量限制。

Max 计划：更高的使用量上限，默认使用 Opus 4.8 模型。

适合：不想操心 token 消耗、偏好固定月费的开发者。

方式三：云平台代理

如果你的公司使用 AWS 或 GCP，可以通过云平台的 IAM 认证访问 Claude：

Amazon Bedrock：

1
2
export CLAUDE_CODE_USE_BEDROCK=1
# 使用 AWS 凭证链认证（IAM Role、环境变量、~/.aws/credentials）

Google Vertex AI：

1
2
export CLAUDE_CODE_USE_VERTEX=1
# 使用 gcloud auth 或服务账号认证

Microsoft Foundry：

1
export CLAUDE_CODE_USE_FOUNDRY=1

适合：企业用户、需要数据不出云的合规场景。

方式四：LLM Gateway

如果你的团队有自己的 AI 网关（比如 LiteLLM、OneAPI），可以配置自定义端点：

1
2
export ANTHROPIC_BASE_URL=https://your-gateway.example.com/v1
export ANTHROPIC_API_KEY=your-gateway-key

适合：有统一 AI 网关的企业、需要审计和成本管控的团队。

五、第一次对话：Hello, Claude

安装完成，认证搞定，让我们开始第一次对话。

启动

1
2
3
4
5
# 进入你的项目目录
cd ~/projects/my-spring-boot-app

# 启动 Claude Code
claude

Claude Code 会扫描当前目录，读取项目结构。你会看到一个简洁的终端界面：

1
2
3
4
5
6
7
╭──────────────────────────────────────────╮
│  Claude Code v2.1.185                    │
│  Model: claude-opus-4-8-20260620         │
│  /help for commands                      │
╰──────────────────────────────────────────╯

> _

第一个任务：了解项目

试试让它帮你理解项目：

1
> 这个项目的整体架构是什么？用中文回答。

Claude Code 会开始读取你的项目文件——pom.xml、application.yml、Controller、Service、Mapper——然后给出一个结构化的分析。

关键区别：它不是在”猜测”你的项目结构，而是真的在读文件。它会递归扫描目录、解析配置文件、追踪依赖关系。

第二个任务：写代码

1
> 给 UserController 加一个分页查询接口，参考现有的 findAll 方法，使用 PageHelper。

Claude Code 会：

  1. 先找到 UserController.java，读取现有代码
  2. 理解 findAll 方法的模式
  3. 找到相关的 Service、Mapper 接口
  4. 生成分页查询的完整代码（Controller → Service → Mapper → XML）
  5. 展示 diff，等待你确认

第三个任务：跑测试

1
> 跑一下 UserService 的单元测试，如果有失败的帮我修。

它会执行 mvn test -Dtest=UserServiceTest，分析测试结果。如果有失败的测试用例，它会：

  1. 读取失败的测试代码
  2. 分析断言失败的原因
  3. 修改源代码或测试代码
  4. 重新跑测试
  5. 循环直到全部通过

权限控制

Claude Code 在执行敏感操作前会征求你的同意：

  • 读取文件：自动执行（你已经授权了目录访问）
  • 编辑文件：展示 diff，等待确认
  • 执行命令：根据配置决定（可设置自动批准安全命令）
  • Git 操作：展示 commit message，等待确认

你可以用 /config 命令调整权限级别，或者使用 --allowedTools 参数在启动时指定。

六、核心概念：Agent Loop

理解 Claude Code 的工作方式，关键在于理解它的 Agent Loop（代理循环）：

1
用户输入 → 思考 → 选择工具 → 执行 → 观察结果 → 思考 → ... → 输出

这和我们在 AI Agent 系列中讲的 ReAct 模式是同构的：

ReAct 概念 Claude Code 实现
Thought（思考） 分析代码结构、规划修改方案
Action（行动） 读文件、编辑代码、执行命令
Observation（观察） 获取命令输出、测试结果、diff
循环 写代码 → 跑测试 → 发现失败 → 修改 → 再跑

每一轮循环，Claude Code 可以：

  • 读取文件（Read 工具）
  • 编辑文件（Edit 工具，展示精确的行级 diff）
  • 执行终端命令（Bash 工具）
  • 搜索代码（Grep / Glob 工具）

一个复杂的任务可能经历 20-30 轮循环。这就是为什么它能完成”给整个模块加缓存”这种跨多文件的复杂任务——它不是一个”一次性回答”的工具，而是一个持续迭代、自我修正的 Agent。

七、CLAUDE.md：你的项目说明书

这是 Claude Code 最重要的特性之一，也是它和其他 AI 工具的核心区别。

在项目根目录放一个 CLAUDE.md 文件，Claude Code 每次启动时都会自动读取它。这个文件相当于给 AI 新同事的一份入职手册。

一个典型的 CLAUDE.md

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
# 项目说明

这是一个 Spring Boot 3.x + MyBatis-Plus 的后端服务。

## 技术栈
- Java 17 + Spring Boot 3.2
- MyBatis-Plus 3.5
- MySQL 8.0
- Redis（缓存 + 分布式锁）
- RabbitMQ（消息队列）

## 项目结构
- controller/ — REST API 层
- service/ — 业务逻辑层
- mapper/ — 数据访问层
- config/ — 配置类
- common/ — 工具类和公共组件

## 开发规范
- 所有接口返回统一的 Result<T> 包装
- 分页使用 PageHelper，不要手写 LIMIT
- 新接口必须写单元测试
- commit message 使用中文，格式：「模块名：描述」

## 常用命令
- 构建：mvn clean package -DskipTests
- 测试：mvn test
- 启动：mvn spring-boot:run

有了这个文件，Claude Code 就知道你的项目用什么技术栈、遵循什么规范、怎么构建和测试。它生成的代码会自动遵循你定义的风格。

层级化的 CLAUDE.md

Claude Code 支持多层级的 CLAUDE.md：

1
2
3
4
项目根目录/CLAUDE.md          ← 全局规范
├── src/CLAUDE.md             ← 源码层说明
├── src/modules/user/CLAUDE.md ← 用户模块特殊说明
└── tests/CLAUDE.md           ← 测试规范

启动时，它会读取当前目录及所有父目录的 CLAUDE.md，合并为完整的上下文。这对于 monorepo 项目特别有用——每个子模块可以有自己的规范。

八、成本管理：别让账单吓到你

Claude Code 按 token 计费，一个复杂的重构任务可能消耗几美元。好消息是，它提供了一套完整的成本管理工具。

/cost：实时查看消费

1
2
3
4
5
6
> /cost

Session cost: $2.37
  Input tokens:  125,430 ($1.25)
  Output tokens:  42,180 ($2.11)
  Cache read:     89,200 ($0.09)

/compact：压缩上下文

长对话会累积大量上下文，导致 token 消耗飙升。/compact 命令会压缩对话历史，保留关键信息：

1
2
3
4
> /compact

Compacted conversation (125K → 15K tokens)
Saved approximately $1.10

/usage：订阅用量分析

对于 Pro/Max 订阅用户，/usage 命令显示详细的用量分解：

1
2
3
4
5
6
7
8
> /usage

Plan: Claude Max
Used today: 45% of daily limit
Breakdown by skill:
  - code-editing: 62%
  - terminal-commands: 23%
  - file-reading: 15%

省钱技巧

  1. 用 /compact 定期压缩——尤其是完成一个子任务后
  2. 选对模型——简单任务用 --model sonnet，省钱又快
  3. 写好 CLAUDE.md——减少 Claude “探索”项目的时间
  4. 用 /clear 清除重来——切换任务时比 /compact 更彻底
  5. 善用 prompt caching——重复读取的文件会自动缓存，大幅降低输入 token 成本

九、和竞品的深度对比

Claude Code vs GitHub Copilot

维度 Claude Code GitHub Copilot
核心能力 自主完成整个任务 逐行/逐块补全代码
交互方式 自然语言指令 Tab 接受/拒绝建议
代码理解 读取整个项目 主要基于当前文件上下文
测试能力 自动跑测试、自动修 bug 不涉及
Git 集成 完整的 Git 工作流 不涉及
价格 $20-$100/月 $10-$19/月

结论：Copilot 是”更快地打字”，Claude Code 是”派一个人帮你干活”。两者不是替代关系，可以同时使用。

Claude Code vs Cursor

维度 Claude Code Cursor
载体 终端 IDE（VS Code fork）
模型 Claude 系列 多模型（可选 Claude、GPT 等）
自主程度 高（Agent Loop） 中（需要更多交互）
终端操作 原生支持 有限
适合场景 后端/全栈/DevOps 前端/全栈

结论：Cursor 更适合喜欢 IDE 可视化体验的开发者；Claude Code 更适合习惯终端工作流的开发者。

Claude Code vs Codex CLI

维度 Claude Code Codex CLI
出品方 Anthropic OpenAI
默认模型 Claude Opus 4.8 o3 / o4-mini
开源 否（代码在 GitHub 但非开源许可） 是
桌面应用 有 无
GitHub 集成 @claude 标签 无
计算机操控 有（研究预览） 无

结论：两者定位相似，都是终端原生 Agent。Claude Code 生态更丰富（桌面应用、IDE 插件、Web 界面、Slack 集成），Codex CLI 开源透明度更高。

十、快速上手：5 分钟体验清单

如果你已经安装好了 Claude Code，按这个清单走一遍：

第 1 步：进入项目目录

1
cd ~/your-project

第 2 步：启动

1
claude

第 3 步：试三个命令

1
2
3
4
5
6
7
8
# 1. 了解项目
> 用中文介绍这个项目的架构和技术栈

# 2. 写一个小功能
> 帮我写一个健康检查接口 /health，返回应用状态和当前时间

# 3. 跑测试
> 跑一下全部测试，告诉我结果

第 4 步：创建 CLAUDE.md

1
> 帮我生成一个 CLAUDE.md 文件，包含这个项目的技术栈、目录结构、开发规范和常用命令

第 5 步：查看消费

1
> /cost

恭喜，你已经完成了第一次完整的 Claude Code 体验。

十一、写在最后

Claude Code 不是银弹。它不能替代你思考架构、不能替代你做技术决策、不能替代你理解业务需求。但它能把你的想法快速变成代码，把”我知道该怎么做但懒得写”的活儿自动化。

从 AI Agent 系列的角度看，Claude Code 就是我们讲过的那些理论的最佳实践：

  • ReAct 循环 → 读代码 → 写代码 → 跑测试 → 观察
  • 工具调用 → 文件读写、终端命令、Git 操作
  • 记忆系统 → CLAUDE.md 项目上下文
  • 上下文工程 → /compact 压缩、Token 预算管理
  • 人机协作 → 权限审批、Plan 模式

理论够了，该动手了。

下一篇，我们深入 Claude Code 的日常开发工作流——看看它如何改变你每天写代码的方式。