実践

74k star の learn-claude-code:Bash is all you need、Claude Code の殻を 0 から作る

shareAI-lab の nano リポジトリは API の使い方ではなく、LLM をターミナルに組み込んで Agent として走らせる方法を教える。コアコードは 500 行未満、harness の設計を 1 行ずつ解体して見せる。

文字サイズ

世にある 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 ステップで回る:

  1. system prompt がツール一覧を定義
  2. ユーザーメッセージをキューに積む
  3. Claude API を呼び出す
  4. 応答中の tool_use ブロックを解析し、ローカル subprocess で bash や python を実行
  5. 結果を messages に積む
  6. モデルがツールを呼ばなくなるまでステップ 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 を読み解く覚悟があるなら、の話だ。


参考:

出典: https://github.com/shareAI-lab/learn-claude-code