mirror of
https://github.com/shareAI-lab/analysis_claude_code.git
synced 2026-09-20 12:13:38 +08:00
feat: refresh course through workflow and goal loops
This commit is contained in:
Haoran
75
README.md
75
README.md
@@ -167,16 +167,16 @@ The loop is constant. Tools, knowledge, and permissions change. Agent = Model (L
|
||||
|
||||
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.
|
||||
- **Current track: root-level `s01-s22`**
|
||||
The root-level `s01_*` ... `s22_*` folders are the canonical version. Each chapter contains an English default README, Chinese/Japanese translations, runnable `code.py`, and diagrams where needed.
|
||||
- **Legacy transition track: `docs/` and `agents/`**
|
||||
These preserve the older 12-lesson version for existing readers and old links during migration.
|
||||
|
||||
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.
|
||||
If you are starting now, read the root-level `s01_agent_loop/` through `s22_goal_loop/` chapters. 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 |
|
||||
| Legacy 12-lesson track | Current 22-lesson track | Topic |
|
||||
|---|---|---|
|
||||
| old s01 | new s01 | Agent Loop |
|
||||
| old s02 | new s02 | Tool Use |
|
||||
@@ -190,7 +190,7 @@ If you are starting now, read the root-level `s01_agent_loop/` through `s20_comp
|
||||
| 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 |
|
||||
| new only | s03, s04, s09, s10, s11, s14, s19, s20, s21, s22 | Permission, Hooks, Memory, Context Assembly, Error Recovery, Cron, MCP, Comprehensive Agent, Workflow Runtime, Goal Loop |
|
||||
|
||||
---
|
||||
|
||||
@@ -208,7 +208,7 @@ The JSONL mailbox protocol in this repository is a teaching implementation, not
|
||||
|
||||
---
|
||||
|
||||
## 20 Progressive Lessons
|
||||
## 22 Progressive Lessons
|
||||
|
||||
**Each lesson adds one harness mechanism. Each mechanism has a motto.**
|
||||
|
||||
@@ -240,9 +240,9 @@ The JSONL mailbox protocol in this repository is a teaching implementation, not
|
||||
>
|
||||
> **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
|
||||
> **s15** *"Too big for one agent -- delegate to teammates"* — Agent Teams runtime lab: persistent teammates + async mailboxes
|
||||
>
|
||||
> **s16** *"Teammates need shared communication rules"* — use a fixed request-reply format for coordination
|
||||
> **s16** *"Teammates need shared communication rules"* — Agent Teams protocol lab: typed request-reply coordination
|
||||
>
|
||||
> **s17** *"Teammates check the board, claim work themselves"* — no leader assigning one by one; self-organizing
|
||||
>
|
||||
@@ -251,12 +251,16 @@ The JSONL mailbox protocol in this repository is a teaching implementation, not
|
||||
> **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
|
||||
>
|
||||
> **s21** *"When the orchestration shape is fixed, put it in code"* — deterministic workflows with resumable journals
|
||||
>
|
||||
> **s22** *"A goal decides when the loop may stop"* — continue until trusted evidence satisfies the goal
|
||||
|
||||
---
|
||||
|
||||
## Learning Path
|
||||
|
||||
Main line: act → handle complex work → remember and recover → run long tasks → collaborate → extend and assemble.
|
||||
Main line: act → handle complex work → remember and recover → run long tasks → collaborate → extend and assemble → orchestrate and close goals.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
@@ -278,7 +282,7 @@ flowchart TD
|
||||
|
||||
S2["<b>2. Handle complex work</b><br/>━━━━━━━━━━━━━<br/><b>s05 TodoWrite</b><br/>└─ plan first, then execute<br/><br/><b>s06 Subagent</b><br/>└─ side work, result back<br/><br/><b>s08 Context Compact</b><br/>└─ make room in long context"]:::stage2
|
||||
|
||||
S3["<b>3. Remember and recover</b><br/>━━━━━━━━━━━━━<br/><b>s09 Memory</b><br/>└─ remember what matters<br/><br/><b>s10 System Prompt</b><br/>└─ assemble at runtime<br/><br/><b>s11 Error Recovery</b><br/>└─ retry or change path"]:::stage3
|
||||
S3["<b>3. Remember and recover</b><br/>━━━━━━━━━━━━━<br/><b>s09 Memory</b><br/>└─ persist and recall across sessions<br/><br/><b>s10 Context Assembly</b><br/>└─ build model input from runtime state<br/><br/><b>s11 Error Recovery</b><br/>└─ retry or change path"]:::stage3
|
||||
|
||||
S1 ==> S2 ==> S3
|
||||
end
|
||||
@@ -288,17 +292,24 @@ flowchart TD
|
||||
direction LR
|
||||
S4["<b>4. Run long tasks</b><br/>━━━━━━━━━━━━━<br/><b>s12 Task System</b><br/>└─ persist tasks and deps<br/><br/><b>s13 Background Tasks</b><br/>└─ send slow work background<br/><br/><b>s14 Cron Scheduler</b><br/>└─ trigger by time"]:::stage4
|
||||
|
||||
S5["<b>5. Coordinate many Agents</b><br/>━━━━━━━━━━━━━<br/><b>s15 Agent Teams</b><br/>└─ teammates + mailboxes<br/><br/><b>s16 Team Protocols</b><br/>└─ fixed request-reply format<br/><br/><b>s17 Autonomous Agents</b><br/>└─ claim work from the board<br/><br/><b>s18 Worktree Isolation</b><br/>└─ separate directories"]:::stage5
|
||||
S5["<b>5. Coordinate many Agents</b><br/>━━━━━━━━━━━━━<br/><b>Agent Teams module</b><br/>├─ s15 Runtime Lab: teammates + mailboxes<br/>└─ s16 Protocol Lab: typed request-reply<br/><br/><b>s17 Autonomous Agents</b><br/>└─ claim work from the board<br/><br/><b>s18 Worktree Isolation</b><br/>└─ separate directories"]:::stage5
|
||||
|
||||
S6["<b>6. Extend and assemble</b><br/>━━━━━━━━━━━━━<br/><b>s07 Skill Loading</b><br/>└─ expand skills on demand<br/><br/><b>s19 MCP Plugin</b><br/>└─ external tools, one pool<br/><br/><b>s20 Comprehensive Agent</b><br/>└─ all mechanisms, one loop"]:::stage6
|
||||
|
||||
S4 ==> S5 ==> S6
|
||||
end
|
||||
|
||||
%% Connect the two layers
|
||||
Phase1 ===> Phase2
|
||||
%% Layer 3: orchestration and goal closure
|
||||
subgraph Phase3 ["🎯 Stage 7: Orchestration and goal closure"]
|
||||
direction LR
|
||||
S7["<b>7. Orchestrate and finish</b><br/>━━━━━━━━━━━━━<br/><b>s21 Workflow Runtime</b><br/>└─ scripts own fixed orchestration<br/><br/><b>s22 Goal Loop</b><br/>└─ trusted evidence decides when to stop"]:::stage1
|
||||
S6 ==> S7
|
||||
end
|
||||
|
||||
class Phase1,Phase2 groupBox
|
||||
%% Connect the three layers
|
||||
Phase1 ===> Phase2 ===> Phase3
|
||||
|
||||
class Phase1,Phase2,Phase3 groupBox
|
||||
```
|
||||
|
||||
---
|
||||
@@ -316,17 +327,19 @@ flowchart TD
|
||||
| [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 |
|
||||
| [s10](./s10_system_prompt/) | Context Assembly | runtime state / stable sections / model input |
|
||||
| [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 |
|
||||
| [s15](./s15_agent_teams/) | Agent Teams: Runtime Lab | `MessageBus` / inbox / permission bubbling |
|
||||
| [s16](./s16_team_protocols/) | Agent Teams: Protocol Lab | typed messages / 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 |
|
||||
| [s21](./s21_workflow_runtime/) | Workflow Runtime | script orchestration / background execution / journal resume |
|
||||
| [s22](./s22_goal_loop/) | Goal Loop | goal gate / trusted evidence / automatic continuation |
|
||||
|
||||
---
|
||||
|
||||
@@ -336,8 +349,8 @@ 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.md # English, the default chapter README
|
||||
README.zh.md # Chinese translation
|
||||
README.ja.md # Japanese translation
|
||||
code.py # standalone runnable implementation
|
||||
images/ # SVG diagrams (where needed)
|
||||
@@ -345,13 +358,13 @@ s08_context_compact/
|
||||
|
||||
Read the `README.md` for the core idea and work through the code. Complex chapters have `<details>` 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.
|
||||
Read from s01 through s22 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
|
||||
### Current 22-Lesson Track
|
||||
|
||||
```sh
|
||||
git clone https://github.com/shareAI-lab/learn-claude-code
|
||||
@@ -361,7 +374,7 @@ 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
|
||||
python s22_goal_loop/code.py # Endpoint: close the loop with a durable goal
|
||||
```
|
||||
|
||||
### Legacy 12-Lesson Track
|
||||
@@ -374,7 +387,7 @@ 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.
|
||||
The web app extracts the root-level course. Lessons s21 and s22 include reading, source, simulator, and architecture views; only their dedicated hero visualizations remain intentionally minimal.
|
||||
|
||||
```sh
|
||||
cd web && npm install && npm run dev # http://localhost:3000
|
||||
@@ -387,19 +400,21 @@ cd web && npm install && npm run dev # http://localhost:3000
|
||||
```
|
||||
learn-claude-code/
|
||||
s01_agent_loop/ # one folder per chapter
|
||||
README.md # Chinese source (complete narrative)
|
||||
README.en.md # English translation
|
||||
README.md # English default (complete narrative)
|
||||
README.zh.md # Chinese translation
|
||||
README.ja.md # Japanese translation
|
||||
code.py # standalone runnable code
|
||||
images/ # SVG diagrams
|
||||
s02_tool_use/
|
||||
...
|
||||
s19_mcp_plugin/
|
||||
s20_comprehensive/ # endpoint chapter
|
||||
s20_comprehensive/
|
||||
s21_workflow_runtime/
|
||||
s22_goal_loop/ # 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
|
||||
web/ # generated from the root-level course
|
||||
tests/
|
||||
```
|
||||
|
||||
@@ -407,7 +422,7 @@ learn-claude-code/
|
||||
|
||||
## What's Next
|
||||
|
||||
After 20 lessons, you understand harness engineering from the inside out. Two paths to turn that knowledge into product:
|
||||
After 22 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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user