人間は文章でシステムを理解しているのか？という疑問からRuykaを作った

Wed, 21 Oct 2026 14:37:04 +0900

LLMとやり取りをしていて、ふと疑問に思った。

そもそも人間の脳は、文章で複雑な物事を理解するのに向いていないのではないか？

文章を読むのは案外しんどい

コードを書いているとき、私の頭の中にはフローチャートのようなものが浮かんでいる。条件によって処理が分岐し、どこかで合流し、また別の処理へ進んでいく。

設計をしているときは少し違う。頭の中にあるのはデータフロー図に近い。データがどこから来て、どのモジュールを通り、どう変換されるのかを考えている。インフラを触っているときも、ほぼ間違いなくデータの流れを考えている。

つまり、プログラミングをしているとき、私の頭の中にあるのは文章ではない。

ところが、これを誰かに説明しようとすると文章になる。LLMへの質問も文章だし、LLMから返ってくる回答も基本的には文章である。頭の中にある構造をいったん文章へ変換し、受け取った側が文章を読んで、もう一度頭の中に構造を組み立てる。ずいぶん回りくどい。

GitHubのPull Requestも同じである。PRを開くと変更されたコードの差分が並ぶ。もちろん差分は重要だが、それを上から読んだだけでは変更の全体像が分からないことも多い。複数のファイルを行き来して、どこがどうつながっているのかを頭の中で再構築しなければならない。

コードを読むことと、コードの変更を理解することは、必ずしも同じではない。

大枠は図で理解して、詳細を文章で補えばよいのでは

個人的な感覚として、何かの仕組みを初めて理解するときの入りやすさには、映像、音声、文章の順があるように思っている。

もちろん、どんな情報にもこの順番が当てはまるわけではない。厳密な条件や数値、細かな仕様を確認するなら文章のほうが都合はよい。ただ、システム全体の構成やデータの流れをつかむには、文章を読み続けるより図を見たほうが早いことが多い。

だとすれば、最初から全部を文章で説明する必要はないのではないか。

まず全体の構成図を見せる。データの流れが重要ならデータフロー図、処理の順序が重要ならシーケンス図、状態の変化が重要なら状態遷移図を使う。その設計を選んだ理由やトレードオフ、細かな仕様は文章で補足する。

図で分かることを文章で説明する必要はない。

逆に、文章でなければ正確に説明できないことまで無理に図にする必要もない。情報の性質に合わせて表現を選べばよい。

これはLLMが得意そうな仕事でもある。LLMはソースコードやドキュメントを読んで内容を説明できる。ならば、その説明を長い文章として出力するのではなく、理解しやすい図へ変換させればよい。

特にコードレビューなら、差分を読む前に変更前後の構造やデータの流れを見られるだけでも、全体像をつかみやすくなるかもしれない。そう考えた。

Ruykaを作った

というわけで、Ruyka（ルイカ）を作った。GitHubのPull Requestを「図が主役、文章は補足」の解説ページへ変換するClaude Codeのスキルである。

使い方は単純で、Claude CodeへPRのURLを渡す。

/ruyka https://github.com/owner/repo/pull/123

owner/repo#123や、カレントディレクトリのリポジトリならPR番号だけでもよい。Ruykaはgh CLIを使い、PRの本文や関連Issue、コミット、変更ファイルの一覧、差分を取得する。差分だけで文脈が足りなければ、周辺のコードも読む。その内容からPRに合う図を選び、解説ページを作る。

ページは自分のアカウントに非公開のArtifactとして保存され、完了するとリンクが返ってくる。同じPRでもう一度実行した場合は、既存のページを同じURLのまま上書きする。

必要なのは、Artifactツールを使えるClaude Codeと、対象リポジトリを読める状態でログインしたgh CLIである。インストール方法はRuykaのREADMEに書いた。

最初の一枚で何が変わるかを伝える

Ruykaでは、最初に「一枚で見る」という図を必ず置く。この一枚だけを見ても、PRが何を変更するのか、変更前後で何が違うのかを把握できるようにする。

2枚目以降は、PRの性質に合わせて選ぶ。例えば、APIの処理経路が変わるならシーケンス図、状態を持つ処理なら状態遷移図、モジュールを分割するなら依存関係図、データベースが変わるならデータモデル、多数のモジュールにまたがる変更なら変更マップ、といった具合である。

原則として図は2〜5枚にしているが、1〜2ファイルだけを直す小さなPRなら1〜2枚でよい。枚数を埋めるために図は増やさない。

各図の横には、変更した理由、設計上のトレードオフ、レビューで確認すべきファイルや関数を文章で添える。ページの末尾には、変更されたファイルがどの図に対応するかを示す表と、レビューの観点を置く。先に概要をつかみ、そこから具体的な差分へ降りていけるようにした。

箱を並べただけの図にはしない

ここで意識したのは、図の枚数を増やすことではない。

図を作ること自体が目的になると、ファイル名を書いた箱を並べただけの図ができる。それでは文章を図へ置き換えただけで、理解しやすくなったとは言えない。定数を30から60へ変えただけなら、図を1枚増やすより1文で書いたほうがよい。

Ruykaでは、その図を見ることで、読者が何を理解できるようになるのかを重視している。1枚の図には1つの主張を持たせ、矢印には「呼ぶ」「書き込む」のように関係を表すラベルを付ける。差分から読み取れない構造は勝手に描かず、推測を書く場合は推測だと明記する。

目標は、レビュアーが2〜3分ほどページを眺めれば、変更の概要と重点的に確認すべき場所を把握できることである。

もちろん、図解によってレビュー時間が本当に短くなるのか、見落としが減るのかは、これから検証する必要がある。LLMが作った図が正しいとも限らない。誤った関係を分かりやすく描けば、文章より強く誤解させる可能性もある。最終的には元のコードと差分を確認しなければならない。

それでも、差分を読む前に変更の全体像をつかめることには価値があると思っている。