readme-optimization

README の最適化

開発者がプロジェクトを試すか、タブを閉じるかを決める、たった1ページに取り組んでいます。既存の README を根拠に照らして診断し、その後、初めて訪れた人がプロジェクトをすばやく正確に評価できるように書き直してください。使わないと決めることも含まれます。それも正しい結果であり、最適化によって覆してはなりません。

README はドキュメントの一種ではありません。ランディングページであり、案内役です。何であるか、なぜ必要かを数秒で伝え、その後、読者を適切な場所へ誘導します。ドキュメントの網羅性ではなく、訪問者を試用へとつなげられるかどうかで評価してください。

限られた書き直しの予算は、情報が不足している部分に使ってください。GitHub リポジトリ393件を対象とした調査（Prana et al. 2019、./references/published-findings.mdで引用。サンプルは2010年代後半のものです。全数調査ではなく、基準値として捉えてください）では、次の結果が示されています。

• プロジェクトが何であるか：97.0％ — 基本情報です。
• 使い方：88.5％ — 基本情報です。
• 代替手段ではなく、それを選ぶ理由：25.7％ — 不足しています。
• プロジェクトの現状：21.4％ — 不足しています。

この2つの不足カテゴリこそ、導入前に評価する開発者が把握すべき情報です。

このページと、その周辺にあるリポジトリ情報（説明、ウェブサイトのリンク、トピック、ソーシャルプレビュー）の範囲内に留めてください。ユーザーの本当の課題がドキュメントサイト、はじめての方向けのページ、コントリビューションの手順、リリースノート、ローンチ、プロフィール README にある場合は、README に無理に詰め込まず、Reference の関連スキルへ案内してください。GitHub のページ周辺にあるプラットフォーム機能（Discussions、リリース通知、スターの方針）は、samber/developer-platform-skills@github-engagement-playbook の対象です。

根拠のない定説として扱う統計

以下の3つは、すべて広く出回っているものの、出典が捏造された統計です。自身の推論でもユーザーへの回答でも、決して繰り返さないでください。

• 「詳しい README があるリポジトリは、コントリビューションが50％増える」
• 「スター履歴のグラフで、スター獲得率が約15％上がる」
• 「人気リポジトリの62％には GIF のデモがある」

ユーザーがそのうちの1つを挙げた場合は、それを前提に話を進めず、出典がないと伝えてください。このスキルで引用する数値はすべて ./references/published-findings.md に出典が記載されています。ユーザーに統計を伝える前に、必ず確認してください。

約束するのは、プロジェクトをより適切に評価できるようにすることです。改善率ではありません。

呼び出し例と出力形式

よくある依頼：

• 「このリポジトリの README を監査してください」
• 「GitHub へのアクセスはあるのに、インストールされません」
• 「ローンチ前に README の冒頭を書き直してください」
• 「自社への導入を検討している人にも読みやすい README にしてください」

実行のたびに、文章を書く前に、まず次の形式のスコアカードを出力します。

README audit - acme/flowmatic   (audience: solo developer)
Band A: A1 pass · A2 FAIL (install needs Node >=20, undocumented) · A3 FAIL · A4 pass · A5 pass
Verdict: does not pass - A2 and A3 blocking; B1 returns the most per hour spent

書き直しに着手するのは、ユーザーがその診断に同意した後だけです。主張の確認、Band B、修正の順序を含むレポートの完全な形式については、./references/audit-scorecard.md を参照してください。

インタビュー

質問は一度に1つずつ尋ね、可能な場合は選択肢を示してください。リポジトリを読めば自分で判断できることは質問しないでください。質問1〜4への回答が書き換えの前提条件です。回答が得られるまでは、文章の草案を作成しないでください。

メモリ：現在のタスクやプロジェクトのコンテキストに関する情報をいくつか保存してください。メモリをファイルに保存する場合は、devrel-context.md を使用してください。別のメモリシステムを使用している場合は、そちらを利用してください。タスク情報はセクションを分けて記録してください。完了したタスクは削除してください。タスクには日付を付け、一般的なプロジェクトのコンテキストには日付を付けないでください。インタビューの回答は、タスクによって異なる場合があります。

1. 対象のリポジトリはどれですか？また、そのリポジトリを読み取り、コマンドを実行できますか？
2. このプロジェクトはどれにあたりますか？ライブラリまたは SDK、CLI ツール、アプリケーションまたはサービス、フレームワークまたはプラットフォーム、テンプレートまたは学習リソース。
3. このページを訪れるのはどのような人ですか？特定の言語エコシステムの開発者、複数の言語を扱う開発者、プラットフォームまたは運用エンジニア、それともセキュリティや調達などを担当する非開発者の評価者ですか？
4. 導入はどのように決まりますか？個人の開発者がインストールして単独で判断しますか？それとも企業が導入し、別の担当者がライセンス、セキュリティ体制、サポート体制を承認しますか？両方でもかまいません。回答によってページの中盤の構成が変わります。
5. どのような成果を増やしたいですか？インストール、コントリビューター、スター、採用へのアピール、エンタープライズとの商談、繰り返し寄せられるサポート質問の削減のうち、どれですか？
6. プロジェクトの実態に即したステータスはどれですか？実験段階、積極的にメンテナンス中、安定しており機能追加は凍結中、メンテナーを募集中のうち、どれですか？
7. 読者がすでに知っている競合や代替手段は何ですか？それらは、あなたのプロジェクトよりどの点が優れていますか？
8. 法律やポリシー上、必ず記載しなければならないことはありますか？ライセンス条項、商標に関する通知、輸出規制やコンプライアンスに関する記述、雇用主の開示などです。
9. 既存のブランド素材はありますか？README に反映すべきロゴ、タグライン、Web サイトで使っているポジショニング文などです。
10. README はほかの場所にも公開されていますか？パッケージレジストリのページ、ミラー、ドキュメントサイトのランディングページなどです。表示先ごとにルールは異なります。
11. 期限はありますか？ローンチ、カンファレンス、資金調達に関する商談など、それとも単にページの更新が遅れているだけですか？
12. その期限までに一度だけ成果を出したいですか？それとも今後も価値を生み続ける資産を作りたいですか？後者なら、今後2年間にわたって再利用できるポジショニング文とページ構成を整えます。
13. どこまで対応できますか？午後の作業、誰かの1週間分の工数、顧客にロゴの使用許可を求めること、簡単には撤回できないガバナンスや財団へのコミットメントを受け入れることなど、許容範囲を教えてください。

回答11〜13によって、以下の優先順位はすべて変わります。計画を提示する際は、どの回答によってどの修正の優先順位が変わったのかを説明してください。

• 期限が迫っている（質問11） — 1時間で反映できる修正の優先順位を上げ、この作業では導入までの流れの再構成を見送ります。
• 長期的な効果を重視（質問12） — 差別化を示す段落と構成の再編成を優先します。そこで作る一文は、パッケージレジストリのページ、ローンチ投稿、リンクのプレビューにも反映されます。
• 対応範囲が限られている（質問13） — ターミナルのデモとエンタープライズ向けの訴求を、リストの最後に回すのではなく、完全に削除します。

質問7に答えられなくても、作業の妨げとみなさず、調査結果として扱ってください。競合や代替手段を挙げられないメンテナーは、README でもプロジェクトの差別化を示せていないことがよくあります。これは、改善できる最も重要な点です。

ステップ 1 - 対象読者を明確にし、README がボトルネックかどうかを確認する

回答 4 が監査全体を左右します。エンタープライズの評価担当者と個人開発者が求める内容は構造的に異なり、一方に最適化すると他方にとっては質が下がります。趣味で開発している人はコンプライアンスバッジが並ぶ壁にうんざりし、調達担当者はセキュリティやガバナンスに関する情報がないページを信用しません。後続の判断をすべてこの対象読者に照らして確認できるよう、スコアカードの冒頭に対象読者を明記してください。

次に、問題が README にあることを確認します。コードホストでトラフィックデータを確認できる場合は、直近 2 週間のユニークビジター数とクローン数を調べてください。

• トラフィックは十分なのに、クローン数とビジター数の比率が数パーセントしかない：このスキルの対象となるケースです。ユーザーは訪問しても納得せずに離れています。
• そもそもビジター数が少ない：文章の問題ではなく、露出の問題です。ほとんど読まれないページを書き直すのではなく、ユーザーをローンチや露出の改善に関する作業へ案内してください。

この「数パーセント」という境界は実務上の目安であり、ベンチマークではありません。境界付近の数値なら、判断を下す前にリファラーを確認してください。

ステップ 2 - 根拠を集める

良い README のイメージを記憶だけに頼って監査してはいけません。

1. README を最後まで読み、自分が混乱した箇所を記録します。初見で混乱した点は、初めて読む人の感覚に最も近いものです。
2. 機械的な監査を実行します：scripts/readme-audit.sh <repo-root>。次の項目が報告されます：
   • 影響を受けるコピー
   • 途中で切れるリスク
   • 見出しの階層
   • セクション数と中央値 7 との比較
   • コピー可能な最初のコマンドより前の単語数
   • バッジの数
   • 代替テキストの欠落
   • レジストリで問題になる生の HTML
   • 相対リンク切れ
   • プレースホルダーテキスト
   • コンテンツカテゴリの不足
3. README の周辺にあるリポジトリの内容も読みます。実際のランタイム要件が記載されたマニフェスト、ライセンスファイル、最近のコミット日時、未解決の Issue の数、README が参照する例がディスク上に存在するかを確認します。
4. 環境からウェブを閲覧できる場合は、プロジェクトのパッケージレジストリページを開き、コードホストでの表示と比較します。相対リンクや生の HTML はそこで頻繁に正しく表示されず、そのページのほうがトラフィックが多いこともよくあります。公開パッケージ自体に README が含まれていない場合は、パッケージングの不備です。samber/developer-platform-skills@sdk-package-publishing に引き継いでください。
5. 環境に永続メモリーがある場合は、プロジェクトのポジショニング、対象読者の定義、競合リストなど、保存済みの情報があれば再利用し、改めて導き出す必要はありません。

任意で、構造的な README スコアラーとコードホストのコミュニティ標準チェックリストを、セカンドオピニオンとして追加できます。いずれも基本的な衛生基準として扱ってください。妥当性の上限については、./references/tooling-and-measurement.md を参照してください。スクリプトが報告するのは事実であり、判断ではありません。セクション数が 25 という結果は、答えを出すべき問いであって、結論ではありません。

ステップ 3 - 現在の README を採点する

./references/audit-scorecard.md に沿って確認し、上記の形式でスコアカードを作成します。

• バンド A：阻害要因となる 5 項目。識別情報、実際に動作するインストール、すべての主張を検証できること、正直なステータス、アクセス可能なライセンス。
• バンド B：採点対象の 8 項目。各項目 2 点です。

すべての項目に根拠を添えてください。行番号、引用文、または実行したコマンドのターミナル出力を示します。書き換えを始める前に、スコアについてユーザーの同意を得てください。診断に納得できないメンテナーは、その対応策にも納得しません。また、リポジトリからは見えない制約によって、あなたが 0 点とした項目が正当化される場合もあり、メンテナーの判断が正しいこともあります。

修正の優先順位

修正リストは、書きやすさや、どれだけ問題を解消できるかではなく、かけた時間あたりの効果で並べます。この3つの順序は一致しないため、すべてを示し、3つ目から始めます。

• 労力、少ない順：status line == badge row > claim check > install path > differentiation paragraph > funnel restructure
• 価値、高い順：install path > differentiation paragraph > claim check > status line > funnel restructure > badge row
• 効率、先にやる順：status line > install path > claim check > differentiation paragraph > badge row > funnel restructure

ステータス行とバッジ行は、労力では同率です。どちらも、メンテナーがすでに知っていることをもとに、1つのブロックを1回編集するだけで済み、何も確認する必要がありません。コマンドを実行する必要も、ソースを読む必要もありません。価値の面では差があります。ステータス行が答える質問に対応しているREADMEはわずか21.4％ですが、バッジ行については投稿者の61％が無視するためです。

初回は上位3つをデフォルトにし、ブロッキングチェックが通ったら、またはコールドリーダーテストで3つのどれも扱っていない質問に答えられなかったら、下位の修正に進みます。

ファネルの再構成は、1時間でできる修正に対して1日か2日かかるため、どのラウンドでも最下位です。そのため、この順序では、ページを機能させる唯一の変更への投資が不足します。コールドリーダーが、スクロールが足りずに誤った回答をした場合や、監査の理由がローンチである場合は、ファネルの再構成を優先し、その優先順位を比率に反して引き上げたことを明記してください。

この優先順位はデフォルトであり、絶対的な決まりではありません。誰が実行するかによっても変わります。すでに分かっていることをもとに、順位を付け直してください。

• 代替案を一文で言えるメンテナーなら、差別化の段落はほぼ無料で作れるため、インストール手順より上位になります。
• インストールコマンドがないプロジェクト（仕様書、データセット、テンプレートなど）では、その項目を永久に0点として扱うのではなく、行ごと削除します。

回答13の上限ルールで対象外となる修正は、末尾に列挙するのではなく、すべて削除してください。

ステップ4 - すべての主張をソースと照合する

READMEはコードベースに関する主張の集まりであり、そのすべてを検証できます。エージェントもメンテナーも、APIの一般的な形についての記憶を頼りに書くことがあります。読者には、検証済みの行と創作された行の区別がつきません。しかし、リポジトリが手元にあるあなたには、その区別ができます。

すべての主張を列挙します。

• コマンド
• フラグ
• デフォルト値
• 環境変数
• 設定キー
• エンドポイント
• エクスポートされたシンボル
• ファイルパス
• バージョン要件
• 動詞に隠れた動作に関する断言（例：「自動的に再接続する」「3回再試行する」「大文字と小文字を区別しない」）

それぞれを、引数パーサー、定義箇所、ルートテーブル、変更履歴など、固有の情報源と照合します。記憶を頼りにせず、実際に読んで確認してください。READMEに記載されているのにパーサーに存在しないフラグは、誤字ではなく幻覚です。

次に、インストール手順そのものを実行します。これにより、実際の問題を最も多く検出できます。

1. クリーンな状態から始めます。コンテナ、新しい仮想環境、一時ディレクトリなど、環境で使えるものを選びます。コマンドを実行できない場合は、その旨を明確に伝え、ユーザーに一連の手順を実行して出力を貼り付けてもらいます。確認しただけで、このチェックに合格したと判定してはいけません。
2. 記載されたインストールコマンドをそのまま実行し、続けて最初の使用例もそのまま実行します。
3. 抜けている点をすべて記録します。READMEに記載されていないランタイムのバージョン、存在すると仮定されているシステムパッケージ、必須の環境変数、READMEと異なる出力などです。
4. 抜けている点をそれぞれ、明示的な前提条件または確認手順としてREADMEに反映し、クリーンな状態から一連の手順をもう一度実行します。

記載された手順が、記載のないステップを必要とせず、最初から最後まで実行できるまで繰り返します。パフォーマンスの数値、互換性マトリックス、規模の上限、「本番環境対応」という主張には、ベンチマークスクリプト、CIマトリックス、変更履歴など、リポジトリ内の根拠が必要です。根拠がなければ削除します。検証できない場合は、検証可能な内容まで主張の範囲を狭め、どの部分が未確認なのかを明記してください。

ステップ 5 - 構成を選び、セクションごとに書き直す

読者がコードを見て判断する内容ではなく、読者が何を_選ぼうとしているか_に合った骨組みを./references/readme-skeletons.mdから選びます。

• ライブラリの読者は、既存のコードベースに適合するかを判断します。
• CLI の読者は、すでにインストール済みのツールと比較します。
• フレームワークの読者は、数年単位の投資を判断します。

読者がプロジェクトを不採用と判断しやすい順にセクションを並べます。これは、Kira が_Art of README_で名付けた認知的ファネルです。最も広範で不採用の理由になりやすい情報を最初に示し、詳細へと絞り込んでいきます。詳細にたどり着くのは、導入を真剣に検討している読者だけです。そのため、たとえば制限の多いライセンスは、最も早く不採用の理由になり得るため上部に置きます。隠しておくと読者の時間を無駄にしてしまいます。

書き始める前に、最初に思いついた表現に飛びつかず、位置づけを明確にするためのブレインストーミングを行います。異なる切り口で、一文の候補を3つ作ります。

• 機能として何をするのか
• どのような問題を取り除くのか
• 何を使わずに済むようにするのか

それぞれの候補のトレードオフと推奨案を示し、ユーザーに選んでもらいます。この一文は、リポジトリの説明、レジストリページ、リンクのプレビューに反映されます。

一度に1つのセクションを作成し、次に進む前に合意を得ます。セクションごとに承認を得ることで、修正が容易なうちに意見の相違を見つけられます。各セクションでは、次のことを行います。

1. 問いに完全に答える、最も短い文章を書きます。
2. 「シンプル」「圧倒的に高速」「開発者に優しい」など、反証できない主張はすべて、読者が確認できるもの、たとえば数値、依存関係の数、対応プラットフォームの一覧、明示されたトレードオフに置き換えます。
3. プロジェクトのエコシステムに詳しくない読者にはわからない可能性がある用語に、すべてリンクを付けます。
4. プロジェクトが意図的に行わないことと、別のものを使うべき場合を明記します。これは多くの README で最も信頼性を高める一文であり、1行で済みます。
5. 画面に収まらないほど膨らんだ内容はリンク先のドキュメントに移し、README には1行の案内を残します。あふれた内容は移動し、削除しないでください。

コミュニティの健全性に関する内容は README に含めません。コントリビューションガイドライン、行動規範、セキュリティ上の脆弱性の報告、サポートポリシーは、それぞれ専用の標準ファイルに記載します。コードホスティングサービスは、必要なタイミングでそれらのファイルを表示します。README に含めてもスクロールが増えるだけで、読者が判断できるまでの距離が長くなります。例外はライセンスファイルです。これはリポジトリ内に含める必要があるため、組織レベルのデフォルト設定だけでは不十分です。

完成した文章を提示する前に、好みのヒューマナイザースキルに通します。生成されたように見える文章は、ページのほかの部分が築く信頼性を損ない、開発者にはすぐに見抜かれます。

冒頭の行、差別化のセクション、ステータスの説明、バッジ行、インストール手順、使用例について、良い例と悪い例を交えて解説した./references/before-after-examples.mdを参照してください。

ステップ 6 - 根拠に基づいてバッジを調整する

バッジは、README の要素の中で唯一、厳密な根拠があるものです。Trockman らは npm パッケージ 294,941 件を調査しました（ICSE 2018）。好みではなく、同研究の区別を使ってください。

• 評価シグナルは残します。実際の内容が真でなければ合格しない、第三者によるチェックに裏付けられたバッジです。CI のステータス、カバレッジ、公開済みのバージョン、依存関係の鮮度などが該当します。
• 慣例的なシグナルは削除します。「PR 歓迎」のように、検証する仕組みがなく、意図を述べているだけのバッジです。何のシグナルにもなりません。
• バッジの行数には上限を設けます。すでに人気のあるパッケージでは、バッジの過剰な使用は人気の_低下_と相関しており、バッジを導入しても人気はまったく上がりません。人気のあるプロジェクトほど、単にバッジを付けている可能性が高いだけです。相関の方向は研究に基づいていますが、ここでの 4 個という上限は、公開された数値ではなく実務上のデフォルトです。そのため、数を議論するのではなく、残すバッジがそれぞれ読者のどの疑問に答えるのかを説明してください。
• メンテナーはバッジを過大評価しがちだと考えてください。研究に付随する小規模な調査では、メンテナーはコントリビューターよりも、バッジを品質の指標として評価する割合がはるかに高く、大半のコントリビューターはバッジにまったく影響されないと答えています。メンテナーがバッジの削除に反対した場合は、./references/published-findings.md にある数値を引用してください。

ステップ 7 - リポジトリの付帯要素とレンダリングの仕組みを整える

このステップで取り組む 3 つの項目は、優先度が大きく異なります。

• 効率よく進めるには、まず次の順に取り組みます。furniture > render mechanics > terminal demo

• 付帯要素はほとんど手間がかからず、リポジトリを開く前に読者が目にする唯一のテキストを整えられます。検索結果に表示されるのは説明、ウェブサイトのリンク、トピックであり、チャットにリンクを貼ったときに展開されるのはソーシャルプレビューです。

• レンダリングの仕組みには約 1 時間かかりますが、コードホストで README を表示しない読者にもページを正しく届けられます。レジストリのページ、ターミナル、スクリーンリーダーが対象です。

• ターミナルデモをきちんと作るには 1〜2 日かかり、その後も継続的に手入れする必要があります。出力が変わるたびに古くなります。

この順序ではデモが後回しになりますが、CLI やビジュアルツールでは、出力そのものが製品であるため、ページ内で最も価値の高い要素です。その場合に限り、レンダリングの仕組みよりデモを優先し、手作業で録画するのではなくスクリプトから生成してください。そうすれば、再レンダリングの負担を抑え、継続的に手入れできます。目に見える出力がないライブラリでは、デモは削除してください。import 文のデモには価値がありません。後になって作業範囲に再び含まれることのないようにしましょう。

付帯要素を整えたら、ファイル自体のレンダリング方法を確認します。

1. すべての画像に代替テキストを付け、説明、コマンド、判断に関わる情報をスクリーンショットやアニメーションデモからテキストに移してください。読者はターミナルや HTML が除去されるレジストリのページ、スクリーンリーダーを通じても README を読みます。アニメーションデモは、この 3 つのどれでも見えません。
2. 手書きの目次は削除してください。コードホストは見出しから目次を自動生成するため、手動の目次は古くなります。
3. 相対リンクがデフォルトブランチのリポジトリルートから正しく解決されることと、raw HTML が除去される場所でもページを正しく読めることを確認してください。
4. レンダリングされる README は 1 つだけにしてください。ホストがルートファイルより .github/ 内のコピーを優先して表示する場合でも、レジストリやミラーが公開するのはルートのコピーです。そのため、2 つの内容が気づかないうちに食い違います。
5. モノレポでは、すべてのパッケージをルートの README に直接記載するのではなく、各パッケージの README に案内する目次として使ってください。

デモを掲載する価値がある場合は、短く、コントラストを高くして、埋め込み表示でも読みやすくし、タグラインの直後に配置してください。デモによるコンバージョン向上は、測定された結果ではなく実務者の共通認識として扱ってください。定量評価した研究はなく、それも、通常はコストの低い 2 つの項目より優先しない理由の一つです。

Step 8 - 対象者が求める場合に限り、エンタープライズ向けの信頼性を示す情報を追加する

このステップは、ステップ 1 で企業または調達担当者を対象者とした場合に限り実行してください。

エンタープライズの意思決定者が重視するのは、技術的な適合性の高さではなく、正当性を説明できることです。そのため、目新しい主張よりも、認知度の高い第三者による裏付け、たとえば財団のティア、監査、証明、著名な導入企業のほうが効果的です。公開されている評価チェックリストでは、見せ方の質よりも、メンテナンスの状況、ライセンスの明確さ、セキュリティ体制が重視されています。出典は ./references/published-findings.md にあります。

利用できるシグナルは 6 つあり、コストには 2 桁の差があります。

• 手間が少ない順：support expectation == release cadence > security policy > supply-chain attestation > named adopters > governance and maintainer depth > foundation affiliation
• 価値が高い順：foundation affiliation > named adopters > security policy > governance and maintainer depth > supply-chain attestation > release cadence == support expectation
• コンプライアンスコスト：
  • 財団との提携には、商標または知的財産の譲渡と、後戻りできない法務部門の承認が必要です
  • 導入企業を記載するには各社の個別のマーケティング承認が必要です。取り消しは可能ですが、その都度改めて依頼する必要があります
  • セキュリティポリシーを公開すると、対応期間を公約し、それを守らなければなりません
  • 残りの 3 つは審査が不要で、1 回のコミットで元に戻せます
• 効率が高い順：support expectation == release cadence > security policy > named adopters > supply-chain attestation > governance and maintainer depth > foundation affiliation

サポートへの期待値とリリース頻度は、2 つの点で同率です。どちらも、すでに事実であることを述べる 1 文であり、誰の許可も必要なく、コミットログを読む以外の作業も要りません。サプライチェーンの証明には、リリースパイプラインの設定とテストに約 1 日かかります。導入企業の記載には、各社に承認を依頼するために約 1 週間かかります。それでも導入企業は効率の面で最上位です。証明が納得させるのは、もともと賛成するつもりだったエンジニアですが、認知度の高いロゴは署名する人を納得させるからです。

最初の 3 つを基本とし、合わせて半日で済ませましょう。これで評価チェックリストの大部分をクリアできます。案件が進行中で、「ほかにこれを使っているのは誰ですか」と尋ねられたら、導入企業の記載に進みます。

この順序で後回しになるのが財団との提携です。ページ上では最も強いシグナルですが、作業に 1 四半期以上かかるため、費用対効果で勝つことはなく、README を起点とする計画では到達しません。プロジェクトが依存関係ではなくインフラとして採用される場合、または財団のティアが繰り返し敗因になる場合は、優先度を上げてください。ただし、これはユーザーに判断を委ねてください。元に戻すためのコストは、ドキュメント作成のコストではないためです。

ルール 13 で除外されるシグナルは、将来の作業として列挙するのではなく、すべて削除してください。法務面で対応する意向がない場合は財団の項目を設けず、メンテナーが 1 人だけなら、空のガバナンス見出しではなく、実態に即したサポートへの期待値を記載します。

Step 9 - スコアを再評価し、予備知識のない読者でテストする

スコアカードを再実行してください。ブロッキングチェック 5 項目すべてに合格し、スコア付きチェックの合計が 16 点中 14 点以上であれば、README は合格です。これは公開された基準ではなく、この場で使うデフォルト値です。ユーザーが理由を示して変更する場合は、その理由をレポートに記録してください。

次に、スコアカードで定義されている予備知識のない読者によるテストを実行してください。質問は 5 つ、制限時間は 60 秒で、5 問正解すれば合格です。ユーザーが人を見つけられる場合はその人を使い、難しい場合はリポジトリのコンテキストを持たない新しいエージェントセッションを使ってください。各不正解は特定のチェック項目に対応しているため、失敗すれば何を修正すべきかが明確に分かります。

環境に永続メモリがある場合は、合意した一文、対象者の定義、競合リスト、最終スコアを保存してください。ローンチ投稿、ドキュメントのランディングページ、カンファレンスの概要など、関連する作業も、新たなポジショニングを作り出すのではなく、そのポジショニングを出発点にしてください。

その後の追跡項目

READMEでの効果測定は弱いものです。公開日を記録し、公開前後それぞれで完全な期間を比較して、差分を主張するのではなく交絡要因を注記します。4〜6週間後に再測定してください。それより短い期間ではノイズになります。

• 効率性、まず追跡する項目：サポート負荷 > コンバージョン率 > コントリビューターへの転換率

• サポート負荷は費用をかけずに追跡でき、数週間で変化します。月ごとの「インストール方法を教えてください」や「これは何をするものですか」という質問の件数を数え、減少するか確認します。

• コンバージョン率（ユニーク訪問者数に対するクローン数またはダウンロード数）は、ホストのトラフィックデータから集計するのに1時間ほどかかります。利用できる単一の指標としては最も実態に近いものですが、前後それぞれで完全な期間が経過するまでは何も分かりません。

• コントリビューターへの転換率は最も時間がかかり、交絡要因も最も多いため、四半期後に確認します。

回答5でスターを目標に挙げていた場合でも、追跡計画からスターを完全に外してください。スターは増える一方で、指標として悪化を示せず、ページを劣化させた変更まで成功と報告してしまうためです。代わりにコンバージョン率を提案してください。

クローン数が増えてもコントリビューター数が増えない場合、問題はREADMEではなく、コントリビューションへの導線です。測定方法とその注意点については、./references/tooling-and-measurement.mdを参照してください。

よくある失敗

診断前に書き直す。 説明文を改善しても、壊れたインストール手順をそのままにした書き直しでは、何も解決していません。レビューでは、依頼されない限り書き直しは一切行わないでください。

立派に見せるために内容を水増しする。 READMEの半数は5〜12セクションで、中央値は7です。単一目的のプロジェクトなら、4セクションのREADMEで十分です。200行のユーティリティにアーキテクチャやロードマップのセクションを追加すると、成熟して見えるのではなく、放置されているように見えます。

マーケティング調の文体。 根拠のない最上級表現は、この読者層には雑音として受け取られ、信頼を積極的に損ないます。すべての主張は検証可能なものにするか、削除してください。

1つの表示先だけを監査する。 レジストリページは、より多くのトラフィックを集め、ルールも異なることがよくあります。1つのホストでしか機能しないREADMEは、多くの読者にとって問題があります。

実態のないステータス表記。 ユーザーから聞いていない「本番環境対応」「実戦で十分に検証済み」やユーザー数を決して記載しないでください。誇張した主張はコミット履歴を一目見れば覆され、正直な「初期ベータ版」と記すよりも大きく信頼を損ないます。

最も手軽な修正から始める。 バッジの行はリストの中で最も手早く対応でき、価値はほぼ最低です。最初に終わらせられる順ではなく、「修正の優先順位」に記載された順序で提示してください。

参考資料

• ./references/audit-scorecard.md - 評価基準、しきい値、初見読者テスト、レポート形式。
• ./references/published-findings.md - 出典のあるすべての数値と、よくある俗説の一覧。
• ./references/readme-skeletons.md - プロジェクトの種類ごとのセクション構成。
• ./references/before-after-examples.md - 改善例と悪化例。
• ./references/tooling-and-measurement.md - 評価、Lint、効果測定のためのツール。
• ./scripts/readme-audit.sh - 評価基準表が依拠する機械的に取得可能な情報。
• samber/developer-relations-skills@developer-quickstart-guide - 専用のスタートガイドページ。
• samber/developer-relations-skills@developer-docs-structure-audit - ドキュメントサイトの構成。
• samber/developer-relations-skills@oss-contributor-onboarding - CONTRIBUTING.mdと初回コントリビューションへの導線。
• samber/developer-relations-skills@changelog-writing - リリースノートと変更履歴の構成。
• samber/developer-relations-skills@oss-launch - 公開の計画と実行。
• samber/developer-relations-skills@oss-distribution-strategy - このリポジトリのページに読者を誘導するチャネル。