Claude Code Advanced and Practical Guide (Based on claude-how-to-zh)

This project is an unofficial Chinese translation of claude-howto. It is a structured, visual, and example-driven practical guide designed to help developers deeply master all the core features of Claude Code from scratch in 11 to 13 hours, achieving a tenfold increase in development efficiency by orchestrating agents, hooks, skills, and MCP servers.

GitHub - icetonges/claude-how-to-zh

🇨🇳 中文版说明 / Chinese Translation Notice This repository is an unofficial Chinese translation of claude-howto. The original project was created and is maintained by Luong NGUYEN (@luongnv89), and all rights to the original content and acknowledgments belong to the original author.

This translated version was generated with the assistance of AI (Claude) solely for the convenience of Chinese readers. It does not represent the views of the original author, nor does it guarantee synchronous updates with the original version. If you find translation issues, you are welcome to correct them for your own use; to get the latest version, submit issues, or contribute code, please go to the original repository. Technical content such as code examples, scripts, and configuration files remains in English without translation.

Even though you have installed Claude Code and run a few simple prompts, you often encounter the following bottlenecks:

• Official documentation lacks scenario composition: The documentation only introduces individual features and does not clarify how to chain slash commands, hooks, memory, and subagents into automated workflows that save hours.
• Lack of a clear learning path: It is unclear whether to learn MCP or hooks first, and how to prioritize skills and subagents, leading to scratching only the surface.
• Examples are too basic: The "hello world"-level commands provided officially cannot handle code review, security scanning, and multi-agent collaboration in production environments.

This guide provides a deeper dimension of practical solutions by comparing with the official documentation:

Four core steps to mastering Claude Code:

1. Assess Level: By completing the self-assessment quiz or running /self-assessment in Claude Code, the system will generate a personalized learning path based on your technical background.
2. Progressive Learning: Learn the 10 modules in sequence and copy ready-made templates directly into your projects.
3. Workflow Composition: Chain slash commands, memory, subagents, and hooks into automated pipelines to handle reviews, deployments, and document generation.
4. Closed-loop Testing: Run /lesson-quiz [topic] after learning each module to precisely identify and fix knowledge gaps.

# 克隆本指南
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/

Start Claude Code and type directly in your terminal:

/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

• Path: 01-slash-commands/README.md
• Essence: Shortcut commands defined using Markdown files.
• Common Templates:
  • optimize.md: Automatically performs code performance and style optimization analysis.
  • pr.md: Automatically organizes current changes and generates Pull Request descriptions.
  • generate-api-docs.md: One-click scanning and generation of API documentation.

• Path: 02-memory/README.md
• Essence: Provides Claude with persistent context background, avoiding the need to repeatedly mention it in prompts.
• Hierarchical Rules:
  • Project-level: CLAUDE.md (team-shared standards)
  • Directory-level: src/api/CLAUDE.md (specific module-exclusive standards)
  • Personal-level: ~/.claude/CLAUDE.md (personal coding preferences and shortcuts)

• Path: 03-skills/README.md
• Essence: Packages scripts, templates, and descriptions, which are automatically perceived and called by Claude in specific scenarios.
• Typical Scenarios: Deep code review, brand voice consistency checks, automated compression of static assets.

• Path: 04-subagents/README.md
• Essence: An efficient AI collaboration network with isolated, independent contexts. The main agent automatically distributes tasks to specialized subagents based on task complexity:
  • code-reviewer.md: Focusing on code quality and refactoring.
  • test-engineer.md: Designing test cases and improving coverage.
  • secure-reviewer.md: Executing read-only security audits.

• Path: 05-mcp/README.md
• Essence: Gives Claude Code a real-time interaction standard for securely connecting to external tools (such as databases, GitHub repositories, specific file systems, etc.).

• Path: 06-hooks/README.md
• Essence: An event-driven automatic trigger mechanism for shell scripts. Inserted and executed at 25 event nodes across 4 major categories of the Claude Code lifecycle (such as PreToolUse, PostToolUse, etc.):

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

• Path: 07-plugins/README.md
• Essence: Plugin packages that support unified packaging and distribution of commands, agents, MCPs, and hooks. Can be deployed with one click via /plugin install pr-review.

• Path: 08-checkpoints/README.md
• Essence: A secure code rollback mechanism based on session snapshots. Pressing Esc twice or entering /rewind provides 5 handling options:
  1. Restore code and chat
  2. Restore chat
  3. Restore code
  4. Summarize from the current point
  5. Cancel operation

• Path: 09-advanced-features/README.md
• Advanced Capabilities:
  • Planning Mode: Forces implementation planning before coding.
  • Extended Thinking: Toggle with the Alt+T / Option+T shortcut for ultra-complex logical reasoning.
  • Headless Mode: Run non-interactively via the command line in CI/CD (e.g., claude -p "Run tests").

• Path: 10-cli/README.md
• CLI Basics: Provides the most complete set of commands for terminal integration.
  • Use with pipes: cat error.log | claude -p "explain this error"
  • JSON formatted output: claude -p --output-format json "list functions"

Features involved: Slash Commands + Subagents + Memory + MCP

Features involved: Plugins + MCP + Hooks

1. User triggers /deploy production.
2. Triggers PreToolUse Hook: Automatically executes local test environment and security baseline validation.
3. Automatically delegates the task to the dedicated deployment-specialist subagent.
4. The subagent executes production environment application upgrades via Kubernetes MCP.
5. Triggers PostToolUse Hook: Performs continuous health checks on the production environment and outputs reports.

├── 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:

  • Start with basic / shortcut commands, move fast with small steps, and gradually introduce automated hooks.
  • Write the team's unified coding standards, technology choices, and prohibited APIs into the CLAUDE.md memory file.
  • Be sure to thoroughly test configuration files in a local environment before sharing them with the team.
  • Implement Git version control for important custom agents and custom prompt configurations.

• Don't:

  • Never hardcode API credentials or secrets in any configuration files.
  • Do not over-engineer simple processes; avoid letting Claude spawn too many subagents in a single task to prevent wasting tokens.
  • Do not skip local security sandbox testing for new skills or hooks.

• Troubleshooting: Check if the file directory path is spelled correctly (such as .claude/commands/). Verify that the Markdown Frontmatter metadata format complies with YAML syntax. Check script execution permissions and confirm Claude Code version compatibility.

• Troubleshooting: Run echo $YOUR_ENV_VAR to confirm that the relevant environment variables (such as GITHUB_TOKEN) have been correctly loaded by the terminal. Test whether the MCP service itself can run independently locally, and confirm that the local network is not blocking ports.

• Troubleshooting: Check if the main agent has sufficient tool calling permissions. In the subagent description file (.md), ensure that the description field is described clearly enough for the main agent to match and delegate at the appropriate time.

The project is equipped with a complete test pipeline, supporting Python versions 3.10, 3.11, and 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

If you need to study this guide systematically offline, you can run the packaging script. The script will automatically bundle all chapters along with the rendered Mermaid flowcharts into the ebook:

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

We highly welcome developers to suggest improvements to the Chinese version. Please read 📄CONTRIBUTING.md↗ in detail before contributing to understand the development standards. For security vulnerabilities, please submit a responsible private report via the GitHub Security Advisories Page.

• Claude Code Official Documentation
• MCP Specification
• Anthropic Official Cookbook
• Claude Code Workflows Shared by Boris Cherny (one of the creators of Claude Code)

• Multi-dimensional collaboration is the key to productivity leaps: The true power of Claude Code lies in integrating Memory (project specifications), Subagents (dedicated assistants), MCP (external data), and Hooks (automated checks) into automated pipelines that meet team standards.
• Focus on security and boundary limitations: Reasonably use acceptEdits or secure-reviewer.md (read-only security subagent) to limit the write permissions of LLMs, and never write sensitive credentials in configuration files.
• Value local trial-and-error: Combined with the Checkpoints & Rewind mechanism, you can establish a one-click rollback safety net when developing new features or refactoring, significantly reducing developers' cognitive load.
• Version Compatibility Notice: This guide is fully compatible with Claude Code v2.1.112+ (April 2026), with targeted optimizations for Claude Sonnet 4.6, Opus 4.6, and Haiku 4.5.

License Information: This project is licensed under the MIT License. You are free to copy, distribute, and integrate it into commercial projects, provided that the original author's copyright notice is retained in the copies. This Chinese version repository is derived from the claude-how-to-zh repository.