個人開発者の GitHub README が素通りされる 3 つの理由
OSS としてリポジトリを公開した。Hacker News か Reddit か、どこかから流入があって、Star がいくつか付いた。Issue もぽつぽつ立つようになった。けれど、README に貼った Documentation のリンクは、ほとんどクリックされない。GitHub の Insights を開いても、Traffic の “Views” や “Unique cloners” の数字は伸びているのに、その先のドキュメントサイトには静寂が広がっている。
「見られてはいる。なのに、その先で何も起きていない」── 個人開発者が自分のリポジトリページを眺めるとき、よく出くわす場所だと思います。原因は、機能の少なさでもバッジの数でも、リポジトリ名の覚えにくさでもありません。GitHub README が素通りされるとき、たいていほぼ同じ 3 つの理由が、毎回同じ順序で重なっています。
理由 1：冒頭の 1 行が「A minimal X for Y」になっている
最初の関門は、README の最初の見出しのすぐ下に置かれた一行 ── プロジェクトの 1 行サマリーです。GitHub のリポジトリページでは、リポジトリ名と “About” の 1 行、そして README の冒頭が、最初に目に入る領域です。Trending や検索結果のプレビュー、X や Hacker News のシェアカードでも、見える範囲はだいたいここまで。読者はこの一行を 0.5 秒で「自分のリポジトリかどうか」で判定しています。ここで素通りされたら、その下の Installation も Features も Pricing もありません ── スクロールはされても、何も受け取らずにタブが閉じられます。
それでも、個人開発者の README の 1 行サマリーは判で押したように似た形になります。
「A minimal, lightweight CLI for managing local environments.」 「TypeScript-first framework for building edge-rendered apps.」 「Zero-config build tool for modern JavaScript projects.」
書いた本人にとっては、プロダクトの強みを過不足なく並べた、誠実な一行です。「minimal」「lightweight」「TypeScript-first」「zero-config」── どれも嘘ではなく、技術的に正しい。
ただし、訪問者の側から見ると、このコピーはすべて 「形容詞の列挙」 に揃っています。「minimal」「lightweight」「modern」「zero-config」「TypeScript-first」── これらは、書き手の頭の中ではプロダクトの強みですが、訪問者の頭の中では まだ何の意味も持っていません。それが「自分の今日の作業」のどこに刺さるのかは、訪問者が翻訳しないと見えない。翻訳のコストは、訪問者ではなく書き手が払うべきものです。
人はリポジトリページで、冒頭を「自分宛か／自分宛じゃないか」で振り分けます。判定材料は、ほぼ「主語が自分の状況に重なるか」だけです。「A minimal CLI for X」が主語のコピーは、その判定で他人宛の側に倒れます。Star は付くかもしれないけれど、Documentation は開かれない、という挙動になる。
1 行サマリーで問うべきは「何ができるツールか」ではなく、**「読者が今日かかえている、どの不満が、このツールで一歩前に進むのか」**です。「A minimal CLI for managing local environments」ではなく「docker-compose.yml を毎プロジェクトで書き直す手間が、要らなくなる」、「TypeScript-first framework for building edge-rendered apps」ではなく「Next.js のエッジで動く API を、設定ファイル 0 で立ち上げる」── 主語を読者の状況に移すだけで、1 行サマリーは「自分宛」の側に動きます。
README の冒頭は、プロジェクトの自己紹介ではありません。README を読むかどうかを決める、リポジトリそのものの最初の一文です。
理由 2：バッジと Installation だけで「信用」の場所が抜けている
冒頭を突破して、訪問者がスクロールに踏みとどまった。ここからが README の本文の仕事です。けれど、README の上半分は、開いた瞬間にもう一度素通りされます。理由は、冒頭直後の構成にあります。
典型的な README の冒頭直後は、こうなります。
      ## Installation npm install foo-cli ## Usage foo-cli init my-project foo-cli build
書き手の側からは、品質を担保するバッジを並べ、すぐに動かせる手順を続けた、効率的な構成に見えます。実際、バッジは品質の宣言だし、Installation は動かす方法を最短で渡している。
ただ、訪問者の脳内では、別のことが起きています。「これは、私の何を解決するページなんだろう？」 という問いを抱えながら、バッジ→Installation→Usage を読んでいる。その問いに、バッジも Installation も Usage の手順も答えていないと、訪問者は「自分宛じゃないかもしれない」と判定を保留したまま、タブを閉じます。
バッジと Installation は、その問いに答えません。「CI passing」も「npm v1.2.3」も「minzip 5kb」も、書き手の側の品質宣言です。npm install foo-cli も foo-cli init も、ツールを動かす手順であって、自分の今日の作業のどこに刺さるかは、依然として翻訳されないと見えない。README の 9 割は、冒頭→バッジ→Installation→Usage→Features の順で進み、訪問者が「これは私の何を解決するか」を理解する場所が、どこにもない 構造になっています。
ここで本来やるべきことは、バッジを増やすことでも Installation を整えることでもなく、冒頭で立てた関心を、信用に橋渡しすることです。具体的には、Installation の 前 に、Before / After のコード差分を置く。
// これまで: // webpack.config.js を 80 行書いて、Babel / PostCSS / dev server を個別に設定 // このツールで: foo-cli dev
このたった 1 ブロックがあるだけで、訪問者の頭の中の「自分の今日のセットアップ」と、ツールの位置が、Installation の前で初めて接続します。バッジは、信用が立った後の補強として、ページ下部に置くか、リポジトリ名のすぐ下に小さく並べる ── どちらにせよ、信用そのものを担う場所ではありません。
関心 → 信用 → 行動、という順序があります。冒頭直後は、その 信用 だけを担当する場所です。Installation も Usage も、信用が立った後にやるもので、信用の代わりに置くものではありません。
理由 3：末尾の CTA が「Star / Sponsor / Discord / Contributing / License」で散らかっている
3 つ目は、README の末尾 ── 訪問者の行動を促す場所です。ここでも、ほぼ全員が同じ場所で転びます。
README の締めは、よくこうなります。
「## Community
- ⭐ Star us on GitHub
- 🐦 Follow on Twitter: @foo_dev
- 💬 Join our Discord
- 💖 Sponsor on GitHub Sponsors
Contributing
See CONTRIBUTING.md for guidelines.
License
MIT」
書き手としては、訪問者の温度感に応じた選択肢を渡している感覚があります。「気に入った人は Star、繋がりたい人は Twitter、議論したい人は Discord、応援したい人は Sponsor、貢献したい人は Contributing」── 親切のつもりで、行動の選択肢を 5 つも 6 つも並べる。
ですが、選択肢を渡された訪問者は、何も選びません。
個人開発者には少し直感に反するところで、丁寧に作った README ほどここで詰まります。GitHub のページに来た人が次に何をするかは、「選択肢の多さ」ではなく「次の一歩の明確さ」で決まります。タップするリンクが 1 本なら押せる。5 本並んでいると、「どれが正解か分からない」と感じて、結局どれも押さない ── あるいは、判断を保留してそのままタブを閉じます。
README の末尾には、メインの行動を 1 つだけ載せる。これが README の一番の規律です。「Star」「Twitter」「Discord」「Sponsor」「Contributing」が並んでいたら、メインは 1 つに絞る。残りは README の最下部に小さく、あるいはリポジトリの About セクションや別ページに分散させる ── あるいは思い切って、最重要なものだけ残してあとは削る。
そして、その「1 つの行動」も、抽象語にしない。「Read the Documentation」は、リンク先で何が起きるかを語っていない、書き手の願望の表明です。「30 秒で npx foo-cli create my-app を動かすところまで、下のクイックスタートで案内します」と書けば、押すリンクと、押した後に起きることが、README の中で確定します。
行動を 1 本に絞り、抽象を具体に置き換える。たったこれだけで、同じ Star 数のリポジトリが、まったく違う Documentation クリック率を返してきます。
3 つの理由は、別々の問題ではない
ここまで、冒頭・バッジと Installation・末尾を別々に解いてきました。けれど、よく見ると 3 つは別々の問題ではなく、ひとつの順序の話を、別の場所で繰り返していることに気づきます。
その順序が、関心 → 信用 → 行動です。
README の冒頭は 関心 の入口です。訪問者の状況を主語にしないと、入口で素通りされる。冒頭直後は、関心を 信用 に橋渡しする場所です。「これは私の今日の作業の話だ」と訪問者の中で輪郭ができないと、橋が落ちる。末尾の CTA は 行動 の蛇口です。蛇口を 5 つ並べたら、訪問者はどれもひねらない。
README が素通りされるとき、たいていこの 3 箇所のうち少なくとも 2 箇所で、順序の同じ場所が抜け落ちています。だから、片方だけ直してもクリックは動かない。3 つを同じ順序で並び替えると、Star 数や Issue 数は変わらなくても、その先の Documentation クリック率 や 採用数 が初めて動き始めます。
まとめ：直すのは、バッジでも CI でもなく、README の順序
README からのクリックや採用が伸びないとき、書き手はまず「バッジを増やそう」「テストカバレッジを 100% にしよう」「ロゴを発注しよう」と考えがちです。けれど、バッジの数も、テストの網羅率も、ロゴの完成度も、プロダクトの信頼性を上げるものです。それでリポジトリの第一印象は整います。けれど、その先で 冒頭→信用→行動の順序が崩れたままなら、Documentation は開かれません。
直すのは、バッジでも CI でもなく、README の順序です。見えれば、直せる。次に README を更新するときは、コミットする前に一度手を止めて、3 つの場所を順に見直してみてください。
- 冒頭の 1 行は、訪問者の状況が主語になっているか
- バッジと Installation の前に、Before / After で信用を立てる場所があるか
- 末尾の CTA は、行動が 1 つに絞られ、具体になっているか
このチェックを通った時点で、README は 9 割の同種リポジトリから抜け出します。書く側の手数は、ほとんど増えません。
姉妹記事として、同じ「関心 → 信用 → 行動」の順序を別の戦場で扱った記事を書いています。LP のファーストビュー戦場は 個人開発者の LP のファーストビューが素通りされる 3 つの理由、メール戦場は 個人開発者のローンチメールが素通りされる 3 つの理由、Twitter 戦場は 個人開発者の Twitter 告知が素通りされる 3 つの理由、動画概要欄戦場は 個人開発の動画の概要欄が素通りされる 3 つの理由、Product Hunt 戦場は 個人開発者の Product Hunt ローンチが素通りされる 3 つの理由 にまとめています。サービスのトップページで起きている構造は 個人開発者のサービスが「素通り」される、たったひとつの構造的な理由 にあります。並べて読むと、GitHub README で起きていることは、戦場が違うだけで同じ構造であることが見えてきます。
ちなみに、ロゴのデザインも、テストカバレッジの数字も、依存ライブラリの少なさも、この 3 つの理由とは独立した話です。どんなに整えても、冒頭・信用・末尾の順序を直さない限り、README からのクリックは動きません。逆に言えば、順序さえ整っていれば、ロゴは無くてもかまわない。
LP も、メールも、Twitter も、動画も、README も直した。けれど、開かれてもなお採用に至らない ── そのとき直すのは、戦場ごとの小技でも文章の熱量でもなく、1 行ごとの順序です。WHY → HOW を 1 冊にまとめたのが、下記の本です。個人開発者・インディー Web 作者・動画作者向けに、LP・短文・メールの戦場別の書き方と、Claude を実際に使ったプロンプト連鎖の実演を含めて統合しています。