{"id":51223075,"url":"https://github.com/jafini/learn-claude-code","last_synced_at":"2026-07-16T19:01:04.970Z","repository":{"id":343260268,"uuid":"982188528","full_name":"jafini/learn-claude-code","owner":"jafini","description":"Build a minimal Claude-style AI agent from scratch that processes messages, interacts with tools, and generates dynamic responses.","archived":false,"fork":false,"pushed_at":"2026-07-15T14:35:13.000Z","size":1092,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-07-15T16:22:34.099Z","etag":null,"topics":["agent-development","ai","ai-agent","ai-programming","ai-tools","claude-code","claude-code-marketplace","claude-code-plugin","claude-code-plugins","claude-code-skills","cli","codex-skills","deeplearning-ai","educational","figma-to-code","information-gathering","llm","reflection","self-learning"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jafini.png","metadata":{"files":{"readme":"README-ja.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-12T13:59:40.000Z","updated_at":"2026-07-15T14:37:40.000Z","dependencies_parsed_at":"2026-04-30T11:03:07.527Z","dependency_job_id":null,"html_url":"https://github.com/jafini/learn-claude-code","commit_stats":null,"previous_names":["jafini/learn-claude-code"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jafini/learn-claude-code","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jafini%2Flearn-claude-code","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jafini%2Flearn-claude-code/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jafini%2Flearn-claude-code/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jafini%2Flearn-claude-code/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jafini","download_url":"https://codeload.github.com/jafini/learn-claude-code/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jafini%2Flearn-claude-code/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35555509,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-16T02:00:06.687Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-development","ai","ai-agent","ai-programming","ai-tools","claude-code","claude-code-marketplace","claude-code-plugin","claude-code-plugins","claude-code-skills","cli","codex-skills","deeplearning-ai","educational","figma-to-code","information-gathering","llm","reflection","self-learning"],"created_at":"2026-06-28T09:00:31.116Z","updated_at":"2026-07-16T19:01:04.965Z","avatar_url":"https://github.com/jafini.png","language":"TypeScript","funding_links":[],"categories":["Source Catalog"],"sub_categories":[],"readme":"# Learn Claude Code -- 0 から 1 へ構築する nano Claude Code-like agent\n\n[English](./README.md) | [中文](./README-zh.md) | [日本語](./README-ja.md)\n\n```\n                    THE AGENT PATTERN\n                    =================\n\n    User --\u003e messages[] --\u003e LLM --\u003e response\n                                      |\n                            stop_reason == \"tool_use\"?\n                           /                          \\\n                         yes                           no\n                          |                             |\n                    execute tools                    return text\n                    append results\n                    loop back -----------------\u003e messages[]\n\n\n    これは最小ループだ。すべての AI コーディングエージェントに必要な土台になる。\n    本番のエージェントには、ポリシー・権限・ライフサイクル層が追加される。\n```\n\n**12 の段階的セッション、シンプルなループから分離された自律実行まで。**\n**各セッションは1つのメカニズムを追加する。各メカニズムには1つのモットーがある。**\n\n\u003e **s01** \u0026nbsp; *\"One loop \u0026 Bash is all you need\"* \u0026mdash; 1つのツール + 1つのループ = エージェント\n\u003e\n\u003e **s02** \u0026nbsp; *\"ツールを足すなら、ハンドラーを1つ足すだけ\"* \u0026mdash; ループは変わらない。新ツールは dispatch map に登録するだけ\n\u003e\n\u003e **s03** \u0026nbsp; *\"計画のないエージェントは行き当たりばったり\"* \u0026mdash; まずステップを書き出し、それから実行\n\u003e\n\u003e **s04** \u0026nbsp; *\"大きなタスクを分割し、各サブタスクにクリーンなコンテキストを\"* \u0026mdash; サブエージェントは独立した messages[] を使い、メイン会話を汚さない\n\u003e\n\u003e **s05** \u0026nbsp; *\"必要な知識を、必要な時に読み込む\"* \u0026mdash; system prompt ではなく tool_result で注入\n\u003e\n\u003e **s06** \u0026nbsp; *\"コンテキストはいつか溢れる、空ける手段が要る\"* \u0026mdash; 3層圧縮で無限セッションを実現\n\u003e\n\u003e **s07** \u0026nbsp; *\"大きな目標を小タスクに分解し、順序付けし、ディスクに記録する\"* \u0026mdash; ファイルベースのタスクグラフ、マルチエージェント協調の基盤\n\u003e\n\u003e **s08** \u0026nbsp; *\"遅い操作はバックグラウンドへ、エージェントは次を考え続ける\"* \u0026mdash; デーモンスレッドがコマンド実行、完了後に通知を注入\n\u003e\n\u003e **s09** \u0026nbsp; *\"一人で終わらないなら、チームメイトに任せる\"* \u0026mdash; 永続チームメイト + 非同期メールボックス\n\u003e\n\u003e **s10** \u0026nbsp; *\"チームメイト間には統一の通信ルールが必要\"* \u0026mdash; 1つの request-response パターンが全交渉を駆動\n\u003e\n\u003e **s11** \u0026nbsp; *\"チームメイトが自らボードを見て、仕事を取る\"* \u0026mdash; リーダーが逐一割り振る必要はない\n\u003e\n\u003e **s12** \u0026nbsp; *\"各自のディレクトリで作業し、互いに干渉しない\"* \u0026mdash; タスクは目標を管理、worktree はディレクトリを管理、IDで紐付け\n\n---\n\n## コアパターン\n\n```python\ndef agent_loop(messages):\n    while True:\n        response = client.messages.create(\n            model=MODEL, system=SYSTEM,\n            messages=messages, tools=TOOLS,\n        )\n        messages.append({\"role\": \"assistant\",\n                         \"content\": response.content})\n\n        if response.stop_reason != \"tool_use\":\n            return\n\n        results = []\n        for block in response.content:\n            if block.type == \"tool_use\":\n                output = TOOL_HANDLERS[block.name](**block.input)\n                results.append({\n                    \"type\": \"tool_result\",\n                    \"tool_use_id\": block.id,\n                    \"content\": output,\n                })\n        messages.append({\"role\": \"user\", \"content\": results})\n```\n\n各セッションはこのループの上に1つのメカニズムを重ねる -- ループ自体は変わらない。\n\n## スコープ (重要)\n\nこのリポジトリは、nano Claude Code-like agent を 0-\u003e1 で構築・学習するための教材プロジェクトです。\n学習を優先するため、以下の本番メカニズムは意図的に簡略化または省略しています。\n\n- 完全なイベント / Hook バス (例: PreToolUse, SessionStart/End, ConfigChange)。  \n  s12 では教材用に最小の追記型ライフサイクルイベントのみ実装している。\n- ルールベースの権限ガバナンスと信頼フロー\n- セッションライフサイクル制御 (resume/fork) と高度な worktree ライフサイクル制御\n- MCP ランタイムの詳細 (transport/OAuth/リソース購読/ポーリング)\n\nこのリポジトリの JSONL メールボックス方式は教材用の実装であり、特定の本番内部実装を主張するものではありません。\n\n## クイックスタート\n\n```sh\ngit clone https://github.com/shareAI-lab/learn-claude-code\ncd learn-claude-code\npip install -r requirements.txt\ncp .env.example .env   # .env を編集して ANTHROPIC_API_KEY を入力\n\npython agents/s01_agent_loop.py       # ここから開始\npython agents/s12_worktree_task_isolation.py  # 全セッションの到達点\npython agents/s_full.py               # 総括: 全メカニズム統合\n```\n\n### Web プラットフォーム\n\nインタラクティブな可視化、ステップスルーアニメーション、ソースビューア、各セッションのドキュメント。\n\n```sh\ncd web \u0026\u0026 npm install \u0026\u0026 npm run dev   # http://localhost:3000\n```\n\n## 学習パス\n\n```\nフェーズ1: ループ                     フェーズ2: 計画と知識\n==================                   ==============================\ns01  エージェントループ      [1]     s03  TodoWrite               [5]\n     while + stop_reason                  TodoManager + nag リマインダー\n     |                                    |\n     +-\u003e s02  Tool Use            [4]     s04  サブエージェント      [5]\n              dispatch map: name-\u003ehandler     子ごとに新しい messages[]\n                                              |\n                                         s05  Skills               [5]\n                                              SKILL.md を tool_result で注入\n                                              |\n                                         s06  Context Compact      [5]\n                                              3層コンテキスト圧縮\n\nフェーズ3: 永続化                     フェーズ4: チーム\n==================                   =====================\ns07  タスクシステム           [8]     s09  エージェントチーム      [9]\n     ファイルベース CRUD + 依存グラフ      チームメイト + JSONL メールボックス\n     |                                    |\ns08  バックグラウンドタスク   [6]     s10  チームプロトコル        [12]\n     デーモンスレッド + 通知キュー         シャットダウン + プラン承認 FSM\n                                          |\n                                     s11  自律エージェント        [14]\n                                          アイドルサイクル + 自動クレーム\n                                     |\n                                     s12  Worktree 分離           [16]\n                                          タスク調整 + 必要時の分離実行レーン\n\n                                     [N] = ツール数\n```\n\n## プロジェクト構成\n\n```\nlearn-claude-code/\n|\n|-- agents/                        # Python リファレンス実装 (s01-s12 + s_full 総括)\n|-- docs/{en,zh,ja}/               # メンタルモデル優先のドキュメント (3言語)\n|-- web/                           # インタラクティブ学習プラットフォーム (Next.js)\n|-- skills/                        # s05 の Skill ファイル\n+-- .github/workflows/ci.yml      # CI: 型チェック + ビルド\n```\n\n## ドキュメント\n\nメンタルモデル優先: 問題、解決策、ASCII図、最小限のコード。\n[English](./docs/en/) | [中文](./docs/zh/) | [日本語](./docs/ja/)\n\n| セッション | トピック | モットー |\n|-----------|---------|---------|\n| [s01](./docs/ja/s01-the-agent-loop.md) | エージェントループ | *One loop \u0026 Bash is all you need* |\n| [s02](./docs/ja/s02-tool-use.md) | Tool Use | *ツールを足すなら、ハンドラーを1つ足すだけ* |\n| [s03](./docs/ja/s03-todo-write.md) | TodoWrite | *計画のないエージェントは行き当たりばったり* |\n| [s04](./docs/ja/s04-subagent.md) | サブエージェント | *大きなタスクを分割し、各サブタスクにクリーンなコンテキストを* |\n| [s05](./docs/ja/s05-skill-loading.md) | Skills | *必要な知識を、必要な時に読み込む* |\n| [s06](./docs/ja/s06-context-compact.md) | Context Compact | *コンテキストはいつか溢れる、空ける手段が要る* |\n| [s07](./docs/ja/s07-task-system.md) | タスクシステム | *大きな目標を小タスクに分解し、順序付けし、ディスクに記録する* |\n| [s08](./docs/ja/s08-background-tasks.md) | バックグラウンドタスク | *遅い操作はバックグラウンドへ、エージェントは次を考え続ける* |\n| [s09](./docs/ja/s09-agent-teams.md) | エージェントチーム | *一人で終わらないなら、チームメイトに任せる* |\n| [s10](./docs/ja/s10-team-protocols.md) | チームプロトコル | *チームメイト間には統一の通信ルールが必要* |\n| [s11](./docs/ja/s11-autonomous-agents.md) | 自律エージェント | *チームメイトが自らボードを見て、仕事を取る* |\n| [s12](./docs/ja/s12-worktree-task-isolation.md) | Worktree + タスク分離 | *各自のディレクトリで作業し、互いに干渉しない* |\n\n## 次のステップ -- 理解から出荷へ\n\n12 セッションを終えれば、エージェントの内部構造を完全に理解している。その知識を活かす 2 つの方法:\n\n### Kode Agent CLI -- オープンソース Coding Agent CLI\n\n\u003e `npm i -g @shareai-lab/kode`\n\nSkill \u0026 LSP 対応、Windows 対応、GLM / MiniMax / DeepSeek 等のオープンモデルに接続可能。インストールしてすぐ使える。\n\nGitHub: **[shareAI-lab/Kode-cli](https://github.com/shareAI-lab/Kode-cli)**\n\n### Kode Agent SDK -- アプリにエージェント機能を埋め込む\n\n公式 Claude Code Agent SDK は内部で完全な CLI プロセスと通信する -- 同時ユーザーごとに独立のターミナルプロセスが必要。Kode SDK は独立ライブラリでユーザーごとのプロセスオーバーヘッドがなく、バックエンド、ブラウザ拡張、組み込みデバイス等に埋め込み可能。\n\nGitHub: **[shareAI-lab/Kode-agent-sdk](https://github.com/shareAI-lab/Kode-agent-sdk)**\n\n---\n\n## 姉妹教材: *オンデマンドセッション*から*常時稼働アシスタント*へ\n\n本リポジトリが教えるエージェントは **使い捨て型** -- ターミナルを開き、タスクを与え、終わったら閉じる。次のセッションは白紙から始まる。これが Claude Code のモデル。\n\n[OpenClaw](https://github.com/openclaw/openclaw) は別の可能性を証明した: 同じ agent core の上に 2 つのメカニズムを追加するだけで、エージェントは「突かないと動かない」から「30 秒ごとに自分で起きて仕事を探す」に変わる:\n\n- **ハートビート** -- 30 秒ごとにシステムがエージェントにメッセージを送り、やることがあるか確認させる。なければスリープ続行、あれば即座に行動。\n- **Cron** -- エージェントが自ら未来のタスクをスケジュールし、時間が来たら自動実行。\n\nさらにマルチチャネル IM ルーティング (WhatsApp / Telegram / Slack / Discord 等 13+ プラットフォーム)、永続コンテキストメモリ、Soul パーソナリティシステムを加えると、エージェントは使い捨てツールから常時稼働のパーソナル AI アシスタントへ変貌する。\n\n**[claw0](https://github.com/shareAI-lab/claw0)** はこれらのメカニズムをゼロから分解する姉妹教材リポジトリ:\n\n```\nclaw agent = agent core + heartbeat + cron + IM chat + memory + soul\n```\n\n```\nlearn-claude-code                   claw0\n(エージェントランタイムコア:          (能動的な常時稼働アシスタント:\n ループ、ツール、計画、                ハートビート、cron、IM チャネル、\n チーム、worktree 分離)                メモリ、Soul パーソナリティ)\n```\n\n## ライセンス\n\nMIT\n\n---\n\n**モデルがエージェントだ。私たちの仕事はツールを与えて邪魔しないこと。**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjafini%2Flearn-claude-code","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjafini%2Flearn-claude-code","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjafini%2Flearn-claude-code/lists"}