Claude Code 中文全面上手指南

从会输入 claude，到真正会组合使用 slash commands、memory、skills、hooks、MCP、subagents 和 plugins。

这是一个基于上游项目 luongnv89/claude-howto 的 非官方中文本土化 fork。它不是生硬逐句翻译，而是面向中国小白用户重写表达方式、补齐学习路径、保留所有关键可执行标识，并加入翻译后兼容性校验。

15 分钟快速开始 | 先判断你适合从哪开始 | 浏览功能总表 | 查看来源与同步说明

---

最近同步

• 最近同步日期：2026-08-06
• 本轮参考范围：b9a973b -> 4f3fa85
• 本次同步内容：
  • 跟进上游 v2.1.220-r2 accuracy review 的后续修复，审阅 EPUB CI、Ruff、依赖清理、Hook 分类与多语言相对链接变化
  • 将中文 EPUB 的 Mermaid 渲染从 Kroki/httpx 切换为本地 mmdc，保留中文封面、元数据、章节标题和根目录内容结构
  • EPUB 构建移出 pre-commit，所有 GitHub Actions 构建路径统一安装 mmdc 并使用 --lang zh 强制构建；任一图表失败都会阻止通过
  • 删除不再使用的 httpx、tenacity，统一 Ruff v0.15.10+，修正 Bandit 配置路径和 tests 的 Ruff 相对路径
  • 取消 Ruff、Bandit、mypy 与 Markdown lint 的静默放行，并补充适合中文长行和 HTML 图片头的规则配置，避免“workflow 绿色但检查其实失败”
  • 升级失去当前 runner 支持的 codecov-action@v3 与 setup-python@v4，并通过 actionlint 校验全部 workflow
  • 明确 5 种 hook 类型决定“如何运行”，31 个 hook 事件决定“何时运行”，两者不是同一分类轴
  • 上游其他语言目录继续只作参考，不重新引入中文 fork 已移除的 ja/vi/uk/zh 树
  • 保留文件名、路径、frontmatter key、JSON/YAML key、CLI flags、环境变量、slash command、skill / subagent / plugin 名称原文
  • 继续保持 Claude Code 中文全面上手指南 为根目录中文主线

---

Table of Contents

• 最近同步
• 这是什么项目
• 本项目做了哪些调整
• 哪些内容为了兼容性不会翻译
• 为什么这份指南更适合中国小白
• 怎么使用这份指南
• 不知道从哪里开始
• 15 分钟快速开始
• 你能用它搭什么
• 常见问题
• 参与贡献
• 许可证

---

这是什么项目

如果你已经装好了 Claude Code，但只会简单对话，很容易卡在这几个地方：

• 官方文档告诉你“有什么功能”，却不会告诉你“这些功能怎么组合起来真正在项目里省时间”。
• 你知道 CLAUDE.md、hooks、MCP、skills、subagents 这些词，但不知道先学哪个、后学哪个。
• 你能看懂一些简单例子，但还不会把它们变成自己的 code review、文档生成、自动化流程。

这个仓库的目标，就是把这些碎片能力整理成一条可落地的学习路径，让你知道：

• 先学什么最有效
• 每个功能什么时候用
• 哪些示例可以直接复制
• 哪些看起来像普通文本、其实不能乱翻

---

本项目做了哪些调整

和上游英文项目相比，这个中文版做了这些本土化处理：

• 把首页、学习路线、速查卡、功能目录等核心入口文档改成中文主线表达。
• 用中国小白更容易理解的方式重写“是什么 / 什么时候用 / 怎么装 / 怎么跑 / 常见坑”。
• 保留所有会影响运行的关键标识，避免为了翻译把示例翻坏。
• 补充中国用户常见障碍说明，比如 GitHub Token、npm / npx / uv / Python 环境、网络与代理、macOS / Windows / WSL 差异。
• 增加来源声明、同步策略和本地化风格规范，方便后续持续跟进上游版本。
• 增加本地化校验脚本，自动检查 frontmatter、JSON/YAML、shell 脚本、关键命令名和受保护标识是否仍然可用。

详细规则见：

• UPSTREAM.md
• LOCALIZATION-STYLE.md

---

哪些内容为了兼容性不会翻译

为了确保示例仍然能直接复制运行，下列内容默认 保留英文，不做中文化改名：

• 目录名、文件名
• slash command 名称
• skill / subagent / plugin 名称
• YAML frontmatter key
• JSON / YAML key
• CLI flags、环境变量名、路径占位符、MCP server 名
• 代码块里的可执行命令、配置片段、协议字段

举例来说，skills、CLI、hooks、MCP、subagents 这些术语在正文里通常会保留英文，并在首次出现时补充中文解释；但不会粗暴改成一个中文词后再让读者回头猜原始命令是什么。

---

为什么这份指南更适合中国小白

这个中文版本不是“翻译腔”文档，而是按学习体验重新组织表达：

• 先讲清楚“这是什么”和“什么时候用”，再给你命令和配置。
• 尽量把容易混淆的概念放在一起对比，比如 slash commands、skills、memory、hooks、plugins 的职责边界。
• 对中国开发者常见的安装、访问和权限问题，直接给出前置提醒，不让你跑到一半才踩坑。
• 对高风险示例明确提醒哪些行不能翻、哪些字段不能改。

---

怎么使用这份指南

1. 先找自己的起点

直接看 LEARNING-ROADMAP.md，先做自测，再按 beginner / intermediate / advanced 路线学。

2. 再按模块逐步上手

仓库里的 10 个模块按推荐顺序排列：

1. Slash Commands
2. Memory
3. Checkpoints
4. CLI Basics
5. Skills
6. Hooks
7. MCP
8. Subagents
9. Advanced Features
10. Plugins

3. 边学边复制模板

这个仓库不是纯阅读材料。很多文件都可以直接复制到你的项目里，例如：

• 01-slash-commands/*.md
• 02-memory/project-CLAUDE.md
• 03-skills/*/SKILL.md
• 04-subagents/*.md
• 05-mcp/*.json
• 06-hooks/*.sh
• 07-plugins/*
• local-progress/index.html

4. 每改一处示例都先确认兼容性

如果你继续 fork 并深度本地化，建议每次改完都跑：

uv run python scripts/validate_localization.py

它会帮你检查：

• Markdown 相对链接
• YAML frontmatter
• JSON / YAML 解析
• shell 脚本语法
• 关键可执行标识是否被误改

---

🌱 不知道从哪里开始

如果你还不确定自己算什么水平，可以直接用下面这套简版判断：

完整路线见 LEARNING-ROADMAP.md。

---

🚀 15 分钟快速开始

如果你只是想先跑起来，不想马上看完整教程，可以先做这一套：

# 1. 准备项目目录
mkdir -p /path/to/your-project/.claude/commands

# 2. 复制第一个 slash command
cp 01-slash-commands/optimize.md /path/to/your-project/.claude/commands/

# 3. 在 Claude Code 里试用
# /optimize

# 4. 加上项目级 memory
cp 02-memory/project-CLAUDE.md /path/to/your-project/CLAUDE.md

# 5. 安装一个 skill
mkdir -p ~/.claude/skills
cp -r 03-skills/code-review-specialist ~/.claude/skills/

如果你想在 1 小时内完成最小可用配置，可以继续：

# Slash commands（快捷命令）
cp 01-slash-commands/*.md .claude/commands/

# Project memory（项目记忆）
cp 02-memory/project-CLAUDE.md ./CLAUDE.md

# A reusable skill（可复用 skill）
cp -r 03-skills/code-review-specialist ~/.claude/skills/

# 周末目标：继续加 hooks、MCP、subagents、plugins

---

你能用它搭什么

---

常见问题

这是官方项目吗？ 不是。这是基于上游社区项目做的中文本土化 fork，来源与同步策略见 UPSTREAM.md。

我能直接复制里面的命令和配置吗？ 大多数可以，但前提是你不要改坏关键标识。像 frontmatter key、JSON key、CLI flags、环境变量名这些不能为了中文化而改掉。

为什么有些术语不翻译？ 因为很多术语一旦翻译，会让你在真实使用 Claude Code、搜索官方文档、复制命令时更容易混淆。这个项目遵循“术语保真，解释中文化”的原则。

中国用户最容易卡在哪？ 常见是：GitHub 访问、Token 权限、npm / npx / uv / Python 环境、Windows 和 WSL 差异、以及把示例里可执行字段误翻译。

能离线看吗？ 可以。运行：

uv run scripts/build_epub.py --lang zh

本机需要可用的 mmdc；命令会生成中文 EPUB 电子书。安装方式与 arm64 限制见 scripts/README.md。

之后怎么跟上游同步？ 请先看 UPSTREAM.md。本仓库默认按“持续同步上游、中文侧增量跟进”的方式维护。

---

快速导航：所有核心能力

能力	说明	入口
功能总表	一眼看全所有功能、安装方式、适用场景	CATALOG.md
学习路线	从新手到进阶的推荐学习顺序	LEARNING-ROADMAP.md
Quick Reference	安装命令、路径、常用场景速查	QUICK_REFERENCE.md
Slash Commands	用户主动触发的快捷操作	01-slash-commands/
Memory	持久上下文与规则	02-memory/
Skills	自动触发的复用能力	03-skills/
Subagents	分工明确的 AI 助手	04-subagents/
MCP	外部工具与实时数据接入	05-mcp/
Hooks	事件驱动自动化	06-hooks/
Plugins	多能力打包分发	07-plugins/
Checkpoints	安全试错与回退	08-checkpoints/
Advanced Features	plan、auto mode、background tasks 等高级能力	09-advanced-features/
CLI	claude / claude -p / session / automation 参考	10-cli/

核心能力对照

能力	触发方式	持久性	最适合什么
Slash Commands	手动输入 /cmd	当前会话	高频快捷操作
Memory	自动加载	跨会话	长期规则与偏好
Skills	自动触发	文件系统级	可复用工作流
Subagents	自动委派或显式调用	独立上下文	任务拆分
MCP	自动查询	实时	外部系统接入
Hooks	事件触发	配置级	自动检查和拦截
Plugins	一次安装	组合能力	团队级打包方案
Checkpoints	内建	会话级	安全试错
Planning Mode	手动或自动进入	计划阶段	复杂实现
CLI	终端命令	脚本 / 会话	自动化与 CI/CD

---

Contributing

欢迎继续把这个中文 fork 做得更适合中文用户，但请遵循两个底线：

• 先看 LOCALIZATION-STYLE.md，不要把可执行标识翻坏。
• 先看 UPSTREAM.md，不要在没有记录映射关系的情况下随意偏离上游结构。

如果你要贡献翻译或重写内容，建议至少本地跑一次：

uv run python scripts/validate_localization.py

---

License

本仓库沿用上游项目的 MIT License。

来源项目、上游 commit、同步策略和本地化边界见 UPSTREAM.md。