mirror of https://github.com/shareAI-lab/analysis_claude_code.git synced 2026-03-22 02:15:42 +08:00

CrazyBoyM 665831c774 better doc

2026-02-27 01:11:57 +08:00

12 KiB

Raw Blame History

Learn Claude Code -- 0 から 1 へ構築する nano Claude Code-like agent

                    THE AGENT PATTERN
                    =================

    User --> messages[] --> LLM --> response
                                      |
                            stop_reason == "tool_use"?
                           /                          \
                         yes                           no
                          |                             |
                    execute tools                    return text
                    append results
                    loop back -----------------> messages[]


    これは最小ループだ。すべての AI コーディングエージェントに必要な土台になる。
    本番のエージェントには、ポリシー・権限・ライフサイクル層が追加される。

12 の段階的セッション、シンプルなループから分離された自律実行まで。 各セッションは1つのメカニズムを追加する。各メカニズムには1つのモットーがある。

s01 "One loop & Bash is all you need" — 1つのツール + 1つのループ = エージェント

s02 "ループは変わらない" — ツール追加はハンドラー追加であり、ループの作り直しではない

s03 "行動する前に計画せよ" — 可視化された計画がタスク完了率を向上させる

s04 "プロセス分離 = コンテキスト分離" — サブエージェントごとに新しい messages[]

s05 "必要な時にロード、事前にではなく" — system prompt ではなく tool_result で知識を注入

s06 "戦略的忘却" — 古いコンテキストを忘れて無限セッションを実現

s07 "状態は圧縮を生き延びる" — ファイルベースの状態はコンテキスト圧縮に耐える

s08 "撃ちっ放し" — ノンブロッキングスレッド + 通知キュー

s09 "追記で送信、排出で読取" — 永続チームメイトのための非同期メールボックス

s10 "同じ request_id、2つのプロトコル" — 1つの FSM パターンでシャットダウン + プラン承認

s11 "ポーリング、クレーム、作業、繰り返し" — コーディネーター不要、エージェントが自己組織化

s12 "ディレクトリで分離し、タスクIDで調整する" — タスクボード + 必要時の worktree レーン

コアパターン

def agent_loop(messages):
    while True:
        response = client.messages.create(
            model=MODEL, system=SYSTEM,
            messages=messages, tools=TOOLS,
        )
        messages.append({"role": "assistant",
                         "content": response.content})

        if response.stop_reason != "tool_use":
            return

        results = []
        for block in response.content:
            if block.type == "tool_use":
                output = TOOL_HANDLERS[block.name](**block.input)
                results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": output,
                })
        messages.append({"role": "user", "content": results})

各セッションはこのループの上に1つのメカニズムを重ねる -- ループ自体は変わらない。

スコープ (重要)

このリポジトリは、nano Claude Code-like agent を 0->1 で構築・学習するための教材プロジェクトです。学習を優先するため、以下の本番メカニズムは意図的に簡略化または省略しています。

完全なイベント / Hook バス (例: PreToolUse, SessionStart/End, ConfigChange)。
s12 では教材用に最小の追記型ライフサイクルイベントのみ実装している。
ルールベースの権限ガバナンスと信頼フロー
セッションライフサイクル制御 (resume/fork) と高度な worktree ライフサイクル制御
MCP ランタイムの詳細 (transport/OAuth/リソース購読/ポーリング)

このリポジトリの JSONL メールボックス方式は教材用の実装であり、特定の本番内部実装を主張するものではありません。

クイックスタート

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/s12_worktree_task_isolation.py  # 全セッションの到達点
python agents/s_full.py               # 総括: 全メカニズム統合

Web プラットフォーム

インタラクティブな可視化、ステップスルーアニメーション、ソースビューア、各セッションのドキュメント。

cd web && npm install && npm run dev   # http://localhost:3000

学習パス

フェーズ1: ループ                     フェーズ2: 計画と知識
==================                   ==============================
s01  エージェントループ      [1]     s03  TodoWrite               [5]
     while + stop_reason                  TodoManager + nag リマインダー
     |                                    |
     +-> s02  Tool Use            [4]     s04  サブエージェント      [5]
              dispatch map: name->handler     子ごとに新しい messages[]
                                              |
                                         s05  Skills               [5]
                                              SKILL.md を tool_result で注入
                                              |
                                         s06  Context Compact      [5]
                                              3層コンテキスト圧縮

フェーズ3: 永続化                     フェーズ4: チーム
==================                   =====================
s07  タスクシステム           [8]     s09  エージェントチーム      [9]
     ファイルベース CRUD + 依存グラフ      チームメイト + JSONL メールボックス
     |                                    |
s08  バックグラウンドタスク   [6]     s10  チームプロトコル        [12]
     デーモンスレッド + 通知キュー         シャットダウン + プラン承認 FSM
                                          |
                                     s11  自律エージェント        [14]
                                          アイドルサイクル + 自動クレーム
                                     |
                                     s12  Worktree 分離           [16]
                                          タスク調整 + 必要時の分離実行レーン

                                     [N] = ツール数

プロジェクト構成

learn-claude-code/
|
|-- agents/                        # Python リファレンス実装 (s01-s12 + s_full 総括)
|-- docs/{en,zh,ja}/               # メンタルモデル優先のドキュメント (3言語)
|-- web/                           # インタラクティブ学習プラットフォーム (Next.js)
|-- skills/                        # s05 の Skill ファイル
+-- .github/workflows/ci.yml      # CI: 型チェック + ビルド

ドキュメント

メンタルモデル優先: 問題、解決策、ASCII図、最小限のコード。 English | 中文 | 日本語

セッション	トピック	モットー
s01	エージェントループ	One loop & Bash is all you need
s02	Tool Use	ループは変わらない
s03	TodoWrite	行動する前に計画せよ
s04	サブエージェント	プロセス分離 = コンテキスト分離
s05	Skills	必要な時にロード、事前にではなく
s06	Context Compact	戦略的忘却
s07	タスクシステム	状態は圧縮を生き延びる
s08	バックグラウンドタスク	撃ちっ放し
s09	エージェントチーム	追記で送信、排出で読取
s10	チームプロトコル	同じ request_id、2つのプロトコル
s11	自律エージェント	ポーリング、クレーム、作業、繰り返し
s12	Worktree + タスク分離	ディレクトリで分離し、タスクIDで調整する

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

12 セッションを終えれば、エージェントの内部構造を完全に理解している。その知識を活かす 2 つの方法:

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

npm i -g @shareai-lab/kode

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

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

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

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

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

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

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

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

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

ライセンス

MIT

モデルがエージェントだ。私たちの仕事はツールを与えて邪魔しないこと。

12 KiB Raw Blame History