Skip to content

README-ja.md

Latest commit

 

History

History
308 lines (220 loc) · 15.8 KB

README-ja.md

File metadata and controls

308 lines (220 loc) · 15.8 KB
Raw

English | 中文 | 日本語

Agency はモデルから生まれる。Agent プロダクト = モデル + Harness

コードの話をする前に、一つ明確にしておく。

Agency -- 知覚し、推論し、行動する能力 -- はモデルの訓練から生まれる。外部コードの編成からではない。 だが実際に動く Agent プロダクトには、モデルと Harness の両方が必要だ。モデルはドライバー、Harness は車。本リポジトリは車の作り方を教える。

Agency はどこから来るか

Agent の核心にあるのはニューラルネットワークだ -- Transformer、RNN、学習された関数 -- 数十億回の勾配更新を経て、行動系列データの上で環境を知覚し、目標を推論し、行動を起こすことを学んだもの。Agency は周囲のコードから与えられるものではない。訓練を通じてモデルが獲得するものだ。

人間が最もわかりやすい例だ。数百万年の進化的訓練によって形作られた生物的ニューラルネットワーク。感覚で世界を知覚し、脳で推論し、身体で行動する。DeepMind、OpenAI、Anthropic が "Agent" と言うとき、その核心は常に同じことを指している：訓練によって行動を学んだモデルと、それを特定の環境で機能させるインフラの組み合わせ。

その作業環境を作る主な部品は次の通りです。

  • Agent Loop: モデルに聞く -> ツールを実行する -> 結果を返す
  • Tools: エージェントの手足
  • Planning: 大きな作業を途中で迷わせないための小さな構造
  • Context Management: アクティブな文脈を小さく保つ
  • Permissions: モデルの意図をそのまま危険な実行にしない
  • Hooks: ループを書き換えずに周辺機能を足す
  • Memory: セッションをまたいで残すべき事実だけを保持する
  • Prompt Construction: 安定ルールと実行時状態から入力を組み立てる
  • Tasks / Teams / Worktree / MCP: 単体 agent をより大きな作業基盤へ育てる

この教材が目指すのは:

  • 主線を順序よく理解できること
  • 初学者が概念で迷子にならないこと
  • 核心メカニズムと重要データ構造を自力で再実装できること

あえて主線から外しているもの

実際の製品コードには、agent の本質とは直接関係しない細部も多くあります。

<<<<<<< HEAD たとえば:

すべてのマイルストーンが同じ事実を示している：Agency -- 知覚し、推論し、行動する能力 -- は訓練によって獲得されるものであり、コードで組み立てるものではない。 しかし同時に、どの Agent も動作するための環境を必要とした：Atari エミュレータ、Dota 2 クライアント、StarCraft II エンジン、IDE とターミナル。モデルが知能を提供し、環境が行動空間を提供する。両方が揃って初めて完全な Agent となる。

4b95969a03f780e8aa17340a10ff0a6d9512a2c9

  • パッケージングや配布の流れ
  • クロスプラットフォーム互換層
  • 企業ポリシーやテレメトリ配線
  • 歴史互換のための分岐
  • 製品統合のための細かな glue code

こうした要素は本番では重要でも、0 から 1 を教える主線には置きません。
教学リポジトリの中心は、あくまで「agent がどう動くか」です。

想定読者

このリポジトリは次の読者を想定しています。

  • 基本的な Python が読める
  • 関数、クラス、リスト、辞書は分かる
  • でも agent システムは初学者でもよい

そのため、書き方の原則をはっきり決めています。

  • 新しい概念は、使う前に説明する
  • 1つの概念は、できるだけ1か所でまとまって理解できるようにする
  • まず「何か」、次に「なぜ必要か」、最後に「どう実装するか」を話す
  • 初学者に断片文書を拾わせて自力でつなげさせない

学習の約束

この教材を一通り終えたとき、目標は次の 2 つです。

  1. 0 から自分で、構造が明快で反復改善できる coding-agent harness を組み立てられること
  2. より複雑な実装を読むときに、何が設計主線で何が製品周辺の detail なのかを見分けられること

このリポジトリが重視するのは:

  • 重要メカニズムと主要データ構造の高い再現度
  • 自分の手で作り直せる実装可能性
  • 途中で心智がねじれにくい読み順と説明密度

推奨される読み順

日本語版でも主線・bridge doc・web の主要導線は揃えています。
章順と補助資料は、日本語でもそのまま追えるように保っています。

初めてこのリポジトリを開くなら

最初から章をばらばらに開かない方が安定します。

最も安全な入口は次の順序です。

  1. docs/ja/s00-architecture-overview.md で全体図をつかむ
  2. docs/ja/s00d-chapter-order-rationale.md で、なぜこの順序で学ぶのかを確認する
  3. docs/ja/s00f-code-reading-order.md で、ローカルの agents/*.py をどの順で開くか確認する
  4. s01-s06 -> s07-s11 -> s12-s14 -> s15-s19 の 4 段階で主線を順に進める
  5. 各段階の終わりで一度止まり、最小版を自分で書き直してから次へ進む

中盤以降で境界が混ざり始めたら、次の順で立て直すのが安定です。

  1. docs/ja/data-structures.md
  2. docs/ja/entity-map.md
  3. いま詰まっている章に近い bridge doc
  4. その後で章本文へ戻る

Web 学習入口

章順、段階境界、章どうしの差分を可視化から入りたい場合は、組み込みの web 教材画面を使えます。

cd web
npm install
npm run dev

開いたあと、まず見ると良いルートは次です。

  • /ja: 日本語の学習入口。最初にどの読み方を選ぶか決める
  • /ja/timeline: 主線を順にたどる最も安定した入口
  • /ja/layers: 4 段階の境界を先に理解する入口
  • /ja/compare: 2 章の差やジャンプ診断を見る入口

初回読みに最も向くのは timeline です。
途中で境界が混ざったら、先に layers と compare を見てから本文へ戻る方が安定します。

橋渡しドキュメント

これは新しい主線章ではなく、中盤以降の理解をつなぐための補助文書です。

4 段階の主線

  1. s01-s06: まず単体 agent のコアを作る
  2. s07-s11: 安全性、拡張性、記憶、prompt、recovery を足す
  3. s12-s14: 一時的な計画を持続的なランタイム作業へ育てる
  4. s15-s19: チーム、プロトコル、自律動作、分離実行、外部 capability routing へ進む

主線の章

章 テーマ 得られるもの
s00 Architecture Overview 全体マップ、用語、学習順
s01 Agent Loop 最小の動く agent ループ
s02 Tool Use 安定したツール分配
s03 Todo / Planning 可視化されたセッション計画
s04 Subagent 委譲時の新鮮な文脈
s05 Skills 必要な知識だけを後から読む仕組み
s06 Context Compact アクティブ文脈を小さく保つ
s07 Permission System 実行前の安全ゲート
s08 Hook System ループ周辺の拡張点
s09 Memory System セッションをまたぐ長期情報
s10 System Prompt セクション分割された prompt 組み立て
s11 Error Recovery 続行・再試行・停止の分岐
s12 Task System 永続タスクグラフ
s13 Background Tasks 非ブロッキング実行
s14 Cron Scheduler 時間起点のトリガー
s15 Agent Teams 永続チームメイト
s16 Team Protocols 共有された協調ルール
s17 Autonomous Agents 自律的な認識・再開
s18 Worktree Isolation 分離実行レーン
s19 MCP & Plugin 外部 capability routing

クイックスタート

git clone https://github.com/shareAI-lab/learn-claude-code
cd learn-claude-code
pip install -r requirements.txt
cp .env.example .env

その後、.env に ANTHROPIC_API_KEY または互換エンドポイントを設定してから:

python agents/s01_agent_loop.py
python agents/s18_worktree_task_isolation.py
python agents/s19_mcp_plugin.py
python agents/s_full.py

おすすめの進め方:

  1. まず s01 を動かし、最小ループが本当に動くことを確認する
  2. s00 を読みながら s01 -> s11 を順に進める
  3. 単体 agent 本体と control plane が安定して理解できてから s12 -> s19 に入る
  4. 最後に s_full.py を見て、全部の機構を一枚の全体像に戻す

各章の読み方

各章は、次の順序で読むと理解しやすいです。

  1. この機構がないと何が困るか
  2. 新しい概念は何か
  3. 最小で正しい実装は何か
  4. 状態はどこに置かれるのか
  5. それがループにどう接続されるのか
  6. この章ではどこで一度止まり、何を後回しにしてよいのか

もし読んでいて:

  • 「これは主線なのか、補足なのか」
  • 「この状態は結局どこにあるのか」

と迷ったら、次を見直してください。

構成

learn-claude-code/
├── agents/              # 章ごとの実行可能な Python 参考実装
├── docs/zh/             # 中国語の主線文書
├── docs/en/             # 英語文書
├── docs/ja/             # 日本語文書
├── skills/              # s05 で使う skill ファイル
├── web/                 # Web 教学プラットフォーム
└── requirements.txt

言語の状態

中国語が正本であり、更新も最も速いです。

  • zh: 最も完全で、最もレビューされている
  • en: 主線章と主要な橋渡し文書が利用できる
  • ja: 主線章と主要な橋渡し文書が利用できる

最も深く、最も更新の速い説明を追うなら、まず中国語版を優先してください。

最終目標

読み終わるころには、次の問いに自分の言葉で答えられるようになるはずです。

  • coding agent の最小状態は何か
  • tool_result がなぜループの中心なのか
  • どういう時に subagent を使うべきか
  • permissions、hooks、memory、prompt、task がそれぞれ何を解決するのか
  • いつ単体 agent を tasks、teams、worktrees、MCP へ成長させるべきか

<<<<<<< HEAD それを説明できて、自分で似たシステムを作れるなら、このリポジトリの目的は達成です。

Skill & LSP 対応、Windows 対応、GLM / MiniMax / DeepSeek 等のオープンモデルに接続可能。インストールしてすぐ使える。

GitHub: shareAI-lab/Kode-cli

Kode Agent SDK -- アプリにエージェント機能を埋め込む

公式 Claude Code Agent SDK は内部で完全な CLI プロセスと通信する -- 同時ユーザーごとに独立のターミナルプロセスが必要。Kode SDK は独立ライブラリでユーザーごとのプロセスオーバーヘッドがなく、バックエンド、ブラウザ拡張、組み込みデバイス等に埋め込み可能。

GitHub: shareAI-lab/Kode-agent-sdk

姉妹教材: オンデマンドセッションから常時稼働アシスタントへ

本リポジトリが教える Harness は 使い捨て型 -- ターミナルを開き、Agent にタスクを与え、終わったら閉じる。次のセッションは白紙から始まる。Claude Code のモデル。

OpenClaw は別の可能性を証明した: 同じ agent core の上に 2 つの Harness メカニズムを追加するだけで、Agent は「突かないと動かない」から「30 秒ごとに自分で起きて仕事を探す」に変わる:

  • ハートビート -- 30 秒ごとに Harness が Agent にメッセージを送り、やることがあるか確認させる。なければスリープ続行、あれば即座に行動。
  • Cron -- Agent が自ら未来のタスクをスケジュールし、時間が来たら自動実行。

さらにマルチチャネル IM ルーティング (WhatsApp / Telegram / Slack / Discord 等 13+ プラットフォーム)、永続コンテキストメモリ、Soul パーソナリティシステムを加えると、Agent は使い捨てツールから常時稼働のパーソナル AI アシスタントへ変貌する。

claw0 はこれらの Harness メカニズムをゼロから分解する姉妹教材リポジトリ:

claw agent = agent core + heartbeat + cron + IM chat + memory + soul

learn-claude-code                   claw0
(agent harness コア:                 (能動的な常時稼働 harness:
 ループ、ツール、計画、                ハートビート、cron、IM チャネル、
 チーム、worktree 分離)                メモリ、Soul パーソナリティ)

ライセンス

MIT

Agency はモデルから生まれる。Harness が Agency を現実にする。優れた Harness を作れ。モデルが残りをやる。

Bash is all you need. Real agents are all the universe needs.

4b95969a03f780e8aa17340a10ff0a6d9512a2c9