From ae98db87189dfd94922bc909c2d669e709dae255 Mon Sep 17 00:00:00 2001 From: wehub-resource-sync Date: Mon, 13 Jul 2026 09:56:38 +0000 Subject: [PATCH] docs: preserve upstream English README --- README.en.md | 462 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 462 insertions(+) create mode 100644 README.en.md diff --git a/README.en.md b/README.en.md new file mode 100644 index 0000000..5acc0f2 --- /dev/null +++ b/README.en.md @@ -0,0 +1,462 @@ +[English](./README.md) | [中文](./README-zh.md) | [日本語](./README-ja.md) + +shareAI-lab%2Flearn-claude-code | Trendshift + +# Learn Claude Code -- Harness Engineering for Real Agents + +## Agency Comes from the Model. An Agent Product = Model + Harness. + +Before we write any code, one thing needs to be clear. + +**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. + +### Where Agency Comes From + +At the core of every agent is a neural network -- a Transformer, an RNN, a trained function -- shaped by billions of gradient updates on sequences of perception, reasoning, and action. Agency was never bestowed by the surrounding code. It was learned during training. + +Humans are the original proof. A biological neural network, refined by millions of years of evolutionary pressure, perceives the world through senses, reasons through a brain, and acts through a body. When DeepMind, OpenAI, or Anthropic say "agent," they all mean the same core thing: **a model that learned to act through training, plus the infrastructure that lets it operate in a specific environment.** + +The historical record is unambiguous: + +- **2013 -- DeepMind DQN plays Atari.** A single neural network, receiving only raw pixels and game scores, learned 7 Atari 2600 games -- surpassing prior algorithms and beating human experts in 3 of them. By 2015, scaled to [49 games at professional tester level](https://www.nature.com/articles/nature14236), published in *Nature*. No game-specific rules. One model, learning from experience. + +- **2019 -- OpenAI Five conquers Dota 2.** Five neural networks played [45,000 years of Dota 2 against themselves](https://openai.com/index/openai-five-defeats-dota-2-world-champions/) over 10 months, then defeated **OG** -- the TI8 world champions -- 2-0 in a live match. In the public arena, the AI won 99.4% of 42,729 games. No scripted strategies. Models learned teamwork through self-play. + +- **2019 -- DeepMind AlphaStar masters StarCraft II.** AlphaStar [beat a professional player 10-1](https://deepmind.google/blog/alphastar-mastering-the-real-time-strategy-game-starcraft-ii/) in closed matches, then reached [Grandmaster rank](https://www.nature.com/articles/d41586-019-03298-6) on the European server -- top 0.15% of 90,000 players. An incomplete-information, real-time game with a combinatorial action space far exceeding chess or Go. + +- **2019 -- Tencent Jueyu dominates Honor of Kings.** Tencent AI Lab's "Jueyu" system [defeated KPL professional players in full 5v5](https://www.jiemian.com/article/3371171.html) at the World Champion Cup semifinal. In 1v1 mode, pros [won just 1 out of 15 matches, lasting under 8 minutes at best](https://developer.aliyun.com/article/851058). Training intensity: one day equaled 440 human years. A model that learned the entire game from scratch through self-play. + +- **2024-2025 -- LLM agents reshape software engineering.** Claude, GPT, Gemini -- large language models trained on the full breadth of human code and reasoning -- are deployed as coding agents. They read codebases, write implementations, debug failures, and coordinate as teams. The architecture is identical to every previous agent: a trained model, placed in an environment, given tools for perception and action. + +Every milestone points to the same fact: **Agency -- the ability to perceive, reason, and act -- is trained, not coded.** But every agent also needs an environment to operate in: an Atari emulator, the Dota 2 client, the StarCraft II engine, an IDE and a terminal. The model supplies the intelligence. The environment supplies the action space. Together they form a complete agent. + +### What an Agent Is NOT + +The word "agent" has been hijacked by an entire prompt-plumbing industry. + +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. That is not an agent. That is a shell script with grandiose pretensions. + +You cannot brute-force intelligence by stacking procedural logic -- sprawling rule trees, node graphs, chained prompt waterfalls -- and praying that enough glue code will spontaneously produce autonomous behavior. It will not. You cannot engineer agency into existence. Agency is learned, not coded. + +### The Mindshift: From "Building Agents" to Building Harnesses + +When someone says "I am building an agent," they can only mean one of two things: + +**1. Training a model.** Adjusting weights through reinforcement learning, fine-tuning, RLHF, or another gradient-based method. Collecting trajectory data -- real-world sequences of perception, reasoning, and action in a target domain -- and using it to shape the model's behavior. This is what DeepMind, OpenAI, Tencent AI Lab, and Anthropic do. + +**2. Building a harness.** Writing the code that gives a model an operational environment. This is what most of us do, and it is the core of this repository. + +A harness is everything an agent needs to work in a specific domain: + +``` +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 +``` + +The model decides. The harness executes. The model reasons. The harness provides context. The model is the driver. The harness is the vehicle. + +This repository teaches you to build the vehicle. A vehicle for coding. But the design patterns generalize to any domain. + +### What Harness Engineers Actually Do + +If you are reading this repository, you are most likely a harness engineer. Here is what the job actually entails: + +- **Implement tools.** Give the agent hands. File read/write, shell execution, API calls, browser control, database queries. Each tool is one action the agent can take in its environment. Design them atomic, composable, and clearly described. + +- **Curate knowledge.** Give the agent domain expertise. Product documentation, architecture decision records, style guides, compliance requirements. Load on demand, not upfront. + +- **Manage context.** Give the agent clean memory. Subagent isolation prevents noise leakage. Context compaction prevents history from drowning the present. Task systems let goals persist beyond a single conversation. + +- **Control permissions.** Give the agent boundaries. Sandbox file access. Require approval for destructive operations. Enforce trust boundaries between the agent and external systems. + +- **Collect trajectory data.** 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. + +You are not writing intelligence. You are building the world that intelligence inhabits. The quality of that world directly determines how effectively the intelligence can express itself. + +**Build the harness well. The model will do the rest.** + +### Why Claude Code + +Because Claude Code is the most elegant, most complete agent harness implementation we have seen. Not because of any clever trick, but because of what it *does not* do: it does not try to be the agent. It does not impose rigid workflows. It does not substitute hand-crafted decision trees for the model's own judgment. It gives the model tools, knowledge, context management, and permission boundaries -- then gets out of the way. + +Strip Claude Code down to its essence: + +``` +Claude Code = one agent loop + + tools (bash, read, write, edit, glob, grep, browser...) + + on-demand skill loading + + context compaction + + subagent spawning + + task system with dependency graphs + + async mailbox team coordination + + worktree-isolated parallel execution + + permission governance + + hooks extension system + + memory persistence + + MCP external capability routing +``` + +That is it. The agent itself? Claude. A model. Trained by Anthropic on the full breadth of human reasoning and code. The harness did not make Claude smart. Claude was already smart. The harness gave Claude hands, eyes, and a workspace. + +The takeaway is not "copy Claude Code." The takeaway is: **the best agent products come from engineers who understand that their job is the harness, not the intelligence.** + +--- + +``` + THE AGENT PATTERN + ================= + + User --> messages[] --> LLM --> response + | + stop_reason == "tool_use"? + / \ + yes no + | | + execute tools return text + append results + loop back -----------------> messages[] + + + The model decides when to call tools and when to stop. + The code just executes what the model asks for. + This repo teaches you to build everything around this loop -- + the harness that makes the agent effective in a specific domain. +``` + +## Core Pattern + +```python +def agent_loop(messages): + while True: + response = client.messages.create( + model=MODEL, system=SYSTEM, + messages=messages, tools=TOOLS, + ) + messages.append({"role": "assistant", + "content": response.content}) + + if response.stop_reason != "tool_use": + return + + results = [] + for block in response.content: + if block.type == "tool_use": + output = TOOL_HANDLERS[block.name](**block.input) + results.append({ + "type": "tool_result", + "tool_use_id": block.id, + "content": output, + }) + messages.append({"role": "user", "content": results}) +``` + +Every lesson layers one harness mechanism on top of this loop -- the loop itself never changes. The loop belongs to the agent. The mechanisms belong to the harness. + +The loop is constant. Tools, knowledge, and permissions change. Agent = Model (LLM) + a generalized operational environment (Harness). + +--- + +## Version Status + +This repository currently contains two tutorial tracks: + +- **Current track: root-level `s01-s20`** + The root-level `s01_*` ... `s20_*` folders are the new canonical version. Each chapter contains a full narrative README, translations, runnable `code.py`, and diagrams where needed. +- **Legacy transition track: `docs/`, `agents/`, and the current `web/` app** + These still preserve the older 12-lesson version. They are kept temporarily for existing readers, old links, and the web platform while the new 20-lesson track settles. + +If you are starting now, read the root-level `s01_agent_loop/` through `s20_comprehensive/` chapters. If you are following an older link or using the current web app, you are likely reading the legacy 12-lesson track. The legacy and current chapter numbers do not always match, so avoid mixing chapter numbers across tracks. + +### Legacy-to-Current Mapping + +| Legacy 12-lesson track | Current 20-lesson track | Topic | +|---|---|---| +| old s01 | new s01 | Agent Loop | +| old s02 | new s02 | Tool Use | +| old s03 | new s05 | TodoWrite | +| old s04 | new s06 | Subagent | +| old s05 | new s07 | Skill Loading | +| old s06 | new s08 | Context Compact | +| old s07 | new s12 | Task System | +| old s08 | new s13 | Background Tasks | +| old s09 | new s15 | Agent Teams | +| old s10 | new s16 | Team Protocols | +| old s11 | new s17 | Autonomous Agents | +| old s12 | new s18 | Worktree Isolation | +| new only | s03, s04, s09, s10, s11, s14, s19, s20 | Permission, Hooks, Memory, System Prompt, Error Recovery, Cron, MCP, Comprehensive Agent | + +--- + +## Scope + +This repository is a 0-to-1 harness engineering learning project: it teaches how to build the working environment around an agent model. To keep the learning path clear, some production mechanisms are intentionally simplified or omitted: + +- Full event / hook bus behavior, such as `PreToolUse`, `SessionStart/End`, and `ConfigChange`. + The teaching code uses minimal lifecycle events where needed. +- Rule-based permission governance and full trust workflows. +- Session lifecycle controls such as resume/fork, plus more complete worktree lifecycle handling. +- Full MCP runtime details such as transport, OAuth, resource subscription, and polling. + +The JSONL mailbox protocol in this repository is a teaching implementation, not a claim about any specific production internal implementation. + +--- + +## 20 Progressive Lessons + +**Each lesson adds one harness mechanism. Each mechanism has a motto.** + +> **s01**   *"One loop & Bash is all you need"* — one tool + one loop = one agent +> +> **s02**   *"Adding a tool means adding one handler"* — the loop stays untouched; new tools register into the dispatch map +> +> **s03**   *"Set boundaries first, then grant freedom"* — check what can run, what must stop, and what needs approval +> +> **s04**   *"Hook around the loop, never rewrite the loop"* — add extension points without changing the main loop +> +> **s05**   *"An agent without a plan drifts"* — list the steps before starting; completion rate doubles +> +> **s06**   *"Big tasks split small, each subtask gets clean context"* — subagents do the side work and bring back only the result +> +> **s07**   *"Load knowledge on demand, not upfront"* — list skills first, expand them only when needed +> +> **s08**   *"Context always fills up -- have a way to make room"* — multi-layer compaction strategies buy you infinite sessions +> +> **s09**   *"Remember what matters, forget what doesn't"* — three subsystems: selection, extraction, consolidation +> +> **s10**   *"Prompts are assembled at runtime, not hardcoded"* — section-based concatenation, loaded on demand +> +> **s11**   *"Errors aren't the end, they're the start of a retry"* — retry, make room, or take another path when things fail +> +> **s12**   *"Big goals break into small tasks, ordered, persisted to disk"* — a file-backed task graph that lays the groundwork for multi-agent coordination +> +> **s13**   *"Slow ops go background, agent keeps thinking"* — background threads run commands; notifications inject on completion +> +> **s14**   *"Fire on schedule, no human kick needed"* — trigger tasks automatically by time +> +> **s15**   *"Too big for one agent -- delegate to teammates"* — persistent teammates + async mailboxes +> +> **s16**   *"Teammates need shared communication rules"* — use a fixed request-reply format for coordination +> +> **s17**   *"Teammates check the board, claim work themselves"* — no leader assigning one by one; self-organizing +> +> **s18**   *"Each works in its own directory, no interference"* — tasks own goals, worktrees own directories, bound by ID +> +> **s19**   *"Not enough capability? Plug in more via MCP"* — connect external tools into the same tool pool +> +> **s20**   *"Many mechanisms, one loop"* — all previous mechanisms return to one complete harness + +--- + +## Learning Path + +Main line: act → handle complex work → remember and recover → run long tasks → collaborate → extend and assemble. + +```mermaid +flowchart TD + %% Card styles + classDef stage1 fill:#E3F2FD,stroke:#1976D2,stroke-width:2px,color:#0D47A1,rx:12,ry:12,text-align:left + classDef stage2 fill:#E8F5E9,stroke:#388E3C,stroke-width:2px,color:#1B5E20,rx:12,ry:12,text-align:left + classDef stage3 fill:#FFF3E0,stroke:#F57C00,stroke-width:2px,color:#E65100,rx:12,ry:12,text-align:left + classDef stage4 fill:#FCE4EC,stroke:#C2185b,stroke-width:2px,color:#880E4F,rx:12,ry:12,text-align:left + classDef stage5 fill:#F3E5F5,stroke:#7B1FA2,stroke-width:2px,color:#4A148C,rx:12,ry:12,text-align:left + classDef stage6 fill:#E0F7FA,stroke:#0097A7,stroke-width:2px,color:#006064,rx:12,ry:12,text-align:left + + %% Group style + classDef groupBox fill:#F8F9FA,stroke:#CED4DA,stroke-width:2px,stroke-dasharray: 5 5,rx:15,ry:15,color:#495057 + + %% Layer 1: stages 1-3 + subgraph Phase1 ["🌱 Stages 1-3: Core capabilities (simple to complex)"] + direction LR + S1["1. Let the Agent act
━━━━━━━━━━━━━
s01 Agent Loop
└─ one loop + bash

s02 Tool Use
└─ one tool to many tools

s03 Permission
└─ decide what can run

s04 Hooks
└─ extension points around tools"]:::stage1 + + S2["2. Handle complex work
━━━━━━━━━━━━━
s05 TodoWrite
└─ plan first, then execute

s06 Subagent
└─ side work, result back

s08 Context Compact
└─ make room in long context"]:::stage2 + + S3["3. Remember and recover
━━━━━━━━━━━━━
s09 Memory
└─ remember what matters

s10 System Prompt
└─ assemble at runtime

s11 Error Recovery
└─ retry or change path"]:::stage3 + + S1 ==> S2 ==> S3 + end + + %% Layer 2: stages 4-6 + subgraph Phase2 ["🚀 Stages 4-6: Advanced capabilities (long-running, collaboration, integration)"] + direction LR + S4["4. Run long tasks
━━━━━━━━━━━━━
s12 Task System
└─ persist tasks and deps

s13 Background Tasks
└─ send slow work background

s14 Cron Scheduler
└─ trigger by time"]:::stage4 + + S5["5. Coordinate many Agents
━━━━━━━━━━━━━
s15 Agent Teams
└─ teammates + mailboxes

s16 Team Protocols
└─ fixed request-reply format

s17 Autonomous Agents
└─ claim work from the board

s18 Worktree Isolation
└─ separate directories"]:::stage5 + + S6["6. Extend and assemble
━━━━━━━━━━━━━
s07 Skill Loading
└─ expand skills on demand

s19 MCP Plugin
└─ external tools, one pool

s20 Comprehensive Agent
└─ all mechanisms, one loop"]:::stage6 + + S4 ==> S5 ==> S6 + end + + %% Connect the two layers + Phase1 ===> Phase2 + + class Phase1,Phase2 groupBox +``` + +--- + +## All Chapters + +| Chapter | Topic | Key Concepts | +|---|---|---| +| [s01](./s01_agent_loop/) | Agent Loop | `messages` / `while True` / `stop_reason` | +| [s02](./s02_tool_use/) | Tool Use | `TOOL_HANDLERS` / dispatch map / concurrency | +| [s03](./s03_permission/) | Permission System | `PermissionRule` / approval pipeline | +| [s04](./s04_hooks/) | Hook System | `PreToolUse` / `PostToolUse` / extension points | +| [s05](./s05_todo_write/) | TodoWrite | `TodoItem` / plan-then-execute | +| [s06](./s06_subagent/) | Subagent | `fresh messages[]` / context isolation | +| [s07](./s07_skill_loading/) | Skill Loading | `SkillManifest` / on-demand injection | +| [s08](./s08_context_compact/) | Context Compact | snipCompact / microCompact / toolResultBudget / autoCompact | +| [s09](./s09_memory/) | Memory System | selection / extraction / consolidation | +| [s10](./s10_system_prompt/) | System Prompt | runtime assembly / section concatenation | +| [s11](./s11_error_recovery/) | Error Recovery | token escalation / fallback model / retry strategies | +| [s12](./s12_task_system/) | Task System | `TaskRecord` / `blockedBy` / disk persistence | +| [s13](./s13_background_tasks/) | Background Tasks | threaded execution / notification queue | +| [s14](./s14_cron_scheduler/) | Cron Scheduler | durable scheduling / session-scoped triggers | +| [s15](./s15_agent_teams/) | Agent Teams | `MessageBus` / inbox / permission bubbling | +| [s16](./s16_team_protocols/) | Team Protocols | shutdown handshake / plan approval | +| [s17](./s17_autonomous_agents/) | Autonomous Agents | idle cycle / auto-claim / self-organization | +| [s18](./s18_worktree_isolation/) | Worktree Isolation | `WorktreeRecord` / task-directory binding | +| [s19](./s19_mcp_plugin/) | MCP Plugin | multi-transport / channel routing / tool pool assembly | +| [s20](./s20_comprehensive/) | Comprehensive Agent | all mechanisms around one loop | + +--- + +## How to Read + +Each chapter is a folder. Open one and you will find: + +``` +s08_context_compact/ + README.md # full narrative with inline code + README.en.md # English translation + README.ja.md # Japanese translation + code.py # standalone runnable implementation + images/ # SVG diagrams (where needed) +``` + +Read the `README.md` for the core idea and work through the code. Complex chapters have `
` folds for deep dives -- open them when you want to go deeper. Simple chapters have 0-1 diagrams, complex chapters have more. + +Read from s01 through s20 in order. Each chapter assumes you've read the previous ones and ends with a hook into the next. + +--- + +## Quick Start + +### Current 20-Lesson Track + +```sh +git clone https://github.com/shareAI-lab/learn-claude-code +cd learn-claude-code +pip install -r requirements.txt +cp .env.example .env # configure ANTHROPIC_API_KEY + +python s01_agent_loop/code.py # Start here -- one loop + bash +python s08_context_compact/code.py # Context compaction (complex) +python s20_comprehensive/code.py # Endpoint: all mechanisms in one loop +``` + +### Legacy 12-Lesson Track + +```sh +python agents/s01_agent_loop.py +python agents/s12_worktree_task_isolation.py +python agents/s_full.py +``` + +### Web Platform + +The current web app still renders the legacy `docs/` s01-s12 track. Use the root-level folders for the new s01-s20 track. + +```sh +cd web && npm install && npm run dev # http://localhost:3000 +``` + +--- + +## Project Structure + +``` +learn-claude-code/ + s01_agent_loop/ # one folder per chapter + README.md # Chinese source (complete narrative) + README.en.md # English translation + README.ja.md # Japanese translation + code.py # standalone runnable code + images/ # SVG diagrams + s02_tool_use/ + ... + s19_mcp_plugin/ + s20_comprehensive/ # endpoint chapter + agents/ # legacy 12 runnable copies + s_full.py + skills/ # skill files used by s07 + docs/ # legacy 12-lesson docs, kept during transition + web/ # currently renders the legacy docs/ track + tests/ +``` + +--- + +## What's Next + +After 20 lessons, you understand harness engineering from the inside out. Two paths to turn that knowledge into product: + +### Kode Agent CLI -- Open-Source Coding Agent CLI + +> `npm i -g @shareai-lab/kode` + +Skill and LSP support, Windows compatible, works with GLM / MiniMax / DeepSeek and other open models. Install and go. + +GitHub: **[shareAI-lab/Kode-CLI](https://github.com/shareAI-lab/Kode-CLI)** + +### Kode Agent SDK -- Embed Agent Capabilities in Your Application + +A standalone library with no per-user process overhead. Embed it in backends, browser extensions, embedded devices, or any runtime. + +GitHub: **[shareAI-lab/kode-agent-sdk](https://github.com/shareAI-lab/kode-agent-sdk)** + +--- + +## Sister Tutorial: From Passive Sessions to Always-On Assistants + +The harness taught in this repository is the **use-and-discard** kind -- open a terminal, give the agent a task, close when done, next session starts fresh. Claude Code works this way. + +But [OpenClaw](https://github.com/openclaw/openclaw) proves another possibility: on the same agent core, two additional harness mechanisms turn an agent from "poke it and it moves" into "wakes itself every 30 seconds to look for work": + +- **Heartbeat** -- every 30 seconds the harness sends the agent a message, letting it check for pending work. Nothing to do? Keep sleeping. Something appeared? Act immediately. +- **Cron** -- the agent can schedule its own future tasks, which fire automatically when the time arrives. + +Add IM multi-channel routing (WhatsApp / Telegram / Slack / Discord and 13+ other platforms), persistent context memory, and a Soul personality system, and the agent transforms from a disposable tool into an always-on personal AI assistant. + +**[claw0](https://github.com/shareAI-lab/claw0)** is our sister teaching repository, breaking down these harness mechanisms from scratch: + +``` +claw agent = agent core + heartbeat + cron + IM chat + memory + soul +``` + +``` +learn-claude-code claw0 +(agent harness internals: (always-on harness: + loop, tools, planning, heartbeat, cron, IM channels, + teams, worktree isolation) memory, Soul personality) +``` + +## License + +MIT + +--- + +**Agency comes from the model. The harness gives agency a place to land. Build the harness well, and the model will do the rest.** + +**Bash is all you need. Real agents are all the universe needs.** + +**This is not "copy the source code." This is "grasp the key designs and build it yourself."**