claude-code-from-scratch: 5000行で coding agent の内部構造を組み立てるチュートリアル
Build your own Claude Code from scratch. 🔍 Claude Code 开源了 50 万行代码，读不动？用 ~5000 行 TypeScript / Python 从零复现核心架构，11 章分步教程带你理解 coding agent 精髓
ひと目でわかる
- これは何？
- Claude Code の公開挙動を参照しながら、Agent Loop から MCP 統合までを TypeScript と Python の二実装で段階的に書き直す学習用リポジトリ。読んで理解する教材ではなく、手を動かして再現する教材として設計されている。
- 誰に向いている？
- Claude Code の中身を読んで理解したいが数十万行を追う気力はない、という開発者には向いている。逆に、本番で使える coding agent の土台を探している人には向かない。
- 商用利用できる？
- できます。MIT は寛容なライセンスで、著作権表示とライセンス表示を残せば、使用・改変・販売が可能です。
- 今もメンテナンスされている？
- されています。最後のコミットは 69 日前です。
- 何の言語で書かれている？
- 主に Python です（GitHub の言語統計による）。
回答はプロジェクトの GitHub データ（最終同期：2026年9月15日）と当サイトの分析に基づくもので、法的助言ではありません。
オープンソース詳細解説
読めない量のコードを、読める量に置き換える
Claude Code のコードベースは数十万行規模だと README は述べている。これを頭から読んで理解するのは現実的でない。このプロジェクトは、その核心部分を約5000行の TypeScript と Python の二実装で書き直し、13章の分步教程として公開している。対象読者は、coding agent がどう動くのかを仕組みのレベルで把握したい開発者だ。ライブラリとして使うためのものではなく、教材として使うためのリポジトリである。README は「これは demo ではない、分步教程だ」と明言しており、実際に手を動かして数千行を書く前提で構成されている。
Agent Loop から MCP まで、13章の積み上げ
章立ては二段階に分かれている。Phase 1 は動く coding agent を作るところまでで、Agent Loop、13のツール、System Prompt、CLI とセッション、ストリーミング、権限と安全、コンテキスト管理の7章。Phase 2 は記憶システム、技能システム、Plan Mode、マルチ Agent、MCP 統合、アーキテクチャ対比、機能テストの7章だ。各章には Claude Code 側の対応ファイルが併記されている。たとえば第1章の agent.ts は query.ts に、第6章の tools.ts は permissions/ (52KB) に対応するという形で、抽象論ではなくファイル単位の対照が示される。この対照表自体が、どこを重点的に読むべきかの地図になっている。
章ごとに単体で動かせる仕組み
教材でありがちな失敗は、コードを読んでも動かせないことだ。このプロジェクトは各章に最小実装を用意し、node steps/run.mjs --list で一覧を出し、node steps/run.mjs 7 で第7章だけを実行できる。--diff を付けるとその章で新たに増えた行だけを表示し、--py で Python 版に切り替わる。出力はローカルの mock モデルが駆動し、ネットワークにも API キーにも依存しない。README によれば、章のコード、ドキュメント中のコードブロック、実行結果はすべて同一のソースから生成されるため、記述と実装がずれない設計になっている。自分のプロンプトで実モデルを試したい場合は --live を付ける。
本物の API につなぐときの設定
実モデルを使う場合、バックエンドは環境変数で自動判別される。Anthropic 形式なら ANTHROPIC_API_KEY を設定し、必要なら ANTHROPIC_BASE_URL でプロキシを指定する。OpenAI 互換形式なら OPENAI_API_KEY と OPENAI_BASE_URL を使う。既定モデルは claude-opus-4-6 で、MINI_CLAUDE_MODEL 環境変数かコマンドライン引数で変更できる。npm start -- --model gpt-4o のように渡すと引数側が優先される。起動オプションには --resume、--plan、--accept-edits、--dont-ask、--max-cost、--max-turns が用意されている。--dont-ask は CI 向けに、確認が必要な操作を自動拒否するモードだ。
TypeScript 版と Python 版の入口の違い
TypeScript 版は npm install && npm run build の後に npm start で起動する。Python 版は Python 3.11 以上が必要で、python ディレクトリで pip install -e . を実行し、mini-claude-py というコマンドで起動する。README はこのコマンド名について、TypeScript 版の mini-claude と衝突しないための命名だと説明している。python -m mini_claude でも起動できる。どちらも npm link または pip install -e . で任意のディレクトリから呼び出せる。二実装を並行して読むと、同じ Agent Loop が言語によってどう違う形になるかを比較できる。
Claude Code の再現ではないという前提
README の冒頭に disclaimer がある。このプロジェクトは Claude Code の公開可観測な挙動と一般的な Agent の書き方に従って作られた学習用であり、実際の内部実装と一致する保証はない、という内容だ。Claude Code は Anthropic の商標で、Anthropic との関係もないと明記されている。つまり「Claude Code はこう動いている」という断定の根拠としてこのリポジトリを引用するのは適切でない。あくまで「公開挙動をこう解釈して、こう実装したら動いた」という一つの解釈だ。この線引きを理解せずに読むと、再現実装を仕様書と誤認する危険がある。
向かない用途と、代わりに読むもの
このリポジトリは本番運用を想定していない。README が demo ではない分步教程と位置づけている以上、プロダクションの coding agent を構築する土台としては設計されていない。そうした目的には、公式の Claude Code 自体や、より成熟した agent フレームワークを使うほうが筋が通る。また、ソースコードを深く読み解きたい読者には姉妹プロジェクトの how-claude-code-works が案内されている。こちらは12篇・33万字で Claude Code のアーキテクチャをソースレベルから解析する構成だという。手を動かして再実装したいのか、読んで分析したいのかで、参照すべきリポジトリが分かれる。
維持コストとライセンスの見取り図
ライセンスは MIT で、リポジトリはアーカイブされていない。最新リリースは v1.0.0 (2026-03-31)、最終 push は 2026-07-09 と記録されている。ただし学習教材という性質上、追従すべき対象は Claude Code 側の変化であり、公開挙動が変われば対照表や解説の前提も見直しが必要になる。依存関係は TypeScript 版が npm、Python 版が pip で、どちらも標準的なツールチェーンに収まっている。MIT なので改変や再配布の制約は緩いが、教材としての正確性は保証されない。フォークして自分の教材に作り替える使い方も、ライセンス上は妨げられない。
編集部の結論
Claude Code の中身を読んで理解したいが数十万行を追う気力はない、という開発者には向いている。逆に、本番で使える coding agent の土台を探している人には向かない。README が明記するとおり Claude Code の実際の内部実装と一致する保証はなく、あくまで公開挙動の再現だ。採用前に確認すべきは steps/run.mjs が手元で動くかどうか、そして --live で自分の API キーを渡したときにどのモデルが呼ばれるかだ。
コミュニティノート