Claude Code 上手实战：从安装到用 AI 完成一个真实开发任务

简介与适用场景

Claude Code 是 Anthropic 推出的智能体式（agentic）编程工具，运行在你的终端里。它不是简单的代码补全，而是一个能读你的项目、跑命令、改文件、跑测试、提交 Git 的 AI 协作者。除了终端 CLI，它还有桌面 App，以及 VS Code、JetBrains（含 Cursor）插件、Slack、Web 版和 GitHub Actions / GitLab CI 集成。

典型适用场景：

  • 快速理解陌生代码库（“这个项目是干什么的？入口在哪？”）
  • 实现新功能、修 Bug、写测试、重构
  • 让 AI 按你的自然语言描述完成多步骤任务
  • 结合 MCP 直连 Jira、GitHub、数据库、Figma 等外部工具

截至 2026 年，Claude Code 默认使用带 100 万上下文的 Claude Sonnet 5 模型。

安装与前置条件

系统要求：macOS 13.0+ / Windows 10 1809+ / Ubuntu 20.04+ / Debian 10+ / Alpine 3.19+；4 GB+ 内存；Bash、Zsh、PowerShell 或 CMD；需联网。

推荐用官方原生安装脚本（自动后台更新）：

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

其他方式：

# macOS Homebrew（需手动升级）
brew install --cask claude-code

# Windows WinGet
winget install Anthropic.ClaudeCode

# npm（需 Node.js 22+，切勿加 sudo）
npm install -g @anthropic-ai/claude-code

验证安装：

claude --version
claude doctor   # 检查安装与配置

登录与计费：Claude Code 需要 Pro、Max、Team、Enterprise 订阅或 Claude Console（API 预付费）账号，免费版不支持。首次运行 claude 会自动打开浏览器登录，之后用 /login 可切换账号。

  • Pro：20 美元/月，与网页版共享用量额度
  • Max 5x：100 美元/月；Max 20x：200 美元/月（用量更高）
  • 订阅额度用完后，可选择性开启按标准 API 费率计费（需你显式同意，不会自动扣费）

详细分步：跑通第一个真实任务

1. 进入项目并启动

cd /path/to/your/project
claude

2. 生成项目记忆文件：在会话里输入 /init。Claude 会分析代码库，自动生成一个 CLAUDE.md，写入构建命令、测试方式、目录约定等。若已存在则给出改进建议而非覆盖。

3. 先让它理解代码库（只读，不改文件）：

what does this project do?
where is the main entry point?

4. 用计划模式规划复杂任务：按 Shift+Tab 循环切换权限模式，切到 Plan Mode（计划模式）。此模式下 Claude 只读文件、跑只读命令来探索并给出方案，不会改动源码。确认方案后再切回执行。

5. 让它动手改代码：

给用户注册表单加上输入校验，空表单不允许提交

Claude 会：定位文件 → 展示 diff → 请求你批准 → 应用修改 → 有测试就跑测试。默认每次修改文件前都会弹权限确认。

6. 审阅 diff 与权限模式：修改前会以 diff 形式展示。权限模式（Shift+Tab 切换）包括：

  • default（手动）：每类工具首次使用时询问
  • acceptEdits：自动接受文件编辑和 mkdir/mv/cp 等常见命令
  • plan：计划模式，只读探索
  • bypassPermissions：跳过大部分确认（仅建议在容器/虚拟机等隔离环境用）

用 /permissions 可查看和管理精细化规则（allow / ask / deny，deny 优先级最高）。

7. 用 Git 收尾：

what files have I changed?
commit my changes with a descriptive message

核心概念

  • CLAUDE.md（项目记忆）：每次会话开始时加载的 Markdown 指令文件，用于写死构建/测试命令、编码规范、架构约定。支持多层级：用户级 ~/.claude/CLAUDE.md、项目级 ./CLAUDE.md 或 ./.claude/CLAUDE.md、本地私有 ./CLAUDE.local.md（记得 gitignore）。建议控制在 200 行内，越具体越容易被遵守。可用 @path/to/file 语法导入其他文件。
  • 上下文管理：每个会话从空白上下文开始。/clear 清空历史开启新任务（老手公认最省 token 的操作），/compact 压缩上下文，/context 查看占用。此外还有 Auto memory（自动记忆），Claude 会根据你的纠正把经验存到 ~/.claude/projects/<project>/memory/。
  • MCP（模型上下文协议）：连接外部工具的开放标准。用 claude mcp add 添加服务器，/mcp 面板管理与 OAuth 授权。三种传输：
    # 远程 HTTP（推荐）
claude mcp add --transport http notion https://mcp.notion.com/mcp
# 本地 stdio 进程
claude mcp add --env KEY=val --transport stdio airtable -- npx server
  • Subagents（子代理）：拥有独立上下文窗口的专用助手，适合探索/审查等会污染主对话的任务。定义文件放在 .claude/agents/（项目级）或 ~/.claude/agents/（全局），用 YAML frontmatter 配置：
    ---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
你是一个严格的代码审查者……
    内置 Explore（只读探索）、Plan（规划）、general-purpose 等类型。
  • Hooks（钩子）：在生命周期特定节点自动执行的 shell 命令/HTTP/提示，配置在 settings.json。常见事件：PreToolUse（工具调用前，可阻止或改参数）、PostToolUse（调用后）、Stop（回答结束时）。适合“必须每次执行”的规则，如提交前强制跑 lint——比写在 CLAUDE.md 里更可靠。
  • 计划模式：见上文第 4 步，先规划后执行，避免 AI 在没想清楚时乱改。

进阶技巧与最佳实践

  1. 让它先探索再动手：复杂任务先在计划模式让它读代码、出方案，你审阅后再执行，质量显著更高。
  2. 勤用 /clear：切换到不相关的新任务时清空上下文，既省 token 又减少干扰。
  3. 持续养 CLAUDE.md：当 Claude 第二次犯同样错误、或你重复输入同一条纠正时，就把它写进 CLAUDE.md。用 .claude/rules/ 按文件路径（paths frontmatter）作用域化，减少上下文占用。
  4. 需求要具体、分步：与其“修 bug”，不如“修登录 bug：输错密码后页面空白”。复杂任务拆成 1/2/3 步列出。
  5. 用 Hooks 做硬约束：CLAUDE.md 只是“引导”不是“强制”，真正必须执行的（保护文件、提交前检查）用 PreToolUse 钩子。
  6. 善用快捷键：Shift+Tab 切权限模式、/ 看全部命令与技能、Tab 补全、↑ 翻历史。

常见问题 FAQ

Q：Claude 不遵守我的 CLAUDE.md 怎么办？ A：先用 /memory 确认文件被加载；把指令写得更具体（“用 2 空格缩进”优于“格式化好代码”）；检查多个 CLAUDE.md 是否有冲突指令；必须强制的改用 Hook。

Q：订阅和 API 计费什么关系？ A：Pro/Max 订阅与网页版共享用量额度；额度耗尽后可选择性启用 API 按量计费（标准费率，需显式同意）。Console 账号则纯走 API 预付费。

Q：命令找不到 / 装完跑不了？ A：运行 claude doctor 诊断；npm 安装别用 sudo；Windows 建议装 Git for Windows 以启用 Bash 工具。

Q：怎么恢复上次会话？ A：claude -c 继续当前目录最近会话，claude -r 或会话内 /resume 选择历史会话。

实用示例

示例一：非交互式一次性任务（适合脚本 / CI）

claude -p "解释 src/auth.ts 里的鉴权逻辑"   # 跑完即退出
claude "fix the build error"                # 一次性任务

示例二：MCP + 子代理完成一个真实工单

# 1. 接入 GitHub MCP
claude mcp add --transport http github https://api.githubcopilot.com/mcp

然后在会话里：

1. 用 Explore 子代理找出订单模块相关代码
2. 按 ENG-4521 描述实现功能
3. 跑测试，通过后创建一个 PR

Claude 会调用只读子代理探索（不污染主上下文），实现功能，跑测试，再通过 MCP 在 GitHub 上开 PR——全程你只需在关键 diff 处审阅批准。