feat: refresh course through workflow and goal loops

2026-09-20 12:13:38 +08:00 · 2026-07-30 19:14:04 +08:00
parent 2dd1852d9e
commit cb8fae1bdd
125 changed files with 10882 additions and 7661 deletions
--- a/README-ja.md
+++ b/README-ja.md
@@ -106,7 +106,7 @@ Claude Code = 一つの agent loop

 これがすべてだ。これが全アーキテクチャ。すべてのコンポーネントは Harness メカニズム -- Agent が住む世界の一部。Agent そのものは？ Claude だ。モデル。Anthropic が人類の推論とコードの全幅で訓練した。Harness が Claude を賢くしたのではない。Claude は元々賢い。Harness が Claude に手と目とワークスペースを与えた。

-これが Claude Code が理想的な教材である理由だ：**モデルを信頼し、工学的努力を Harness に集中させるとどうなるかを示している。** このリポジトリの各セッション（s01-s20）は Claude Code アーキテクチャの Harness メカニズムを段階的に分解し、最後に組み直す。終了時には、Claude Code の仕組みだけでなく、あらゆるドメインのあらゆる Agent に適用される Harness 工学の普遍的原則を理解している。
+これが Claude Code が理想的な教材である理由だ：**モデルを信頼し、工学的努力を Harness に集中させるとどうなるかを示している。** このリポジトリの各セッション（s01-s22）は Claude Code アーキテクチャの Harness メカニズムを段階的に分解し、最後に組み直す。終了時には、Claude Code の仕組みだけでなく、あらゆるドメインのあらゆる Agent に適用される Harness 工学の普遍的原則を理解している。

 教訓は「Claude Code をコピーせよ」ではない。教訓は：**最高の Agent プロダクトは、自分の仕事が Harness であって Intelligence ではないと理解しているエンジニアが作る。**

@@ -159,7 +159,7 @@ Claude Code = 一つの agent loop
    Agent を特定ドメインで効果的にする Harness -- の作り方を教える。
 ```

-**20 の段階的セッション、シンプルなループから完全な Harness まで。**
+**22 の段階的セッション、シンプルなループから目標を閉じる Harness まで。**
 **各セッションは 1 つの Harness メカニズムを追加する。各メカニズムには 1 つのモットーがある。**

 > **s01** &nbsp; *"One loop & Bash is all you need"* &mdash; 1つのツール + 1つのループ = エージェント
@@ -190,9 +190,9 @@ Claude Code = 一つの agent loop
 >
 > **s14** &nbsp; *"スケジュールで発火、人間の起動は不要"* &mdash; 時間になったら自動でタスクを動かす
 >
-> **s15** &nbsp; *"一人で終わらないなら、チームメイトに任せる"* &mdash; 永続チームメイト + 非同期メールボックス
+> **s15** &nbsp; *"一人で終わらないなら、チームメイトに任せる"* &mdash; Agent Teams ランタイム実験：永続チームメイト + 非同期メールボックス
 >
-> **s16** &nbsp; *"チームメイト間には統一の通信ルールが必要"* &mdash; 固定のリクエスト-返信形式で連携する
+> **s16** &nbsp; *"チームメイト間には統一の通信ルールが必要"* &mdash; Agent Teams プロトコル実験：型付きリクエスト-返信
 >
 > **s17** &nbsp; *"チームメイトが自らボードを見て、仕事を取る"* &mdash; リーダーが逐一割り振る必要はない
 >
@@ -201,6 +201,10 @@ Claude Code = 一つの agent loop
 > **s19** &nbsp; *"能力不足？ MCP でプラグイン"* &mdash; 外部ツールを同じツールプールに接続する
 >
 > **s20** &nbsp; *"仕組みは多く、ループは一つ"* &mdash; すべての仕組みを 1 つの Harness に戻す
+>
+> **s21** &nbsp; *"編成の形が固定なら、コードにする"* &mdash; 再開可能なジャーナルを持つ決定的 Workflow
+>
+> **s22** &nbsp; *"本当に終われる時を目標が決める"* &mdash; 信頼できる証拠が目標を満たすまで継続する

 ---

@@ -237,16 +241,16 @@ def agent_loop(messages):

 このリポジトリには現在、2 つのチュートリアルトラックが共存している：

- **現行トラック：ルート直下の `s01-s20`**
-  ルート直下の `s01_*` から `s20_*` までが新しい正規版であり、現在推奨する読書経路。各セッションには中国語原文、英語/日本語訳、実行可能な `code.py`、必要に応じた図が含まれる。
- **旧版移行トラック：`docs/`、`agents/`、現在の `web/`**
-  これらは旧 12 セッション版を保持している。既存読者、旧リンク、Web プラットフォームのために移行期間中は一時的に残している。
+- **現行トラック：ルート直下の `s01-s22`**
+  ルート直下の `s01_*` から `s22_*` までが新しい正規版であり、現在推奨する読書経路。各セッションには既定の英語 README、中国語/日本語訳、実行可能な `code.py`、必要に応じた図が含まれる。
+- **旧版移行トラック：`docs/`、`agents/`**
+  これらは旧 12 セッション版を保持している。既存読者と旧リンクのために移行期間中は一時的に残している。

-新しく読む場合は、ルート直下の `s01_agent_loop/` から `s20_comprehensive/` までを読む。旧リンクや現在の Web アプリから入った場合は、旧 12 セッション版を読んでいる可能性が高い。旧版と現行版のセッション番号は常に一致しないため、番号を混同しないこと。
+新しく読む場合は、ルート直下の `s01_agent_loop/` から `s22_goal_loop/` までを読む。旧版と現行版のセッション番号は常に一致しないため、番号を混同しないこと。

 ### 旧版から現行版への対応

-| 旧 12 セッション版 | 現行 20 セッション版 | トピック |
+| 旧 12 セッション版 | 現行 22 セッション版 | トピック |
 |---|---|---|
 | 旧 s01 | 現行 s01 | Agent Loop |
 | 旧 s02 | 現行 s02 | Tool Use |
@@ -260,7 +264,7 @@ def agent_loop(messages):
 | 旧 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 |
+| 現行版のみ | 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 |

 ## スコープ (重要)

@@ -277,7 +281,7 @@ def agent_loop(messages):

 ## クイックスタート

-### 現行 20 セッション版
+### 現行 22 セッション版

 ```sh
 git clone https://github.com/shareAI-lab/learn-claude-code
@@ -287,7 +291,7 @@ cp .env.example .env   # .env を編集して ANTHROPIC_API_KEY を入力

 python s01_agent_loop/code.py        # ここから開始 — 1ループ + bash
 python s08_context_compact/code.py    # コンテキスト圧縮（複雑章）
-python s20_comprehensive/code.py      # 終点: 全メカニズムを 1 つのループへ
+python s22_goal_loop/code.py          # 終点: 目標でループを閉じる
 ```

 ### 旧 12 セッション移行版
@@ -300,7 +304,7 @@ python agents/s_full.py

 ### Web プラットフォーム

-現在の Web プラットフォームはまだ `docs/` の旧 12 セッション版を表示する。現行 20 セッション版はルート直下の `s01-s20` を読む。
+Web プラットフォームはルート直下のコースから内容を生成する。s21 と s22 は読解、ソース、シミュレーター、アーキテクチャの各 view を提供し、専用 hero visualization だけを最小限に保つ。

 ```sh
 cd web && npm install && npm run dev   # http://localhost:3000
@@ -330,7 +334,7 @@ flowchart TD

        S2["<b>第2段階：複雑な仕事をこなす</b><br/>━━━━━━━━━━━━━<br/><b>s05 TodoWrite</b><br/>└─ 先に計画し、それから実行<br/><br/><b>s06 Subagent</b><br/>└─ サブ Agent が結果を返す<br/><br/><b>s08 Context Compact</b><br/>└─ 長いコンテキストに空きを作る"]:::stage2

-        S3["<b>第3段階：記憶して回復する</b><br/>━━━━━━━━━━━━━<br/><b>s09 Memory</b><br/>└─ 覚えるべきことを覚える<br/><br/><b>s10 System Prompt</b><br/>└─ 実行時に組み立てる<br/><br/><b>s11 Error Recovery</b><br/>└─ 再試行し、別の道へ"]:::stage3
+        S3["<b>第3段階：記憶して回復する</b><br/>━━━━━━━━━━━━━<br/><b>s09 Memory</b><br/>└─ セッションを越えて保存・想起<br/><br/><b>s10 Context Assembly</b><br/>└─ 実行時状態からモデル入力を組み立てる<br/><br/><b>s11 Error Recovery</b><br/>└─ 再試行し、別の道へ"]:::stage3

        S1 ==> S2 ==> S3
    end
@@ -340,17 +344,24 @@ flowchart TD
        direction LR
        S4["<b>第4段階：長く動くタスク</b><br/>━━━━━━━━━━━━━<br/><b>s12 Task System</b><br/>└─ タスクと依存関係を保存<br/><br/><b>s13 Background Tasks</b><br/>└─ 遅い作業をバックグラウンドへ<br/><br/><b>s14 Cron Scheduler</b><br/>└─ 時間で自動実行"]:::stage4

-        S5["<b>第5段階：複数 Agent の協作</b><br/>━━━━━━━━━━━━━<br/><b>s15 Agent Teams</b><br/>└─ チームメイト + メールボックス<br/><br/><b>s16 Team Protocols</b><br/>└─ 固定のリクエスト-返信形式<br/><br/><b>s17 Autonomous Agents</b><br/>└─ ボードを見て仕事を取る<br/><br/><b>s18 Worktree Isolation</b><br/>└─ 別ディレクトリで作業"]:::stage5
+        S5["<b>第5段階：複数 Agent の協作</b><br/>━━━━━━━━━━━━━<br/><b>Agent Teams モジュール</b><br/>├─ s15 ランタイム実験：チームメイト + メールボックス<br/>└─ s16 プロトコル実験：型付きリクエスト-返信<br/><br/><b>s17 Autonomous Agents</b><br/>└─ ボードを見て仕事を取る<br/><br/><b>s18 Worktree Isolation</b><br/>└─ 別ディレクトリで作業"]:::stage5

        S6["<b>第6段階：外部能力と統合</b><br/>━━━━━━━━━━━━━<br/><b>s07 Skill Loading</b><br/>└─ スキルを必要時に展開<br/><br/><b>s19 MCP Plugin</b><br/>└─ 外部ツールを同じプールへ<br/><br/><b>s20 Comprehensive Agent</b><br/>└─ すべてを1つのループへ"]:::stage6

        S4 ==> S5 ==> S6
    end

-    %% 2つの層を接続
-    Phase1 ===> Phase2
+    %% 第3層：編成と目標の完了
+    subgraph Phase3 ["第7段階：編成と目標の完了"]
+        direction LR
+        S7["<b>第7段階：編成して完了する</b><br/>━━━━━━━━━━━━━<br/><b>s21 Workflow Runtime</b><br/>└─ 固定編成はスクリプトが担う<br/><br/><b>s22 Goal Loop</b><br/>└─ 信頼できる証拠で停止を決める"]:::stage1
+        S6 ==> S7
+    end

-    class Phase1,Phase2 groupBox
+    %% 3つの層を接続
+    Phase1 ===> Phase2 ===> Phase3
+
+    class Phase1,Phase2,Phase3 groupBox
 ```

 ## 全セッション
@@ -366,42 +377,46 @@ flowchart TD
 | [s07](./s07_skill_loading/) | Skill Loading | `SkillManifest` / オンデマンド注入 |
 | [s08](./s08_context_compact/) | Context Compact | snip / micro / budget / auto 4層圧縮 |
 | [s09](./s09_memory/) | Memory | selection / extraction / consolidation |
-| [s10](./s10_system_prompt/) | System Prompt | ランタイム組立 / セクション連結 |
+| [s10](./s10_system_prompt/) | Context Assembly | 実行時状態 / 安定セクション / モデル入力 |
 | [s11](./s11_error_recovery/) | Error Recovery | token 拡張 / fallback モデル / リトライ戦略 |
 | [s12](./s12_task_system/) | Task System | `TaskRecord` / `blockedBy` / ディスク永続化 |
 | [s13](./s13_background_tasks/) | Background Tasks | スレッド実行 / 通知キュー |
 | [s14](./s14_cron_scheduler/) | Cron Scheduler | 永続スケジューリング / セッション限定トリガー |
-| [s15](./s15_agent_teams/) | Agent Teams | `MessageBus` / 受信箱 / 権限バブリング |
-| [s16](./s16_team_protocols/) | Team Protocols | シャットダウンハンドシェイク / プラン承認 |
+| [s15](./s15_agent_teams/) | Agent Teams：ランタイム実験 | `MessageBus` / 受信箱 / 権限バブリング |
+| [s16](./s16_team_protocols/) | Agent Teams：プロトコル実験 | 型付きメッセージ / シャットダウンハンドシェイク / プラン承認 |
 | [s17](./s17_autonomous_agents/) | Autonomous Agents | アイドルサイクル / 自動クレーム |
 | [s18](./s18_worktree_isolation/) | Worktree Isolation | `WorktreeRecord` / タスク-ディレクトリ紐付け |
 | [s19](./s19_mcp_plugin/) | MCP Plugin | マルチトランスポート / チャネルルーティング / ツールプール組み立て |
 | [s20](./s20_comprehensive/) | Comprehensive Agent | すべての仕組みを 1 つのループへ |
+| [s21](./s21_workflow_runtime/) | Workflow Runtime | スクリプト編成 / バックグラウンド実行 / ジャーナル再開 |
+| [s22](./s22_goal_loop/) | Goal Loop | 目標ゲート / 信頼できる証拠 / 自動継続 |

 ## プロジェクト構成

 ```
 learn-claude-code/
  s01_agent_loop/          # セッションごとに1フォルダ
-    README.md              #   中国語ソース（完全なナラティブ）
-    README.en.md           #   英語訳
+    README.md              #   既定の英語文書（完全なナラティブ）
+    README.zh.md           #   中国語訳
    README.ja.md           #   日本語訳
    code.py                #   単体実行可能なコード
    images/                #   SVG ダイアグラム
  s02_tool_use/
  ...
  s19_mcp_plugin/
-  s20_comprehensive/       # 終点セッション
+  s20_comprehensive/
+  s21_workflow_runtime/
+  s22_goal_loop/           # 終点セッション
  agents/                  # 旧 12 セッションの実行可能コピー + s_full.py
  skills/                  # s07 で使用するスキルファイル
  docs/                    # 旧 12 セッション文書、移行期間中は保持
-  web/                     # 現在は docs/ の旧版内容を生成・表示
+  web/                     # ルート直下のコースから生成
  tests/
 ```

 ## 次のステップ -- 理解から出荷へ

-20 セッションを終えれば、Harness 工学の内部構造を完全に理解している。その知識を活かす 2 つの方法:
+22 セッションを終えれば、Harness 工学の内部構造を完全に理解している。その知識を活かす 2 つの方法:

 ### Kode Agent CLI -- オープンソース Coding Agent CLI