# Learn Claude Code -- AI Agent をゼロから構築する

[English](./README.md) | [中文](./README-zh.md) | [日本語](./README-ja.md)

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

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


    これだけだ。すべての AI コーディングエージェントはこのループ。
    他はすべて改良に過ぎない。
```

**11 の段階的セッション、シンプルなループから完全な自律チームまで。**
**各セッションは1つのメカニズムを追加する。各メカニズムには1つのモットーがある。**

> **s01**   *"Bash があれば十分"* — 1つのツール + 1つのループ = エージェント
>
> **s02**   *"ループは変わらない"* — ツール追加はハンドラー追加であり、ロジック追加ではない
>
> **s03**   *"行動する前に計画せよ"* — 可視化された計画がタスク完了率を向上させる
>
> **s04**   *"プロセス分離 = コンテキスト分離"* — サブエージェントごとに新しい messages[]
>
> **s05**   *"必要な時にロード、事前にではなく"* — system prompt ではなく tool_result で知識を注入
>
> **s06**   *"戦略的忘却"* — 古いコンテキストを忘れて無限セッションを実現
>
> **s07**   *"状態は圧縮を生き延びる"* — ファイルベースの状態はコンテキスト圧縮に耐える
>
> **s08**   *"撃ちっ放し"* — ノンブロッキングスレッド + 通知キュー
>
> **s09**   *"追記で送信、排出で読取"* — 永続チームメイトのための非同期メールボックス
>
> **s10**   *"同じ request_id、2つのプロトコル"* — 1つの FSM パターンでシャットダウン + プラン承認
>
> **s11**   *"ポーリング、クレーム、作業、繰り返し"* — コーディネーター不要、エージェントが自己組織化

---

## コアパターン

```python
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つのメカニズムを重ねる -- ループ自体は変わらない。

## クイックスタート

```sh
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/s11_autonomous_agents.py  # 完全自律チーム
```

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

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

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

## 学習パス

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

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

                                     [N] = ツール数
```

## プロジェクト構成

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

## ドキュメント

メンタルモデル優先: 問題、解決策、ASCII図、最小限のコード。
[English](./docs/en/) | [中文](./docs/zh/) | [日本語](./docs/ja/)

| セッション | トピック | モットー |
|-----------|---------|---------|
| [s01](./docs/ja/s01-the-agent-loop.md) | エージェントループ | *Bash があれば十分* |
| [s02](./docs/ja/s02-tool-use.md) | ツール | *ループは変わらない* |
| [s03](./docs/ja/s03-todo-write.md) | TodoWrite | *行動する前に計画せよ* |
| [s04](./docs/ja/s04-subagent.md) | サブエージェント | *プロセス分離 = コンテキスト分離* |
| [s05](./docs/ja/s05-skill-loading.md) | Skills | *必要な時にロード、事前にではなく* |
| [s06](./docs/ja/s06-context-compact.md) | Compact | *戦略的忘却* |
| [s07](./docs/ja/s07-task-system.md) | タスクシステム | *状態は圧縮を生き延びる* |
| [s08](./docs/ja/s08-background-tasks.md) | バックグラウンドタスク | *撃ちっ放し* |
| [s09](./docs/ja/s09-agent-teams.md) | エージェントチーム | *追記で送信、排出で読取* |
| [s10](./docs/ja/s10-team-protocols.md) | チームプロトコル | *同じ request_id、2つのプロトコル* |
| [s11](./docs/ja/s11-autonomous-agents.md) | 自律エージェント | *ポーリング、クレーム、作業、繰り返し* |

## ライセンス

MIT

---

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