Claude Code 完全新手指南（2026版）

很多开发者使用 Claude Code 一段时间后，发现它写出的代码时对时错，改着改着把不该动的文件也改了，长时间对话后回答开始偏题。问题不在工具本身，而在于缺少一套正确的使用框架。本文基于 2026 年最新版本，系统讲解 Claude Code 的安装配置、核心原理、上下文管理、CLAUDE.md 项目记忆、Subagents 子代理、Hooks 触发器、Worktree 并行隔离，并给出三套可直接套用的实战 SOP，帮助开发者从入门到精通。

第一章 认识 Claude Code

1.1 一句话理解

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 网页版	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 额度，用自己的真实工作流评估一两周，再决定是否订阅 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

JetBrains 注意事项：若 Esc 无法中断操作，进入 Settings → Tools → Terminal，取消勾选「Move focus to the editor with Escape」。远程开发时，插件需装在远程主机上而非本地客户端。

2.4 首次登录

cd ~/your-project
claude   # 首次启动，弹出浏览器授权
claude /doctor  # 运行诊断，确认一切正常

完成 OAuth 授权后，凭证会保存在本地，后续无需重复登录。

第三章 核心概念

3.1 Agent Loop（代理循环）

Claude Code 采用循环代理模式，不是一问一答，而是持续执行直到任务完成。循环步骤为：

1. 收集上下文：读取相关文件、搜索代码、运行命令了解现状
2. 规划任务：分析要做什么、按什么顺序、影响哪些文件
3. 执行操作：编辑文件、执行 Shell 命令、调用 MCP 工具
4. 验证结果：运行测试、检查错误、对比预期行为
5. 自我纠正：验证失败则分析原因，重新执行步骤 3、4

循环重复，直到任务完成或你按 Ctrl+C 中断。你可以在任何时刻暂停并重新引导方向。

3.2 上下文是有限资源

上下文窗口（约 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 等完全自动化场景

权限白名单配置：

// .claude/settings.json
{
  "permissions": {
    "allow": [
      "Bash(git:*)",
      "Bash(pnpm:*)",
      "Bash(./gradlew:*)"
    ]
  }
}

3.4 模型选择策略

模型	定位	适用场景	切换命令
Claude Sonnet 4.6	默认，综合最优	80% 日常编码任务	无需切换

其他模型（如 Opus、Haiku）可按任务复杂度选择，具体可通过 /model 命令切换。

第四章 快速入门

用 30 分钟完成第一个真实任务。典型流程：

1. 在项目目录启动 claude
2. 用一句完整的话描述需求，指定输入输出和约束
3. 允许 Claude 进入 Plan Mode 先给出计划
4. 审查计划后退出 Plan Mode，让它执行
5. 在关键节点暂停，验证中间结果
6. 完成后用 git diff 审查改动

不要一开始就让 Claude 做大型重构，先从小功能练起，熟悉它的节奏和边界。

第五章 CLAUDE.md——项目记忆配置

CLAUDE.md 是 Claude Code 的项目记忆文件，放在仓库根目录或 ~/.claude/CLAUDE.md 中。它让 Claude 记住项目规范、架构决策、命令约定等。建议包含：

• 项目简介与核心技术栈
• 代码风格与目录结构约定
• 常用命令（构建、测试、格式化）
• 需要避免的陷阱或已知问题

CLAUDE.md 是控制 Claude 行为最有效的杠杆之一。把规范写清楚，Claude 就能少犯错。

第六章 完整命令速查

常用斜杠命令：

• /help：查看帮助
• /status：查看当前任务状态
• /model：切换模型
• /compact：压缩上下文
• /clear：清空会话
• /context：查看上下文使用率
• /cost：查看 API 消耗
• /doctor：诊断安装问题
• /agents：管理 Subagents

常用快捷键：

• Ctrl+C 中断当前操作
• Shift+Tab 切换 Plan Mode
• Esc 取消当前输入（JetBrains 需要注意设置）

第七章 进阶技巧

7.1 Plan Mode 的正确用法

复杂任务先进入 Plan Mode，让 Claude 输出执行计划。你审阅计划、提出修改，确认后再执行。这能大幅减少返工。

7.2 提示词公式

一个有效的提示词包含四要素：

• 角色：你是一个熟悉 X 框架的资深工程师
• 任务：我要做 Y，具体内容是...
• 约束：不要修改 Z 文件，代码风格遵循...
• 验证：完成后运行 npm test，确保全部通过

7.3 MCP 集成

MCP（Model Context Protocol）让 Claude Code 可以连接数据库、API、浏览器等外部工具。配置 MCP server 后，Claude 可以直接查询数据、调用服务、操作页面。

第八章 Subagents——专用子代理

Subagents 是拥有独立上下文的专用 AI 助手。你可以定义不同的 subagent 来处理特定任务，例如：

• 代码审查员：只负责 review 代码，不受主对话上下文影响
• 测试生成器：专门编写测试用例
• 文档撰写员：负责生成文档

每个 subagent 有独立的 system prompt 和上下文预算，适合将大任务拆解给多个专家并行或轮流处理。

第九章 Hooks——自动化触发器

Hooks 能在特定事件发生时自动执行命令或脚本。例如：

• 在 Claude 修改文件前，自动运行 lint 检查
• 在任务完成后，自动运行测试并通知
• 在对话开始时，加载特定上下文

Hooks 用配置文件声明，支持 PreToolUse、PostToolUse、Stop 等事件。

第十章 Worktree——并行任务隔离工作区

Worktree 是 Git 的一个功能，Claude Code 可以利用它创建多个并行工作区。每个任务在独立的分支和工作目录中进行，互不干扰。适合：

• 同时进行多个功能开发
• 让不同 subagent 并行工作
• 保持主分支稳定，测试通过后再合并

第十一章 实战 SOP

11.1 老项目重构 SOP

1. 创建新的 git 分支
2. 使用 Plan Mode 分析现状，列出改动清单
3. 分批小步重构，每步跑通测试
4. 每次提交保持可运行状态
5. 全部完成后 review diff，再合并主分支

11.2 快速迭代新需求 SOP

1. 将一句话需求写成可执行的规格说明
2. 用 Plan Mode 拆解任务列表
3. 创建子代理并行开发独立模块
4. 集成测试，修复问题
5. 生成 changelog 与 commit message

11.3 新项目研发 SOP

1. 先用 Claude 讨论架构决策（技术栈、目录结构、数据库设计）
2. 生成初始骨架代码
3. 逐步实现核心功能
4. 接入 CI/CD 流水线（GitHub Actions 等）
5. 配置 CLAUDE.md 保证后续开发一致性

第十二章 常见错误与避坑指南

• 不设边界：让 Claude 随意改文件，导致改动失控
• 长会话不清理：上下文超载后质量下降
• 跳过 Plan Mode：直接让 Claude 写复杂代码，返工率高
• 忽略测试：没有验证标准，Claude 不知道什么是对
• 一次任务太大：应拆分成可验证的小步骤

正确做法是：每次新任务 /clear，用带约束的提示词，先 Plan 再执行，小步验证，使用 CLAUDE.md 固化规范。

附录：速查卡与专业配置

将常用命令、CLAUDE.md 模板、Hooks 示例整理成速查卡，放在手边。专业级配置可以参考 .claude/settings.json 的完整权限、hooks、model 配置示例。

---

以上即是 Claude Code 从入门到精通的完整路径。核心原则是：把它当作团队里的工程师，而不是一个自动补全器；给足背景与约束，让它按你的标准和流程工作。