世にある Agent チュートリアルの 9 割は、prompt の書き方や ReAct 論文の読み方、LangChain 编排の優雅さを語っている。だが誰も気にしていない問いがある: Claude Code のようなターミナル Agent は、具体的にどうやってモデルを shell に繋いでいるのか?モデルは運転手で、harness が車——資料の多くは運転手の育て方だけ説明し、車の造り方を分解しない。
shareAI-lab/learn-claude-code はその空白を埋めるリポジトリだ。記事執筆時点で 74,754 star を獲得し、GitHub Trending に繰り返し登場している。
解決する問題
Claude Code はブラックボックスだ。ターミナルで claude と打てば、コードを読み、ファイルを書き換えて、テストを走らせてくれるが、内部で何が起きているかは見えない。Anthropic はソースを公開していない。
リポジトリの作者は明確な概念整理を提供する:
- Agency: 知性はモデル自体から生まれるもの。harness 側からは変えられない
- Harness: モデルをツール循環に組み込む外部工学。学べ、量産でき、改められる
つまりこのリポジトリが扱うのは harness レイヤーのみ。prompt engineering も、モデル fine-tuning も、RLHF も扱わない。テーマはあくまで「500 行の Python で Claude API をターミナルに繋ぐ方法」。
README は冒頭で 4 つのマイルストーンで歴史を敷く: DQN → OpenAI Five → AlphaStar → テンセント JueWu (絶悟)。各世代は「モデルが走れる環境が徐々に複雑になる」という物語だ。このリポジトリはその環境を極限まで単純化する: つまり bash。
使い方
手順は 3 つ:
git clone https://github.com/shareAI-lab/learn-claude-code.git
cd learn-claude-code
export ANTHROPIC_API_KEY=sk-ant-...
python main.py
以上でターミナルから agent と対話できる。リポジトリの nano-variants/ ディレクトリは一層ずつ剥ける教育の玉ねぎだ。最も素の bash loop (v0) から完全な tool-use (vN) まで、各ステップがそのまま動き、そのままで読める。
最小例として、30 行以内のコア loop を示す:
import anthropic, subprocess, json
client = anthropic.Anthropic()
tools = [
{"name": "bash", "description": "Run a shell command",
"input_schema": {"type": "object",
"properties": {"cmd": {"type": "string"}}}}
]
messages = [{"role": "user",
"content": "統計当前目录所有 .py 文件总行数"}]
while True:
resp = client.messages.create(
model="claude-sonnet-4-5", max_tokens=2048,
tools=tools, messages=messages)
if resp.stop_reason != "tool_use":
print(resp.content[0].text); break
messages.append({"role": "assistant", "content": resp.content})
for block in resp.content:
if block.type == "tool_use":
out = subprocess.run(block.input["cmd"],
shell=True, capture_output=True,
text=True, timeout=30).stdout
messages.append({"role": "user", "content": [
{"type": "tool_result",
"tool_use_id": block.id,
"content": out}]})
このコードを読めば、Claude Code の 6 割の秘密が見えてくる: つまりただの while loop だ。
アーキテクチャ
ループは 4 ステップで回る:
- system prompt がツール一覧を定義
- ユーザーメッセージをキューに積む
- Claude API を呼び出す
- 応答中の
tool_useブロックを解析し、ローカル subprocess で bash や python を実行 - 結果を messages に積む
- モデルがツールを呼ばなくなるまでステップ 3 へ戻る
設計上の重要ポイント:
- ツールを超簡素に: 露出するのは Read / Write / Bash の 3 つだけ。Bash is all you need——grep も find も curl も全部
bashで済む。仮想ツールに抽象化しない - timeout による遮断: bash コマンドが 30 秒を越えて走ったら即 kill、agent のハングを防ぐ
- 本物のファイルシステム: ファイル操作は実際のパスを使う、仮想 FS は使わない
- JSONL 永続化: messages 配列を毎ターン
.jsonlファイルに追記、中断からの再開も容易
この哲学は Anthropic 公式の Claude Code と共通している。Anthropic のエンジニアが podcast で述べた言葉を借りると「Agent 向けに安全な DSL を設計しようとしたが、結局 bash で十分だった」。
良いところ / 悪いところ
良いところ:
- コアコード < 500 行。1 行単位で精読できる
- LangChain / AutoGen / CrewAI といった重量級オーケストレーションフレームワークに依存しない。抽象税の支払いはゼロ
- README は英 / 中 / 日 3 言語版。作者の shareAI-lab は中国のチーム
- DQN、OpenAI Five、AlphaStar、テンセント絶悟を認知的アンカーとして使う。Agent は新種ではなく DRL パラダイムの自然な延長だと示す
- nano variants ディレクトリが発展経路を平坦に展開、各ステップがコミット単位で走る
悪いところ:
- MCP (Model Context Protocol) 非対応。今や業界標準なのに
- 子 agent のスケジューリングなし、multi-agent オーケストレーションもなし
- 権限サンドボックスなし。bash コマンドはそのまま
subprocess.runで実行されるため、悪意ある prompt がrm -rf ~を呼び出せる - 本番機能の欠落: retry も rate limit も token カウントもコスト制御もなし
- エラー処理はほぼ try/except 任せ、落ちたら最初からやり直し
LangChain / AutoGen / CrewAI と比較すれば、これは本番コンポーネントではなく教育用の切り出しだ。v0 / Bolt のような商用製品と比べれば、これは製品ではなく参考実装だ。立ち位置は明快: 「使わせる」のではなく「読ませる」ためのものだ。
試してみた
clone 直後に v0-bash-loop 版を走らせた。課題: agent に「現在のディレクトリの行数を数える Python スクリプトを自分で書かせる」。
3 ターンで完了:
- ターン 1: モデルは bash を呼ぶと決め、まず
lsでディレクトリ構造を確認 - ターン 2: モデルは Write を呼ぶと決め、
os.walk+sum(1 for _ in open(f))を使うスクリプトを書く - ターン 3: モデルは bash を呼んでスクリプトを実行、最終結果を出力
所要時間 11 秒。Sonnet 4.5 上で 3 ターン合計約 4k tokens 消費。最終的に生成されたスクリプトを wc -l で検証したところ、数字は一致した。
公式の Claude Code CLI で同じタスクを走らせるより遅い。CLI は起動オーバーヘッドが小さく、ツール実装も最適化されている。だがこのバージョンでは、各ターンのツール呼び出しがはっきり見える: [tool_use] bash: ls -la → [tool_result] total 48...。教育上の価値はまさにこの点にある。
誰に向くか
向く層:
- Claude Code の内部メカニズムを理解したいエンジニア
- チーム向けに Agent 研修を設計する tech lead
- ゼロから自分の coding agent を書きたい独立開発者
- System Design ラウンドで Agent アーキテクチャを語ることになる面接準備中の求職者
向かない層:
- フレームワークをそのまま使って本番サービスを組みたい起業家
- MCP / multi-agent / 複雑な権限管理が必要な企業シーン
- Python の
subprocessモジュールに触れたくないフロントエンドの人
一文でまとめ
Bash is all you need。ただしその while loop を読み解く覚悟があるなら、の話だ。
参考:
- shareAI-lab/learn-claude-code GitHub リポジトリ
- 記事執筆時点 star 数: 74,754