Learn Claude Code Review: 20 Lessons from Agent Loop to Complete Harness
Quick verdict
Learn Claude Code is not a shortcut guide for operating Claude Code. It is a 20-lesson code-reading course about the harness around a coding agent: the message loop, tool dispatch, permissions, hooks, plans, subagents, compaction, memory, persistent tasks, background work, teams, worktree isolation, and MCP. Its strongest design choice is that every mechanism grows around the same small agent loop. You see where complexity enters instead of treating a framework as magic.
The course is best for developers who already know Python, Git, processes, and HTTP APIs and now want to understand agent internals. If the goal is simply to use the product, start with Claude Code. Compare Codex and Gemini CLI for other terminal-agent products. Do not copy s20_comprehensive into a production service and mistake successful execution for production readiness.
Two tracks exist today
As of July 21, 2026, the root-level s01_* through s20_* directories are the canonical course. Each chapter includes narrative documentation, Chinese, English, and Japanese variants, runnable code.py, and diagrams where useful. The docs/, agents/, and current web application retain the old 12-lesson track during transition. Their numbering is not fully aligned, so mixing a web chapter with a root-level file of the same number can teach the wrong mechanism.
The current curriculum has six useful stages:
| Stage | Lessons | Engineering question |
|---|---|---|
| Let the agent act | s01-s04 | How do loop, tools, permissions, and hooks remain separate? |
| Handle complex work | s05-s08 | How do plans, subagents, skills, and compaction control context? |
| Remember and recover | s09-s11 | What should persist, and what happens after failure? |
| Run long tasks | s12-s14 | How are dependencies, background jobs, and schedules represented? |
| Coordinate agents | s15-s18 | How do mailboxes, task claiming, and worktrees limit interference? |
| Extend and assemble | s19-s20 | How does MCP enter one tool pool, and how do the parts combine? |
The three layers worth learning
The first layer is the API protocol. When the model returns text, the loop can finish. When it returns tool_use, the harness finds a handler, executes it, appends tool_result, and asks the model again. That turns “agent behavior” into observable requests, actions, and state transitions.
The second layer is execution. The course starts with Bash, then adds file operations, skills, tasks, and external MCP tools. The important lesson is not the number of tools. It is the separation between tool schemas, dispatch, execution, and result handling. The model proposes an action; your process performs it. Model intelligence never substitutes for operating-system authorization.
The third layer is duration. Context fills, jobs block, subagents fail, and parallel workers collide. Compaction, durable tasks, background notifications, team protocols, and worktrees expose those engineering problems. This makes the course more useful than a demo that only records one successful run.
A better way to work through it
Clone the repository, create an isolated environment, and use a test API key with a budget limit:
git clone https://github.com/shareAI-lab/learn-claude-code.git
cd learn-claude-code
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
python s01_agent_loop/code.py
Do not jump straight to s20. In s01, constrain the Bash handler to harmless commands such as pwd, ls, and a test command. In s02, log the tool name, arguments, duration, exit code, and truncated output. At s03, test exactly what the permission rules block and what they fail to block. At s06, observe how a fresh subagent context removes noise but can also omit implicit requirements. At s18, use a disposable Git repository to create a real parallel-edit conflict.
Run s20 only after those exercises. Read it as an architecture exam: which components share mutable state, which failures lack compensation, what disappears after process exit, which tool can escape the working directory, and where an MCP identity comes from. Answering those questions demonstrates harness understanding; merely receiving a final answer does not.
API cost, keys, and license
The repository is free to obtain, but inference is not. The quick start expects ANTHROPIC_API_KEY. Model requests, retries, subagents, summaries, and team workflows can all add token usage. The course does not promise a fixed run cost. Use Anthropic’s current console and pricing as the source of truth, enable budget alerts, isolate the key to a test project, and never commit .env.
The MIT license applies to repository material the project is authorized to license. It does not convert the Claude API, Claude models, third-party packages, data read by an example, or an external MCP service into MIT software. A product incorporating the lessons still needs dependency review, provider terms, data-processing analysis, and compliance work.
Tool execution is the real security lesson
Instructions can enter context through a README, web page, log, issue, or tool result. External text telling the agent to upload a secret, delete a directory, or ignore policy is data, not authority. A safe lab should therefore:
- Run in a disposable directory, container, or VM without home-directory or production-secret mounts.
- Grant read, write, process, network, and credential capabilities independently and minimally.
- Require human approval for deletion, publishing, payments, messages, permission changes, and external side effects.
- Enforce command allowlists, working directories, timeouts, output caps, and child-process cleanup.
- Treat tool results as untrusted input and log decisions, parameters, results, and operators.
- Cap model cost, API cost, concurrency, retries, and total run time.
s03 permissions and s04 hooks reveal control points, but they are not a complete security product. Production requires identity binding, tenant isolation, non-bypassable approvals, tamper-resistant audit records, secret scanning, network egress policy, retention controls, incident response, and safe upgrades.
Educational code, not a production runtime
The repository explicitly identifies simplifications: a full lifecycle event bus, rule-driven permission governance, complete trust workflows, session resume and fork, mature worktree lifecycle handling, and full MCP transport, OAuth, subscription, and polling behavior are not all implemented. Its JSONL mailbox is a teaching protocol, not a claim about a commercial product’s internals.
Consequently, s20 is useful for learning composition but inappropriate for unattended releases, customer repositories, or privileged operations. Productionization would add authentication, authorization, sandboxing, managed secrets, durable-state consistency, idempotency, compensation, observability, evaluations, human takeover, data governance, and supply-chain review. The course’s honesty about this gap is a strength.
Strengths and limitations
Strengths: incremental code, a coherent 20-lesson arc, multilingual narratives, executable examples, an MIT license, and a stable conceptual center in the agent loop. The course also acknowledges its production omissions rather than presenting a toy as a platform.
Limitations: the web track is stale relative to the root curriculum; meaningful runs incur provider cost; some arguments reflect the maintainers’ strong perspective rather than settled industry consensus; security and reliability are intentionally incomplete; and this is an explanatory reimplementation of harness ideas, not official Claude Code source code.
Who should take it
It fits Python developers, agent-platform engineers, teams designing tool permissions, and readers who want to understand the problems underneath orchestration libraries such as LangGraph. Learners should already understand exceptions, filesystems, subprocesses, Git, and API billing.
It is not the shortest route for prompt-writing beginners and not a purchasable production platform. Security teams can use it for threat-model exercises, but should not adopt example defaults as controls. Enterprise builders still need architecture review, data classification, red-team testing, and operational runbooks.
Bottom line
Learn Claude Code turns model tool use into an engineering process you can trace one step at a time. Its journey from one loop to permissions, memory, tasks, teams, and MCP provides a strong harness mental model. The best final project is not deploying s20. It is identifying every gap between s20 and production and designing a testable control for each high-impact action.
Follow the root s01-s20 track, modify every lesson, and write one failure test and one security control per chapter. That produces something more durable than another agent demo: a practical standard for judging whether an agent system is understandable, bounded, and operable.