Codex / Claude Code · 小白

Claude Code 小白教学：更新新版本后先学哪些新特性

面向第一次使用 Claude Code 的小白，讲清安装、更新、版本检查、CLAUDE.md 规则文件，以及如何用 /help 核对本机可用命令，避免把 Claude Code 与 Codex 的同名命令混用。

Claude Code
新版本
命令边界
Agents
Fast Mode
小白教学

更新于 2026-05-28

一句话结论

更新后先别急着让它大改项目：先查版本，再用 /help 确认本机支持的斜杠命令；把验收目标写进提示词或 CLAUDE.md，不要把 Codex 教程直接搬到 Claude Code。

适用场景

刚装好 Claude Code，不知道怎么确认自己是不是新版本
看到别人提 claude agents、/fast，但不知道哪些是 Claude Code、哪些是 Codex 或插件能力
想让 Claude Code 帮你改网站、排错、跑构建、写教程，但怕它跑偏
想把 Claude Code 用到静态站、WordPress、前端页面、脚本工具这类真实项目里
Windows / macOS / WSL 上更新后出现命令找不到、自动更新失败、权限提示看不懂

常见现象

输入 claude 之后能打开，但不知道下一步该输什么
让它做长任务时，做到一半开始偏题，或者不知道什么时候算完成
同时开了几个会话，分不清哪个在跑、哪个卡住、哪个需要你批准
Claude Code 问你是否允许写文件、跑命令、访问目录，你不知道该不该点同意
它说已经完成，但你不知道有没有真的 build、有没有改到正确文件、有没有上线
用了 /fast 以后速度变快，但不清楚费用、质量和适用场景
更新失败、npm 全局安装不能自动更新，或者 /doctor 里出现安装修复提示

原因解释

Claude Code 的新能力大多藏在斜杠命令、后台会话、插件和诊断工具里，不学命令就只会把它当普通聊天窗口
验收目标解决的是「怎样才算做完」的问题；把目标直接写进提示词或 CLAUDE.md，用 /help 确认本机命令
claude agents 解决的是「多个后台任务怎么管」的问题，适合并行检查、长时间构建、跨分支实验
/fast 解决的是「需要更快反馈」的问题，fast mode 使用的模型以当前客户端为准（先用 /help 或 /model 查看），速度、成本和稳定性要按任务选择
CLAUDE.md 解决的是「每次新会话都重新交代规则」的问题，适合把项目目标、禁止触碰、构建命令写成长期规则

解决步骤

先确认安装方式和版本：运行 claude --version，再运行 claude doctor，看当前安装、登录、自动更新和环境是否正常。
第一次使用先从一个测试项目开始：进入项目目录后运行 claude，让它解释项目结构，不要直接让它改生产项目。
先让它只读项目：问「这个项目做什么、入口文件在哪里、构建命令是什么」，确认它没看错目录再允许改文件。
做超过 10 分钟的任务前先写清验收目标：直接在提示词里写「完成条件」，或写进 CLAUDE.md。
把项目规矩写进 CLAUDE.md：哪些目录不能碰、哪些命令必须跑、部署前要检查哪些 URL。
需要多个任务同时跑时，在普通终端打开 claude agents；把后台会话按运行中、卡住、完成分组看，看到需要你批准的任务再进去处理。
需要快速试方案或看小问题时用 /fast；涉及关键重构、付费接口、生产部署时先关掉 fast 或切回更稳的模型。
更新后先看 /help、/model、/usage、/plugin；这些页面能告诉你当前命令、默认模型、用量来源、插件和技能是否已经生效。
完成后让它自己复核三件事：改了哪些文件、跑了什么验证、还有什么风险。最后你再看 diff 和页面效果。

可复制命令

# macOS / Linux / WSL 官方安装脚本
curl -fsSL https://claude.ai/install.sh | bash

# 检查当前版本和环境
claude --version
claude doctor

# 如果你的安装方式支持内置更新，可先试这个
claude update

# Windows PowerShell 官方安装脚本
irm https://claude.ai/install.ps1 | iex

# 检查版本和诊断信息
claude --version
claude doctor

# 进入项目后，先用这几个命令熟悉环境
/help
/model
/usage
/plugin

# 长任务前给 Claude Code 一个明确验收条件（直接当普通提示词发送）
本轮完成条件：npm run build 通过；新文章路由能打开；dist 里的 HTML 能搜到文章标题。

# 在普通终端里查看后台 Claude Code 会话
claude agents

# 需要脚本化读取时，新版本支持 JSON 输出
claude agents --json

# 需要更快试方案时，在 Claude Code 会话里输入
/fast

# 不确定成本或任务很关键时，先不要开 fast；先用 /model 选择更稳的模型。

# 如果需要切换 fast mode 行为，先用 /help 或 /model 确认当前版本支持什么
# 环境变量和开关以官方文档为准，不同版本可能不同
claude --help

# CLAUDE.md 小白版模板

## 项目是什么
这个项目是：<一句话写清楚网站 / 工具 / Bot 的用途>。
目标用户是：<小白用户 / 客户 / 内部运营>。

## 常用命令
- 安装依赖：npm install
- 本地开发：npm run dev
- 构建验证：npm run build

## 每次改完必须检查
1. 说明改了哪些文件。
2. 运行 npm run build，并告诉我结果。
3. 如果是页面内容，确认 dist 里的 HTML 能搜到核心标题。
4. 如果需要部署，先问我，不要自己部署到别的项目。

## 禁止触碰
- 不要打印 token、API Key、Cookie。
- 不要改生产数据库。
- 不要删除用户已有文件。
- 不要改和本任务无关的项目。

## 输出格式
- 改动摘要
- 验证结果
- 风险和后续建议

# 给 Claude Code 的静态站更新提示词

你现在负责更新一个静态知识库站点。

项目路径：<填项目路径>
本轮目标：新增或加厚一篇教程：<填标题>
目标用户：不懂代码的小白用户

请按顺序做：
1. 先读项目结构、路由、文章数据源、构建脚本。
2. 找到最适合新增内容的位置，不要新建重复页面。
3. 内容必须有：一句话结论、适用场景、常见现象、原因解释、解决步骤、可复制命令、仍然不行怎么办、参考链接。
4. 首页或分类页要能找到这篇内容。
5. 修改后运行 npm run build。
6. 最后告诉我改了哪些文件、新增了什么路由、build 是否通过。

禁止：
- 不要改 Sub2API 主站。
- 不要改 22222 面板。
- 不要打印任何 token。

# 验收目标写法示例（直接当普通提示词发送，或写进 CLAUDE.md）

本轮完成条件——Claude Code 新版本教程加厚：
1. 新文章或原文章必须包含 claude agents、/fast、/doctor、CLAUDE.md、权限边界、构建验证案例。
2. 首页或分类页能点到这篇文章。
3. npm run build 通过。
4. dist/article/<slug>/index.html 能直接搜到文章标题、claude agents。
5. 输出改动文件、验证结果、是否部署。

仍然不行怎么办

claude 命令找不到：重新打开终端，检查安装脚本是否把 Claude Code 加进 PATH；Windows 先确认自己用的是 PowerShell 还是 CMD。
自动更新失败：先运行 claude doctor，看它提示是 npm 全局权限、网络、安装来源还是 release channel 问题。
claude agents 看不到旧会话：先确认已经更新到支持后台会话的新版本，再检查是不是在另一个用户、另一个项目目录或旧 daemon 里启动。
验收目标写了但仍然跑偏：把目标改成可验证的句子，例如「npm run build 通过」「这 3 个 URL 返回 200」，不要写成「把页面优化好」。
/fast 结果不稳：把任务拆小，先让它输出方案或 diff 摘要，关键修改再切回普通模型。

参考教程摘录整合：先核对命令，再写目标

官方 Claude Code Quickstart 的共同思路是：先进项目目录，运行 claude，让它理解项目，再从解释、修改、Git、测试这些常见工作流开始。
官方 slash command / common workflows 类文档的重点是：斜杠命令会随版本、插件和环境变化，所以小白第一步永远是 /help，而不是照抄别人截图里的命令。
社区教程常见做法是先写 CLAUDE.md，把项目目标、构建命令、禁止触碰、验收方式固定下来，减少每次重新解释。
Codex 教程里常见的长任务命令、AGENTS.md、目标管理工作流，不能原样搬到 Claude Code；能复用的是「写清完成条件」这个思想，落地方式是写进提示词或 CLAUDE.md。
最稳的落地方式：把验收目标写进普通提示词或 CLAUDE.md，用 /help 确认本机命令。

2026-05 新版本能力，小白翻译版

验收目标：把完成标准写进普通提示词或 CLAUDE.md，用 /help 确认本机命令。Codex 有自己的长任务命令语境，不要直接混用教程。
claude agents：后台任务看板。你可以看到哪些会话在运行、哪些被权限卡住、哪些已经完成，适合同时跑排错、review、构建验证。
/fast：更快反馈模式。fast mode 使用的模型以当前客户端 /model 显示为准，适合快速试方案、改小块文案、查小问题；重要部署前仍要正常验证。
claude doctor：体检命令。新版本会显示上次更新尝试结果，也会提示 npm 全局安装不能自动更新时该怎么修。
/model：模型选择更清楚。新版本里模型选择可以保存为默认，也可以只对当前会话生效；小白先用默认，不要频繁切。
/usage：看消耗来源。新版能按技能、子 Agent、插件、MCP 等维度拆用量，适合排查为什么额度消耗变快。
/code-review --fix：让 Claude Code 做代码审查并尝试修复。适合改完后再跑一轮检查，但正式项目仍然要看 diff 和构建结果。
/reload-skills：装完或改完技能后不用重启会话，直接让 Claude Code 重新扫描技能目录。

先分清 4 种使用模式

问答模式：只让 Claude Code 解释项目、找文件、讲报错，不允许它改文件。适合第一天熟悉项目。
编辑模式：允许它修改文件，但每次都要看 diff。适合改文案、修小 Bug、补教程。
后台模式：把长任务放到 claude agents 里看状态。适合跑 review、构建、跨文件排查。
技能 / 插件模式：通过技能、插件、MCP 扩展能力。适合长期重复任务，不适合刚上手就乱装。

小白命令选择表

不知道能干什么：输入 /help。
不知道当前用哪个模型：输入 /model。
不知道为什么额度消耗快：输入 /usage。
不知道插件和技能有没有生效：输入 /plugin 或 /reload-skills。
不知道安装有没有问题：在普通终端运行 claude doctor。
长任务怕跑偏：先写验收目标，写进提示词或 CLAUDE.md。
多个任务乱了：在普通终端运行 claude agents。
只想快速试一个想法：在会话里输入 /fast。

小白推荐学习顺序

第一天只学安装、登录、claude --version、claude doctor。
第二天学 /help、/model、/usage，知道当前会话能做什么、用哪个模型、消耗在哪里。
第三天学「验收目标」写法，把「帮我优化页面」改成「构建通过、3 个路由可访问、首页文案更清楚」；用 /help 确认本机命令。
第四天学 claude agents，开始把长任务放后台，看哪里需要你介入。
第五天再碰 /fast、插件、技能、MCP；这些是提速和扩展，不是第一天必须会的东西。

第一次用 Claude Code 改网页的完整流程

打开终端，进入项目目录，不要在用户主目录随便运行。
运行 claude 后先问：这个项目是什么技术栈？入口页面在哪？文章数据源在哪？构建命令是什么？
让它输出计划，但先不要改文件。你确认计划没有碰错项目后，再允许它动手。
写清验收条件：build 通过、目标路由可访问、HTML 源码能搜到核心正文。验收目标写进提示词或 CLAUDE.md，用 /help 确认本机命令。
让它修改内容，并要求每次只围绕一个主题改，不要顺手重构无关样式。
改完让它运行构建命令，并让它抽查 dist 里的 HTML 或本地预览页面。
需要上线时，只部署指定项目；如果你有多个站，必须写清 Cloudflare Pages 项目名。

三个最实用的任务模板

改网页：先让 Claude Code 读路由和数据源，再写验收目标：npm run build 通过，首页 HTML 能搜到核心标题，新文章进 sitemap。
修报错：把报错全文、出现命令、最近改动贴进去，再写验收目标：定位原因，给最小修复，运行对应测试。
更新教程：先让它看官方 changelog，再让它输出小白版解释、可复制命令、仍然不行怎么办。

静态站加厚内容案例

这是给 Agent 小白智库这类站点最常见的任务。重点不是写很多空话，而是让正文能被搜索引擎抓到、让小白能点到、让命令能复制。

先定位文章数据源，例如 src/data/zhiku.ts。
补充文章主体，不要只改首页卡片。
给首页快捷入口、热门问题、工具矩阵或分类页加入口。
运行 npm run build，确认预渲染后的 dist/article/.../index.html 里能搜到正文。
上线后验证 thinktank 主域、pages.dev 域、sitemap.xml。

构建失败时怎么让 Claude Code 排查

先把完整错误贴给它，不要只说「报错了」。
要求它先判断是 TypeScript、Vite、依赖版本、语法、路径大小写，还是内容数据结构问题。
让它只改导致 build 失败的最小范围，不要顺手优化页面。
修完必须重新运行同一个命令，不能只说理论上好了。
如果连续两次修不好，让它输出已尝试方案和剩余怀疑点，换 Codex 或人工继续。

claude agents、/agents、Codex 命令别混了

claude agents 是 Claude Code 的终端命令，用来看后台会话和任务状态。
/agents 是会话内命令或插件命令语境，具体能力看当前版本和插件；Codex 也可能有自己的命令体系。
小白记法：普通终端里敲 claude agents；Claude Code 会话里敲 /help；Codex 里敲 codex --help 或会话内 /help。
如果命令不存在，先 claude --version 和 claude doctor，不要照抄旧教程硬试。

权限弹窗怎么判断能不能同意

读文件：通常可以同意，但先确认它读的是当前项目，不是家目录、密钥目录或其他项目。
写文件：只允许写本任务相关文件；看到它要改配置、密钥、数据库迁移、部署脚本时先暂停。
跑命令：npm run build、npm test、rg、git diff 这类验证命令通常安全；rm、curl | bash、sudo、上传部署类命令要谨慎。
联网：查官方文档可以；上传文件、粘贴 token、访问生产后台前必须人工确认。
部署：只在你明确说部署时同意，并写清项目名，例如 agent-help；不要让它猜。

什么时候不要开 /fast

正在改生产部署、数据库、计费、密钥、权限、订单这类高风险代码。
任务需要完整读懂很多上下文，且你没有写清验收目标和禁止触碰范围。
你已经发现 fast 结果开始省略验证、漏看文件或给出不确定命令。
预算紧张、正在跑批量 review 或后台 agents 很多时，先看 /usage 再决定。

常见误区

误区 1：新版本一定更会自动完成。实际是命令更多了，但目标和边界仍然要你写清楚。
误区 2：验收目标是魔法。它只是完成条件，条件写得虚，结果还是虚；而且不同客户端同名命令不一定同行为。
误区 3：claude agents 开得越多越好。后台任务越多，越需要命名、交接和用量控制。
误区 4：/fast 永远更好。它适合快速反馈，不适合高风险、长上下文和必须严谨验证的任务。
误区 5：插件装越多越强。插件、技能、MCP 都会增加权限和上下文成本，要按场景装。

给客户或团队的落地建议

把 Claude Code 当成工程助理，不要当成完全无人值守员工。
团队项目统一维护 CLAUDE.md，把常用命令、禁止触碰、部署项目、验收方式写进去。
每次任务结束都要求它输出：改动文件、验证命令、结果、风险。
复杂项目采用 Claude Code + Codex 分工：Claude Code 负责解释、方案、体验复核；Codex 负责长任务落地和构建验证。
涉及客户资料、订单、API Key、支付、数据库时，默认人工确认后再执行。

更新后检查清单

claude --version 能看到当前版本；截至 2026-05-28 官方 changelog 最新记录为 2.1.153。
claude doctor 没有红色阻断项；如果提示自动更新不可用，先按提示修安装来源或权限。
在项目根目录能运行 claude，并且它能解释当前项目目录。
/help 能显示当前可用命令；常用命令如 /model、/usage、/fast 按当前版本为准；claude agents 能在普通终端显示会话列表。
CLAUDE.md 写了项目目标、构建命令、禁止触碰目录、验收方式。

参考链接

Claude Code Quickstart：https://code.claude.com/docs/en/quickstart
Claude Code Changelog：https://code.claude.com/docs/en/changelog
Claude Code Week 20 更新说明：https://code.claude.com/docs/en/whats-new/2026-w20

还卡着？

可以把截图、日志、需求单或当前页面链接发到 zhemuy@gmail.com。