From beginner to expert — master every Claude Code capability through hands-on practice
📖 Read Online · 🗺️ Learning Path · 🔗 Ecosystem
A hands-on, progressive tutorial for Claude Code. Every concept comes with a runnable demo so you actually learn by doing, not just reading.
Most tutorials stop at "here's what it does." This one says: "open your terminal and try it right now."
- 41 hands-on demos — real GitHub projects (FastAPI, Flask, httpie), not toy examples
- 3 capstone projects — CLI Bookmark Manager, PR Review Bot, AI Code Review Pipeline
- Cross-platform — Windows (Git Bash), macOS, and Linux supported equally
- Cutting edge — covers Managed Agents, Harness architecture, Agent SDK (April 2026)
- Ecosystem coverage — patterns from ECC (148k⭐), gstack (68k⭐), GSD (50k⭐), BMAD (44k⭐)
- Bilingual — English (default) with full Chinese translation
The tutorial is built with VitePress and deployed on GitHub Pages. Click the link above to start reading immediately — no installation needed.
- English: docjlm.github.io/claude-code-best-practices/
- 中文: docjlm.github.io/claude-code-best-practices/zh-cn/
# Clone the repo
git clone https://github.com/DocJlm/claude-code-best-practices.git
cd claude-code-best-practices
# Install dependencies
npm install
# Start the dev server
npm run docs:dev
# Open http://localhost:5173 in your browser- Node.js 18+ (for VitePress docs site)
- Git (Git for Windows includes Git Bash)
- Claude Code CLI —
npm install -g @anthropic-ai/claude-code - Anthropic API Key or Claude Pro/Max subscription
┌─────────────────────────────────────────────────────────────────┐
│ Stage 1: Beginner │
│ Ch1 Installation → Ch2 CLAUDE.md → Ch3 Context → Ch4 Git │
│ 🎯 Capstone: CLI Bookmark Manager │
├─────────────────────────────────────────────────────────────────┤
│ Stage 2: Intermediate │
│ Ch5 Hooks → Ch6 Skills → Ch7 MCP → Ch8 Subagents → Ch9 Teams │
│ 🎯 Capstone: PR Review Bot │
├─────────────────────────────────────────────────────────────────┤
│ Stage 3: Advanced │
│ Ch10 Security → Ch11 IDE → Ch12 CI/CD → Ch13 SDK │
│ Ch14 Managed Agents → Ch15 Production Workflows │
│ 🎯 Capstone: AI Code Review Pipeline │
└─────────────────────────────────────────────────────────────────┘
| Chapter | Topic | What You'll Build |
|---|---|---|
| Ch1 | Installation & First Session | GitHub Profile Analyzer, FastAPI request tracer |
| Ch2 | CLAUDE.md & Memory | Production-grade config with gstack-style voice rules |
| Ch3 | Context Window Management | Context experiments with Flask source code |
| Ch4 | Git Workflows & PR Automation | Dark mode feature with atomic commits |
| 🎯 | Capstone | CLI Bookmark Manager with fuzzy search & tags |
| Chapter | Topic | What You'll Build |
|---|---|---|
| Ch5 | Hooks System | Commit quality gate, secret scanner, learning observer |
| Ch6 | Custom Skills | /deep-research, /review, /investigate (from ECC & gstack) |
| Ch7 | MCP Integration | GitHub PR triage, live docs lookup, browser automation |
| Ch8 | Subagent Architecture | Architect agent (Opus), security scanner, test writer |
| Ch9 | Agent Teams | Autoplan review pipeline (CEO/Design/Eng) |
| 🎯 | Capstone | PR Review Bot with parallel security/quality agents |
| Chapter | Topic | What You'll Build |
|---|---|---|
| Ch10 | Permissions & Security | Team trust tiers, AgentShield, zero-prompt auto mode |
| Ch11 | IDE & Multi-device | VS Code refactoring, Remote Control, scheduled reviews |
| Ch12 | CI/CD & GitHub Actions | Automated PR review, issue triage, security gate |
| Ch13 | Agent SDK | PR Review Bot SDK, dependency auditor, migration pipeline |
| Ch14 | Managed Agents & Harness | Cloud agents, session persistence, self-evaluation |
| Ch15 | Production Workflows | R→P→E→R→S workflow, cost optimization, framework guide |
| 🎯 | Capstone | AI Code Review Pipeline (full production system) |
This tutorial incorporates patterns and techniques from the top Claude Code frameworks:
| Framework | Stars | Key Innovation | What We Took |
|---|---|---|---|
| Everything Claude Code | 148k | 47 agents, 181 skills, AgentShield | Skills format, hook patterns, security guide |
| gstack | 68k | Role-based skills, "Boil the Lake" | CEO/Design/Eng reviews, effort transparency |
| Get Shit Done | 50k | Wave execution, context management | 40-60% golden zone, atomic commits |
| BMAD-METHOD | 44k | 12 agent personas, full SDLC | Agent role design, phase-gating |
| GitHub Spec Kit | 87k | Spec-driven development | Constitutional governance pattern |
| oh-my-claudecode | 27k | Smart model routing | Cost optimization via Haiku/Opus routing |
| HumanLayer | 10k+ | RPI pattern for 300k LOC | Context engineering for large codebases |
| You are... | Recommended path |
|---|---|
| New to Claude Code | Start at Chapter 1, work through the Beginner stage |
| Used Claude Code, want to go deeper | Jump to Stage 2 (Chapter 5) |
| Deploying Claude Code for a team | Focus on Ch10 Security + Ch12 CI/CD + Ch15 Production |
| Building AI Agent products | Ch13 Agent SDK + Ch14 Managed Agents |
| Just need a quick reference | Check the Cheatsheets |
claude-code-best-practices/
├── docs/ # Tutorial content (English, VitePress)
│ ├── stage1-beginner/ # Chapters 1-4
│ ├── stage2-intermediate/ # Chapters 5-9
│ ├── stage3-advanced/ # Chapters 10-15
│ ├── capstones/ # 3 capstone projects
│ ├── platform-notes/ # Windows & macOS guides
│ └── zh-cn/ # Chinese translation (中文版)
├── templates/ # Reusable CLAUDE.md, agent, and skill templates
├── cheatsheets/ # Quick reference cards
└── scripts/ # Setup verification scripts
Built on the shoulders of these outstanding projects:
- claude-code-best-practice — comprehensive Claude Code documentation
- Everything Claude Code — production agent/skill library
- gstack — role-based skill system by Y Combinator's Garry Tan
- Get Shit Done — context management & wave execution
- easy-vibe — tutorial structure inspiration
- Claude Code Official Docs — authoritative reference
- Managed Agents Engineering Blog — harness architecture
Contributions welcome! See CONTRIBUTING.md for guidelines.
- Found a bug or outdated content? Open an Issue
- Want to add a demo or chapter? Submit a Pull Request
- Have tips to share? Join the Discussions