Claude Code 进阶与实战指南 (基于 claude-how-to-zh)

本项目是 claude-howto 的非官方中文翻译版。它是一份结构化、可视化、以示例驱动的实用指南，旨在帮助开发者在 11 到 13 小时内，从零基础深度掌握 Claude Code 的所有核心功能，通过编排 agents、hooks、skills 和 MCP servers 实现开发效率的十倍提升。

GitHub - icetonges/claude-how-to-zh

🇨🇳 中文版说明 / Chinese Translation Notice 本仓库是 claude-howto 的非官方中文翻译版。原项目由 Luong NGUYEN（@luongnv89）创建并维护，全部内容的原创权利与致谢均归属原作者。

本翻译版本由 AI（Claude）辅助生成，仅用于方便中文读者学习，不代表原作者观点，也不保证与原版本同步更新。如发现翻译问题，欢迎自行修正后使用；如需获取最新版本、提交 issue 或贡献代码，请前往原始仓库。代码示例、脚本、配置文件等技术内容保持英文原样，未做翻译。

虽然你已经安装了 Claude Code 并运行了几个简单的提示词，但往往会遇到以下瓶颈：

• 官方文档缺乏场景组合：文档仅介绍了单一功能，未阐明如何将斜杠命令（slash commands）、钩子（hooks）、上下文记忆（memory）和子智能体（subagents）串联成能节省数小时的自动化工作流。
• 缺乏清晰的学习路径：不清楚应该先学 MCP 还是 hooks，技能（skills）和子智能体（subagents）又该如何排序，导致浅尝辄止。
• 示例过于基础：官方提供的 "hello world" 级别命令，无法应对生产环境中的代码审查、安全扫描及多智能体协同。

本指南通过对比官方文档，提供了更深维度的实用方案：

掌握 Claude Code 的四个核心步骤：

1. 评估水平：通过完成自我评估测验，或在 Claude Code 中运行 /self-assessment，系统会根据你的技术储备生成个性化学习路线。
2. 渐进式学习：按照顺序学习 10 个模块，将现成模板直接复制到项目中。
3. 工作流组合：将 slash commands、memory、subagents 和 hooks 串联成自动化流水线，处理审查、部署及文档生成。
4. 闭环测试：学完每个模块后运行 /lesson-quiz [topic] 精准查漏补缺。

# 克隆本指南
git clone https://github.com/luongnv89/claude-howto.git
cd claude-howto

# 复制你的第一个 slash command 到自己的项目中
mkdir -p /path/to/your-project/.claude/commands
cp 01-slash-commands/optimize.md /path/to/your-project/.claude/commands/

启动 Claude Code，在终端中直接输入：

/optimize

# 复制项目全局记忆模板
cp 02-memory/project-CLAUDE.md /path/to/your-project/CLAUDE.md

# 安装代码审查专家技能到全局
cp -r 03-skills/code-review-specialist ~/.claude/skills/

# 1. 导入 Slash Commands
cp 01-slash-commands/*.md .claude/commands/

# 2. 导入项目 Memory
cp 02-memory/project-CLAUDE.md ./CLAUDE.md

# 3. 部署 Skills
cp -r 03-skills/code-review-specialist ~/.claude/skills/

# 4. 配置 Subagents
cp 04-subagents/*.md .claude/agents/

# 5. 集成 GitHub MCP Server
export GITHUB_TOKEN="your_github_token"
claude mcp add github -- npx -y @modelcontextprotocol/server-github

# 6. 配置并启用 Hooks
mkdir -p ~/.claude/hooks
cp 06-hooks/*.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/*.sh

• 路径: 01-slash-commands/README.md
• 本质: 使用 Markdown 文件定义的快捷指令。
• 常用模版:
  • optimize.md：自动进行代码性能和规范优化分析。
  • pr.md：自动整理当前变更，生成 Pull Request 描述信息。
  • generate-api-docs.md：一键扫描并生成 API 接口文档。

• 路径: 02-memory/README.md
• 本质: 为 Claude 提供持久的、免于在 prompt 中反复提及的上下文背景。
• 分级规则:
  • 项目级：CLAUDE.md（团队共享规范）
  • 目录级：src/api/CLAUDE.md（特定模块专属规范）
  • 个人级：~/.claude/CLAUDE.md（个人编码偏好与快捷键）

• 路径: 03-skills/README.md
• 本质: 将脚本、模板与说明打包，在特定场景由 Claude 自动感知并调用。
• 典型场景: 代码深度评审、品牌语气一致性检查、静态资源自动化压缩。

• 路径: 04-subagents/README.md
• 本质: 拥有独立隔离上下文的高效 AI 协同网。主 agent 根据任务复杂度，自动将任务分发给专业的下级 agent：
  • code-reviewer.md：专注代码质量与重构。
  • test-engineer.md：设计测试用例及覆盖率提升。
  • secure-reviewer.md：执行只读权限的安全审计。

• 路径: 05-mcp/README.md
• 本质: 赋予 Claude Code 安全连接外部工具（如数据库、GitHub 仓库、具体文件系统等）的实时交互标准。

• 路径: 06-hooks/README.md
• 本质: 事件驱动的 Shell 脚本自动触发机制。在 Claude Code 声明周期的 4 大类 25 个事件节点（如 PreToolUse, PostToolUse 等）插入执行：

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write",
      "hooks": ["~/.claude/hooks/format-code.sh"]
    }],
    "PostToolUse": [{
      "matcher": "Write",
      "hooks": ["~/.claude/hooks/security-scan.sh"]
    }]
  }
}

• 路径: 07-plugins/README.md
• 本质: 插件包，支持将 commands、agents、MCP 和 hooks 统一打包并分发。可通过 /plugin install pr-review 一键部署。

• 路径: 08-checkpoints/README.md
• 本质: 基于会话快照的代码安全回退机制。按两次 Esc 键或输入 /rewind 即可提供 5 种处理方案：
  1. 恢复代码和对话
  2. 恢复对话
  3. 恢复代码
  4. 从当前点开始总结
  5. 取消操作

• 路径: 09-advanced-features/README.md
• 高阶能力:
  • Planning Mode：编码前强制生成实现规划。
  • Extended Thinking（深度思考模式）：通过 Alt+T / Option+T 快捷键切换，进行超复杂逻辑推理。
  • Headless Mode：在 CI/CD 中通过命令行非交互式运行（例如：claude -p "Run tests"）。

• 路径: 10-cli/README.md
• 命令行基础: 提供与终端集成的最完整命令集。
  • 配合管道使用：cat error.log | claude -p "explain this error"
  • JSON 格式化输出：claude -p --output-format json "list functions"

涉及功能: Slash Commands + Subagents + Memory + MCP

涉及功能: Plugins + MCP + Hooks

1. 用户触发 /deploy production。
2. 触发 PreToolUse Hook：自动执行本地测试环境与安全基线验证。
3. 自动将任务委托给专属的 deployment-specialist 子智能体。
4. 子智能体通过 Kubernetes MCP 执行生产环境应用升级。
5. 触发 PostToolUse Hook：对生成环境进行持续的健康检查（Health Check）并输出报告。

├── 01-slash-commands/          # 快捷指令
│   ├── optimize.md
│   ├── pr.md
│   ├── generate-api-docs.md
│   └── README.md
├── 02-memory/                  # 上下文记忆
│   ├── project-CLAUDE.md
│   ├── directory-api-CLAUDE.md
│   ├── personal-CLAUDE.md
│   └── README.md
├── 03-skills/                  # 可复用能力
│   ├── code-review/
│   │   ├── SKILL.md
│   │   ├── scripts/
│   │   └── templates/
│   ├── brand-voice/
│   │   ├── SKILL.md
│   │   └── templates/
│   ├── doc-generator/
│   │   ├── SKILL.md
│   │   └── generate-docs.py
│   └── README.md
├── 04-subagents/               # 子智能体
│   ├── code-reviewer.md
│   ├── test-engineer.md
│   ├── documentation-writer.md
│   ├── secure-reviewer.md
│   ├── implementation-agent.md
│   └── README.md
├── 05-mcp/                     # MCP 协议集成
│   ├── github-mcp.json
│   ├── database-mcp.json
│   ├── filesystem-mcp.json
│   ├── multi-mcp.json
│   └── README.md
├── 06-hooks/                   # 事件钩子
│   ├── format-code.sh
│   ├── pre-commit.sh
│   ├── security-scan.sh
│   ├── log-bash.sh
│   ├── validate-prompt.sh
│   ├── notify-team.sh
│   └── README.md
├── 07-plugins/                 # 功能插件包
│   ├── pr-review/
│   ├── devops-automation/
│   ├── documentation/
│   └── README.md
├── 08-checkpoints/             # 会话快照与回退
│   ├── checkpoint-examples.md
│   └── README.md
├── 09-advanced-features/       # 深度思考、规划与后台任务
│   ├── config-examples.json
│   ├── planning-mode-examples.md
│   └── README.md
├── 10-cli/                     # CLI 参考手册
│   └── README.md
└── README.md                   # 根说明文件

• 推荐做的事情 (Do)：

  • 从基础的 / 快捷命令开始，小步快跑，逐步引入自动化 Hook。
  • 将团队的统一编码规范、技术选型和禁止使用的 API 写进 CLAUDE.md 记忆文件。
  • 在将配置文件共享到团队之前，务必在本地环境进行彻底测试。
  • 对重要的自定义 Agent 和自定义 Prompt 配置实施 Git 版本控制。

• 严禁发生的事情 (Don't)：

  • 不要在任何配置文件中硬编码 API 凭证或密钥 (Secrets)。
  • 不要过度设计简单的流程，避免让 Claude 在单次任务中派生过多 Subagent 导致 Token 浪费。
  • 不要跳过对新技能或新 Hook 的本地安全沙箱测试。

• 排查方法：检查文件所在的目录路径是否拼写正确（如 .claude/commands/）。验证 Markdown 的 Frontmatter 元数据格式是否符合 YAML 语法。检查脚本执行权限并确认 Claude Code 版本兼容性。

• 排查方法：运行 echo $YOUR_ENV_VAR 确认相关环境变量（如 GITHUB_TOKEN）已被终端正确载入。测试 MCP 服务本身在本地能否独立运行，并确认本地网络未阻断端口。

• 排查方法：检查主 Agent 是否具备足够的工具调用权限。在 Subagent 描述文件（.md）中，确保 description 字段表述清晰，足以让主 Agent 在合适时机匹配并委派。

项目配有完善的测试流水线，支持 Python 3.10、3.11 与 3.12 版本：

# 1. 安装开发调试依赖
uv pip install -r requirements-dev.txt

# 2. 运行单元测试
pytest scripts/tests/ -v

# 3. 运行代码 Lint (Ruff)
ruff check scripts/
ruff format --check scripts/

# 4. 安全扫描
bandit -c pyproject.toml -r scripts/ --exclude scripts/tests/

# 5. 静态类型检查
mypy scripts/ --ignore-missing-imports

若需要离线系统学习本指南，可运行打包脚本。该脚本会自动将全部章节以及渲染好的 Mermaid 流程图打入电子书中：

uv run scripts/build_epub.py
# 运行后会在根目录下生成 claude-howto-guide.epub

非常欢迎开发者对中文版提出改进意见。贡献前请详细阅读 📄CONTRIBUTING.md↗ 了解开发规范。对于安全漏洞，请通过 GitHub 安全漏洞报告页面 进行负责任的私密报告。

• Claude Code 官方文档
• MCP 协议规范说明
• Anthropic 官方 Cookbook
• Boris Cherny 共享的 Claude Code 工作流 (Claude Code 的创造者之一)

• 多维协同是生产力跃迁的关键：Claude Code 的真正威力在于将 Memory（项目规范）、Subagents（专职助理）、MCP（外部数据）与 Hooks（自动化检测）融合成符合团队标准的自动化管道。
• 注重安全与边界限制：合理使用 acceptEdits 或 secure-reviewer.md（只读安全智能体）来限制大模型的写入权限，永远不要将敏感凭证写入配置文件。
• 重视本地试错：结合 Checkpoints & Rewind 机制，能在开发新特性或重构时建立一键回退的安全网，极大地消除了开发者的心智负担。
• 版本兼容提示：本指南与 Claude Code v2.1.112+ (2026年4月) 完全兼容，并对 Claude Sonnet 4.6、Opus 4.6 及 Haiku 4.5 提供了针对性优化。

许可证信息：本项目基于 MIT 许可证 授权，你可以自由拷贝、分发和集成到商业项目，但须在副本中保留原作者的版权声明。本中文版仓库源于 claude-how-to-zh 仓库地址。