From bd2f63ad6379a639030e82adcfbbd1cb32c12ce7 Mon Sep 17 00:00:00 2001 From: Gui-Yue Date: Tue, 19 May 2026 16:34:56 +0800 Subject: [PATCH] Clarify README tutorial track transition --- README-ja.md | 117 ++++++++++++--- README-zh.md | 118 ++++++++++++--- README.md | 139 +++++++++++++++--- s04_hooks/README.md | 38 ++--- s04_hooks/code.py | 4 +- s04_hooks/images/hooks-overview.en.svg | 6 +- s04_hooks/images/hooks-overview.ja.svg | 6 +- s04_hooks/images/hooks-overview.svg | 12 +- s05_todo_write/README.en.md | 21 ++- s05_todo_write/README.ja.md | 21 ++- s05_todo_write/README.md | 21 ++- s05_todo_write/example/hello.py | 6 + s05_todo_write/images/todo-overview.en.svg | 2 +- s05_todo_write/images/todo-overview.ja.svg | 2 +- s05_todo_write/images/todo-overview.svg | 2 +- s06_subagent/README.en.md | 4 +- s06_subagent/README.ja.md | 4 +- s06_subagent/README.md | 4 +- s06_subagent/images/subagent-overview.svg | 2 +- s07_skill_loading/README.en.md | 6 +- s07_skill_loading/README.ja.md | 6 +- s07_skill_loading/README.md | 6 +- .../images/skill-overview.en.svg | 2 +- .../images/skill-overview.ja.svg | 2 +- s07_skill_loading/images/skill-overview.svg | 2 +- .../images/compact-overview.en.svg | 2 +- .../images/compact-overview.ja.svg | 2 +- .../images/compact-overview.svg | 4 +- .../images/compaction-layers.en.svg | 7 +- .../images/compaction-layers.ja.svg | 7 +- .../images/compaction-layers.svg | 7 +- 31 files changed, 416 insertions(+), 166 deletions(-) create mode 100644 s05_todo_write/example/hello.py diff --git a/README-ja.md b/README-ja.md index 0756ec4..e8fc493 100644 --- a/README-ja.md +++ b/README-ja.md @@ -166,15 +166,15 @@ Claude Code = 一つの agent loop > > **s02**   *"ツールを足すなら、ハンドラーを1つ足すだけ"* — ループは変わらない。新ツールは dispatch map に登録するだけ > -> **s03**   *"まず境界を決め、それから自由を与える"* — 権限パイプラインが承認の要否を判断する +> **s03**   *"まず境界を決め、それから自由を与える"* — 実行してよいか、止めるか、ユーザーに聞くかを判断する > -> **s04**   *"ループの外にフックし、ループは書き換えない"* — フックがツール実行前後に拡張ロジックを注入 +> **s04**   *"ループの外にフックし、ループは書き換えない"* — メインループを変えずに拡張できる入口を作る > > **s05**   *"計画のないエージェントは行き当たりばったり"* — まずステップを書き出し、それから実行 > -> **s06**   *"大きなタスクを分割し、各サブタスクにクリーンなコンテキストを"* — サブエージェントは独立した messages[] を使い、メイン会話を汚さない +> **s06**   *"大きなタスクを分割し、各サブタスクにクリーンなコンテキストを"* — サブ Agent が作業し、結果だけを持ち帰る > -> **s07**   *"必要な知識を、必要な時に読み込む"* — system prompt ではなく tool_result で注入 +> **s07**   *"必要な知識を、必要な時に読み込む"* — スキルはまず一覧だけ、必要な時に展開する > > **s08**   *"コンテキストはいつか溢れる、空ける手段が要る"* — 4層圧縮、安い方から先に実行 > @@ -182,23 +182,23 @@ Claude Code = 一つの agent loop > > **s10**   *"プロンプトは実行時に組み立てる、ハードコードではない"* — セクション分割 + オンデマンド連結 > -> **s11**   *"エラーは終わりではない、リトライの始まりだ"* — トークン拡張、コンテキスト圧縮、モデル切替 +> **s11**   *"エラーは終わりではない、リトライの始まりだ"* — 失敗したら再試行し、空きを作り、別の道を試す > > **s12**   *"大きな目標を小タスクに分解し、順序付けし、ディスクに記録する"* — ファイルベースのタスクグラフ、マルチエージェント協調の基盤 > > **s13**   *"遅い操作はバックグラウンドへ、エージェントは次を考え続ける"* — バックグラウンドスレッドがコマンド実行、完了後に通知を注入 > -> **s14**   *"スケジュールで発火、人間の起動は不要"* — cron スケジューリング、永続 or セッション限定 +> **s14**   *"スケジュールで発火、人間の起動は不要"* — 時間になったら自動でタスクを動かす > > **s15**   *"一人で終わらないなら、チームメイトに任せる"* — 永続チームメイト + 非同期メールボックス > -> **s16**   *"チームメイト間には統一の通信ルールが必要"* — 1つの request-response パターンが全交渉を駆動 +> **s16**   *"チームメイト間には統一の通信ルールが必要"* — 固定のリクエスト-返信形式で連携する > > **s17**   *"チームメイトが自らボードを見て、仕事を取る"* — リーダーが逐一割り振る必要はない > > **s18**   *"各自のディレクトリで作業し、互いに干渉しない"* — タスクは目標を管理、worktree はディレクトリを管理、IDで紐付け > -> **s19**   *"能力不足？ MCP でプラグイン"* — マルチトランスポート、チャネルルーティング、ツールプール統合 +> **s19**   *"能力不足？ MCP でプラグイン"* — 外部ツールを同じツールプールに接続する > > **s20**   *"仕組みは多く、ループは一つ"* — すべての仕組みを 1 つの Harness に戻す @@ -233,6 +233,35 @@ def agent_loop(messages): 各セッションはこのループの上に 1 つの Harness メカニズムを重ねる -- ループ自体は変わらない。ループは Agent のもの。メカニズムは Harness のもの。 +## バージョン状況 + +このリポジトリには現在、2 つのチュートリアルトラックが共存している： + +- **現行トラック：ルート直下の `s01-s20`** + ルート直下の `s01_*` から `s20_*` までが新しい正規版であり、現在推奨する読書経路。各セッションには中国語原文、英語/日本語訳、実行可能な `code.py`、必要に応じた図が含まれる。 +- **旧版移行トラック：`docs/`、`agents/`、現在の `web/`** + これらは旧 12 セッション版を保持している。既存読者、旧リンク、Web プラットフォームのために移行期間中は一時的に残している。 + +新しく読む場合は、ルート直下の `s01_agent_loop/` から `s20_comprehensive/` までを読む。旧リンクや現在の Web アプリから入った場合は、旧 12 セッション版を読んでいる可能性が高い。旧版と現行版のセッション番号は常に一致しないため、番号を混同しないこと。 + +### 旧版から現行版への対応 + +| 旧 12 セッション版 | 現行 20 セッション版 | トピック | +|---|---|---| +| 旧 s01 | 現行 s01 | Agent Loop | +| 旧 s02 | 現行 s02 | Tool Use | +| 旧 s03 | 現行 s05 | TodoWrite | +| 旧 s04 | 現行 s06 | Subagent | +| 旧 s05 | 現行 s07 | Skill Loading | +| 旧 s06 | 現行 s08 | Context Compact | +| 旧 s07 | 現行 s12 | Task System | +| 旧 s08 | 現行 s13 | Background Tasks | +| 旧 s09 | 現行 s15 | Agent Teams | +| 旧 s10 | 現行 s16 | Team Protocols | +| 旧 s11 | 現行 s17 | Autonomous Agents | +| 旧 s12 | 現行 s18 | Worktree Isolation | +| 現行版のみ | s03、s04、s09、s10、s11、s14、s19、s20 | Permission、Hooks、Memory、System Prompt、Error Recovery、Cron、MCP、Comprehensive Agent | + ## スコープ (重要) このリポジトリは Harness 工学の 0->1 学習プロジェクト -- Agent モデルを囲む環境の構築を学ぶ。 @@ -248,6 +277,8 @@ def agent_loop(messages): ## クイックスタート +### 現行 20 セッション版 + ```sh git clone https://github.com/shareAI-lab/learn-claude-code cd learn-claude-code @@ -259,24 +290,68 @@ python s08_context_compact/code.py # コンテキスト圧縮（複雑章） python s20_comprehensive/code.py # 終点: 全メカニズムを 1 つのループへ ``` +### 旧 12 セッション移行版 + +```sh +python agents/s01_agent_loop.py +python agents/s12_worktree_task_isolation.py +python agents/s_full.py +``` + ### Web プラットフォーム -インタラクティブな可視化、ステップスルーアニメーション、ソースビューア、各セッションのドキュメント。 +現在の Web プラットフォームはまだ `docs/` の旧 12 セッション版を表示する。現行 20 セッション版はルート直下の `s01-s20` を読む。 ```sh cd web && npm install && npm run dev # http://localhost:3000 ``` -## 6つの段階 +## 学習パス -| 段階 | セッション | 構築するもの | -|---|---|---| -| **ツールパイプライン** | `s01-s04` | loop → dispatch → permission → hooks | -| **シングルエージェント機能** | `s05-s08` | planning → subagent → skill → context compact | -| **知識と回復力** | `s09-s11` | memory → prompt assembly → error recovery | -| **永続的作業** | `s12-s14` | task graph → background → cron | -| **マルチエージェント基盤** | `s15-s19` | teams → protocols → autonomy → worktree → MCP | -| **完全な Harness** | `s20` | すべての仕組みを agent loop に統合 | +主線：動ける → 複雑な仕事ができる → 記憶して回復できる → 長く動ける → 協作できる → 拡張して統合する + +```mermaid +flowchart TD + %% カードスタイル + 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 + + %% 背景スタイル + classDef groupBox fill:#F8F9FA,stroke:#CED4DA,stroke-width:2px,stroke-dasharray: 5 5,rx:15,ry:15,color:#495057 + + %% 第1層：1-3段階 + subgraph Phase1 ["🌱 段階 1-3：基礎能力の構築（単純から複雑へ）"] + direction LR + S1["第1段階：Agent が動ける
━━━━━━━━━━━━━
s01 Agent Loop
└─ 1つのループ + bash

s02 Tool Use
└─ 1つのツールから複数へ

s03 Permission
└─ 実行してよいか判断する

s04 Hooks
└─ ツール前後に拡張入口を作る"]:::stage1 + + S2["第2段階：複雑な仕事をこなす
━━━━━━━━━━━━━
s05 TodoWrite
└─ 先に計画し、それから実行

s06 Subagent
└─ サブ Agent が結果を返す

s07 Skill Loading
└─ スキルを必要時に展開

s08 Context Compact
└─ 長いコンテキストに空きを作る"]:::stage2 + + S3["第3段階：記憶して回復する
━━━━━━━━━━━━━
s09 Memory
└─ 覚えるべきことを覚える

s10 System Prompt
└─ 実行時に組み立てる

s11 Error Recovery
└─ 再試行し、別の道へ"]:::stage3 + + S1 ==> S2 ==> S3 + end + + %% 第2層：4-6段階 + subgraph Phase2 ["🚀 段階 4-6：高次能力の進化（長期実行、協作、統合）"] + direction LR + S4["第4段階：長く動くタスク
━━━━━━━━━━━━━
s12 Task System
└─ タスクと依存関係を保存

s13 Background Tasks
└─ 遅い作業をバックグラウンドへ

s14 Cron Scheduler
└─ 時間で自動実行"]:::stage4 + + S5["第5段階：複数 Agent の協作
━━━━━━━━━━━━━
s15 Agent Teams
└─ チームメイト + メールボックス

s16 Team Protocols
└─ 固定のリクエスト-返信形式

s17 Autonomous Agents
└─ ボードを見て仕事を取る

s18 Worktree Isolation
└─ 別ディレクトリで作業"]:::stage5 + + S6["第6段階：外部能力と統合
━━━━━━━━━━━━━
s19 MCP Plugin
└─ 外部ツールを同じプールへ

s20 Comprehensive Agent
└─ すべてを1つのループへ"]:::stage6 + + S4 ==> S5 ==> S6 + end + + %% 2つの層を接続 + Phase1 ===> Phase2 + + class Phase1,Phase2 groupBox +``` ## 全セッション @@ -317,10 +392,10 @@ learn-claude-code/ ... s19_mcp_plugin/ s20_comprehensive/ # 終点セッション - agents/ # フラットコピー、python agents/sXX.py でクイック実行 + agents/ # 旧 12 セッションの実行可能コピー + s_full.py skills/ # s07 で使用するスキルファイル - docs/ # 旧バージョン（アーカイブ） - web/ # Web 学習プラットフォーム + docs/ # 旧 12 セッション文書、移行期間中は保持 + web/ # 現在は docs/ の旧版内容を生成・表示 tests/ ``` diff --git a/README-zh.md b/README-zh.md index 1bbca57..6e89bea 100644 --- a/README-zh.md +++ b/README-zh.md @@ -166,15 +166,15 @@ Claude Code = 一个 agent loop > > **s02**   *"加一个工具, 只加一个 handler"* — 循环不用动, 新工具注册进 dispatch map 就行 > -> **s03**   *"先划边界, 再给自由"* — 权限管线决定哪些操作需要审批 +> **s03**   *"先划边界, 再给自由"* — 先判断操作能不能做，要不要问用户 > -> **s04**   *"挂在循环上, 不写进循环里"* — 钩子在工具执行前后注入扩展逻辑 +> **s04**   *"挂在循环上, 不写进循环里"* — 在工具前后留插口，不改主循环也能扩展 > > **s05**   *"没有计划的 agent 走哪算哪"* — 先列步骤再动手, 完成率翻倍 > -> **s06**   *"大任务拆小, 每个小任务干净的上下文"* — Subagent 用独立 messages[], 不污染主对话 +> **s06**   *"大任务拆小, 每个小任务干净的上下文"* — 子 Agent 自己干活，只把结果带回来 > -> **s07**   *"用到时再加载, 别全塞 prompt 里"* — 通过 tool_result 注入, 不塞 system prompt +> **s07**   *"用到时再加载, 别全塞 prompt 里"* — 技能先列目录，用到时再展开 > > **s08**   *"上下文总会满, 要有办法腾地方"* — 四层压缩策略, 便宜的先跑贵的后跑 > @@ -182,23 +182,23 @@ Claude Code = 一个 agent loop > > **s10**   *"prompt 是组装出来的, 不是写死的"* — 分段 + 按需拼接 > -> **s11**   *"错误不是终点, 是重试的起点"* — 升级 token、压缩上下文、切换模型 +> **s11**   *"错误不是终点, 是重试的起点"* — 出错时会重试、腾空间、换路子 > > **s12**   *"大目标拆成小任务, 排好序, 持久化"* — 文件持久化的任务图, 多 agent 协作的基础 > > **s13**   *"慢操作丢后台, agent 继续思考"* — 后台线程跑命令, 完成后注入通知 > -> **s14**   *"定时触发, 不需要人推"* — cron 调度, 持久化或会话级 +> **s14**   *"定时触发, 不需要人推"* — 按时间自动触发任务 > > **s15**   *"一个搞不定, 组队来"* — 持久化队友 + 异步邮箱 > -> **s16**   *"队友之间要有约定"* — 一个 request-response 模式驱动所有协商 +> **s16**   *"队友之间要有约定"* — 用固定的请求-回复格式沟通 > > **s17**   *"队友自己看板, 有活就认领"* — 不需要领导逐个分配, 自组织 > > **s18**   *"各干各的目录, 互不干扰"* — 任务管目标, worktree 管目录, 按 ID 绑定 > -> **s19**   *"能力不够? 插上 MCP"* — 多传输、通道路由、工具池合并 +> **s19**   *"能力不够? 插上 MCP"* — 把外部工具接进同一个工具池 > > **s20**   *"机制很多，循环一个"* — 前面所有机制回到一个完整 harness @@ -233,6 +233,35 @@ def agent_loop(messages): 每个课程在这个循环之上叠加一个 harness 机制 -- 循环本身始终不变。循环属于 agent。机制属于 harness。 +## 版本说明 + +本仓库现在同时保留两条教程线： + +- **新版主线：根目录 `s01-s20`** + 根目录下的 `s01_*` 到 `s20_*` 是新的主版本，也是当前推荐阅读路径。每章包含完整叙事 README、英文/日文译本、可运行的 `code.py`，以及必要的图示。 +- **旧版过渡：`docs/`、`agents/`、当前 `web/`** + 这些仍保留旧 12 章体系，暂时用于已有读者、旧链接和 Web 平台过渡。 + +新读者请从根目录 `s01_agent_loop/` 读到 `s20_comprehensive/`。如果你是从旧链接或当前 Web 平台进入，大概率看到的是旧 12 章版本。旧版章节号和新版不完全一致，不要混用章节号。 + +### 旧版到新版的对应关系 + +| 旧 12 章版本 | 新 20 章版本 | 主题 | +|---|---|---| +| 旧 s01 | 新 s01 | Agent Loop | +| 旧 s02 | 新 s02 | Tool Use | +| 旧 s03 | 新 s05 | TodoWrite | +| 旧 s04 | 新 s06 | Subagent | +| 旧 s05 | 新 s07 | Skill Loading | +| 旧 s06 | 新 s08 | Context Compact | +| 旧 s07 | 新 s12 | Task System | +| 旧 s08 | 新 s13 | Background Tasks | +| 旧 s09 | 新 s15 | Agent Teams | +| 旧 s10 | 新 s16 | Team Protocols | +| 旧 s11 | 新 s17 | Autonomous Agents | +| 旧 s12 | 新 s18 | Worktree Isolation | +| 新版新增 | s03、s04、s09、s10、s11、s14、s19、s20 | Permission、Hooks、Memory、System Prompt、Error Recovery、Cron、MCP、Comprehensive Agent | + ## 范围说明 (重要) 本仓库是一个 0->1 的 harness 工程学习项目 -- 构建围绕 agent 模型的工作环境。 @@ -248,6 +277,8 @@ def agent_loop(messages): ## 快速开始 +### 新版 20 章主线 + ```sh git clone https://github.com/shareAI-lab/learn-claude-code cd learn-claude-code @@ -259,24 +290,69 @@ python s08_context_compact/code.py # 上下文压缩（复杂章） python s20_comprehensive/code.py # 终点章: 全部机制归到一个循环 ``` +### 旧版 12 章过渡线 + +```sh +python agents/s01_agent_loop.py +python agents/s12_worktree_task_isolation.py +python agents/s_full.py +``` + ### Web 平台 -交互式可视化、分步动画、源码查看器, 以及每个课程的文档。 +当前 Web 平台仍读取 `docs/` 中的旧 12 章内容。新版 20 章请直接阅读根目录 `s01-s20`。 ```sh cd web && npm install && npm run dev # http://localhost:3000 ``` -## 六个阶段 +## 学习路径 -| 阶段 | 章节 | 你在构建什么 | -|---|---|---| -| **工具管线** | `s01-s04` | loop → dispatch → permission → hooks | -| **单 Agent 能力** | `s05-s08` | planning → subagent → skill → context compact | -| **知识与韧性** | `s09-s11` | memory → prompt assembly → error recovery | -| **持久化工作** | `s12-s14` | task graph → background → cron | -| **多 Agent 平台** | `s15-s19` | teams → protocols → autonomy → worktree → MCP | -| **完整 Harness** | `s20` | 全部机制归到一个 agent loop | +主线：能动手 → 能做复杂任务 → 能记住和恢复 → 能长期运行 → 能协作 → 能扩展并合体 + +```mermaid +flowchart TD + %% 统一定义卡片样式：加入 text-align:left 保证列表不会居中乱飘 + 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 + + %% 背景框样式 + classDef groupBox fill:#F8F9FA,stroke:#CED4DA,stroke-width:2px,stroke-dasharray: 5 5,rx:15,ry:15,color:#495057 + + %% 第一层：1-3阶段 + subgraph Phase1 ["🌱 阶段 1-3：基础能力构建（从简单到复杂）"] + direction LR + S1["第一阶段：让 Agent 能动手
━━━━━━━━━━━━━
s01 Agent Loop
└─ 一个循环 + bash

s02 Tool Use
└─ 单个到多个工具

s03 Permission
└─ 判断能不能做

s04 Hooks
└─ 工具前后留扩展插口"]:::stage1 + + S2["第二阶段：做复杂任务
━━━━━━━━━━━━━
s05 TodoWrite
└─ 先列计划，再执行

s06 Subagent
└─ 子节点干活带回结果

s07 Skill Loading
└─ 技能按需展开

s08 Context Compact
└─ 长下文腾空间"]:::stage2 + + S3["第三阶段：记住和恢复
━━━━━━━━━━━━━
s09 Memory
└─ 该记记，该忘忘

s10 System Prompt
└─ 运行时组装

s11 Error Recovery
└─ 重试换路子"]:::stage3 + + S1 ==> S2 ==> S3 + end + + %% 第二层：4-6阶段 + subgraph Phase2 ["🚀 阶段 4-6：高阶能力进化（长期、协作与融合）"] + direction LR + S4["第四阶段：让任务长期运行
━━━━━━━━━━━━━
s12 Task System
└─ 任务落盘记依赖

s13 Background Tasks
└─ 慢操作丢后台

s14 Cron Scheduler
└─ 按时自动触发"]:::stage4 + + S5["第五阶段：让多个 Agent 协作
━━━━━━━━━━━━━
s15 Agent Teams
└─ 队友 + 邮箱通信

s16 Team Protocols
└─ 固定收发格式

s17 Autonomous Agents
└─ 自己看板认领活

s18 Worktree Isolation
└─ 隔离目录"]:::stage5 + + S6["第六阶段：接外部能力合体
━━━━━━━━━━━━━
s19 MCP Plugin
└─ 外部接进工具池

s20 Comprehensive Agent
└─ 全机制回单循环"]:::stage6 + + S4 ==> S5 ==> S6 + end + + %% 将两个模块连接起来，形成 Z 字形阅读流 + Phase1 ===> Phase2 + + %% 应用背景样式 + class Phase1,Phase2 groupBox +``` ## 全部章节 @@ -317,10 +393,10 @@ learn-claude-code/ ... s19_mcp_plugin/ s20_comprehensive/ # 终点章 - agents/ # 扁平副本，方便 python agents/sXX.py 快速运行 + agents/ # 旧 12 章可运行副本 + s_full.py skills/ # s07 使用的 skill 文件 - docs/ # 旧版线上文档（已归档） - web/ # Web 教学平台 + docs/ # 旧 12 章文档，过渡期保留 + web/ # 当前仍基于 docs/ 旧版内容生成 tests/ ``` diff --git a/README.md b/README.md index b2a41f0..57cddc5 100644 --- a/README.md +++ b/README.md @@ -159,6 +159,51 @@ Every lesson layers one harness mechanism on top of this loop -- the loop itself --- +## 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.** @@ -167,15 +212,15 @@ Every lesson layers one harness mechanism on top of this loop -- the loop itself > > **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"* — the permission pipeline decides which operations need approval +> **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"* — hooks inject extension logic before and after tool execution +> **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 use a fresh messages[], keeping the main conversation clean +> **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"* — inject via tool_result, not the system prompt +> **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 > @@ -183,38 +228,74 @@ Every lesson layers one harness mechanism on top of this loop -- the loop itself > > **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"* — escalate tokens, compact context, switch models +> **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"* — cron scheduling, durable or session-scoped +> **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"* — one request-response pattern drives all negotiation +> **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"* — multi-transport, channel routing, tool pool merging +> **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 --- -## Six Stages +## Learning Path -| Stage | Chapters | What you are building | -|---|---|---| -| **Tool pipeline** | `s01-s04` | loop → tool dispatch → permission pipeline → hook extensions | -| **Single-agent capability** | `s05-s08` | planning → subagent → skill loading → context compaction | -| **Knowledge and resilience** | `s09-s11` | memory → prompt assembly → error recovery | -| **Durable work** | `s12-s14` | task graph → background execution → scheduled triggers | -| **Multi-agent platform** | `s15-s19` | teams → protocols → autonomy → worktree isolation → MCP | -| **Complete harness** | `s20` | full agent loop with all mechanisms assembled | +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

s07 Skill Loading
└─ expand skills on demand

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
━━━━━━━━━━━━━
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 +``` --- @@ -266,6 +347,8 @@ Read from s01 through s20 in order. Each chapter assumes you've read the previou ## Quick Start +### Current 20-Lesson Track + ```sh git clone https://github.com/shareAI-lab/learn-claude-code cd learn-claude-code @@ -277,6 +360,22 @@ 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 @@ -293,10 +392,10 @@ learn-claude-code/ ... s19_mcp_plugin/ s20_comprehensive/ # endpoint chapter - agents/ # flat copies for quick python agents/sXX.py + agents/ # legacy 12 runnable copies + s_full.py skills/ # skill files used by s07 - docs/ # legacy online docs (archived) - web/ # web teaching platform + docs/ # legacy 12-lesson docs, kept during transition + web/ # currently renders the legacy docs/ track tests/ ``` diff --git a/s04_hooks/README.md b/s04_hooks/README.md index bcd3ea2..928b6c9 100644 --- a/s04_hooks/README.md +++ b/s04_hooks/README.md @@ -4,9 +4,9 @@ s01 → s02 → s03 → `s04` → [s05](../s05_todo_write/) → s06 → ... → s20 -> *"挂在循环上, 不写进循环里"* — 钩子在工具执行前后注入扩展逻辑。 +> *"挂在循环上, 不写进循环里"* — hook 在工具执行前后注入扩展逻辑。 > -> **Harness 层**: 钩子 — 扩展点不侵入循环。 +> **Harness 层**: hook — 扩展点不侵入循环。 --- @@ -38,7 +38,7 @@ def agent_loop(messages): ![Hooks Overview](images/hooks-overview.svg) -s03 的循环和权限逻辑完全保留。唯一的变动是把 `check_permission()` 从循环体内移到了钩子上，循环不再直接调用任何检查函数，改为 `trigger_hooks("PreToolUse", block)`，由注册表决定跑什么。 +s03 的循环和权限逻辑完全保留。唯一的变动是把 `check_permission()` 从循环体内移到了 hook 上，循环不再直接调用任何检查函数，改为 `trigger_hooks("PreToolUse", block)`，由注册表决定跑什么。 四个事件，覆盖一个完整的 agent cycle： @@ -55,7 +55,7 @@ s03 的循环和权限逻辑完全保留。唯一的变动是把 `check_permissi ## 工作原理 -**钩子注册表**：一个字典，事件名映射到回调列表。 +**hook 注册表**：一个字典，事件名映射到回调列表。 ```python HOOKS = { @@ -71,12 +71,12 @@ def register_hook(event: str, callback): def trigger_hooks(event: str, *args): for callback in HOOKS[event]: result = callback(*args) - if result is not None: # 返回值 ≠ None → 钩子说"停" + if result is not None: # 返回值 ≠ None → hook 说"停" return result return None ``` -教学版中，PreToolUse 返回非 None 表示阻止执行，Stop 返回非 None 表示强制续跑。UserPromptSubmit 和 PostToolUse 的返回值未被使用。 +教学版中，PreToolUse 的非 None 返回值会阻止本次工具执行，Stop 的非 None 返回值会强制续跑。UserPromptSubmit 和 PostToolUse 的返回值未被使用。 **UserPromptSubmit**，用户输入提交后、进入 LLM 前触发。CC 中可以拦截或修改输入，教学版只做日志演示： @@ -98,10 +98,10 @@ history.append({"role": "user", "content": query}) agent_loop(history) ``` -**PreToolUse / PostToolUse**，工具执行前后的钩子。s03 的权限检查逻辑现在包装成 PreToolUse 钩子，再加一个日志钩子和一个大输出提醒： +**PreToolUse / PostToolUse**，工具执行前后的 hook。s03 的权限检查逻辑现在包装成 PreToolUse hook，再加一个日志 hook 和一个大输出提醒： ```python -# PreToolUse: 权限检查（s03 的逻辑，从循环移到钩子） +# PreToolUse: 权限检查（s03 的逻辑，从循环移到 hook） def permission_hook(block): if block.name == "bash": for pattern in DENY_LIST: @@ -163,7 +163,7 @@ for block in response.content: continue # s03: if not check_permission(block): ... - # s04: 钩子替代硬编码 + # s04: hook 替代硬编码 blocked = trigger_hooks("PreToolUse", block) if blocked: results.append({"type": "tool_result", "tool_use_id": block.id, @@ -179,7 +179,7 @@ for block in response.content: "content": output}) ``` -四个钩子覆盖了 agent cycle 的关键节点：输入→执行前→执行后→退出。循环只负责调用 trigger_hooks()，具体逻辑全在钩子回调里。 +四个 hook 覆盖了 agent cycle 的关键节点：输入→执行前→执行后→退出。循环只负责调用 trigger_hooks()，具体逻辑全在 hook 回调里。 --- @@ -189,7 +189,7 @@ for block in response.content: |------|-----------|-----------| | 扩展方式 | check_permission() 硬编码在循环里 | HOOKS 注册表 + trigger_hooks() | | 新函数 | — | register_hook, trigger_hooks | -| 钩子回调 | — | context_inject_hook, permission_hook, log_hook, large_output_hook, summary_hook | +| hook 回调 | — | context_inject_hook, permission_hook, log_hook, large_output_hook, summary_hook | | 循环 | 直接调用 check_permission() | 调用 trigger_hooks("PreToolUse", ...) | | 退出控制 | 无 | trigger_hooks("Stop", ...) 可阻止退出 | | 输入拦截 | 无 | trigger_hooks("UserPromptSubmit", ...) 可注入上下文 | @@ -205,11 +205,11 @@ python s04_hooks/code.py 试试这些 prompt： -1. `Read the file README.md`（应该直接通过，观察钩子日志） +1. `Read the file README.md`（应该直接通过，观察 hook 日志） 2. `Create a file called test.txt`（通过后观察 PostToolUse 是否触发） -3. `Delete all temporary files in /tmp`（bash + rm 触发权限钩子） +3. `Delete all temporary files in /tmp`（bash + rm 触发权限 hook） -观察重点：每次工具执行前，是否出现了 `[HOOK]` 日志？权限被拒时，是钩子拦截的还是循环里硬编码的？ +观察重点：每次工具执行前，是否出现了 `[HOOK]` 日志？权限被拒时，是 hook 拦截的还是循环里硬编码的？ --- @@ -251,16 +251,16 @@ CC 的 `HookResult`（`types/hooks.ts:260-275`）有 14 个字段，以下是常 | `outcome` | success/blocking/non_blocking_error/cancelled | 执行结果 | | `preventContinuation` | boolean | 阻止后续执行 | | `stopReason` | string | 停止原因描述 | -| `permissionBehavior` | allow/deny/ask/passthrough | 钩子返回权限决策 | +| `permissionBehavior` | allow/deny/ask/passthrough | hook 返回权限决策 | | `updatedInput` | Record | 修改工具输入 | | `additionalContext` | string | 附加上下文 | | `updatedMCPToolOutput` | unknown | MCP 工具输出修改 | ### 三、关键不变式：Hook 'allow' 不能绕过 deny/ask 规则 -这是 CC 权限系统最重要的安全设计（`toolHooks.ts:325-331`）：**钩子返回 allow 时，仍然要检查 settings.json 的 deny/ask 规则**。即使用户的钩子脚本说"允许"，如果在 settings.json 中禁用了这个工具，操作仍然会被阻止。 +这是 CC 权限系统最重要的安全设计（`toolHooks.ts:325-331`）：**hook 返回 allow 时，仍然要检查 settings.json 的 deny/ask 规则**。即使用户的 hook 脚本说"允许"，如果在 settings.json 中禁用了这个工具，操作仍然会被阻止。 -教学版没有这个层次，钩子返回非 None 就直接中断。这在教学场景中够了，但在生产环境中会形成安全漏洞。 +教学版没有这个层次，只把 PreToolUse 的非 None 返回值解释为阻止本次工具执行。这在教学场景中够了，但在生产环境中会形成安全漏洞。 ### 四、stopHookActive 机制 @@ -268,12 +268,12 @@ CC 的 Stop hooks 有一个防无限循环机制（`query.ts:212,1300`）：`sto ### 五、hook_stopped_continuation -PostToolUse hooks 返回 `preventContinuation: true` 时，会产生一个 `hook_stopped_continuation` 附件（`toolHooks.ts:117-130`）。query.ts（L1388-1393）检测到后设置 `shouldPreventContinuation = true`，循环退出。这是"钩子优雅地让 Agent 停机"的机制——不是崩溃，是完成。 +PostToolUse hooks 返回 `preventContinuation: true` 时，会产生一个 `hook_stopped_continuation` 附件（`toolHooks.ts:117-130`）。query.ts（L1388-1393）检测到后设置 `shouldPreventContinuation = true`，循环退出。这是 "hook 优雅地让 Agent 停机" 的机制，不是崩溃，是完成。 ### 教学版的简化是刻意的 - 27 个事件 → 4 个（UserPromptSubmit/PreToolUse/PostToolUse/Stop）：覆盖 agent cycle 关键节点 -- 14 个字段 → 简单的返回值（None = 继续，非 None = 中断/续跑）：心智负担降到最低 +- 14 个字段 → 简单的返回值（None = 继续，非 None = 阻止/续跑）：心智负担降到最低 - Hook allow vs deny/ask 不变式 → 省略：教学版没有 settings.json 层 - stopHookActive → 省略：教学版 Stop hook 只做简单续跑，不涉及防无限循环机制 diff --git a/s04_hooks/code.py b/s04_hooks/code.py index ad27e2b..756bf7d 100644 --- a/s04_hooks/code.py +++ b/s04_hooks/code.py @@ -10,7 +10,7 @@ s04: Hooks — move extension logic out of the loop, onto hooks. └────────┬─────────┘ ▼ ┌────────────┐ ┌─────────────────────────────┐ - │ messages │────▶│ LLM (stop_reason?) │ + │ messages │────▶│ LLM (stop_reason=tool_use?)│ └────────────┘ │ No ──▶ Stop hooks ──▶ exit │ │ Yes ──▶ tool_use block ──┐ │ └────────────────────────────┘ │ @@ -164,7 +164,7 @@ def register_hook(event: str, callback): def trigger_hooks(event: str, *args): for callback in HOOKS[event]: result = callback(*args) - if result is not None: # non-None return → abort + if result is not None: # teaching shortcut: block this tool call return result return None diff --git a/s04_hooks/images/hooks-overview.en.svg b/s04_hooks/images/hooks-overview.en.svg index 5fa4995..87afdc0 100644 --- a/s04_hooks/images/hooks-overview.en.svg +++ b/s04_hooks/images/hooks-overview.en.svg @@ -39,7 +39,7 @@ LLM - stop_reason? + stop_reason=tool_use? @@ -57,12 +57,12 @@ PreToolUse permission_hook · log_hook - return non-None → block + Teaching: non-None → block - Skip Execution + Write tool_result diff --git a/s04_hooks/images/hooks-overview.ja.svg b/s04_hooks/images/hooks-overview.ja.svg index 6348c5b..d1addf6 100644 --- a/s04_hooks/images/hooks-overview.ja.svg +++ b/s04_hooks/images/hooks-overview.ja.svg @@ -39,7 +39,7 @@ LLM - stop_reason? + stop_reason=tool_use? @@ -57,12 +57,12 @@ PreToolUse permission_hook · log_hook - 非 None を返す → 中断 + 教育版: 非 None → ブロック - 実行をスキップ + tool_result に返す diff --git a/s04_hooks/images/hooks-overview.svg b/s04_hooks/images/hooks-overview.svg index 6fe7d5f..410593a 100644 --- a/s04_hooks/images/hooks-overview.svg +++ b/s04_hooks/images/hooks-overview.svg @@ -39,7 +39,7 @@ LLM - stop_reason? + stop_reason=tool_use? @@ -51,18 +51,18 @@ 是 - + trigger_hooks() PreToolUse permission_hook · log_hook - 返回非 None → 中断 + 教学版：非 None → 阻止 - + - 跳过执行 + 写入 tool_result @@ -78,7 +78,7 @@ 执行后 - + trigger_hooks() PostToolUse diff --git a/s05_todo_write/README.en.md b/s05_todo_write/README.en.md index 48d4451..9ae6089 100644 --- a/s05_todo_write/README.en.md +++ b/s05_todo_write/README.en.md @@ -83,15 +83,14 @@ TOOL_HANDLERS["todo_write"] = run_todo_write ```python if rounds_since_todo >= 3 and messages: - last = messages[-1] - if last["role"] == "user" and isinstance(last.get("content"), list): - last["content"].insert(0, { - "type": "text", - "text": "Update your todos.", - }) + messages.append({ + "role": "user", + "content": "Update your todos.", + }) + rounds_since_todo = 0 ``` -Typical flow when the Agent receives a task: first call `todo_write` to list all steps (all `pending`) → pick one step, set it to `in_progress` → complete it, set to `completed` → look at the next `pending` → continue. After 3 rounds without updates, the reminder prompts the Agent to update TODO status. +Typical flow when the Agent receives a task: first call `todo_write` to list all steps (all `pending`) → pick one step, set it to `in_progress` → complete it, set to `completed` → look at the next `pending` → continue. After 3 rounds without `todo_write`, the loop appends a reminder before the next LLM call. **Key insight**: todo_write doesn't give the Agent any additional **execution capability**. What it adds is **planning capability**. @@ -117,11 +116,11 @@ python s05_todo_write/code.py Try these prompts: -1. `Refactor the file hello.py: add type hints, docstrings, and a main guard` (should list 3 steps first, then execute) -2. `Create a Python package with __init__.py, utils.py, and tests/test_utils.py` -3. `Review all Python files and fix any style issues` +1. `Refactor s05_todo_write/example/hello.py: add type hints, docstrings, and a main guard` (should list 3 steps first, then execute) +2. `Create a Python package under s05_todo_write/example/demo_pkg with __init__.py, utils.py, and tests/test_utils.py` +3. `Review Python files under s05_todo_write/example and fix any style issues` -What to watch for: Did the Agent call `todo_write` first? How many steps did it list? Did it go back to update TODO status during execution? Did the nag reminder appear after 3 rounds without updates? +What to watch for: Was the first tool call `todo_write`? How many TODO steps were listed? Did statuses move from `pending` to `in_progress` / `completed` during execution? --- diff --git a/s05_todo_write/README.ja.md b/s05_todo_write/README.ja.md index 8b5e577..db383de 100644 --- a/s05_todo_write/README.ja.md +++ b/s05_todo_write/README.ja.md @@ -83,15 +83,14 @@ TOOL_HANDLERS["todo_write"] = run_todo_write ```python if rounds_since_todo >= 3 and messages: - last = messages[-1] - if last["role"] == "user" and isinstance(last.get("content"), list): - last["content"].insert(0, { - "type": "text", - "text": "Update your todos.", - }) + messages.append({ + "role": "user", + "content": "Update your todos.", + }) + rounds_since_todo = 0 ``` -Agent がタスクを受け取った後の典型的な流れ：まず `todo_write` を呼び出して全手順を列挙（全て `pending`）→ 一つの手順に取り掛かり、`in_progress` に変更 → 完了したら `completed` に変更 → 次の `pending` を見る → 続行。3 ラウンド更新なしの場合、リマインダーが TODO の更新を促す。 +Agent がタスクを受け取った後の典型的な流れ：まず `todo_write` を呼び出して全手順を列挙（全て `pending`）→ 一つの手順に取り掛かり、`in_progress` に変更 → 完了したら `completed` に変更 → 次の `pending` を見る → 続行。3 ラウンド `todo_write` がない場合、次の LLM 呼び出し前にリマインダーが追加される。 **重要な洞察**：todo_write は Agent に**実行能力**を何も追加しない。追加するのは**計画能力**だ。 @@ -117,11 +116,11 @@ python s05_todo_write/code.py 以下のプロンプトを試してみよう： -1. `Refactor the file hello.py: add type hints, docstrings, and a main guard`（まず 3 手順を列挙してから実行するはず） -2. `Create a Python package with __init__.py, utils.py, and tests/test_utils.py` -3. `Review all Python files and fix any style issues` +1. `Refactor s05_todo_write/example/hello.py: add type hints, docstrings, and a main guard`（まず 3 手順を列挙してから実行するはず） +2. `Create a Python package under s05_todo_write/example/demo_pkg with __init__.py, utils.py, and tests/test_utils.py` +3. `Review Python files under s05_todo_write/example and fix any style issues` -観察のポイント：Agent はまず `todo_write` を呼び出したか？ 何手順列挙したか？ 実行中に TODO のステータスを更新し戻ったか？ 3 ラウンド更新なしで Nag リマインダーが表示されたか？ +観察のポイント：最初のツール呼び出しは `todo_write` か？ TODO は何手順列挙されたか？ 実行中にステータスが `pending` から `in_progress` / `completed` に変わったか？ --- diff --git a/s05_todo_write/README.md b/s05_todo_write/README.md index e850ac3..146a4d6 100644 --- a/s05_todo_write/README.md +++ b/s05_todo_write/README.md @@ -83,15 +83,14 @@ TOOL_HANDLERS["todo_write"] = run_todo_write ```python if rounds_since_todo >= 3 and messages: - last = messages[-1] - if last["role"] == "user" and isinstance(last.get("content"), list): - last["content"].insert(0, { - "type": "text", - "text": "Update your todos.", - }) + messages.append({ + "role": "user", + "content": "Update your todos.", + }) + rounds_since_todo = 0 ``` -Agent 收到任务后的典型流程：先调 `todo_write` 列出所有步骤（全 `pending`）→ 做一个步骤，改成 `in_progress` → 做完改成 `completed` → 看下一个 `pending` → 继续。3 轮不更新时，reminder 会提醒它回头更新 TODO 状态。 +Agent 收到任务后的典型流程：先调 `todo_write` 列出所有步骤（全 `pending`）→ 做一个步骤，改成 `in_progress` → 做完改成 `completed` → 看下一个 `pending` → 继续。连续 3 轮没有调用 `todo_write` 时，循环会在下一次 LLM 调用前追加一条 reminder。 **关键洞察**：todo_write 不给 Agent 增加任何**执行能力**。它增加的是**规划能力**。 @@ -117,11 +116,11 @@ python s05_todo_write/code.py 试试这些 prompt： -1. `Refactor the file hello.py: add type hints, docstrings, and a main guard`（先列 3 步再执行） -2. `Create a Python package with __init__.py, utils.py, and tests/test_utils.py` -3. `Review all Python files and fix any style issues` +1. `Refactor s05_todo_write/example/hello.py: add type hints, docstrings, and a main guard`（先列 3 步再执行） +2. `Create a Python package under s05_todo_write/example/demo_pkg with __init__.py, utils.py, and tests/test_utils.py` +3. `Review Python files under s05_todo_write/example and fix any style issues` -观察重点：Agent 先调了 `todo_write` 吗？它列了几个步骤？执行过程中有没有回头更新 TODO 状态？连续 3 轮不更新时是否出现了 nag reminder？ +观察重点：第一次工具调用是不是 `todo_write`？TODO 列了几步？执行过程中状态有没有从 `pending` 变成 `in_progress` / `completed`？ --- diff --git a/s05_todo_write/example/hello.py b/s05_todo_write/example/hello.py new file mode 100644 index 0000000..b65d74f --- /dev/null +++ b/s05_todo_write/example/hello.py @@ -0,0 +1,6 @@ +def greet(name): + message = "Hello, " + name + print(message) + + +greet("Claude") diff --git a/s05_todo_write/images/todo-overview.en.svg b/s05_todo_write/images/todo-overview.en.svg index be4b926..afec010 100644 --- a/s05_todo_write/images/todo-overview.en.svg +++ b/s05_todo_write/images/todo-overview.en.svg @@ -36,7 +36,7 @@ LLM - stop_reason? + stop_reason=tool_use? diff --git a/s05_todo_write/images/todo-overview.ja.svg b/s05_todo_write/images/todo-overview.ja.svg index 5d6cd13..8b3a506 100644 --- a/s05_todo_write/images/todo-overview.ja.svg +++ b/s05_todo_write/images/todo-overview.ja.svg @@ -36,7 +36,7 @@ LLM - stop_reason? + stop_reason=tool_use? diff --git a/s05_todo_write/images/todo-overview.svg b/s05_todo_write/images/todo-overview.svg index 59c7168..53d05fe 100644 --- a/s05_todo_write/images/todo-overview.svg +++ b/s05_todo_write/images/todo-overview.svg @@ -36,7 +36,7 @@ LLM - stop_reason? + stop_reason=tool_use? diff --git a/s06_subagent/README.en.md b/s06_subagent/README.en.md index 35ec044..93313e3 100644 --- a/s06_subagent/README.en.md +++ b/s06_subagent/README.en.md @@ -119,9 +119,9 @@ Try these prompts: 1. `Use a subtask to find what testing framework this project uses` (sub-Agent reads files, main Agent receives only the conclusion) 2. `Delegate: read all .py files in agents/ and summarize what each one does` -3. `Use a task to create a new module, then verify it from here` +3. `Use a task to create s06_subagent/example/string_tools.py with a slugify(text: str) function, then verify it from the parent agent` -What to watch for: Does the Agent spawn a sub-Agent to read files? Do the sub-Agent's intermediate steps appear in the main conversation? Does the final conclusion include the file contents that the sub-Agent read? +What to watch for: Do `[Subagent spawned]` / `[Subagent done]` appear? Do sub-Agent tool calls print as `[sub] ...`? Does the parent Agent continue with only the summary returned by the sub-Agent? --- diff --git a/s06_subagent/README.ja.md b/s06_subagent/README.ja.md index c3aabee..fc28520 100644 --- a/s06_subagent/README.ja.md +++ b/s06_subagent/README.ja.md @@ -119,9 +119,9 @@ python s06_subagent/code.py 1. `Use a subtask to find what testing framework this project uses`（サブエージェントがファイルを読み、メイン Agent は結論のみ受け取る） 2. `Delegate: read all .py files in agents/ and summarize what each one does` -3. `Use a task to create a new module, then verify it from here` +3. `Use a task to create s06_subagent/example/string_tools.py with a slugify(text: str) function, then verify it from the parent agent` -観察のポイント：Agent はサブエージェントを spawn してファイルを読みに行くか？ サブエージェントの中間過程はメイン会話に現れるか？ 最後に返された結論に、サブエージェントが読んだファイルの内容は含まれているか？ +観察のポイント：`[Subagent spawned]` / `[Subagent done]` が表示されるか？ サブエージェントのツール呼び出しが `[sub] ...` として出力されるか？ 親 Agent はサブエージェントが返した要約だけを受け取って続行するか？ --- diff --git a/s06_subagent/README.md b/s06_subagent/README.md index 2ad28f4..6744566 100644 --- a/s06_subagent/README.md +++ b/s06_subagent/README.md @@ -123,9 +123,9 @@ python s06_subagent/code.py 1. `Use a subtask to find what testing framework this project uses`（子 Agent 去读文件，主 Agent 只收结论） 2. `Delegate: read all .py files in agents/ and summarize what each one does` -3. `Use a task to create a new module, then verify it from here` +3. `Use a task to create s06_subagent/example/string_tools.py with a slugify(text: str) function, then verify it from the parent agent` -观察重点：Agent 会 spawn 子 Agent 去读文件吗？子 Agent 的中间过程是否出现在主对话中？最后返回的结论包含子 Agent 读的那些文件内容吗？ +观察重点：是否出现 `[Subagent spawned]` / `[Subagent done]`？子 Agent 的工具调用是否以 `[sub] ...` 输出？主 Agent 最后是否只继续处理子 Agent 返回的摘要？ --- diff --git a/s06_subagent/images/subagent-overview.svg b/s06_subagent/images/subagent-overview.svg index 2b53e18..c18d660 100644 --- a/s06_subagent/images/subagent-overview.svg +++ b/s06_subagent/images/subagent-overview.svg @@ -111,7 +111,7 @@ - s05 保留：循环、钩子、todo_write、6 个基础工具 + s05 保留：循环、hook、todo_write、6 个基础工具 s06 新增：task 工具 + spawn_subagent() — 独立 messages[]，只回传摘要 diff --git a/s07_skill_loading/README.en.md b/s07_skill_loading/README.en.md index 612aed8..eb76756 100644 --- a/s07_skill_loading/README.en.md +++ b/s07_skill_loading/README.en.md @@ -125,11 +125,11 @@ python s07_skill_loading/code.py Try these prompts: -1. `What skills are available?` (should answer directly from the SYSTEM prompt catalog, no tool call) -2. `Load the code-review skill and follow its instructions` (should call load_skill) +1. `What skills are available?` +2. `Load the code-review skill and follow its instructions` 3. `I need to do a code review -- load the relevant skill first` -What to watch for: Does the Agent know which skills are available directly from the SYSTEM catalog? Does it proactively call `load_skill` when it needs specific specs? Does the full skill content appear in the system prompt? +What to watch for: Does the Agent know available skills from the SYSTEM catalog? Does `[HOOK] load_skill` appear when full instructions are needed? Does the answer use the loaded skill's instructions? --- diff --git a/s07_skill_loading/README.ja.md b/s07_skill_loading/README.ja.md index a3d12cf..e38afaa 100644 --- a/s07_skill_loading/README.ja.md +++ b/s07_skill_loading/README.ja.md @@ -125,11 +125,11 @@ python s07_skill_loading/code.py 以下のプロンプトを試してみよう： -1. `What skills are available?`（SYSTEM prompt のカタログから直接回答するはず、ツール呼び出しなし） -2. `Load the code-review skill and follow its instructions`（load_skill を呼び出すはず） +1. `What skills are available?` +2. `Load the code-review skill and follow its instructions` 3. `I need to do a code review -- load the relevant skill first` -観察のポイント：Agent は SYSTEM 内のカタログから利用可能なスキルを知っているか？ 具体的な仕様が必要なときに `load_skill` を積極的に呼び出すか？ system prompt にスキルの完全な内容が含まれているか？ +観察のポイント：Agent は SYSTEM 内のカタログから利用可能なスキルを知っているか？ 完全な手順が必要なときに `[HOOK] load_skill` が表示されるか？ 読み込んだスキルの説明を使って回答しているか？ --- diff --git a/s07_skill_loading/README.md b/s07_skill_loading/README.md index 112c8ed..86be90e 100644 --- a/s07_skill_loading/README.md +++ b/s07_skill_loading/README.md @@ -125,11 +125,11 @@ python s07_skill_loading/code.py 试试这些 prompt： -1. `What skills are available?`（应该直接从 SYSTEM prompt 里的目录回答，不调工具） -2. `Load the code-review skill and follow its instructions`（应该调 load_skill） +1. `What skills are available?` +2. `Load the code-review skill and follow its instructions` 3. `I need to do a code review -- load the relevant skill first` -观察重点：Agent 是否直接从 SYSTEM 里的目录知道有哪些技能？它在需要具体规范时主动调了 `load_skill` 吗？system prompt 里有没有出现 skill 的完整内容？ +观察重点：Agent 是否直接从 SYSTEM 里的目录知道有哪些技能？需要完整规范时是否出现 `[HOOK] load_skill`？加载后回答是否使用了对应 skill 的说明？ --- diff --git a/s07_skill_loading/images/skill-overview.en.svg b/s07_skill_loading/images/skill-overview.en.svg index 7d8115e..ff31907 100644 --- a/s07_skill_loading/images/skill-overview.en.svg +++ b/s07_skill_loading/images/skill-overview.en.svg @@ -39,7 +39,7 @@ LLM - stop_reason? + stop_reason=tool_use? diff --git a/s07_skill_loading/images/skill-overview.ja.svg b/s07_skill_loading/images/skill-overview.ja.svg index 441c092..596dcd5 100644 --- a/s07_skill_loading/images/skill-overview.ja.svg +++ b/s07_skill_loading/images/skill-overview.ja.svg @@ -39,7 +39,7 @@ LLM - stop_reason? + stop_reason=tool_use? diff --git a/s07_skill_loading/images/skill-overview.svg b/s07_skill_loading/images/skill-overview.svg index 20e2a0d..600747b 100644 --- a/s07_skill_loading/images/skill-overview.svg +++ b/s07_skill_loading/images/skill-overview.svg @@ -39,7 +39,7 @@ LLM - stop_reason? + stop_reason=tool_use? diff --git a/s08_context_compact/images/compact-overview.en.svg b/s08_context_compact/images/compact-overview.en.svg index ea47fa6..542b156 100644 --- a/s08_context_compact/images/compact-overview.en.svg +++ b/s08_context_compact/images/compact-overview.en.svg @@ -85,7 +85,7 @@ LLM - stop_reason? + stop_reason=tool_use? diff --git a/s08_context_compact/images/compact-overview.ja.svg b/s08_context_compact/images/compact-overview.ja.svg index f80fba2..350cd13 100644 --- a/s08_context_compact/images/compact-overview.ja.svg +++ b/s08_context_compact/images/compact-overview.ja.svg @@ -85,7 +85,7 @@ LLM - stop_reason? + stop_reason=tool_use? diff --git a/s08_context_compact/images/compact-overview.svg b/s08_context_compact/images/compact-overview.svg index ad678b5..837e9bb 100644 --- a/s08_context_compact/images/compact-overview.svg +++ b/s08_context_compact/images/compact-overview.svg @@ -85,7 +85,7 @@ LLM - stop_reason? + stop_reason=tool_use? @@ -123,7 +123,7 @@ - s07 保留：循环、钩子、技能加载、子 Agent + s07 保留：循环、hook、技能加载、子 Agent ① 每轮自动：L3→L1→L2 在每次 LLM 调用前无条件执行，0 API diff --git a/s08_context_compact/images/compaction-layers.en.svg b/s08_context_compact/images/compaction-layers.en.svg index 163cd49..5a27e96 100644 --- a/s08_context_compact/images/compaction-layers.en.svg +++ b/s08_context_compact/images/compaction-layers.en.svg @@ -89,11 +89,10 @@ Emergency Fallback (triggered when API still returns prompt_too_long) - + Emrg reactiveCompact - API 413 → byte-level trim, keep last 5 + summary - more aggressive - Trigger: API returns prompt_too_long or 413 error + API returns 413 / prompt_too_long → byte-level trim + Keep last 5 + summary; more aggressive than autoCompact diff --git a/s08_context_compact/images/compaction-layers.ja.svg b/s08_context_compact/images/compaction-layers.ja.svg index 4eac997..8519054 100644 --- a/s08_context_compact/images/compaction-layers.ja.svg +++ b/s08_context_compact/images/compaction-layers.ja.svg @@ -89,11 +89,10 @@ 緊急フォールバック（API が引き続き prompt_too_long を返す場合にトリガー） - + 緊急 reactiveCompact - API が 413 を返す → バイトレベルでトリム、最後の 5 件 + 要約を保持 - autoCompact より積極的 - トリガー：API が prompt_too_long または 413 エラーを返す + API が 413 / prompt_too_long を返す → バイト単位でトリム + 最後の 5 件 + 要約を保持、autoCompact より積極的 diff --git a/s08_context_compact/images/compaction-layers.svg b/s08_context_compact/images/compaction-layers.svg index b05105c..818b44e 100644 --- a/s08_context_compact/images/compaction-layers.svg +++ b/s08_context_compact/images/compaction-layers.svg @@ -89,11 +89,10 @@ 应急兜底（API 仍然返回 prompt_too_long 时触发） - + 应急 reactiveCompact - API 返回 413 → 字节级裁剪，保留最后 5 条 + 摘要 - 比 autoCompact 更激进 - 触发：API 返回 prompt_too_long 或 413 错误 + API 返回 413 / prompt_too_long → 字节级裁剪 + 保留最后 5 条 + 摘要，比 autoCompact 更激进