diff --git a/README.md b/README.md index 8acce1d..7c86393 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ **Learn how modern AI agents work by building one from scratch.** -[中文文档](./README_zh.md) +[Chinese / 中文](./README_zh.md) | [Japanese / 日本語](./README_ja.md) --- @@ -121,31 +121,24 @@ learn-claude-code/ ├── v3_subagent.py # ~450 lines: + Task tool, agent registry ├── v4_skills_agent.py # ~550 lines: + Skill tool, SkillLoader ├── skills/ # Example skills (pdf, code-review, mcp-builder, agent-builder) -├── docs/ # Technical documentation (EN + ZH) +├── docs/ # Technical documentation (EN + ZH + JA) ├── articles/ # Blog-style articles (ZH) └── tests/ # Unit and integration tests ``` -## Deep Dives +## Documentation -### Technical Documentation (docs/) +### Technical Tutorials (docs/) -| English | 中文 | -|---------|------| -| [v0: Bash is All You Need](./docs/v0-bash-is-all-you-need.md) | [v0: Bash 就是一切](./docs/v0-Bash就是一切.md) | -| [v1: Model as Agent](./docs/v1-model-as-agent.md) | [v1: 模型即代理](./docs/v1-模型即代理.md) | -| [v2: Structured Planning](./docs/v2-structured-planning.md) | [v2: 结构化规划](./docs/v2-结构化规划.md) | -| [v3: Subagent Mechanism](./docs/v3-subagent-mechanism.md) | [v3: 子代理机制](./docs/v3-子代理机制.md) | -| [v4: Skills Mechanism](./docs/v4-skills-mechanism.md) | [v4: Skills 机制](./docs/v4-Skills机制.md) | +- [v0: Bash is All You Need](./docs/v0-bash-is-all-you-need.md) +- [v1: Model as Agent](./docs/v1-model-as-agent.md) +- [v2: Structured Planning](./docs/v2-structured-planning.md) +- [v3: Subagent Mechanism](./docs/v3-subagent-mechanism.md) +- [v4: Skills Mechanism](./docs/v4-skills-mechanism.md) -### Articles (articles/) - Chinese, Social Media Style +### Articles -- [v0文章](./articles/v0文章.md) - Bash is All You Need -- [v1文章](./articles/v1文章.md) - The $30M Secret in 400 Lines -- [v2文章](./articles/v2文章.md) - Self-Constraining with Todo -- [v3文章](./articles/v3文章.md) - Subagent Mechanism -- [v4文章](./articles/v4文章.md) - Skills Mechanism -- [上下文缓存经济学](./articles/上下文缓存经济学.md) - Context Caching Economics +See [articles/](./articles/) for blog-style explanations. ## Using the Skills System diff --git a/README_ja.md b/README_ja.md new file mode 100644 index 0000000..67881c6 --- /dev/null +++ b/README_ja.md @@ -0,0 +1,214 @@ +# Learn Claude Code - Bashがあれば、エージェントは作れる + +[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/) +[![Tests](https://github.com/shareAI-lab/learn-claude-code/actions/workflows/test.yml/badge.svg)](https://github.com/shareAI-lab/learn-claude-code/actions) +[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE) + +> **免責事項**: これは [shareAI Lab](https://github.com/shareAI-lab) による独立した教育プロジェクトです。Anthropic社とは無関係であり、同社からの承認やスポンサーを受けていません。「Claude Code」はAnthropic社の商標です。 + +**ゼロからAIエージェントの仕組みを学ぶ。** + +[English](./README.md) | [中文](./README_zh.md) + +--- + +## なぜこのリポジトリを作ったのか？ + +このリポジトリは、Claude Code への敬意から生まれました。私たちは **Claude Code を世界最高のAIコーディングエージェント** だと考えています。当初、行動観察と推測によってその設計をリバースエンジニアリングしようとしました。しかし、公開した分析には不正確な情報、根拠のない推測、技術的な誤りが含まれていました。Claude Code チームと、誤った情報を信じてしまった方々に深くお詫び申し上げます。 + +過去6ヶ月間、実際のエージェントシステムを構築し反復する中で、**「真のAIエージェントとは何か」** についての理解が根本的に変わりました。その知見を皆さんと共有したいと思います。以前の推測的なコンテンツはすべて削除し、オリジナルの教材に置き換えました。 + +--- + +> **[Kode CLI](https://github.com/shareAI-lab/Kode)**、**Claude Code**、**Cursor**、および [Agent Skills Spec](https://github.com/anthropics/agent-skills) をサポートするすべてのエージェントで動作します。 + +demo + +## 学べること + +このチュートリアルを完了すると、以下を理解できます： + +- **エージェントループ** - すべてのAIコーディングエージェントの背後にある驚くほどシンプルなパターン +- **ツール設計** - AIモデルに現実世界と対話する能力を与える方法 +- **明示的な計画** - 制約を使ってAIの動作を予測可能にする +- **コンテキスト管理** - サブエージェントの分離によりエージェントのメモリをクリーンに保つ +- **知識注入** - 再学習なしでドメイン専門知識をオンデマンドで読み込む + +## 学習パス + +``` +ここから始める + | + v +[v0: Bash Agent] -----> 「1つのツールで十分」 + | 16-50行 + v +[v1: Basic Agent] ----> 「完全なエージェントパターン」 + | 4ツール、約200行 + v +[v2: Todo Agent] -----> 「計画を明示化する」 + | +TodoManager、約300行 + v +[v3: Subagent] -------> 「分割統治」 + | +Taskツール、約450行 + v +[v4: Skills Agent] ---> 「オンデマンドのドメイン専門性」 + +Skillツール、約550行 +``` + +**おすすめの学習方法：** +1. まずv0を読んで実行 - コアループを理解する +2. v0とv1を比較 - ツールがどう進化するか見る +3. v2で計画パターンを学ぶ +4. v3で複雑なタスク分解を探求する +5. v4で拡張可能なエージェント構築をマスターする + +## クイックスタート + +```bash +# リポジトリをクローン +git clone https://github.com/shareAI-lab/learn-claude-code +cd learn-claude-code + +# 依存関係をインストール +pip install -r requirements.txt + +# API キーを設定 +cp .env.example .env +# .env を編集して ANTHROPIC_API_KEY を入力 + +# 任意のバージョンを実行 +python v0_bash_agent.py # 最小限（ここから始めよう！） +python v1_basic_agent.py # コアエージェントループ +python v2_todo_agent.py # + Todo計画 +python v3_subagent.py # + サブエージェント +python v4_skills_agent.py # + Skills +``` + +## コアパターン + +すべてのコーディングエージェントは、このループにすぎない： + +```python +while True: + response = model(messages, tools) + if response.stop_reason != "tool_use": + return response.text + results = execute(response.tool_calls) + messages.append(results) +``` + +これだけです。モデルは完了するまでツールを呼び出し続けます。他のすべては改良にすぎません。 + +## バージョン比較 + +| バージョン | 行数 | ツール | コア追加 | 重要な洞察 | +|------------|------|--------|----------|------------| +| [v0](./v0_bash_agent.py) | ~50 | bash | 再帰的サブエージェント | 1つのツールで十分 | +| [v1](./v1_basic_agent.py) | ~200 | bash, read, write, edit | コアループ | モデルがエージェント | +| [v2](./v2_todo_agent.py) | ~300 | +TodoWrite | 明示的計画 | 制約が複雑さを可能にする | +| [v3](./v3_subagent.py) | ~450 | +Task | コンテキスト分離 | クリーンなコンテキスト = より良い結果 | +| [v4](./v4_skills_agent.py) | ~550 | +Skill | 知識読み込み | 再学習なしの専門性 | + +## ファイル構造 + +``` +learn-claude-code/ +├── v0_bash_agent.py # ~50行: 1ツール、再帰的サブエージェント +├── v0_bash_agent_mini.py # ~16行: 極限圧縮 +├── v1_basic_agent.py # ~200行: 4ツール、コアループ +├── v2_todo_agent.py # ~300行: + TodoManager +├── v3_subagent.py # ~450行: + Taskツール、エージェントレジストリ +├── v4_skills_agent.py # ~550行: + Skillツール、SkillLoader +├── skills/ # サンプルSkills（pdf, code-review, mcp-builder, agent-builder） +├── docs/ # 技術ドキュメント（EN + ZH + JA） +├── articles/ # ブログ形式の記事（ZH） +└── tests/ # ユニットテストと統合テスト +``` + +## ドキュメント + +### 技術チュートリアル (docs/) + +- [v0: Bashがすべて](./docs/v0-Bashがすべて.md) +- [v1: モデルがエージェント](./docs/v1-モデルがエージェント.md) +- [v2: 構造化プランニング](./docs/v2-構造化プランニング.md) +- [v3: サブエージェント機構](./docs/v3-サブエージェント.md) +- [v4: スキル機構](./docs/v4-スキル機構.md) + +### 記事 + +[articles/](./articles/) でブログ形式の解説を参照してください（中国語）。 + +## Skillsシステムの使用 + +### 含まれているサンプルSkills + +| Skill | 用途 | +|-------|------| +| [agent-builder](./skills/agent-builder/) | メタスキル：エージェントの作り方 | +| [code-review](./skills/code-review/) | 体系的なコードレビュー手法 | +| [pdf](./skills/pdf/) | PDF操作パターン | +| [mcp-builder](./skills/mcp-builder/) | MCPサーバー開発 | + +### 新しいエージェントのスキャフォールド + +```bash +# agent-builder skillを使って新しいプロジェクトを作成 +python skills/agent-builder/scripts/init_agent.py my-agent + +# 複雑さのレベルを指定 +python skills/agent-builder/scripts/init_agent.py my-agent --level 0 # 最小限 +python skills/agent-builder/scripts/init_agent.py my-agent --level 1 # 4ツール +``` + +### 本番環境用Skillsのインストール + +```bash +# Kode CLI（推奨） +kode plugins install https://github.com/shareAI-lab/shareAI-skills + +# Claude Code +claude plugins install https://github.com/shareAI-lab/shareAI-skills +``` + +## 設定 + +```bash +# .env ファイルのオプション +ANTHROPIC_API_KEY=sk-ant-xxx # 必須：あなたのAPIキー +ANTHROPIC_BASE_URL=https://... # 任意：APIプロキシ用 +MODEL_ID=claude-sonnet-4-5-20250929 # 任意：モデル選択 +``` + +## 関連プロジェクト + +| リポジトリ | 説明 | +|------------|------| +| [Kode](https://github.com/shareAI-lab/Kode) | 本番対応のオープンソースエージェントCLI | +| [shareAI-skills](https://github.com/shareAI-lab/shareAI-skills) | 本番用Skillsコレクション | +| [Agent Skills Spec](https://github.com/anthropics/agent-skills) | 公式仕様 | + +## 設計思想 + +> **モデルが80%、コードは20%。** + +KodeやClaude Codeのような現代のエージェントが機能するのは、巧妙なエンジニアリングのためではなく、モデルがエージェントとして訓練されているからです。私たちの仕事は、モデルにツールを与えて、邪魔をしないことです。 + +## コントリビュート + +コントリビューションを歓迎します！お気軽にissueやpull requestを送ってください。 + +- `skills/` に新しいサンプルSkillsを追加 +- `docs/` のドキュメントを改善 +- [Issues](https://github.com/shareAI-lab/learn-claude-code/issues) でバグ報告や機能提案 + +## ライセンス + +MIT + +--- + +**モデルがエージェント。これがすべての秘密。** + +[@baicai003](https://x.com/baicai003) | [shareAI Lab](https://github.com/shareAI-lab) diff --git a/README_zh.md b/README_zh.md index 8f1c967..bad495c 100644 --- a/README_zh.md +++ b/README_zh.md @@ -8,7 +8,7 @@ **从零开始构建你自己的 AI Agent。** -[English](./README.md) +[English](./README.md) | [Japanese / 日本語](./README_ja.md) --- @@ -130,15 +130,13 @@ learn-claude-code/ ### 技术文档 (docs/) -| English | 中文 | -|---------|------| -| [v0: Bash is All You Need](./docs/v0-bash-is-all-you-need.md) | [v0: Bash 就是一切](./docs/v0-Bash就是一切.md) | -| [v1: Model as Agent](./docs/v1-model-as-agent.md) | [v1: 模型即代理](./docs/v1-模型即代理.md) | -| [v2: Structured Planning](./docs/v2-structured-planning.md) | [v2: 结构化规划](./docs/v2-结构化规划.md) | -| [v3: Subagent Mechanism](./docs/v3-subagent-mechanism.md) | [v3: 子代理机制](./docs/v3-子代理机制.md) | -| [v4: Skills Mechanism](./docs/v4-skills-mechanism.md) | [v4: Skills 机制](./docs/v4-Skills机制.md) | +- [v0: Bash 就是一切](./docs/v0-Bash就是一切.md) +- [v1: 模型即代理](./docs/v1-模型即代理.md) +- [v2: 结构化规划](./docs/v2-结构化规划.md) +- [v3: 子代理机制](./docs/v3-子代理机制.md) +- [v4: Skills 机制](./docs/v4-Skills机制.md) -### 原创文章 (articles/) - 公众号风格 +### 原创文章 (articles/) - [v0文章](./articles/v0文章.md) - Bash 就是一切 - [v1文章](./articles/v1文章.md) - 价值 3000 万美金的 400 行代码 diff --git a/docs/v0-Bashがすべて.md b/docs/v0-Bashがすべて.md new file mode 100644 index 0000000..8eb1168 --- /dev/null +++ b/docs/v0-Bashがすべて.md @@ -0,0 +1,117 @@ +# v0: Bashがすべて + +**究極の簡素化：約50行、1ツール、完全なエージェント機能。** + +v1、v2、v3を構築した後、ある疑問が浮かびます：エージェントの*本質*とは何か？ + +v0は逆方向に進むことでこれに答えます—コアだけが残るまですべてを削ぎ落とします。 + +## コアの洞察 + +Unix哲学：すべてはファイル、すべてはパイプできる。Bashはこの世界への入り口です： + +| 必要なこと | Bashコマンド | +|----------|--------------| +| ファイルを読む | `cat`, `head`, `grep` | +| ファイルに書く | `echo '...' > file` | +| 検索 | `find`, `grep`, `rg` | +| 実行 | `python`, `npm`, `make` | +| **サブエージェント** | `python v0_bash_agent.py "task"` | + +最後の行が重要な洞察です：**bash経由で自分自身を呼び出すことでサブエージェントを実装**。Taskツールも、Agent Registryも不要—ただの再帰です。 + +## 完全なコード + +```python +#!/usr/bin/env python +from anthropic import Anthropic +import subprocess, sys, os + +client = Anthropic(api_key="your-key", base_url="...") +TOOL = [{ + "name": "bash", + "description": """Execute shell command. Patterns: +- Read: cat/grep/find/ls +- Write: echo '...' > file +- Subagent: python v0_bash_agent.py 'task description'""", + "input_schema": {"type": "object", "properties": {"command": {"type": "string"}}, "required": ["command"]} +}] +SYSTEM = f"CLI agent at {os.getcwd()}. Use bash. Spawn subagent for complex tasks." + +def chat(prompt, history=[]): + history.append({"role": "user", "content": prompt}) + while True: + r = client.messages.create(model="...", system=SYSTEM, messages=history, tools=TOOL, max_tokens=8000) + history.append({"role": "assistant", "content": r.content}) + if r.stop_reason != "tool_use": + return "".join(b.text for b in r.content if hasattr(b, "text")) + results = [] + for b in r.content: + if b.type == "tool_use": + out = subprocess.run(b.input["command"], shell=True, capture_output=True, text=True, timeout=300) + results.append({"type": "tool_result", "tool_use_id": b.id, "content": out.stdout + out.stderr}) + history.append({"role": "user", "content": results}) + +if __name__ == "__main__": + if len(sys.argv) > 1: + print(chat(sys.argv[1])) # Subagent mode + else: + h = [] + while (q := input(">> ")) not in ("q", ""): + print(chat(q, h)) +``` + +これが完全なエージェントです。約50行。 + +## サブエージェントの仕組み + +``` +メインエージェント + └─ bash: python v0_bash_agent.py "analyze architecture" + └─ サブエージェント（分離されたプロセス、新しい履歴） + ├─ bash: find . -name "*.py" + ├─ bash: cat src/main.py + └─ stdoutで要約を返す +``` + +**プロセス分離 = コンテキスト分離** +- 子プロセスは独自の `history=[]` を持つ +- 親はstdoutをツール結果としてキャプチャ +- 再帰呼び出しで無制限のネストが可能 + +## v0が犠牲にするもの + +| 機能 | v0 | v3 | +|------|----|-----| +| エージェントタイプ | なし | explore/code/plan | +| ツールフィルタリング | なし | ホワイトリスト | +| 進捗表示 | 通常のstdout | インライン更新 | +| コードの複雑さ | 約50行 | 約450行 | + +## v0が証明すること + +**複雑な能力はシンプルなルールから生まれる：** + +1. **1つのツールで十分** — Bashはすべてへの入り口 +2. **再帰 = 階層** — 自己呼び出しでサブエージェントを実装 +3. **プロセス = 分離** — OSがコンテキスト分離を提供 +4. **プロンプト = 制約** — 指示が振る舞いを形作る + +コアパターンは決して変わらない： + +```python +while True: + response = model(messages, tools) + if response.stop_reason != "tool_use": + return response.text + results = execute(response.tool_calls) + messages.append(results) +``` + +他のすべて—Todo、サブエージェント、権限—はこのループの周りの改良です。 + +--- + +**Bashがすべて。** + +[← READMEに戻る](../README_ja.md) | [v1 →](./v1-モデルがエージェント.md) diff --git a/docs/v1-モデルがエージェント.md b/docs/v1-モデルがエージェント.md new file mode 100644 index 0000000..bf93159 --- /dev/null +++ b/docs/v1-モデルがエージェント.md @@ -0,0 +1,139 @@ +# v1: モデルがエージェント + +**約200行。4ツール。すべてのコーディングエージェントの本質。** + +Claude Codeの秘密？**秘密などない。** + +CLIの装飾、プログレスバー、権限システムを取り除く。残るのは驚くほどシンプル：モデルがタスク完了までツールを呼び出すループ。 + +## コアの洞察 + +従来のアシスタント： +``` +ユーザー -> モデル -> テキスト応答 +``` + +エージェントシステム： +``` +ユーザー -> モデル -> [ツール -> 結果]* -> 応答 + ^___________| +``` + +アスタリスクが重要。モデルはタスク完了を決定するまでツールを**繰り返し**呼び出す。これがチャットボットを自律エージェントに変える。 + +**重要な洞察**: モデルが意思決定者。コードはツールを提供してループを実行するだけ。 + +## 4つの必須ツール + +Claude Codeは約20のツールを持つ。しかし4つで90%のユースケースをカバー： + +| ツール | 目的 | 例 | +|--------|------|-----| +| `bash` | コマンド実行 | `npm install`, `git status` | +| `read_file` | 内容を読む | `src/index.ts`を表示 | +| `write_file` | 作成/上書き | `README.md`を作成 | +| `edit_file` | 精密な変更 | 関数を置換 | + +この4つのツールで、モデルは： +- コードベースを探索（`bash: find, grep, ls`） +- コードを理解（`read_file`） +- 変更を加える（`write_file`, `edit_file`） +- 何でも実行（`bash: python, npm, make`） + +## エージェントループ + +1つの関数で完全なエージェント： + +```python +def agent_loop(messages): + while True: + # 1. モデルに聞く + response = client.messages.create( + model=MODEL, system=SYSTEM, + messages=messages, tools=TOOLS + ) + + # 2. テキスト出力を表示 + for block in response.content: + if hasattr(block, "text"): + print(block.text) + + # 3. ツール呼び出しがなければ完了 + if response.stop_reason != "tool_use": + return messages + + # 4. ツールを実行して続行 + results = [] + for tc in response.tool_calls: + output = execute_tool(tc.name, tc.input) + results.append({"type": "tool_result", "tool_use_id": tc.id, "content": output}) + + messages.append({"role": "assistant", "content": response.content}) + messages.append({"role": "user", "content": results}) +``` + +**なぜこれが機能するか：** +1. モデルがループを制御（`stop_reason != "tool_use"`までツールを呼び続ける） +2. 結果がコンテキストになる（"user"メッセージとしてフィードバック） +3. メモリは自動（messagesリストに履歴が蓄積） + +## システムプロンプト + +必要な唯一の「設定」： + +```python +SYSTEM = f"""You are a coding agent at {WORKDIR}. + +Loop: think briefly -> use tools -> report results. + +Rules: +- Prefer tools over prose. Act, don't just explain. +- Never invent file paths. Use ls/find first if unsure. +- Make minimal changes. Don't over-engineer. +- After finishing, summarize what changed.""" +``` + +複雑なロジックなし。明確な指示のみ。 + +## この設計が機能する理由 + +**1. シンプルさ** +ステートマシンなし。計画モジュールなし。フレームワークなし。 + +**2. モデルが考える** +モデルがどのツールを、どの順序で、いつ停止するか決定。 + +**3. 透明性** +すべてのツール呼び出しが可視。すべての結果が会話に。 + +**4. 拡張性** +ツール追加 = 1関数 + 1JSONスキーマ。 + +## 何が欠けているか + +| 機能 | 省略理由 | 追加先 | +|------|----------|--------| +| Todo追跡 | 必須ではない | v2 | +| サブエージェント | 複雑さ | v3 | +| 権限 | 学習ではモデルを信頼 | 本番 | + +要点：**コアは極小**。他のすべては改良。 + +## より大きな視点 + +Claude Code、Cursor Agent、Codex CLI、Devin—すべてこのパターンを共有： + +```python +while not done: + response = model(conversation, tools) + results = execute(response.tool_calls) + conversation.append(results) +``` + +違いはツール、表示、安全性。しかし本質は常に：**モデルにツールを与えて作業させる**。 + +--- + +**モデルがエージェント。これがすべての秘密。** + +[← v0](./v0-Bashがすべて.md) | [READMEに戻る](../README_ja.md) | [v2 →](./v2-構造化プランニング.md) diff --git a/docs/v2-構造化プランニング.md b/docs/v2-構造化プランニング.md new file mode 100644 index 0000000..da92111 --- /dev/null +++ b/docs/v2-構造化プランニング.md @@ -0,0 +1,171 @@ +# v2: Todoによる構造化プランニング + +**約300行。+1ツール。明示的なタスク追跡。** + +v1は機能する。しかし複雑なタスクでは、モデルが見失うことがある。 + +「認証をリファクタリングし、テストを追加し、ドキュメントを更新して」と頼むと何が起こるか見てみよう。明示的な計画なしでは、タスク間を飛び回り、ステップを忘れ、集中を失う。 + +v2は1つのものを追加：**Todoツール**。エージェントの動作を根本的に変える約100行の新コード。 + +## 問題 + +v1では、計画はモデルの「頭の中」にのみ存在： + +``` +v1: "Aをして、次にB、次にC" （見えない） + 10ツール後: "あれ、何をしていたっけ？" +``` + +Todoツールはそれを明示化： + +``` +v2: + [ ] 認証モジュールをリファクタリング + [>] ユニットテストを追加 <- 現在ここ + [ ] ドキュメントを更新 +``` + +これであなたもモデルも計画が見える。 + +## TodoManager + +制約のあるリスト： + +```python +class TodoManager: + def __init__(self): + self.items = [] # 最大20 + + def update(self, items): + # バリデーション: + # - 各項目に必要: content, status, activeForm + # - Status: pending | in_progress | completed + # - in_progressは1つだけ + # - 重複なし、空なし +``` + +制約が重要： + +| ルール | 理由 | +|--------|------| +| 最大20項目 | 無限リストを防ぐ | +| in_progressは1つ | 集中を強制 | +| 必須フィールド | 構造化出力 | + +これらは任意ではない—ガードレールだ。 + +## ツール + +```python +{ + "name": "TodoWrite", + "input_schema": { + "items": [{ + "content": "タスクの説明", + "status": "pending | in_progress | completed", + "activeForm": "現在形: 'ファイルを読んでいます'" + }] + } +} +``` + +`activeForm`は今何が起こっているかを示す： + +``` +[>] 認証コードを読んでいます... <- activeForm +[ ] ユニットテストを追加 +``` + +## システムリマインダー + +Todo使用を促すソフト制約： + +```python +INITIAL_REMINDER = "マルチステップタスクにはTodoWriteを使用してください。" +NAG_REMINDER = "10ターン以上todoなし。更新してください。" +``` + +コマンドではなくコンテキストとして注入： + +```python +# INITIAL_REMINDER: 会話開始時（mainで） +if first_message: + inject_reminder(INITIAL_REMINDER) + +# NAG_REMINDER: agent_loop内で、タスク実行中に +if rounds_without_todo > 10: + inject_reminder(NAG_REMINDER) +``` + +重要な洞察：NAG_REMINDERは**エージェントループ内**で注入されるので、モデルは長時間実行タスク中にそれを見る、タスク間だけではなく。 + +## フィードバックループ + +モデルが`TodoWrite`を呼び出すとき： + +``` +入力: + [x] 認証をリファクタリング (完了) + [>] テストを追加 (進行中) + [ ] ドキュメントを更新 (保留) + +返却: + "[x] 認証をリファクタリング + [>] テストを追加 + [ ] ドキュメントを更新 + (1/3 完了)" +``` + +モデルは自分の計画を見る。それを更新する。コンテキストを持って続行する。 + +## Todoが役立つとき + +すべてのタスクに必要なわけではない： + +| 適切な場面 | 理由 | +|------------|------| +| マルチステップ作業 | 追跡すべき5つ以上のステップ | +| 長い会話 | 20以上のツール呼び出し | +| 複雑なリファクタリング | 複数のファイル | +| 教育 | 「思考」が可視 | + +経験則：**チェックリストを書くなら、todoを使う**。 + +## 統合 + +v2はv1を変更せずに追加： + +```python +# v1のツール +tools = [bash, read_file, write_file, edit_file] + +# v2が追加 +tools.append(TodoWrite) +todo_manager = TodoManager() + +# v2は使用を追跡 +if rounds_without_todo > 10: + inject_reminder() +``` + +約100行の新コード。同じエージェントループ。 + +## より深い洞察 + +> **構造は制約し、可能にする。** + +Todo制約（最大項目数、1つのin_progress）が可能にする（可視の計画、追跡された進捗）。 + +エージェント設計のパターン： +- `max_tokens`は制約 → 管理可能な応答を可能に +- ツールスキーマは制約 → 構造化された呼び出しを可能に +- Todoは制約 → 複雑なタスク完了を可能に + +良い制約は制限ではない。足場だ。 + +--- + +**明示的な計画がエージェントを信頼性あるものにする。** + +[← v1](./v1-モデルがエージェント.md) | [READMEに戻る](../README_ja.md) | [v3 →](./v3-サブエージェント.md) diff --git a/docs/v3-サブエージェント.md b/docs/v3-サブエージェント.md new file mode 100644 index 0000000..1108e82 --- /dev/null +++ b/docs/v3-サブエージェント.md @@ -0,0 +1,190 @@ +# v3: サブエージェント機構 + +**約450行。+1ツール。分割統治。** + +v2で計画を追加。しかし「コードベースを探索してから認証をリファクタリング」のような大きなタスクでは、単一のエージェントはコンテキスト制限に達する。探索で20ファイルが履歴にダンプされる。リファクタリングで集中を失う。 + +v3は**Taskツール**を追加：分離されたコンテキストで子エージェントを生成。 + +## 問題 + +単一エージェントのコンテキスト汚染： + +``` +メインエージェント履歴: + [探索中...] cat file1.py -> 500行 + [探索中...] cat file2.py -> 300行 + ... さらに15ファイル ... + [リファクタリング中...] 「あれ、file1の内容は？」 +``` + +解決策：**探索をサブエージェントに委任**： + +``` +メインエージェント履歴: + [Task: コードベースを探索] + -> サブエージェントが20ファイルを探索 + -> 返却: "認証はsrc/auth/、DBはsrc/models/" + [クリーンなコンテキストでリファクタリング] +``` + +## エージェントタイプレジストリ + +各エージェントタイプが能力を定義： + +```python +AGENT_TYPES = { + "explore": { + "description": "検索と分析のための読み取り専用", + "tools": ["bash", "read_file"], # 書き込みなし + "prompt": "検索と分析。変更しない。簡潔な要約を返す。" + }, + "code": { + "description": "実装のためのフルエージェント", + "tools": "*", # すべてのツール + "prompt": "効率的に変更を実装。" + }, + "plan": { + "description": "計画と分析", + "tools": ["bash", "read_file"], # 読み取り専用 + "prompt": "分析して番号付き計画を出力。ファイルを変更しない。" + } +} +``` + +## Taskツール + +```python +{ + "name": "Task", + "description": "集中したサブタスクのためにサブエージェントを生成", + "input_schema": { + "description": "短いタスク名（3-5語）", + "prompt": "詳細な指示", + "agent_type": "explore | code | plan" + } +} +``` + +メインエージェントがTaskを呼び出す → 子エージェントが実行 → 要約を返す。 + +## サブエージェント実行 + +Taskツールの心臓部： + +```python +def run_task(description, prompt, agent_type): + config = AGENT_TYPES[agent_type] + + # 1. エージェント固有のシステムプロンプト + sub_system = f"You are a {agent_type} subagent.\n{config['prompt']}" + + # 2. フィルタリングされたツール + sub_tools = get_tools_for_agent(agent_type) + + # 3. 分離された履歴（重要: 親コンテキストなし） + sub_messages = [{"role": "user", "content": prompt}] + + # 4. 同じクエリループ + while True: + response = client.messages.create( + model=MODEL, system=sub_system, + messages=sub_messages, tools=sub_tools + ) + if response.stop_reason != "tool_use": + break + # ツールを実行、結果を追加... + + # 5. 最終テキストのみを返す + return extract_final_text(response) +``` + +**重要な概念：** + +| 概念 | 実装 | +|------|------| +| コンテキスト分離 | 新しい`sub_messages = []` | +| ツールフィルタリング | `get_tools_for_agent()` | +| 専門化された振る舞い | エージェント固有のシステムプロンプト | +| 結果の抽象化 | 最終テキストのみ返却 | + +## ツールフィルタリング + +```python +def get_tools_for_agent(agent_type): + allowed = AGENT_TYPES[agent_type]["tools"] + if allowed == "*": + return BASE_TOOLS # Taskなし（デモでは再帰なし） + return [t for t in BASE_TOOLS if t["name"] in allowed] +``` + +- `explore`: bashとread_fileのみ +- `code`: すべてのツール +- `plan`: bashとread_fileのみ + +サブエージェントはTaskツールを取得しない（このデモでは無限再帰を防ぐ）。 + +## 進捗表示 + +サブエージェント出力はメインチャットを汚染しない： + +``` +あなた: コードベースを探索して +> Task: コードベースを探索 + [explore] コードベースを探索 ... 5ツール, 3.2秒 + [explore] コードベースを探索 - 完了 (8ツール, 5.1秒) + +見つかったものはこちら: ... +``` + +リアルタイム進捗、クリーンな最終出力。 + +## 典型的なフロー + +``` +ユーザー: "認証をJWTを使うようにリファクタリング" + +メインエージェント: + 1. Task(explore): "認証関連のすべてのファイルを見つける" + -> サブエージェントが10ファイルを読む + -> 返却: "認証はsrc/auth/login.py、セッションは..." + + 2. Task(plan): "JWT移行を設計" + -> サブエージェントが構造を分析 + -> 返却: "1. jwtライブラリを追加 2. トークンユーティリティを作成..." + + 3. Task(code): "JWTトークンを実装" + -> サブエージェントがコードを書く + -> 返却: "jwt_utils.pyを作成、login.pyを更新" + + 4. 変更を要約 +``` + +各サブエージェントはクリーンなコンテキストを持つ。メインエージェントは集中を保つ。 + +## 比較 + +| 側面 | v2 | v3 | +|------|----|----| +| コンテキスト | 単一、増大 | タスクごとに分離 | +| 探索 | 履歴を汚染 | サブエージェントに含まれる | +| 並列性 | なし | 可能（デモにはなし） | +| 追加コード | 約300行 | 約450行 | + +## パターン + +``` +複雑なタスク + └─ メインエージェント（コーディネーター） + ├─ サブエージェントA (explore) -> 要約 + ├─ サブエージェントB (plan) -> 計画 + └─ サブエージェントC (code) -> 結果 +``` + +同じエージェントループ、異なるコンテキスト。これがすべてのトリック。 + +--- + +**分割統治。コンテキスト分離。** + +[← v2](./v2-構造化プランニング.md) | [READMEに戻る](../README_ja.md) | [v4 →](./v4-スキル機構.md) diff --git a/docs/v4-スキル機構.md b/docs/v4-スキル機構.md new file mode 100644 index 0000000..4966e02 --- /dev/null +++ b/docs/v4-スキル機構.md @@ -0,0 +1,194 @@ +# v4: スキル機構 + +**コアの洞察: スキルはツールではなく、知識パッケージ。** + +## 知識の外部化: トレーニングから編集へ + +スキルは深いパラダイムシフトを体現する：**知識の外部化**。 + +### 従来のアプローチ: パラメータに内在化された知識 + +従来のAIシステムはすべての知識をモデルパラメータに保存。アクセス、変更、再利用できない。 + +モデルに新しいスキルを学ばせたい？必要なこと： +1. 大量の訓練データを収集 +2. 分散訓練クラスタをセットアップ +3. 複雑なパラメータファインチューニング（LoRA、フルファインチューニングなど） +4. 新しいモデルバージョンをデプロイ + +### 新しいパラダイム: ドキュメントとして外部化された知識 + +コード実行パラダイムがすべてを変える。 + +``` +┌──────────────────────────────────────────────────────────────────────┐ +│ 知識ストレージ階層 │ +│ │ +│ モデルパラメータ → コンテキストウィンドウ → ファイルシステム → スキルライブラリ │ +│ (内在化) (ランタイム) (永続) (構造化) │ +│ │ +│ ←────── トレーニング必要 ──────→ ←─── 自然言語で編集 ────→ │ +│ クラスタ、データ、専門知識必要 誰でも変更可能 │ +└──────────────────────────────────────────────────────────────────────┘ +``` + +**重要なブレークスルー**: +- **以前**: モデル動作の変更 = パラメータの変更 = トレーニング必要 = GPUクラスタ + 訓練データ + ML専門知識 +- **今**: モデル動作の変更 = SKILL.mdの編集 = テキストファイルの編集 = 誰でもできる + +## 問題 + +v3でタスク分解のためのサブエージェントを得た。しかしより深い問題がある：**モデルはドメイン固有のタスクをどのように処理するか知っているのか？** + +- PDFを処理？`pdftotext` vs `PyMuPDF`を知る必要がある +- MCPサーバーを構築？プロトコル仕様とベストプラクティスが必要 +- コードレビュー？体系的なチェックリストが必要 + +この知識はツールではない—**専門知識**だ。スキルはモデルがオンデマンドでドメイン知識を読み込むことで解決。 + +## 重要な概念 + +### ツール vs スキル + +| 概念 | 何か | 例 | +|------|------|-----| +| **ツール** | モデルが何をCAN DO | bash, read_file, write_file | +| **スキル** | モデルがどうKNOW TO DO | PDF処理、MCP構築 | + +ツールは能力。スキルは知識。 + +### SKILL.md標準 + +``` +skills/ +├── pdf/ +│ └── SKILL.md # 必須 +├── mcp-builder/ +│ ├── SKILL.md +│ └── references/ # オプション +└── code-review/ + ├── SKILL.md + └── scripts/ # オプション +``` + +**SKILL.mdフォーマット**: YAMLフロントマター + Markdownボディ + +```markdown +--- +name: pdf +description: PDFファイルを処理。PDF読み込み、作成、マージ時に使用。 +--- + +# PDF処理スキル + +## PDFの読み込み + +高速抽出にはpdftotext使用： +\`\`\`bash +pdftotext input.pdf - +\`\`\` +... +``` + +## 実装（約100行追加） + +### SkillLoaderクラス + +```python +class SkillLoader: + def __init__(self, skills_dir: Path): + self.skills = {} + self.load_skills() + + def parse_skill_md(self, path: Path) -> dict: + """YAMLフロントマター + Markdownボディをパース。""" + content = path.read_text() + match = re.match(r'^---\s*\n(.*?)\n---\s*\n(.*)$', content, re.DOTALL) + # {name, description, body, path, dir}を返す + + def get_descriptions(self) -> str: + """システムプロンプト用のメタデータを生成。""" + return "\n".join(f"- {name}: {skill['description']}" + for name, skill in self.skills.items()) + + def get_skill_content(self, name: str) -> str: + """コンテキスト注入用のフルコンテンツを取得。""" + return f"# Skill: {name}\n\n{skill['body']}" +``` + +### Skillツール + +```python +SKILL_TOOL = { + "name": "Skill", + "description": "専門知識を得るためにスキルを読み込む。", + "input_schema": { + "properties": {"skill": {"type": "string"}}, + "required": ["skill"] + } +} +``` + +### メッセージ注入（キャッシュ保持） + +重要な洞察: スキルコンテンツは**tool_result**（userメッセージの一部）に入る、システムプロンプトではない： + +```python +def run_skill(skill_name: str) -> str: + content = SKILLS.get_skill_content(skill_name) + return f""" +{content} + + +上記のスキルの指示に従ってください。""" +``` + +**重要な洞察**: +- スキルコンテンツは新しいメッセージとして**末尾に追加** +- 前のすべて（システムプロンプト + すべての以前のメッセージ）はキャッシュされ再利用 +- 新しく追加されたスキルコンテンツのみ計算が必要—**プレフィックス全体がキャッシュヒット** + +## キャッシュ経済学 + +### キャッシュを無視するコスト + +多くの開発者がLangGraph、LangChain、AutoGenで習慣的に： +- システムプロンプトに動的状態を注入 +- メッセージ履歴を編集・圧縮 +- スライディングウィンドウで会話を切り詰め + +**これらの操作はキャッシュを無効化し、コストを7-50倍に爆発させる。** + +典型的な50ラウンドのSWEタスク： +- **キャッシュ破壊**: $14.06（毎ラウンドシステムプロンプトを変更） +- **キャッシュ最適化**: $1.85（追記のみ） +- **節約**: 86.9% + +### アンチパターン + +| アンチパターン | 効果 | コスト乗数 | +|--------------|------|-----------| +| 動的システムプロンプト | 100%キャッシュミス | **20-50倍** | +| メッセージ圧縮 | 置換点から無効化 | **5-15倍** | +| スライディングウィンドウ | 100%キャッシュミス | **30-50倍** | +| メッセージ編集 | 編集点から無効化 | **10-30倍** | + +## スキル設計ガイドライン + +1. **単一責任**: 1スキル = 1ドメイン +2. **自己完結**: 外部参照を最小化 +3. **アクション指向**: 指示、説明ではなく +4. **構造化**: セクションは素早い参照用 + +## より深い洞察 + +> **知識はドキュメントになり、誰でも教師になれる。** + +従来のファインチューニングは**オフライン学習**: データ収集 -> 訓練 -> デプロイ -> 使用。 +スキルは**オンライン学習**を可能に: ランタイムでオンデマンド知識を読み込み、即座に有効。 + +--- + +**スキルは外部化された専門知識。** + +[← v3](./v3-サブエージェント.md) | [READMEに戻る](../README_ja.md)