abc/analysis_claude_code
1
0
Fork 0
mirror of https://github.com/shareAI-lab/analysis_claude_code.git synced 2026-09-20 12:13:38 +08:00
Code Issues Packages Projects Releases Wiki Activity

refactor: streamline the course to 17 lessons

Browse Source
This commit is contained in:
Haoran
2026-08-12 03:02:42 +08:00
parent ab35e59672
commit 7e2f2fd99b
250 changed files with 12179 additions and 18653 deletions
Download Patch File Download Diff File Expand all files Collapse all files

100
README-ja.md
View File

@@ -74,7 +74,7 @@ Harness = Tools + Knowledge + Observation + Action Interfaces + Permissions
- **知識のキュレーション。** Agent にドメイン専門性を与える。製品ドキュメント、アーキテクチャ決定記録、スタイルガイド、規制要件。オンデマンドで読み込み（s07）、前もって詰め込まない。Agent は何が利用可能か知った上で、必要なものを自ら取得すべき。
- **コンテキストの管理。** サブ Agent は明確な作業を別のメッセージリストに置く。コンテキスト圧縮（s08）は古い履歴を短くし、タスクシステム（s12）は目標を単一の会話を超えて永続化する。
- **コンテキストの管理。** サブ Agent は明確な作業を別のメッセージリストに置く。コンテキスト圧縮（s08）は古い履歴を短くし、タスクシステム（s10）は目標を単一の会話を超えて永続化する。
- **権限の制御。** Agent に境界を与える。ファイルアクセスのサンドボックス化。破壊的操作への承認要求。Agent と外部システム間の信頼境界の実施。安全工学と Harness 工学の交差点。
@@ -106,7 +106,7 @@ Claude Code = 一つの agent loop
これがすべてだ。これが全アーキテクチャ。すべてのコンポーネントは Harness メカニズム -- Agent が住む世界の一部。Agent そのものは？ Claude だ。モデル。Anthropic が人類の推論とコードの全幅で訓練した。Harness が Claude を賢くしたのではない。Claude は元々賢い。Harness が Claude に手と目とワークスペースを与えた。
これが Claude Code を教材として扱う理由だ：**モデルを信頼し、工学的努力を Harness に集中させるとどうなるかを示している。** このリポジトリの各セッション（s01-s19）は Harness メカニズムを段階的に分解し、最後に組み直す。終了時には、一つの coding agent の仕組みだけでなく、さまざまな領域に適用できる Harness 工学の原則を理解できる。
これが Claude Code を教材として扱う理由だ：**モデルを信頼し、工学的努力を Harness に集中させるとどうなるかを示している。** このリポジトリの各セッション（s01-s17）は Harness メカニズムを段階的に分解し、最後に組み直す。終了時には、一つの coding agent の仕組みだけでなく、さまざまな領域に適用できる Harness 工学の原則を理解できる。
教訓は「Claude Code をコピーせよ」ではない。教訓は：**最高の Agent プロダクトは、自分の仕事が Harness であって Intelligence ではないと理解しているエンジニアが作る。**
@@ -159,7 +159,7 @@ Claude Code = 一つの agent loop
Agent を特定ドメインで効果的にする Harness -- の作り方を教える。
```
**19 の段階的セッション、シンプルなループから目標を閉じる Harness まで。**
**17 の段階的セッション、シンプルなループから目標を閉じる Harness まで。**
**各セッションは 1 つの Harness メカニズムを追加する。各メカニズムには 1 つのモットーがある。**
> **s01**   *"One loop & Bash is all you need"* — 1つのツール + 1つのループ = エージェント
@@ -176,29 +176,25 @@ Claude Code = 一つの agent loop
>
> **s07**   *"必要な知識を、必要な時に読み込む"* — スキルはまず一覧だけ、必要な時に展開する
>
> **s08**   *"コンテキストはいつか溢れる、空ける手段が要る"* — 4層圧縮、安い方から先に実行
> **s08**   *"コンテキストはいつか溢れる、空ける手段が要る"* — 4 段階の圧縮でツール結果を先に整理し、上限超過時に履歴を要約
>
> **s09**   *"覚えるべきことを覚え、忘れるべきことを忘れる"* — 3つのサブシステム：選択、抽出、整理
>
> **s10**   *"プロンプトは実行時に組み立てる、ハードコードではない"* — セクション分割 + オンデマンド連結
> **s10**   *"大きな目標を小タスクに分解し、順序付けし、ディスクに記録する"* — ファイルベースのタスクグラフ、マルチエージェント協調の基盤
>
> **s11**   *"エラーは終わりではない、リトライの始まりだ"* — 失敗したら再試行し、空きを作り、別の道を試す
> **s11**   *"遅い操作はバックグラウンドへ、エージェントは次を考え続ける"* — バックグラウンドスレッドがコマンド実行、完了後に通知を注入
>
> **s12**   *"大きな目標を小タスクに分解し、順序付けし、ディスクに記録する"* — ファイルベースのタスクグラフ、マルチエージェント協調の基盤
> **s12**   *"スケジュールで発火、人間の起動は不要"* — 時間になったら自動でタスクを動かす
>
> **s13**   *"遅い操作はバックグラウンドへ、エージェントは次を考え続ける"* — バックグラウンドスレッドがコマンド実行、完了後に通知を注入
> **s13**   *"一人で扱いきれないなら、チームメイトで分担する"* — 永続チームメイトが協調し、実行可能なタスクを認領して、タスクに紐付いた作業ディレクトリを使う
>
> **s14**   *"スケジュールで発火、人間の起動は不要"* — 時間になったら自動でタスクを動かす
> **s14**   *"能力不足？ MCP でプラグイン"* — 外部ツールを同じツールプールに接続する
>
> **s15**   *"一人で扱いきれないなら、チームメイトで分担する"* — 永続チームメイトが協調し、実行可能なタスクを認領して、タスクに紐付いた作業ディレクトリを使う
> **s15**   *"仕組みは多く、ループは一つ"* — 統合例で使う仕組みを 1 つの Harness に戻す
>
> **s16**   *"能力不足？ MCP でプラグイン"* — 外部ツールを同じツールプールに接続する
> **s16**   *"編成の形が固定なら、コードにする"* — 保存済み Workflow を journal から再開する
>
> **s17**   *"仕組みは多く、ループは一つ"* — 統合例で使う仕組みを 1 つの Harness に戻す
>
> **s18**   *"編成の形が固定なら、コードにする"* — 再開可能なジャーナルを持つ決定的 Workflow
>
> **s19**   *"本当に終われる時を目標が決める"* — 停止候補ごとに独立 evaluator が確認し、不可能、失敗、継続上限の場合は user に制御を返す
> **s17**   *"本当に終われる時を目標が決める"* — 停止候補ごとに独立 evaluator が確認し、不可能、失敗、継続上限の場合は user に制御を返す
---
@@ -229,22 +225,22 @@ def agent_loop(messages):
messages.append({"role": "user", "content": results})
```
各セッションはこの loop の周りで 1 つの Harness mechanism を分けて扱う。s17 で累積 runtime を再統合し、s18 と s19 で Workflow 編成と goal closure を個別に扱う。loop は Agent のもので、mechanism は Harness のものである。
各セッションはこの loop の周りで 1 つの Harness mechanism を分けて扱う。s15 で累積 runtime を再統合し、s16 と s17 で Workflow 編成と goal closure を個別に扱う。loop は Agent のもので、mechanism は Harness のものである。
## バージョン状況
このリポジトリには現在、2 つのチュートリアルトラックが共存している：
- **現行トラック：ルート直下の `s01-s19`**
ルート直下の `s01_*` から `s19_*` までが新しい正規版であり、現在推奨する読書経路。各セッションには既定の英語 README、中国語/日本語訳、実行可能な `code.py`、必要に応じた図が含まれる。
- **現行トラック：ルート直下の `s01-s17`**
ルート直下の `s01_*` から `s17_*` までが新しい正規版であり、現在推奨する読書経路。各セッションには既定の英語 README、中国語/日本語訳、実行可能な `code.py`、必要に応じた図が含まれる。
- **旧版移行トラック：`docs/`、`agents/`**
これらは旧 12 セッション版を保持している。既存読者と旧リンクのために移行期間中は一時的に残している。
新しく読む場合は、ルート直下の `s01_agent_loop/` から `s19_goal_loop/` までを読む。旧版と現行版のセッション番号は常に一致しないため、番号を混同しないこと。
新しく読む場合は、ルート直下の `s01_agent_loop/` から `s17_goal_loop/` までを読む。旧版と現行版のセッション番号は常に一致しないため、番号を混同しないこと。
### 旧版から現行版への対応
| 旧 12 セッション版 | 現行 19 セッション版 | トピック |
| 旧 12 セッション版 | 現行 17 セッション版 | トピック |
|---|---|---|
| 旧 s01 | 現行 s01 | Agent Loop |
| 旧 s02 | 現行 s02 | Tool Use |
@@ -252,21 +248,21 @@ def agent_loop(messages):
| 旧 s04 | 現行 s06 | Subagent |
| 旧 s05 | 現行 s07 | Skill Loading |
| 旧 s06 | 現行 s08 | Context Compact |
| 旧 s07 | 現行 s12 | Task System |
| 旧 s08 | 現行 s13 | Background Tasks |
| 旧 s09 | 現行 s15 | Agent Teams |
| 旧 s10 | 現行 s15 | Team Protocols |
| 旧 s11 | 現行 s15 | 自律的なタスク認領 |
| 旧 s12 | 現行 s15 | タスクに紐付く Worktree |
| 現行版のみ | s03、s04、s09、s10、s11、s14、s16、s17、s18、s19 | Permission、Hooks、Memory、Context Assembly、Error Recovery、Cron、MCP、Integrated Harness、Workflow Runtime、Goal Loop |
| 旧 s07 | 現行 s10 | Task System |
| 旧 s08 | 現行 s11 | Background Tasks |
| 旧 s09 | 現行 s13 | Agent Teams |
| 旧 s10 | 現行 s13 | Team Protocols |
| 旧 s11 | 現行 s13 | 自律的なタスク認領 |
| 旧 s12 | 現行 s13 | タスクに紐付く Worktree |
| 現行版のみ | s03、s04、s09、s12、s14、s15、s16、s17 | Permission、Hooks、Memory、Cron、MCP、Integrated Harness、Workflow Runtime、Goal Loop |
## コースの範囲
これは Harness 工学を 0 から組み立てるコースである。各セッションで一つの仕組みを分けて扱い、s17 で累積 runtime を一つの Agent loop に戻す。s18 はその loop に Workflow 編成を追加する。s19 はより小さな tool pool で goal-controlled continuation に集中する mechanism example であり、もう一つの累積 runtime ではない。
これは Harness 工学を 0 から組み立てるコースである。各セッションで一つの仕組みを分けて扱い、s15 で累積 runtime を一つの Agent loop に戻す。s16 はその loop に Workflow 編成を追加する。s17 はより小さな tool pool で goal-controlled continuation に集中する mechanism example であり、もう一つの累積 runtime ではない。
## クイックスタート
### 現行 19 セッション版
### 現行 17 セッション版
```sh
git clone https://github.com/shareAI-lab/learn-claude-code
@@ -276,7 +272,7 @@ cp .env.example .env # .env を編集して ANTHROPIC_API_KEY を入力
python s01_agent_loop/code.py # ここから開始 — 1ループ + bash
python s08_context_compact/code.py # コンテキスト圧縮（複雑章）
python s19_goal_loop/code.py # 終点: 目標でループを閉じる
python s17_goal_loop/code.py # 終点: 目標でループを閉じる
```
### 旧 12 セッション移行版
@@ -289,7 +285,7 @@ python agents/s_full.py
### Web プラットフォーム
Web プラットフォームはルート直下のコースから内容を生成する。s18 と s19 は読解、ソース、シミュレーター、アーキテクチャの各 view を提供し、専用 hero visualization だけを最小限に保つ。
Web プラットフォームはルート直下のコースから内容を生成する。s16 と s17 は読解、ソース、シミュレーター、アーキテクチャの各 view を提供し、専用 hero visualization だけを最小限に保つ。
```sh
cd web && npm install && npm run dev # http://localhost:3000
@@ -319,7 +315,7 @@ flowchart TD
S2["<b>第2段階：複雑な仕事をこなす</b><br/>━━━━━━━━━━━━━<br/><b>s05 TodoWrite</b><br/>└─ 先に計画し、それから実行<br/><br/><b>s06 Subagent</b><br/>└─ 新しい messages、最終テキストを返す<br/><br/><b>s08 Context Compact</b><br/>└─ 長いコンテキストに空きを作る"]:::stage2
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
S3["<b>第3段階：セッションを越えて記憶する</b><br/>━━━━━━━━━━━━━<br/><b>s09 Memory</b><br/>└─ 再利用する知識を保存・想起"]:::stage3
S1 ==> S2 ==> S3
end
@@ -327,11 +323,11 @@ flowchart TD
%% 第2層：4-6段階
subgraph Phase2 ["🚀 段階 4-6：高次能力の進化（長期実行、協作、統合）"]
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
S4["<b>第4段階：長く動くタスク</b><br/>━━━━━━━━━━━━━<br/><b>s10 Task System</b><br/>└─ タスクと依存関係を保存<br/><br/><b>s11 Background Tasks</b><br/>└─ 遅い作業をバックグラウンドへ<br/><br/><b>s12 Cron Scheduler</b><br/>└─ 時間で自動実行"]:::stage4
S5["<b>第5段階：複数 Agent の協作</b><br/>━━━━━━━━━━━━━<br/><b>s15 Agent Teams</b><br/>└─ チームメイト + 配信 + プロトコル<br/>└─ 実行可能なタスクを原子的に認領<br/>└─ タスクに紐付く Worktree"]:::stage5
S5["<b>第5段階：複数 Agent の協作</b><br/>━━━━━━━━━━━━━<br/><b>s13 Agent Teams</b><br/>└─ チームメイト + 配信 + プロトコル<br/>└─ 実行可能なタスクを原子的に認領<br/>└─ タスクに紐付く Worktree"]:::stage5
S6["<b>第6段階：外部能力と統合</b><br/>━━━━━━━━━━━━━<br/><b>s07 Skill Loading</b><br/>└─ スキルを必要時に展開<br/><br/><b>s16 MCP Plugin</b><br/>└─ 外部ツールを同じプールへ<br/><br/><b>s17 Integrated Harness</b><br/>└─ すべてを1つのループへ"]:::stage6
S6["<b>第6段階：外部能力と統合</b><br/>━━━━━━━━━━━━━<br/><b>s07 Skill Loading</b><br/>└─ スキルを必要時に展開<br/><br/><b>s14 MCP Plugin</b><br/>└─ 外部ツールを同じプールへ<br/><br/><b>s15 Integrated Harness</b><br/>└─ course mechanisms を 1 つの loop へ"]:::stage6
S4 ==> S5 ==> S6
end
@@ -339,7 +335,7 @@ flowchart TD
%% 第3層：編成と目標の完了
subgraph Phase3 ["第7段階：編成と目標の完了"]
direction LR
S7["<b>第7段階：編成して完了する</b><br/>━━━━━━━━━━━━━<br/><b>s18 Workflow Runtime</b><br/>└─ 固定編成はスクリプトが担う<br/><br/><b>s19 Goal Loop</b><br/>└─ 独立した評価で停止を決める"]:::stage1
S7["<b>第7段階：編成して完了する</b><br/>━━━━━━━━━━━━━<br/><b>s16 Workflow Runtime</b><br/>└─ 固定編成はスクリプトが担う<br/><br/><b>s17 Goal Loop</b><br/>└─ 独立した評価で停止を決める"]:::stage1
S6 ==> S7
end
@@ -359,19 +355,17 @@ flowchart TD
| [s04](./s04_hooks/) | Hooks | `PreToolUse` / `PostToolUse` / 拡張ポイント |
| [s05](./s05_todo_write/) | TodoWrite | `TodoItem` / 計画してから実行 |
| [s06](./s06_subagent/) | Subagent | `fresh messages[]` / コンテキスト分離 |
| [s07](./s07_skill_loading/) | Skill Loading | `SkillManifest` / オンデマンド注入 |
| [s07](./s07_skill_loading/) | Skill Loading | `SkillLoader` / カタログ / オンデマンド注入 |
| [s08](./s08_context_compact/) | Context Compact | budget / snip / micro / summary の 4 ステップ |
| [s09](./s09_memory/) | Memory | selection / extraction / consolidation |
| [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 | 永続チームメイト / 原子的認領 / タスクに紐付く Worktree / 型付きプロトコル |
| [s16](./s16_mcp_plugin/) | MCP Plugin | ツール発見 / 名前空間 / ツールプール組み立て |
| [s17](./s17_integrated_harness/) | Integrated Harness | tools、runtime context、tasks、teams、scheduling、MCP を 1 つの loop へ |
| [s18](./s18_workflow_runtime/) | Workflow Runtime | スクリプト編成 / lifecycle event / ジャーナル再開 |
| [s19](./s19_goal_loop/) | Goal Loop | 目標ゲート / conversation の評価 / 自動継続 |
| [s10](./s10_task_system/) | Task System | `TaskRecord` / `blockedBy` / ディスク永続化 |
| [s11](./s11_background_tasks/) | Background Tasks | スレッド実行 / 通知キュー |
| [s12](./s12_cron_scheduler/) | Cron Scheduler | 永続スケジューリング / セッション限定トリガー |
| [s13](./s13_agent_teams/) | Agent Teams | 永続チームメイト / 原子的認領 / タスクに紐付く Worktree / 型付きプロトコル |
| [s14](./s14_mcp_plugin/) | MCP Plugin | ツール発見 / 名前空間 / ツールプール組み立て |
| [s15](./s15_integrated_harness/) | Integrated Harness | tools、runtime context、tasks、teams、scheduling、MCP を 1 つの loop へ |
| [s16](./s16_workflow_runtime/) | Workflow Runtime | スクリプト編成 / lifecycle event / ジャーナル再開 |
| [s17](./s17_goal_loop/) | Goal Loop | 目標ゲート / conversation の評価 / 自動継続 |
## プロジェクト構成
@@ -385,10 +379,10 @@ learn-claude-code/
images/ # SVG ダイアグラム
s02_tool_use/
...
s16_mcp_plugin/
s17_integrated_harness/
s18_workflow_runtime/
s19_goal_loop/ # 終点セッション
s14_mcp_plugin/
s15_integrated_harness/
s16_workflow_runtime/
s17_goal_loop/ # 終点セッション
agents/ # 旧 12 セッションの実行可能コピー + s_full.py
skills/ # s07 で使用するスキルファイル
docs/ # 旧 12 セッション文書、移行期間中は保持
@@ -398,7 +392,7 @@ learn-claude-code/
## 次のステップ -- 理解から出荷へ
19 セッションを終えれば、Harness 工学の内部構造を理解できる。その知識を活かす 2 つの方法:
17 セッションを終えれば、Harness 工学の内部構造を理解できる。その知識を活かす 2 つの方法:
### Kode Agent CLI -- オープンソース Coding Agent CLI