05a - Claude Code 快速入门
本文是《AI Agent 实战手册》第 5 章第 1 节。 上一节：Prompt 版本管理 | 下一节：CLAUDE.md 编写指南
概述
Claude Code 是 Anthropic 推出的终端原生 AI 编码助手，与 Cursor、Copilot 等 IDE 插件不同，它直接运行在命令行中，能读取整个代码库、执行多文件编辑、运行测试、提交代码甚至创建 PR。本节从零开始，覆盖安装配置、核心概念、基本用法，并提供一个”前 10 分钟”实战教程，帮你快速上手。
1. Claude Code 是什么
Claude Code 是一个 Agentic 编码工具——它不只是补全代码，而是像一个驻扎在终端里的 AI 结对程序员。你用自然语言描述需求，它会自主完成以下工作：
- 读取代码库：自动索引项目文件，理解代码结构和依赖关系
- 多文件编辑：跨文件重构、添加功能、修复 bug
- 执行命令：运行测试、构建项目、执行 shell 命令
- Git 操作：提交代码、创建分支、发起 PR
- 连接外部工具：通过 MCP（Model Context Protocol）连接数据库、API、第三方服务
与其他工具的定位对比
| 特性 | Claude Code | Cursor | GitHub Copilot |
|---|---|---|---|
| 运行环境 | 终端 CLI | IDE（VS Code fork） | IDE 插件 |
| 交互方式 | 自然语言对话 | 对话 + 内联补全 | 内联补全 + Chat |
| 自主执行能力 | ✅ 完整 Agentic Loop | ✅ 部分 | ❌ 有限 |
| 多文件操作 | ✅ 原生支持 | ✅ 支持 | ⚠️ 有限 |
| 命令执行 | ✅ 直接执行 shell | ⚠️ 需确认 | ❌ 不支持 |
| MCP 支持 | ✅ 原生 | ✅ 支持 | ❌ 不支持 |
| Git 集成 | ✅ 深度集成 | ✅ 支持 | ⚠️ 基础 |
| 价格 | $20/月起 | $20/月起 | $10/月起 |
2. 安装与配置
系统要求
- 操作系统：macOS、Linux、Windows（通过 WSL）
- Node.js：18+ 版本（npm 安装方式需要）
- Anthropic 账户：需要 Pro 或以上订阅
工具推荐
| 工具 | 用途 | 价格 | 适用场景 |
|---|---|---|---|
| Claude Code CLI | 终端 AI 编码助手 | Pro $20/月，Max 5x $100/月，Max 20x $200/月 | 日常开发、项目构建 |
| Node.js 18+ | Claude Code 运行环境（npm 方式） | 免费 | 安装前置依赖 |
| VS Code / JetBrains | IDE 集成（可选） | 免费 / $24.90/月 | 配合 Claude Code 使用 |
| Git | 版本控制 | 免费 | 代码提交与 PR |
操作步骤
步骤 1：安装 Claude Code
推荐使用官方安装脚本（最稳定）：
# macOS / Linux（推荐方式）
curl -fsSL https://claude.ai/install.sh | bash
# macOS（Homebrew）
brew install --cask claude-code
# Windows（PowerShell）
irm https://claude.ai/install.ps1 | iex
# 通过 npm 安装（备选方式，需 Node.js 18+）
npm install -g @anthropic-ai/claude-code步骤 2：首次认证
# 启动 Claude Code，首次运行会打开浏览器进行 OAuth 认证
claude首次运行时，Claude Code 会自动打开浏览器窗口，引导你登录 Anthropic 账户完成授权。认证成功后，终端会显示交互式对话界面。
步骤 3：验证安装
# 检查安装状态
claude /doctor
# 查看版本
claude --version
# 查看账户和用量状态
claude /status步骤 4：进入项目开始使用
cd your-project
claude进入项目目录后运行 claude，即可开始交互式编码会话。
3. 核心概念
3.1 Agentic Loop（代理循环）
Claude Code 的核心工作机制是一个自主循环：
用户输入 → 理解意图 → 选择工具 → 执行操作 → 检查结果 → 自我修正 → 返回结果与传统的”问答式”AI 不同，Claude Code 会自主决定需要读取哪些文件、执行哪些命令、如何验证结果。如果第一次尝试失败，它会自动调整策略重试。
3.2 CLAUDE.md（项目上下文文件）
CLAUDE.md 是项目的”说明书”，告诉 Claude Code 你的项目使用什么技术栈、遵循什么编码规范、有哪些特殊约定。Claude Code 启动时会自动读取这个文件。
# 项目：我的 SaaS 应用
## 技术栈
- Next.js 14 + App Router
- TypeScript（严格模式）
- Tailwind CSS
- Prisma + PostgreSQL
## 编码规范
- 文件名使用 kebab-case
- 组件放在 src/components/
- 永远使用 async/await，不用 .then()
## 测试
- 提交前运行 npm test3.3 MCP（Model Context Protocol）
MCP 让 Claude Code 能连接外部工具和服务——可以理解为 Claude Code 的”插件系统”。通过 MCP Server，Claude Code 可以直接操作 GitHub、查询数据库、发送 Slack 消息等。
3.4 Hooks（钩子）
Hooks 允许你在 Claude Code 执行特定操作前后自动运行脚本。例如：提交代码前自动运行 lint，编辑文件后自动运行测试。
3.5 Subagent（子代理）
Claude Code 可以生成独立的子代理来并行处理任务。每个子代理有自己的上下文窗口，不会污染主对话。适合将大任务拆分为多个独立子任务。
3.6 Skills（技能）
Skills 是可复用的能力扩展模板，让 Claude Code 掌握特定领域的专业知识和工作流程。可以是项目级的，也可以是全局的。
4. 基本用法
4.1 常用斜杠命令
| 命令 | 功能 | 使用场景 |
|---|---|---|
/help | 显示所有可用命令 | 随时查看帮助 |
/init | 初始化项目，生成 CLAUDE.md | 新项目首次使用 |
/compact | 压缩对话历史，节省 token | 长对话时定期使用 |
/clear | 清空当前对话 | 切换不相关任务时 |
/cost | 显示当前会话 token 用量 | 追踪成本 |
/model | 切换 AI 模型 | 需要不同模型能力时 |
/doctor | 检查安装健康状态 | 排查问题 |
/memory | 编辑持久化记忆文件 | 存储跨会话偏好 |
/mcp | 管理 MCP 服务器连接 | 配置外部工具 |
/review | 请求代码审查 | 提交前审查 |
/rewind | 回退对话和/或代码变更 | 撤销不满意的修改 |
/agents | 管理自定义子代理 | 并行任务处理 |
/status | 查看账户和系统状态 | 检查用量和限制 |
/usage | 查看用量限制和速率状态 | 订阅用户查看配额 |
4.2 快捷键
| 快捷键 | 功能 |
|---|---|
! | Bash 模式前缀（直接执行命令） |
@ | 引用文件或文件夹 |
\ + Enter | 换行（不发送） |
Esc | 中断 Claude 当前操作 |
Esc + Esc | 打开回退菜单（撤销变更） |
Ctrl+R | 显示完整输出/上下文 |
Ctrl+V | 粘贴图片 |
Shift+Tab | 自动接受模式（“YOLO 模式”） |
Shift+Tab+Tab | Plan 模式 |
4.3 Headless 模式（无头模式）
用于脚本和 CI/CD 自动化，执行一次性命令后退出：
# 单次执行（print 模式）
claude -p "分析这个项目的目录结构并给出改进建议"
# 指定输出格式
claude -p "列出所有 TODO 注释" --output-format json
# 在 CI/CD 中使用
claude -p "审查最近一次 commit 的代码变更"5. 前 10 分钟教程
以下是一个从零开始的实战教程，帮你在 10 分钟内体验 Claude Code 的核心能力。
提示词模板
你好！我刚安装了 Claude Code，请帮我完成以下任务：
1. 查看当前项目结构
2. 创建一个 CLAUDE.md 文件，描述项目的技术栈和编码规范
3. [你的具体需求]分钟 0-2：安装与启动
# 安装
curl -fsSL https://claude.ai/install.sh | bash
# 进入你的项目（或创建一个新项目）
mkdir my-first-claude-project && cd my-first-claude-project
git init
# 启动 Claude Code
claude分钟 2-4：初始化项目
在 Claude Code 对话中输入：
/initClaude Code 会分析你的项目并自动生成 CLAUDE.md 文件。如果是空项目，它会询问你的技术栈偏好。
分钟 4-6：创建一个简单应用
帮我创建一个 Node.js + TypeScript 的 CLI 工具，功能是统计指定目录下的文件数量和总大小。
要求：
- 使用 commander 处理命令行参数
- 支持 --recursive 递归统计
- 输出格式化的表格观察 Claude Code 如何自主完成：
- 初始化
package.json - 安装依赖
- 创建 TypeScript 配置
- 编写源代码
- 添加构建脚本
分钟 6-8：运行和调试
运行这个工具，统计当前目录的文件信息如果有错误，Claude Code 会自动读取错误信息并修复。你也可以直接说：
运行报错了，请修复分钟 8-10：代码审查与提交
/reviewClaude Code 会审查代码质量，提出改进建议。确认后：
把所有改动提交到 git，commit message 用中文教程小结
在这 10 分钟里，你体验了 Claude Code 的核心工作流：
- 初始化：
/init生成项目上下文 - 创建：用自然语言描述需求，Claude Code 自主实现
- 调试：自动识别错误并修复
- 审查：
/review进行代码审查 - 提交：直接通过对话完成 git 操作
6. 订阅方案与成本
方案对比
| 方案 | 月费 | Claude Code 访问 | Token 容量 | 适用场景 |
|---|---|---|---|---|
| Pro | $20/月（年付 $17/月） | ✅ 完整访问 | 基础（约 45 条/5 小时窗口） | 日常编码、个人开发者 |
| Max 5x | $100/月 | ✅ 扩展限制 | 5 倍 Pro | 重度使用、复杂项目 |
| Max 20x | $200/月 | ✅ 最大容量 | 20 倍 Pro | 全天编码、专业开发 |
| Teams | $150/用户/月 | ✅ 高级席位 | 介于 Pro 和 Max 5x 之间 | 团队协作（最少 5 席） |
| API | 按 token 计费 | ✅ 通过终端 | 无限（按量付费） | 自定义集成、CI/CD |
API Token 价格参考
| 模型 | 输入（每百万 token） | 输出（每百万 token） |
|---|---|---|
| Haiku 4.5 | $1 | $5 |
| Sonnet 4.5 | $3 | $15 |
| Opus 4.5 | $5 | $25 |
成本控制提示
- 使用
/compact定期压缩对话，减少 token 消耗 - 使用
/clear在切换任务时清空上下文 - 使用
/cost随时查看当前会话消耗 - 开启 Extra Usage 并设置月度上限，避免超支
- Anthropic 官方数据：平均日成本约 $6，90% 开发者低于 $12/天
7. 配置文件体系
Claude Code 的配置文件按优先级从高到低排列：
| 优先级 | 文件路径 | 用途 | 是否提交 Git |
|---|---|---|---|
| 1（最高） | /etc/claude-code/managed-settings.json | 企业级管控 | N/A |
| 2 | .claude/settings.local.json | 个人本地配置 | ❌ git-ignored |
| 3 | .claude/settings.json | 团队共享配置 | ✅ |
| 4 | ~/.claude/settings.json | 全局个人默认 | N/A |
配置管理命令
# 查看所有配置
claude config list
# 获取特定配置值
claude config get <key>
# 设置配置
claude config set <key> <value>
# 添加到列表配置（如权限）
claude config add <key> <value>
# 从列表移除
claude config remove <key> <value>实战案例：用 Claude Code 重构一个 Express API
场景
你有一个 Express.js API 项目，路由和业务逻辑混在一起，想重构为分层架构。
操作流程
cd my-express-api
claude第一步：让 Claude Code 分析现状
分析这个项目的代码结构，找出架构问题，给出重构建议第二步：执行重构
按照你的建议重构项目：
1. 分离路由层、服务层、数据访问层
2. 添加统一的错误处理中间件
3. 保持所有现有 API 行为不变第三步：验证
运行所有测试，确保重构没有破坏任何功能第四步：提交
把重构的改动分成多个有意义的 commit 提交案例分析
- Claude Code 会先读取所有源文件，理解现有架构
- 然后制定重构计划，逐步执行多文件修改
- 每步修改后自动运行测试验证
- 最终按逻辑拆分为多个 git commit
这个过程体现了 Agentic Loop 的核心价值：你只需描述目标，Claude Code 自主规划和执行。
避坑指南
❌ 常见错误
-
不写 CLAUDE.md 就开始使用
- 问题：Claude Code 缺少项目上下文，生成的代码可能不符合项目规范
- 正确做法：首次使用时运行
/init或手动创建CLAUDE.md
-
长对话不压缩
- 问题：上下文窗口被历史消息占满，Claude Code 开始”遗忘”早期信息，且 token 消耗激增
- 正确做法：每完成一个独立任务后使用
/compact或/clear
-
一次性给太大的任务
- 问题：任务过大导致 Claude Code 迷失方向，输出质量下降
- 正确做法：将大任务拆分为小步骤，逐步推进，每步验证
-
忽略权限设置
- 问题：Claude Code 默认会请求确认危险操作，但 YOLO 模式（Shift+Tab）会跳过确认
- 正确做法：生产环境中保持默认权限，只在实验项目中使用自动接受
-
不使用 @ 引用文件
- 问题：Claude Code 需要自己搜索相关文件，浪费 token 和时间
- 正确做法：用
@filename主动提供相关文件，减少上下文搜索开销
-
免费账户尝试使用 Claude Code
- 问题：Claude Code 需要 Pro 或以上订阅，免费账户无法使用
- 正确做法：至少订阅 Pro 方案（$20/月）
✅ 最佳实践
- 每个项目都维护一份
CLAUDE.md，保持更新 - 善用
/compact管理上下文长度 - 用
@引用具体文件，减少不必要的上下文搜索 - 大任务拆小步，每步验证后再继续
- 使用
/cost定期检查 token 消耗 - 配置 MCP Server 连接常用外部工具
- 利用 Hooks 自动化重复性检查（lint、test）
- 使用 Git worktree + 多实例并行开发不同功能
相关资源与延伸阅读
官方资源
- Claude Code 官方文档 — 最权威的 Claude Code 使用指南，持续更新
- Claude Code Best Practices — Anthropic — 官方最佳实践文档
速查与技巧
- Claude Code 2.0 Cheatsheet — Awesome Claude — 可下载的 PDF/PNG 速查表，涵盖所有命令和快捷键
- 40+ Claude Code Tips — Awesome Claude — 从基础到高级的 40+ 实用技巧
- Claude Code Tips — GitHub (ykdojo) — 社区维护的技巧集合，包含自定义状态栏脚本等高级用法
GitHub 资源
- Awesome Claude Code — GitHub — 社区精选的 Claude Code 命令、CLAUDE.md 文件和工作流集合
- Claude Code Guide — GitHub (zebbern) — 完整的 Claude Code 优化指南，包含隐藏命令
社区
- r/ClaudeAI — Claude 用户社区，有大量 Claude Code 使用经验分享
- Awesome Claude AI — Claude 生态资源聚合站，包含 Claude Code 专区
参考来源
- Claude Code 官方文档 - Anthropic （持续更新）
- Claude Code 官方产品页 （持续更新）
- Claude Code Complete Guide 2025 - VibeRank （2025-10）
- Claude Code Cheatsheet - Awesome Claude （2025-12）
- Claude Code Pricing Guide - BrainGrid （2026-01）
- Claude Code CLI Cheatsheet - Shipyard （2026-01）
- Claude Code Best Practices - Anthropic （持续更新）
📖 返回 总览与导航 | 上一节：Prompt 版本管理 | 下一节：CLAUDE.md 编写指南