learn-claude-code: Harness Engineering for Real Claude Agents

The core argument: agency is trained, harnesses are built

The repository opens with a position that shapes all 17 sessions. The README states that agency, defined as the capacity to perceive, reason and act, comes from model training rather than from code orchestration. The historical record it cites is specific: DeepMind's DQN learned 49 Atari games at professional tester level in 2015; OpenAI Five defeated OG, the TI8 world champions, 2-0 in a live Dota 2 match in 2019 after training for the equivalent of 45,000 human years; DeepMind AlphaStar reached Grandmaster rank on the European StarCraft II server, placing in the top 0.15% of 90,000 players; Tencent's Jueyu defeated KPL professional players in full 5v5 Honor of Kings. Every milestone involved a trained model, not a framework that imposed agentic behavior from outside.

The practical consequence is a distinction between two activities. Training a model adjusts weights through gradient-based methods. Building a harness writes the code that gives a trained model an operational environment. The repository teaches the second activity.

The README explicitly criticises drag-and-drop workflow builders and prompt-chain orchestration libraries as producing what it calls Rube Goldberg machines: procedural rule pipelines with an LLM used as a text completion node. The repository's approach treats the model as the decision-maker and the harness as the infrastructure that provides context and executes actions.

What a harness consists of

The README defines a harness as five components, shown in this diagram from the repository:

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

Tools give the model actions it can take. Knowledge provides domain expertise loaded on demand rather than up front. Observation feeds the model information about the current state of the environment. Permissions define what the agent is allowed to do and in what context.

The README describes the harness engineer's job in concrete terms: implement tools that are atomic, composable and clearly described; curate knowledge such as product documentation, architecture decision records and compliance requirements; manage context by keeping subagent work in a separate message list and using context compaction to shorten older history; let task systems make goals persist beyond a single conversation.

The 17 sessions and what they cover

The repository contains 17 numbered directories. The first block, sessions s01 through s05, builds the foundation: the basic agent loop, tool use, permission handling, hooks and the TodoWrite pattern for structured task tracking.

Sessions s06 through s09 address runtime management: subagent architecture for keeping focused work in isolated message contexts, skill loading for injecting domain expertise on demand, context compaction for shortening growing message histories, and memory mechanisms that survive context boundaries. The README notes that subagents keep focused work in a separate message list, context compaction shortens older history, and task systems let goals persist beyond a single conversation.

Sessions s10 through s12 cover persistence and scheduling: a task system that lets goals live beyond a single conversation, background task execution and a cron scheduler for recurring work.

Sessions s13 through s17 address multi-agent and production concerns: agent teams that coordinate across roles, MCP plugin integration for connecting the harness to external tool servers, the integrated harness combining all prior components, a workflow runtime and a goal-directed loop that drives the agent toward a defined objective.

Additional directories include agents/, docs/, skills/, tests/ and web/. The presence of a web/ directory suggests the repository includes a browser-based interface, though the README does not describe its contents in detail.

Setting up and running the first session

Three Python packages are required, as listed in requirements.txt:

anthropic>=0.25.0
python-dotenv>=1.0.0
pyyaml>=6.0

Configuration requires a copy of .env.example renamed to .env. The minimum configuration is two variables:

ANTHROPIC_API_KEY=sk-ant-xxx
MODEL_ID=claude-sonnet-4-6

The .env.example also documents configurations for several Anthropic-compatible providers, including MiniMax (MiniMax-M3), GLM/Zhipu (glm-5.2), Kimi/Moonshot (kimi-k2.7-code) and DeepSeek (deepseek-v4-pro and deepseek-v4-flash). Each provider requires a different ANTHROPIC_BASE_URL in addition to the MODEL_ID. The comments note that Anthropic-compatible does not guarantee identical model behavior: providers may differ in supported parameters, reasoning defaults, response content blocks and tool-use history requirements. The file recommends the default Anthropic setup for the most predictable course experience.

What the repository does not cover

The repository teaches harness construction in Python against the Anthropic SDK. It does not teach how to use the Claude Code CLI as an end user: there are no sessions on Claude Code's slash commands, MCP server configuration through Claude Code's settings file, or the Claude Code permission system as experienced by an operator.

Fine-tuning models and reinforcement learning are explicitly outside scope. The README draws the line clearly: the repository is for harness engineers, not model trainers. It does not cover how to collect trajectory data or run RLHF, which the README describes as what DeepMind, OpenAI and Anthropic actually do.

The last push was on 2026-08-26. There are no GitHub releases, so there is no changelog. Users following the sessions should use the version constraints in requirements.txt rather than installing the latest versions of packages, to reduce the risk of breaking changes in the anthropic package between sessions. The CONTRIBUTING.md file is present in the repository for developers who want to add sessions or fix examples.

Comparing learn-claude-code to LangChain tutorials

LangChain and LangGraph tutorials teach agent construction through high-level abstractions: chains, graphs and callbacks. learn-claude-code takes a lower-level approach, building the agent loop and tool dispatcher from first principles using the Anthropic SDK directly.

The README's criticism of orchestration libraries as producing brittle procedural pipelines applies directly to LangChain-style frameworks. An engineer who completes the 17 sessions understands what happens inside those abstractions rather than relying on them as a dependency. The cost is that the resulting harness is tied to the Anthropic SDK and the Claude model family, whereas a LangChain implementation can swap underlying models by changing a configuration parameter. For teams already committed to Claude, that constraint is not a limitation; for teams evaluating multiple model providers, it is.

The repository's position also differs from Microsoft's AutoGen and similar multi-agent frameworks in that it does not provide a pre-built agent communication layer. The s13_agent_teams session teaches how to build agent coordination from the harness level, rather than importing it as a library. Whether that depth is appropriate depends on whether the team needs to understand and control the exact communication protocol between agents.

Editorial conclusion

learn-claude-code is the right starting point for an engineer who wants to understand how Claude Code works internally and build a comparable harness for a different domain. It is not a tutorial on operating Claude Code as an end user: there are no sessions on slash commands, settings files or permission grants. Running the sessions requires an ANTHROPIC_API_KEY and incurs API costs; the .env.example recommends the default Anthropic endpoint for the most predictable course experience, rather than the third-party compatible providers it also documents.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository