how-claude-code-works を読む前に: 50万行の TypeScript をどう分解したか

このリポジトリが埋めようとしている穴

Claude Code は TypeScript で書かれた大規模なコードベースであり、README はその規模を「50 万行」と表現している。この数字が正確かどうかを外部から確かめる方法は提示されていないが、ともかく膨大であるという前提で話が進む。問題は、関心があっても読み始める場所が分からないことだ。README は、そうしたコードベースを前にして「どこから読めばいいのか分からない」という著者自身の困りごとが出発点だったと説明している。解決策として著者らは Claude Code 自身にコードを読ませ、その過程を文書化する方法を採った。結果として生まれたのが、コアのループから安全機構までを扱う 21 章のドキュメントである。想定読者は二種類いる。Claude Code を日常的に使い、なぜ特定の挙動になるのかを知りたい開発者と、自分で Coding Agent を作ろうとしている開発者だ。姉妹プロジェクトとして claude-code-from-scratch が挙げられており、そちらは約 4300 行の TypeScript と Python による clean-room の教育実装で、13 章の段階的チュートリアルという位置づけになっている。読み物としての本リポジトリと、手を動かすための別リポジトリという分担である。

「ソースコード分析」と「推論」の境界が明示されている点

この手のリポジトリで最初に確認すべきは、記述の根拠が何かという点だ。README には免責事項が置かれ、内容は独立した研究と推理によるもので、Anthropic の公式設計を代表するものではなく、実際の内部実装と一致する保証もないと書かれている。同時に、Anthropic から提供されたソースコードを再配布するものではないとも明記されている。ここは評価できる。多くの解析記事は、推論と事実の区別を曖昧にしたまま断定調で書かれる。本リポジトリは少なくとも、自分たちが何を根拠にしているかを冒頭で開示している。ただし、開示されているのは姿勢であって検証手段ではない。章によって確度は違うはずで、たとえば 2026 年 3 月末のソースコード流出以降に追加された機能を扱う第 17 章と第 18 章には、鍵となる語の隣に虫眼鏡の記号が付き、「スナップショット以降・ブラックボックス逆向き解析」と注記されている。著者ら自身が、既存のソースコードを読む章と、挙動から推測する章を区別しているわけだ。読む側は、この区別を章ごとの信頼度の目安として使える。

Agent ループとコンテキスト圧縮: 文書が扱う中核

リポジトリには mermaid 形式のアーキテクチャ図が置かれている。ユーザー入力が QueryEngine に入り、query の主ループから Claude API が呼ばれ、応答がテキストとツール呼び出しに分岐する。ツール実行エンジン側にはファイル読み書き、Shell 実行、検索、MCP ツールが並び、その結果が主ループへ戻される。コンテキスト工程はシステムプロンプト、Git 状態、CLAUDE.md、圧縮パイプラインから主ループへ供給され、権限システムはルール層、Bash の AST 解析、ユーザー確認の三段でツール側に接続する。この図が示すのは、ツール結果がループへ再注入される閉じた構造である。文書の中で最も細かく扱われているのは圧縮の設計だ。README によれば、コンテキストが上限に近づくと 4 段階で処理する。まず古いツール出力などの大きな塊を切り詰め、次にほぼ無コストで重複を除去し、その次に非アクティブな対話区間を折りたたむ。折りたたみは元の内容を書き換えないため展開して復元できる。最後の手段として子 Agent を起動して対話全体を要約する。各段階で十分な空きが確保できれば、後続の段階は実行されない。圧縮後には直近で編集した 5 ファイルの内容を自動的に復元し、モデルが作業対象を見失うのを防ぐと説明されている。

起動時間と「速さ」の作り方に関する記述

README は、Claude Code が体感として速い理由を三つ挙げている。第一に API 呼び出しから端末描画までの全経路がストリーミングであること。第二にツールの先行実行で、モデルがファイル読み取りを宣言した時点で既に読み始めており、モデルの生成に要する 5 秒から 30 秒の窓に約 1 秒のツール遅延を隠すという説明だ。第三に起動時の 9 段階並列化で、クリティカルパスを約 235ms に圧縮するという。ここで注意したいのは、これらの数値がすべてリポジトリ内の記述であって、第三者が再現できる形で示された計測ではないことだ。235ms という数字も、どの環境で何を起点に測ったのかは README からは分からない。同様に、トークン出力が上限に達した場合に 8K から 64K へ自動で引き上げて再試行するという記述や、Agent ループに 7 種類の「継続」戦略があるという記述も、仕組みの説明としては具体的だが、その挙動を自分で確認する手順までは示されていない。読む際は、設計意図の解説として受け取り、性能の保証として扱わないほうが安全だ。

権限と安全: 7 層という構成の読み方

安全性の章は、単一の確認ダイアログではなく多層で守るという主張になっている。README に列挙される層は次の通り。ワークスペース信頼で、初回にディレクトリを信頼するか確認し、信頼しなければそのプロジェクトのカスタム Hook を無効化して悪意あるリポジトリの仕込みを防ぐ。権限モードで信頼レベルごとに操作範囲を制限する。ルールマッチでコマンドパターンに基づく allow、deny、ask のリストを適用する。Bash コマンドの深い解析では、正規表現ではなく構文木を使って Shell コマンドの意図を分解し、コマンド注入、環境変数の漏洩、特殊文字攻撃などを含む 23 項目の静的検査を行う。ツール単位の安全機構、プロセスレベルのサンドボックスと Git Worktree による分離、そして最後にユーザー確認が置かれる。確認は Hook や LLM 分類器と競争する形で、200ms のデバウンス保護があり、人間の操作が常に優先されるという。このうち構文木解析と 23 項目という数字は具体的で、設計の重心がどこにあるかを示している。ただし 23 項目の検査内容そのものは README には列挙されておらず、詳細は docs/11-permission-security.md を参照する必要がある。

ツールとマルチ Agent の設計思想

ツール群について README が繰り返すのは、すべてのツールが同一のインターフェース規約に従うという点だ。第三者の MCP ツールも組み込みツールと同じ実行パイプラインを通り、同じ安全检查と権限制御を受ける。並行性は手動管理ではなく、読み取り専用ツールは自動で並列、書き込みは自動で直列という規則で扱われる。ツール出力が 100K 文字を超えると自動でディスクに落とし、モデルには要約とファイルパスだけを渡して、必要になった時点で全文を読ませる。マルチ Agent については三つのモードが説明されている。主 Agent が子 Agent にタスクを割り当てて結果を待つ子 Agent 型、調整役がタスク配分だけを行い自分ではファイルを読まずコードも書かないコーディネータ型、複数の名前付き Agent が点対点で通信する Swarm 型である。複数の Agent が同じファイルを同時に書き換える衝突を避けるため、Git Worktree で Agent ごとに独立したコードのコピーを与えると説明されている。ここで気になるのは、Worktree の作成と後片付けのコストがどこで吸収されるかという点だが、README からは分からない。

欠けているもの: 検証手段とメンテナンスの見通し

このリポジトリを採用判断の材料として使うときの最大の制約は、記述を裏付ける一次情報に読者が到達できないことだ。ソースコードは再配布されておらず、各章の主張を照合する手段は、Claude Code 自身の挙動を観察するか、公式の発表を待つかしかない。したがって、たとえば「圧縮後に直近 5 ファイルを復元する」という仕様が現在のバージョンでも成り立つかを、このリポジトリだけで保証することはできない。メンテナンスについても手がかりは限られる。README には 2026 年 7 月 4 日付で、3 月末の流出以降に追加された /goal や /loop による loop engineering、dynamic workflow といった新機能を継続的に逆向き解析して更新しているという記述がある。リポジトリの最終 push は 2026 年 8 月 17 日で、アーカイブはされておらず、リリースは取得できていない。つまり版管理されたスナップショットは存在せず、常に main ブランチの最新状態を読む形になる。ライセンスは MIT で、リポジトリ内の LICENSE ファイルを参照する形になっている。文章と図の利用条件は MIT の枠組みで読めるが、扱っている対象が Anthropic の商標であり、本リポジトリが Anthropic と無関係であることは明記されている。商用利用や再配布を検討する場合は、この免責事項の範囲を自組織の法務観点で確認する必要がある。ここでは法的助言はできない。

代替となる選択肢と、それぞれの違い

同じ目的に対して取りうる道は三つある。第一に、Claude Code の公式ドキュメントとリリースノートを読む。これは一次情報であり、バージョンとの対応も明確だが、内部の設計判断やアルゴリズムの説明は基本的に含まれない。第二に、姉妹プロジェクトの claude-code-from-scratch を使う。こちらは約 4300 行の TypeScript と Python による clean-room 実装で、13 章に分けて段階的に組み立てる構成だ。読んで理解するのではなく、動くものを自分で書いて確かめる方向に重心がある。第三に、自分で Claude Code の挙動を観測する。第 17 章と第 18 章では、静的な文字列と平文のリバースプロキシによるパケットキャプチャという再現可能な逆向き解析の手法が付録として示されているという。この手法を自分で回せば、記述の正しさを独立に確かめられる。本リポジトリは、この三つの間で、読むための地図を提供する位置にある。地図は現地調査の代わりにはならない。

編集部の結論

Claude Code を使っていて内部の挙動に関心がある開発者、あるいは Coding Agent を自作しようとしている人にとって、このリポジトリは読む価値のある二次資料である。ただし README 自身が「独立研究与推理であり、Anthropic の公式設計ではない」と明記しており、内容の正しさを一次情報で検証する手段は提供されていない。採用判断の前に、docs/11-permission-security.md の 7 層防御の記述と docs/03-context-engineering.md の 4 級圧縮の記述を読み、そこで示される仕組みが自分の運用で観測した挙動と一致するかを確かめるのが現実的な手順になる。逆に、Anthropic の公式サポートや SLA を必要とする業務、あるいはバージョン固定で挙動を保証したい用途には向かない。ソースコードのスナップショットに基づく記述は、その後のリリースで陳腐化しうる。

公式情報源

1. Issues
2. License: MIT
3. Project website
4. README
5. Windy3f3f3f3f/how-claude-code-works on GitHub