很多开发者用了 Claude Code 一段时间后，感觉「好像也没那么神奇」——写出来的代码时对时错，改着改着把不该动的文件也改了，长时间对话后回答开始偏题。问题不在工具本身，在于缺少一套正确的使用框架。
这份《Claude Code 完全新手指南》共 12 章，从最基础的安装配置讲起，深入 Agent Loop 工作原理、上下文管理策略、CLAUDE.md 项目记忆配置，再到 Subagents 专用子代理、Hooks 自动化触发器、Worktree 并行任务隔离等进阶功能，最后提供三套直接可用的实战 SOP。
第一章 认识 Claude Code
1.1 一句话理解 Claude Code
Claude Code 是 Anthropic 基于 Claude 模型打造的终端 AI 编程 Agent。它不是聊天机器人，也不是代码补全插件——它是一个可以直接操作你代码仓库的 AI 软件工程师：
- 理解整个代码库（多文件、多语言、多层依赖）
- 自主规划任务，跨文件编写和修改代码
- 执行 Shell 命令、运行测试、验证结果
- 处理 Git 工作流（commit / PR / merge conflict）
- 通过 MCP 协议连接数据库、API 等外部工具
核心认知——你的角色转变
Claude Code 最核心的变化：你的角色从「写代码」变成「描述需求 + 设定边界 + 审查结果」。
Claude 越能干，你越要注意：给清晰边界和验证标准，是用好它的关键。没有边界，它会改出你不想要的代码；没有验证标准，它不知道什么叫做对。
1.2 与 AI IDE 的核心区别
| 工具 | 本质 | 使用方式 | 最适合场景 |
|---|---|---|---|
| Claude Code | CLI Agent | 终端命令行 | Repo 级自动化、大规模重构、DevOps |
| Cursor | AI IDE | 编辑器（内联） | 逐行辅助、实时补全、单文件精细操作 |
| Windsurf | AI IDE | 编辑器（内联） | 代码上下文感知、内联建议 |
| Claude.ai | 网页版 | 浏览器 | 轻量查询、移动端、无需安装 |
两者互补，不是替代。Cursor 适合精细的逐行操作，Claude Code 适合大任务自动化。
1.3 Claude Code 能力全景
代码开发：读懂整个 repo → 按需求写代码 → 跨多文件实现功能 → 安装依赖
调试修复：复现 bug → 追踪根因 → 修改代码 → 运行测试验证
重构升级：JS→TS 迁移、框架版本升级、模块化拆分、架构调整
测试自动化：为现有代码补写单元测试、集成测试，修复失败用例
Git 工作流：生成 commit message、解决冲突、创建 PR、代码审查
文档生成：README、API 文档、CHANGELOG、架构说明
外部集成：通过 MCP 查询数据库、调用 API、控制浏览器
CI/CD 自动化：配合 GitHub Actions 做自动代码审查和流水线生成
第二章 安装与账号配置
2.1 订阅要求
Claude Code 需要付费订阅，无免费版本：
| 方案 | 说明 | 适合人群 |
|---|---|---|
| Claude Pro | claude.ai 订阅，包含 Claude Code 访问权限 | 个人开发者、初学者 |
| Claude Max | 更高用量上限 + 高峰期优先 + 新功能优先体验 | 重度日常使用者 |
| API 按量付费 | Anthropic Console 充值，按 token 计费 | 评估阶段、轻量使用 |
| Team / Enterprise | 团队协作 + 共享 CLAUDE.md + 管理后台 | 开发团队 |
新手建议：先充值约 20 美元 API 额度，用自己真实工作流评估 1-2 周，再决定是否订阅 Max。
登录地址：claude.com 或 console.anthropic.com
2.2 系统要求
- 操作系统：macOS 12+、Linux（Ubuntu 20.04+ / Debian 10+）、Windows 原生或 WSL2
- 网络：需要互联网连接（模型调用为云端 API）
- 强烈建议：项目目录是 Git 仓库（Claude Code 深度集成 Git 工作流）
- 可选：安装 gh CLI（
brew install gh），让 Claude 直接创建 issue、开 PR、读 PR 评论
2.3 安装方法
macOS / Linux / WSL（推荐）
# 官方安装脚本——无需 Node.js，安装后自动后台更新
curl -fsSL https://claude.ai/install.sh | bash
# 验证安装
claude --version
# Homebrew 安装（需手动升级）
brew install --cask claude-code
brew upgrade --cask claude-code
Windows
# 方式一：PowerShell 一键安装（推荐）
irm https://claude.ai/install.ps1 | iex
# 方式二：WinGet（需手动升级）
winget install Anthropic.ClaudeCode
winget upgrade Anthropic.ClaudeCode
IDE 插件集成
- VS Code：扩展市场搜索「Claude Code」安装，支持 @ 引用文件（含行号范围）、内联 Diff、多标签并行对话
- JetBrains（IDEA / PyCharm / WebStorm）：JetBrains Marketplace 安装，启动快捷键 Cmd+Esc (Mac) / Ctrl+Esc (Windows)，支持可视化 diff
2.4 首次登录
cd ~/your-project
claude # 首次启动，弹出浏览器授权
claude /doctor # 运行诊断，确认一切正常
完成 OAuth 授权后凭证本地保存，后续无需重复登录。
第三章 核心概念
3.1 Agent Loop（代理循环）
Claude Code 采用循环代理模式——不是一问一答，而是持续执行直到任务完成：
- 收集上下文：读取相关文件、搜索代码、运行命令了解现状
- 规划任务：分析要做什么、按什么顺序、影响哪些文件
- 执行操作：编辑文件、执行 Shell 命令、调用 MCP 工具
- 验证结果：运行测试、检查错误、对比预期行为
- 自我纠正：验证失败则分析原因，重新执行
循环重复，直到任务完成或你按 Ctrl+C 中断。
3.2 上下文是有限资源
这是使用 Claude Code 最重要的认知之一。上下文窗口（约 20 万 token）会消耗你说的每一句话、Claude 读取的每个文件、每个命令的输出，以及压缩后的历史摘要。上下文一旦过长，Claude 就会开始「遗忘」前面的指令，输出质量明显下降。
| 命令 | 作用 | 何时使用 |
|---|---|---|
| /clear | 清空全部对话历史 | 切换任务前（必须养成习惯） |
| /compact [说明] | 智能压缩历史，保留摘要 | 上下文超过 70% 时 |
| /context | 可视化显示上下文使用比例 | 长时间工作时随时检查 |
| /cost | 查看当前会话 token 用量 | 了解成本，优化使用习惯 |
重要原则：同一个问题修正超过两次，直接 /clear 用更精确的提示重新开始。新会话 + 好提示 > 长会话 + 累积修正。
3.3 三种权限模式
| 模式 | 触发方式 | 行为 | 适用场景 |
|---|---|---|---|
| Normal Mode（默认） | 默认启动 | 重大操作前弹窗请求批准 | 日常开发任务 |
| Plan Mode | Shift+Tab 两次 / /plan | 只读分析，不执行任何修改 | 复杂任务先分析再执行 |
| Auto-Accept | –dangerously-skip-permissions | 自动批准所有操作 | CI/CD 等完全自动化场景 |
3.4 模型选择策略
| 模型 | 定位 | 适用场景 | 切换命令 |
|---|---|---|---|
| Claude Sonnet 4.6 | 默认，综合最优 | 80% 日常编码任务 | 无需切换 |
| Claude Opus 4.6 | 最强推理能力 | ���杂架构设计、难以定位的 bug | claude –model opus |
| Claude Haiku | 最快，最省费用 | 简单查询、预算受限场景 | claude –model haiku |
第四章 快速入门——30 分钟第一个任务
4.1 启动与基本对话
cd ~/my-project # 进入真实项目目录
claude # 启动
然后可以问：
这个项目是做什么的？给我结构概览和技术栈总结。
4.2 四种基础输入方式
- 自然语言：帮我在 src/utils.js 添加一个格式化日期的函数
- @ 文件引用：
@src/api/users.js 这里的分页逻辑有 bug - ! Shell 执行：
!git status 然后告诉我有哪些未提交的改动 - 粘贴错误：直接粘贴终端报错，Claude 分析根因
4.3 第一个完整任务示例
mkdir todo-api && cd todo-api && git init
claude
用 Node.js + Express 创建一个 Todo REST API，包含增删改查接口、参数验证和错误处理。先告诉我你的实现计划，等我确认后再写代码。
方案可以，开始实现，做完跑测试。
为所有接口写 Jest 单元测试，先写失败测试，测试能正确运行后再修复让测试通过。
第五章 CLAUDE.md——给 Claude 持久记忆
5.1 什么是 CLAUDE.md？
CLAUDE.md 是 Claude Code 每次启动时自动读取的配置文件，让 Claude 始终了解你的规范。
| 文件位置 | 作用范围 |
|---|---|
| 项目根目录/CLAUDE.md | 当前项目，提交到 git |
| .claude/CLAUDE.md | 当前项目（更整洁） |
| CLAUDE.local.md | 当前项目，不提交 |
| ~/.claude/CLAUDE.md | 全局，所有项目 |
5.2 快速创建
claude
> /init # 生成后手动补充你最重要的规范
5.3 专业 CLAUDE.md 模板
# 项目名称 - Claude 工作指南
## 项目概述
一句话描述项目用途和边界。
## 技术栈
- 后端：Spring Boot 3.x, Java 17, MyBatis Plus
- 前端：React 18, TypeScript, Ant Design
- 数据库：MySQL 8.0
## 常用命令
- 启动后端：./gradlew bootRun
- 启动前端：cd frontend && pnpm dev
- 跑单个测试：./gradlew test --tests 'UserServiceTest'
## 代码规范
- 所有 API 返回用 Result 统一包装
- Service 层只包含业务逻辑，不直接操作数据库
- 禁止在 Controller 层写业务逻辑
## 禁止事项
- IMPORTANT: 不要修改 prisma/migrations/ 下的文件
- IMPORTANT: 所有数据库改动通过 Flyway Migration 文件
第六章 完整命令速查手册
6.1 启动参数
| 命令 | 说明 |
|---|---|
| claude | 默认启动（交互模式） |
| claude –model opus | 启动时指定模型 |
| claude –permission-mode plan | 以 Plan Mode 启动 |
| claude –worktree feature-xxx | 在隔离 Worktree 中启动 |
| claude –continue | 继续最近一次对话 |
| claude –dangerously-skip-permissions | 跳过所有权限检查 |
6.2 Headless 模式（非交互）
claude -p "解释项目结构" # 单次查询后退出
claude -p "列出所有 API 接口" --output-format json
cat error.log | claude -p "分析这个错误的根因"
git diff HEAD | claude -p "审查这次改动有无安全隐患"
6.3 会话内命令
| 命令 | 说明 |
|---|---|
| /clear | 清空对话历史 |
| /compact | 压缩对话 |
| /context | 查看上下文使用比例 |
| /cost | 查看 token 用量 |
| /model | 切换模型 |
| /config | 打开设置界面 |
| /doctor | 运行健康检查 |
| /init | 生成 CLAUDE.md 模板 |
| /exit | 退出 |
6.4 键盘快捷键
| 快捷键 | 功能 |
|---|---|
| Shift + Tab（两次） | 进入 Plan Mode |
| Ctrl + C | 中断当前操作 |
| Ctrl + G | 用系统编辑器编写多行提示词 |
| Ctrl + B | 将任务切到后台 |
| Esc | 中断当前操作 |
| ↑ / ↓ | 浏览历史输入记录 |
第七章 进阶技巧
7.1 Plan Mode 的正确姿势
- 按 Shift+Tab 两次进入 Plan Mode
- 描述你要做的事，让 Claude 分析影响面和执行步骤
- 仔细审查输出的规划，可以继续追问
- 确认无误后，按 Shift+Tab 切回 Normal Mode 执行
探索 → 规划 → 执行 三步法
Step 1：分析现有实现，给我一个方案
Step 2：方案可以，开始实现
Step 3：Claude 执行，完成后跑测试验证
7.2 黄金提示词公式
【目标】+【位置】+【验证】+【约束】
好的示例：
为 @src/api/users.ts 中的 getUserById 函数添加 Redis 缓存，缓存有效期 5 分钟，使用现有的 @src/lib/redis.ts 客户端。实现后运行 pnpm test 确保所有测试通过，禁止修改函数签名和返回类型。
7.3 描述症状，不是猜测原因
差的问法：修复登录 bug
好的问法：
用户反馈会话超时后登录失败。检查 @src/auth/ 下的认证流程，特别是 token 刷新逻辑。先写失败测试复现，再修复，修完跑测试验证。
7.4 MCP 服务器集成
# 添加 MCP 服务器
claude mcp add context7 npx @context7/mcp
claude mcp add playwright npx '@playwright/mcp@latest'
claude mcp add github npx @github/mcp
# 查看已添加的服务器
claude mcp list
第八章 Subagents——独立上下文的专用助手
8.1 什么是 Subagent？
Subagent 是在独立上下文窗口里运行的专用 AI 助手，有自定义的系统提示和工具权限限制。
核心价值：
- 隔离大量输出——测试报告不会污染主会话上下文
- 强制工具限制——只读代理无法写文件，安全可控
- 并行探索——多个 Subagent 同时在不同模块并行调查
8.2 创建自定义 Subagent
mkdir -p .claude/agents
创建 .claude/agents/code-reviewer.md：
---
name: code-reviewer
description: 代码审查专家。代码修改后主动使用。
tools: Read, Grep, Glob, Bash
model: inherit
---
你是资深代码审查专家。
调用时：
1. 运行 git diff 查看最近变更
2. 聚焦修改的文件立即开始审查
按优先级组织反馈：
- [严重] 必须修复，存在 bug 或安全漏洞
- [警告] 应该修复
- [建议] 可考虑改进
第九章 Hooks——自动化触发器
9.1 什么是 Hooks？
Hooks 是在特定事件发生时自动执行的 Shell 命令，让 Claude Code 的操作触发外部自动化行为。
9.2 实用 Hooks 配置示例
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "npm run lint -- --fix --quiet",
"timeout": 30000
}
]
}
]
}
}
第十章 Worktree——并行任务隔离
10.1 什么是 Worktree？
Worktree 基于 Git 的 worktree 功能，让你在独立的目录中对同一仓库的不同分支并行工作。
10.2 基本用法
# 在隔离 Worktree 中启动
claude --worktree feature-auth
# 同时在两个终端运行
claude --worktree feature-user-export
claude --worktree bugfix-login-timeout
10.3 Writer / Reviewer 双会话模式
# 终端 1：实现会话
claude --worktree feature-payment
> 实现支付模块，完成后告诉我
# 终端 2：审查会话（全新上下文）
claude
> 审查 @src/payment/ 下最近一次 git commit 的改动，重点检查：边界情况、安全隐患、与现有代码风格一致性。
第十一章 实战 SOP
11.1 SOP A：老项目重构
| 阶段 | 目标 | 关键操作 |
|---|---|---|
| Phase 0 | 摸底 | Plan Mode + Subagent 扫描，生成技术债报告 |
| Phase 1 | 安全网 | 先补测试，固定现有行为 |
| Phase 2 | 规划 | Plan Mode 生成重构清单，人工审核 |
| Phase 3 | 执行 | Worktree 隔离，每步验证 |
| Phase 4 | 收尾 | 全量对比验证，创建 PR |
11.2 SOP B：快速需求迭代
| 阶段 | 目标 | 时间估计 |
|---|---|---|
| Phase 0 | 需求规格化 | 5-10 分钟 |
| Phase 1 | 影响面评估 | 5 分钟 |
| Phase 2 | 并行开发 | 并行节省 30-50% |
| Phase 3 | 互审 | 15 分钟 |
| Phase 4 | 交付 | 10 分钟 |
11.3 SOP C：全新项目研发
| 阶段 | 目标 | 关键操作 |
|---|---|---|
| Phase 0 | 架构决策 | ADR 文档化 |
| Phase 1 | 项目初始化 | CLAUDE.md + Subagents + Hooks 一次配齐 |
| Phase 2 | 骨架生成 | Plan Mode 确认后生成 |
| Phase 3 | 迭代开发 | SPEC → Plan → Code → Verify → Commit |
| Phase 4 | CI/CD 接入 | GitHub Actions + Claude PR 审查 |
第十二章 常见错误与避坑指南
12.1 使用习惯类错误
❌ 不清空上下文就切换任务
解决：每次切换任务前执行 /clear，养成习惯。
❌ 提示词太模糊
解决：使用黄金提示词公式：目标 + 文件位置 + 验证标准 + 约束条件。
❌ 不先规划就执行大改动
解决：改动超过 3 个文件，先用 Plan Mode 看清楚规划后再执行。
❌ 完全信任 AI 不审查输出
解决：AI 生成的代码必须经过人工审查，重点看边界条件、错误处理、权限检查。
12.2 技术配置类错误
❌ CLAUDE.md 写太长
解决：精简 CLAUDE.md，只留「Claude 最容易弄错的事」。
❌ Claude 读了太多不必要的文件
解决：用 @ 精确引用文件而非整个目录。
附录
A. 完整斜杠命令速查
| 命令 | 说明 |
|---|---|
| /clear | 清空对话历史 |
| /compact | 压缩对话 |
| /context | 查看上下文使用比例 |
| /cost | 查看 token 用量 |
| /export | 导出当前对话 |
| /model | 切换模型 |
| /config | 打开设置 |
| /permissions | 管理工具权限 |
| /doctor | 健康检查 |
| /init | 生成 CLAUDE.md 模板 |
| /memory | 查看自动记忆 |
| /hooks | 查看 Hooks 配置 |
| /mcp | 管理 MCP 服务器 |
| /agents | 管理 Subagents |
| /exit | 退出 |
B. 推荐 .claude/ 目录结构
.claude/
├── settings.json # 权限 + Hooks 配置
├── CLAUDE.md # 项目级记忆
├── agents/ # 自定义 Subagents
│ ├── code-reviewer.md
│ └── debugger.md
├── skills/ # 按需加载的知识片段
└── specs/ # 功能需求规格
C. 官方资源
- 完整文档：code.claude.com/docs
- Anthropic Console：console.anthropic.com
- 社区资源：github.com/anthropics/awesome-claude-code
总结
Claude Code 的本质：一个可以直接操作代码仓库的 AI 软件工程师。
打开终端，输入 claude，开始你的第一个任务 🚀