Skip to content
/
Tier B A13 Methodology

learn-claude-code

learn-claude-code · shareAI-lab/learn-claude-code · ★ 63k · last commit 2026-05-26

Primitive shape 4 total
Skills 4
00

Summary

learn-claude-code — Summary

learn-claude-code by shareAI-lab is the most comprehensive harness-engineering curriculum in this batch: 62,800 stars, 23 contributors, trilingual (English, Chinese, Japanese), 20 structured lessons covering the complete arc from basic agent loops to autonomous teams, MCP plugins, and worktree isolation. Each lesson (s01–s20) contains a README in 3 languages plus working Python code demonstrating the concept. Topics include: agent loop, tool use, permissions, hooks, TodoWrite, subagents, skill loading, context compaction, memory, system prompts, error recovery, task systems, background tasks, cron scheduling, agent teams, team protocols, autonomous agents, worktree isolation, MCP plugins, and a comprehensive final project. The repo ships 4 community skills in .skills/ (agent-builder, code-review, mcp-builder, pdf), a Next.js web companion (web/), and tests (tests/). The README opens with a philosophical declaration that "agency comes from the model, not from external code orchestration."

Differs from seeds: Unlike any seed, this is an educational harness engineering curriculum — not a deployable framework. The closest structural parallel is superpowers (teaching what Claude Code can do) but learn-claude-code teaches implementation-level harness engineering (how to build the vehicle, not how to use it). The philosophical framing ("agency is trained, not coded; harness engineers build the vehicle") is the most intellectually rigorous anti-pattern argument in the corpus, directly refuting "drag-and-drop workflow builders" and "no-code AI Agent platforms."

01

Overview

learn-claude-code — Overview

Origin

By shareAI-lab. 62,800 stars, 23 contributors, MIT license. Available in English, Chinese (README-zh.md), and Japanese (README-ja.md). Last commit 2026-05-26 (actively maintained).

Mission (verbatim)

"Agency — the capacity to perceive, reason, and act — comes from model training, not from external code orchestration. But a working agent product needs both the model and the harness. The model is the driver. The harness is the vehicle. This repository teaches you how to build the vehicle."

The "Rube Goldberg" critique (verbatim)

"Drag-and-drop workflow builders. No-code 'AI Agent' platforms. Prompt-chain orchestration libraries. They share a single delusion: that stringing LLM API calls together with if-else branches, node graphs, and hardcoded routing logic constitutes 'building an agent.' It does not. What they produce are Rube Goldberg machines — over-engineered, brittle, procedural rule pipelines with an LLM wedged in as a glorified text-completion node."

Harness definition (verbatim)

Harness = Tools + Knowledge + Observation + Action Interfaces + Permissions

    Tools:          file I/O, shell, network, database, browser
    Knowledge:      product docs, domain references, API specs, style guides
    Observation:    git diff, error logs, browser state, sensor data
    Action:         CLI commands, API calls, UI interactions
    Permissions:    sandbox isolation, approval workflows, trust boundaries

Curriculum philosophy

"Every action sequence the agent executes in your harness is training signal. Real deployment trajectories are the raw material for fine-tuning the next generation of agent models."

Historical framing

The README grounds the curriculum in milestones: DQN (2013), OpenAI Five (2019), AlphaStar (2019), Tencent Jueyu (2019), LLM coding agents (2024-2025) — arguing that agency has always been trained, never coded.

02

Architecture

learn-claude-code — Architecture

Distribution

standalone-repo — clone and study. Also has a web companion (Next.js/Vercel).

Install

git clone https://github.com/shareAI-lab/learn-claude-code
pip install -r requirements.txt   # Python examples

Directory structure

.
├── s01_agent_loop/          (while True loop basics)
├── s02_tool_use/            (tool calling patterns)
├── s03_permission/          (permission checks)
├── s04_hooks/               (hook injection pattern)
├── s05_todo_write/          (TodoWrite tool)
├── s06_subagent/            (subagent spawning)
├── s07_skill_loading/       (skill loading)
├── s08_context_compact/     (context compaction)
├── s09_memory/              (memory systems)
├── s10_system_prompt/       (system prompt design)
├── s11_error_recovery/      (error handling)
├── s12_task_system/         (task management)
├── s13_background_tasks/    (background execution)
├── s14_cron_scheduler/      (cron scheduling)
├── s15_agent_teams/         (team coordination)
├── s16_team_protocols/      (team communication protocols)
├── s17_autonomous_agents/   (autonomous behavior)
├── s18_worktree_isolation/  (git worktree per task)
├── s19_mcp_plugin/          (MCP server building)
├── s20_comprehensive/       (synthesis project)
├── agents/                  (example agents)
├── skills/
│   ├── agent-builder/
│   ├── code-review/
│   ├── mcp-builder/
│   └── pdf/
├── tests/
├── web/                     (Next.js companion app)
└── requirements.txt         (Python deps)

Runtime requirements

  • Python 3.x (for lesson code examples)
  • Node.js (for web companion)
  • Anthropic API key (for running examples)

Each lesson structure

  • README.md (Chinese) + README.en.md (English) + README.ja.md (Japanese)
  • code.py — working Python implementation of the concept
  • images/ — SVG diagrams

Target AI tools

Claude Code (primary), but the Python code examples are standalone Anthropic SDK implementations.

03

Components

learn-claude-code — Components

Lesson modules (20, each with code.py + trilingual README + images)

Lesson Topic Key Concept
s01_agent_loop Agent Loop while True loop; stop on non-tool_use
s02_tool_use Tool Use Tool calling patterns
s03_permission Permissions Permission check hooks
s04_hooks Hooks PreToolUse/PostToolUse hook injection without modifying loop
s05_todo_write TodoWrite Task tracking via TodoWrite tool
s06_subagent Subagents Spawning specialized workers
s07_skill_loading Skill Loading Dynamic skill injection
s08_context_compact Context Compaction Compaction strategies
s09_memory Memory Memory persistence patterns
s10_system_prompt System Prompts System prompt design
s11_error_recovery Error Recovery Fault tolerance
s12_task_system Task System Task management
s13_background_tasks Background Tasks Async execution
s14_cron_scheduler Cron Scheduler Scheduled tasks
s15_agent_teams Agent Teams Team coordination
s16_team_protocols Team Protocols Communication protocols
s17_autonomous_agents Autonomous Agents Self-directed behavior
s18_worktree_isolation Worktree Isolation git worktree per task
s19_mcp_plugin MCP Plugin Building MCP servers
s20_comprehensive Comprehensive Full synthesis project

Community Skills (4 in skills/)

Name Purpose
agent-builder Build new Claude Code agents
code-review Code review automation
mcp-builder Build MCP servers
pdf PDF processing

Hooks (documented in s04, not deployed at project level)

Four hook events taught:

  • UserPromptSubmit
  • PreToolUse
  • PostToolUse
  • Stop

No deployed project-level primitives

Zero project-level commands, hooks, agents. The skills/ directory contains community-contributed skills but they are supplementary to the curriculum.

05

Prompts

learn-claude-code — Prompts

Prompt 1: Agent Loop lesson (s01) — core principle

Source: s01_agent_loop/README.en.md

Technique: Signal-table teaching pattern — reduce concept to binary signal

A `while True` loop: keep going when the model calls a tool, stop when it doesn't.
The entire process hinges on two signals:

| Signal | Meaning | Loop Action |
|--------|---------|-------------|
| `stop_reason == "tool_use"` | Model raises hand: "I need a tool" | Execute → feed result back → continue |
| `stop_reason != "tool_use"` | Model says: "I'm done" | Exit loop |

Key design: Reduces the entire agent loop concept to a two-row lookup table. The teaching technique is reduction to the minimum essential signal — a pattern used across all 20 lessons.

Prompt 2: Hooks lesson (s04) — "Hang on the loop, don't write into it"

Source: s04_hooks/README.en.md

Technique: Anti-pattern first, then solution pattern

> "Hang on the loop, don't write into it" — Hooks inject extension logic before and after tool execution.

## The Problem
The s03 Agent has permission checks. But every new check — "log every bash call", "auto git add after writes"
— requires modifying the `agent_loop` function.

The loop quickly becomes this:
def agent_loop(messages):
    while True:
        # ... LLM call ...
        for block in response.content:
            if block.type == "tool_use":
                log_to_file(block)          # added a line
                check_permission(block)     # added a line
                notify_slack(block)         # added another line
                output = execute(block)
                auto_git_add(block)         # yet another line

## The Solution
Four events, covering a complete agent cycle:
| Event | Trigger Timing |
|-------|---------------|
| UserPromptSubmit | After user input, before LLM |
| PreToolUse | Before tool execution |
| PostToolUse | After tool execution |
| Stop | When loop is about to exit |

This is the clearest pedagogical explanation of the hook pattern in the entire corpus.

09

Uniqueness

learn-claude-code — Uniqueness

Differs from seeds

No seed matches this archetype. The closest conceptual parallel is superpowers (teaches what Claude Code can do), but learn-claude-code teaches implementation-level harness engineering from first principles — starting with a while-True loop, not with a finished framework. The philosophical framing (agency is trained, not coded; harness engineers build vehicles) is the most rigorous intellectual critique of naive "AI agent" frameworks in the entire corpus. With 62,800 stars, this is the highest-star framework in this batch by a factor of 2.3x over the next (davila7 at 27,587). The trilingual (EN/ZH/JA) curriculum and SVG-diagram-per-lesson pedagogical structure are unique. The curriculum's coverage breadth (20 topics from basic loop to MCP plugins, cron scheduling, and agent teams) exceeds any other educational resource in the batch.

Positioning

The premier harness engineering education resource for Claude Code. Targeted at developers who want to build on top of Claude Code rather than use pre-built frameworks. The high star count reflects its value as the go-to reference for understanding Claude Code's internals from first principles.

Observable failure modes

  1. Teaches building, not using: Developers who want a ready-made workflow get no help here.
  2. Python-first: All code examples are Python; Claude Code is typically TypeScript/shell. Some translation required.
  3. No deployment path: Learning harness engineering requires additional steps to actually deploy what you build.
  4. Curriculum gap at s20: The "comprehensive" final lesson may not fully synthesize all 19 prior concepts.
  5. Rapid obsolescence risk: Claude Code's primitives evolve quickly; a hooks lesson from 6 months ago may not reflect current API.
04

Workflow

learn-claude-code — Workflow

Curriculum progression

The lessons are explicitly numbered and sequential, each building on the previous:

s01 → s02 → s03 → s04 → ... → s20

Each lesson cites its position: s01 → [s02] → s03 → s04 → ...

Learning workflow per lesson

  1. Read README.en.md (conceptual explanation with the problem + solution)
  2. Study SVG diagrams in images/
  3. Read code.py (working Python implementation)
  4. Run code.py with your own Anthropic API key
  5. Experiment / adapt to your own use case

Hook teaching pattern (s04)

The hooks lesson explicitly demonstrates the "hang on the loop, don't write into it" principle:

  • The core agent_loop() function is never modified
  • New behaviors are added via trigger_hooks("PreToolUse", block) registry
  • Four events: UserPromptSubmit, PreToolUse, PostToolUse, Stop

Agent team progression (s15–s17)

  • s15: basic team coordination
  • s16: team communication protocols
  • s17: autonomous agents (self-directed behavior)

No approval gates — self-paced learning.

06

Memory Context

learn-claude-code — Memory & Context

Memory lessons

  • s08_context_compact — context compaction strategies
  • s09_memory — memory persistence patterns (file-based, session, global)

Curriculum state

Each lesson's code.py is stateless when run individually. Students accumulate understanding progressively through the numbered sequence.

Web companion state

The web/ Next.js application may provide a stateful learning tracker (not fully fetched).

No framework-level memory.

07

Orchestration

learn-claude-code — Orchestration

Multi-agent (taught)

Lessons s15–s17 teach agent team coordination, team protocols, and autonomous behavior. The s18_worktree_isolation lesson teaches worktree-per-agent isolation.

No deployed orchestration

The curriculum teaches orchestration concepts via Python examples; no Claude Code primitives are deployed for orchestration.

Execution mode taught

  • s01–s14: single-agent interactive-loop
  • s13: background-daemon
  • s14: scheduled (cron)
  • s15–s17: multi-agent team patterns
  • s17: continuous-ralph style autonomous behavior

Harness model

The framework's own stated conceptual model:

Harness = Tools + Knowledge + Observation + Action Interfaces + Permissions
08

Ui Cli Surface

learn-claude-code — UI & CLI Surface

Dedicated CLI

None.

Web companion

web/ — Next.js application deployed to Vercel. Purpose: companion site for the curriculum (likely interactive lesson browser or learning tracker). Not self-hosted as a local dashboard.

IDE integration

4 community skills in skills/ (agent-builder, code-review, mcp-builder, pdf) can be installed as Claude Code skills.

Python examples

Each lesson's code.py is a standalone runnable Python file. These are the primary "CLI surface" — run with python s04_hooks/code.py.

Observability

None at framework level.

Related frameworks

same archetype · same primary tool · same memory type

Context-Engineering Handbook ★ 9.0k
A13 Methodology

Provides a first-principles, research-grounded vocabulary and learning path for context engineering — the discipline of designing…

walkinglabs/learn-harness-engineering ★ 6.6k
A13 Methodology

Teach harness engineering from first principles (12 lectures + 6 projects) and provide a scaffolding skill (harness-creator) that…

Awesome Harness Engineering (walkinglabs) ★ 2.7k
A13 Methodology

Curate the authoritative reference list of articles, benchmarks, and tools for harness engineering — the practice of shaping the…

cline-memory-bank (nickbaumann98) ★ 581
A13 Methodology

Custom instructions + 6-file hierarchical Markdown memory bank so Cline maintains full project context across sessions, with a…

FPF (First Principles Framework) ★ 372
A13 Methodology

Provides a formal pattern language for making reasoning explicit, traceable, and publishable in mixed human/AI engineering work —…

nexu-io/harness-engineering-guide ★ 134
A13 Methodology

Provide a practical, code-first reference guide to harness engineering — from first principles to production patterns —…