EP01. “Claude Code 是什么与新手上手”
🔒 登录后可标记已读- Claude Code 是 Anthropic 出的 AI 编程助手，这篇笔记讲它是什么、能在哪些地方跑、怎么安装、怎么开始第一次对话
- 讲
CLAUDE.md这个项目说明文件怎么写——这是让 Claude 理解你的代码库最关键的一步 - 讲清楚 Claude Code 的核心四阶段工作流程（Explore → Plan → Implement → Verify），理解这个循环是用好这个工具的关键
- 前置知识：会用终端机（Terminal）基本操作会比较顺手，但不是必需——不熟悉终端的话可以直接用 Desktop App
重点内容
Claude Code 是什么
Claude Code 跑在 Claude 最新的模型上——Opus 4.8、Sonnet 4.6，顶级档位是 Fable 5，支持最高 100 万 token 的上下文窗口，意味着能把整个代码库一次性记在"脑子"里。默认用哪个模型看你的订阅方案（Pro/Team 用 Sonnet 4.6，Max 用 Opus 4.8），可以随时用 /model 切换。
这不是玩具级工具——2026 年 2 月 Pragmatic Engineer 针对 15,000 名开发者的调查显示，Claude Code 拿到 46% 的「最受喜爱」评分，是所有 AI 编程工具里最高的；约 42.8% 的开发者在用 Claude 系列模型；73% 的工程团队每天都在用 AI 编程工具（2025 年是 41%，2024 年只有 18%）；每天有 2900 万次安装；70% 的财富 100 强企业在用。
Claude Code 可以在哪里跑
同一个引擎，四种使用界面，各有适合的场景：
| 界面 | 特点 |
|---|---|
| Terminal CLI | 最原始也最完整的版本，hooks、后台 agent、MCP、排程任务都只有这里才有 |
| Desktop App（Mac/Windows） | 同一个引擎配 GUI，有并排视觉diff、方便开多个并行会话、有 Routines 排程面板 |
| Web（claude.ai/code） | 跑在云端，不用装任何东西，适合临时任务或用别人的电脑 |
| VS Code / JetBrains 插件 | 行内 diff + 编辑器上下文（@提及、选取内容），JetBrains 版需要额外装 CLI |
📌 新手建议：习惯用终端机就装 CLI；不习惯就先用 Desktop App 入门。之后可以随时切换用哪个界面——它们共用同一个账号和项目的 CLAUDE.md。
安装方式（三选一）
原生安装器（推荐）——会自动更新，不需要装 Node：
# macOS / Linux
curl -fsSL https://claude.ai/install.sh | bash# Windows (PowerShell)
irm https://claude.ai/install.ps1 | iexnpm——如果你本来就在用 Node：
npm install -g @anthropic-ai/claude-codeDesktop App / Web——去 claude.com 下载 Mac/Windows 版 App，或直接开浏览器进 claude.ai/code，不用装任何东西。
装完用 claude --version 确认安装成功——有些新功能（比如 Fable 5 模型、Routines）需要比较新的版本，版本太旧记得更新。
Windows 安装踩坑：终端机找不到 claude 命令
用 npm 装完之后，Windows 上常见两个坑，跟 PATH（系统用来找命令的路径清单）有关：
坑一：装完直接输入 claude 报错 not recognized
原因是安装路径 C:\Users\你的用户名\.local\bin 没有加进系统 PATH。两种修法（择一）：
- 图形界面：
Win + S搜索「环境变量」→「编辑系统环境变量」→ 右下角「环境变量」→ 用户变量找到 Path → 编辑 → 新建，填入C:\Users\你的用户名\.local\bin→ 一路确定。
[截图：Windows「编辑环境变量」窗口，Path 列表里新增了 .local\bin 这一行]
- PowerShell 命令（效果一样，图形界面嫌麻烦可以用这个）：
[Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";C:\Users\你的用户名\.local\bin", "User")改完必须重开终端机才会生效，重开后跑 claude --version 确认能显示版本号。
坑二：系统 PowerShell 能用，VS Code 内建终端却不行
VS Code 的内建终端是独立的 PowerShell 实例，PATH 更新不会自动同步进去。修法（任选一个）：
Ctrl + Shift + P→ 输入Restart Terminal执行- 直接关掉终端面板重开（`
Ctrl +``） - 或者在 VS Code 终端里临时加一次 PATH：
$env:PATH += ";C:\Users\你的用户名\.local\bin"，再跑claude --version
📌 用户名里有空格（例如 Tan Shi Bin）是正常情况，路径照写不用额外加引号处理，PowerShell 环境变量这里不受影响。
登录验证
两种方式二选一：
- API key：把 Anthropic API key 设成环境变量
export ANTHROPIC_API_KEY=your-key-here - Max 订阅：有 Claude Max 方案的话，Claude Code 会透过账号自动验证登录
第一次使用
打开终端机，进到任何一个项目目录，输入：
claude就这样。Claude 会读取项目结构、判断用的技术栈，准备好开始帮你。可以先试试简单的指令，例如：
> Explain the architecture of this project
（解释一下这个项目的架构）
Claude 会扫描文件、识别用了哪些框架，给出一个结构化的项目概览。
[截图：终端机窗口，运行 claude 后 Claude 回复的项目结构分析结果]
CLAUDE.md 文件：最重要的第一步
在项目根目录建一个 CLAUDE.md 文件，写清楚这个代码库专属的说明——这是所有设置里最重要的一步。示范内容：
# CLAUDE.md
## Project Overview
E-commerce platform built with Next.js 16 and TypeScript.
## Commands
- npm run dev — Development server
- npm run build — Production build
- npm run test — Run test suite
## Architecture
- App Router with server components
- Prisma ORM with PostgreSQL
- Stripe for payments
## Conventions
- Use server components by default
- All API routes return typed responses
- Tests required for business logicClaude 每次在这个项目里开新会话，都会先读这份文件。可以把它想成是给你的 AI 同事写的入职文档——项目演进时要记得同步更新它，每次会话都能因此受益。
核心工作流程：Explore → Plan → Implement → Verify
Claude Code 遵循一个四阶段循环，这个循环模仿的是资深工程师自然的工作方式——理解这个循环是用好这个工具的关键。
阶段一：Explore（探索）
交代任务后，Claude 会先读代码库里相关的部分——检查文件结构、读 import、追踪函数调用，建立一个"事情怎么串起来"的心智模型。
> The checkout page is throwing a hydration error
（结账页面出现 hydration 报错）
Claude 会先读结账组件、它的父层 layout、数据抓取逻辑、共享状态——都读完才会开始建议怎么修。
阶段二：Plan（规划）
写代码之前，Claude 会先提出一个做法——这是你能介入把关的地方。方案不对就直接说，方案没问题就确认放行。
📌 复杂任务建议先切到 Plan Mode：按 Shift+Tab 循环切换权限模式（default 逐项询问 → auto-accept-edits 自动接受修改 → plan 规划模式）。Plan Mode 底下 Claude 只会读代码、提出方案，在你批准之前不会动任何一个文件——这是处理不简单的任务时最好的习惯：在写代码之前就抓到错误的方向，而不是写完了才发现不对。
阶段三：Implement（实作）
Claude 写代码，每个改动都会呈现出来给你看——一个文件一个文件、一个 diff 一个 diff，你可以批准、拒绝、或要求修改。这不是自动补全，Claude 写的是完整、可上生产环境的代码，同时会遵守你项目原有的规范和写法习惯。
[截图：终端机里逐文件呈现的 diff 画面，红绿对照显示改动前后的代码]
阶段四：Verify（验证）
实作完成后，Claude 会跑你的构建工具、linter、测试来确认一切正常：
Claude: Changes complete. Running verification:
npm run lint ✓ (no warnings)
npm run build ✓ (compiled successfully)
npm run test ✓ (47 tests passed)
如果有东西坏了，Claude 会自己找出问题并修好，不用你介入。
适用版本
内容对应 2026 年版本的 Claude Code（Opus 4.8 / Sonnet 4.6 / Fable 5 模型体系），部分功能（Fable 5 模型、Routines 排程）需要较新版本才有，装好后记得跑 claude --version 确认。
常见错误
- ❌ 跳过 CLAUDE.md 这一步直接开工——没有项目说明文件，Claude 对代码库的理解会打折扣，写出来的代码风格也容易跟项目习惯对不上
- ❌ 复杂任务直接让 Claude 动手写代码，不用 Plan Mode 先过一遍方案——等代码都写完才发现方向不对，返工成本高很多
- ❌ 装完之后没确认版本——旧版本可能用不了 Fable 5 模型或 Routines 这类新功能
- ❌ Windows 上用 npm 装完就直接输入
claude，不知道要重开终端机——PATH 更新后一定要重开终端机（VS Code 内建终端和系统终端要分别重开）才会生效 - 💡 CLAUDE.md 不是写一次就不管了，项目换了数据库、换了框架、定了新的团队规范，都要记得回来同步更新这份文件
Sources
Blog / Website：
- Claude Code Tutorial（Beginners Guide 2026）— https://www.techlifeadventures.com/post/claude-code-tutorial-beginners-guide-2026