READMEを評価する
概要
READMEはリポジトリの玄関です。ほとんどのREADMEは失敗しています。なぜなら、表面（APIの見た目）ではなく、メンタルモデル（システムとは何か、どのように動作するか、どこで壊れるか）を文書化すべきだからです。このスキルは、8つの軸にわたってREADMEを採点し、全体評価のための最良の単一ヒューリスティックを提示します。
この評価基準を用いて、書面によるレビューを作成してください。 各セクションについて、何が機能しているか、何が欠けているか、何を修正すべきかを記述します。具体的に、行を引用し、見出しを指摘し、バグを特定してください。
使用方法
- まずREADMEを最初から最後まで一度だけ、評価せずに読みます——第一印象が重要です。
- 以下の8つのセクションを順に進めます。各セクションには質問があります。READMEからの証拠を添えてそれぞれに答えてください。
- 最後に最良の単一ヒューリスティックを適用し、あなたの評価の妥当性を確認します。
- リストアップされたアンチパターンがないか確認します——これらは自動減点項目です。
- 修正リストを作成します：優先順位順に、何を修正すべきか。
評価基準
1. 最初の30秒テスト
見知らぬ人が、スクロールせずに見える範囲で方向性を把握できるかどうか。
- これは何ですか？ 見知らぬ人でも理解できる、スクロールせずに見える位置にある一文。
- 誰のためのものですか？ 最初の段落内で、読者が自分に関係あるかどうかを判断できる。
- 実際に動作していますか？ 生存の証拠——CIステータス、週間ダウンロード数、最終リリース日、バージョンバッジ、「Xでテスト済み」。実際のダウンロード数はリリース日よりも強いシグナルです。緑色のCIバッジはそのどちらよりも強いシグナルです。誰も放棄されたリポジトリを信頼しません。
2. 5分以内にインストールできますか？
すべてのコードブロックを順番にコピーペーストした読者が、最終的に動作するものになるかどうか。
- 前提条件が明示されている——ランタイムバージョン、ピア依存関係、外部サービス。
- インストールは1つのコピー可能なブロックである。 「インストールについてはドキュメントサイトを参照」ではない。
- クイックスタートが最初から最後まで動作する。 ギャップがない。「Xを設定」が方法の説明なしにある、といったことがない。
- 例で一貫した名前が使われている。 セットアップで
mainKnowledgePool、検索で'main'は、READMEのバグ第1位です——コピーペーストするユーザーをすべて静かに壊します。
3. 現実と一致していますか？
READMEがコードと一緒にメンテナンスされているかどうか。
- すべてのコードサンプルがコンパイルできる。 古い型シグネチャや名前が変わったエクスポートは、例がないよりも悪いです。
- バージョンの乖離が認められている。 動画/ブログ記事/セクションが古くなっている場合は、読者が苦労して発見するのを待つのではなく、その場でその旨を明記する。
- エラーレスポンスとエッジケースが文書化されている、正常系のパスだけではない——何が壊れるかを認めるドキュメントを読者は信頼します。
4. ナビゲーションしやすいですか？
3回目に戻ってきた人が、必要な情報を素早く見つけられるかどうか。
- 目次が約300行を超えるものには必要。
- セクションの深さに意味がある。 h3の下のh4、h2の下のh3は、実際の包含関係を反映すべきであり、「
##を使い切ったから」という理由であってはならない。孤立したサブセクションは、文書が再構成されることなく肥大化した証拠です。 - 相互参照はリンクであり、散文ではない。 「上記参照」はすぐに古くなります。
[メタデータフィルタリング](#metadata-filtering-where)は編集に耐えます。 - 重複情報は危険です。 同じエンドポイントが2回文書化されていると、一方が腐ります。正規の場所を1つ選びましょう。
5. メンタルモデルを教えていますか？APIだけではありませんか？
読者が構文だけでなく、直感を持ち帰れるかどうか。
- 方法だけでなく、理由も。 「一括実行は自動キューイングされません——手動でトリガーする必要があります」は、シグネチャの羅列よりも多くのことを教えてくれます。
- ライフサイクルと不変条件が述べられている。 「プールごとに一度に実行できる一括実行は1つだけ」、「削除は無効化できない」、「IDはXとYを関連付ける」——これらは、文書化されていなければユーザーが苦労して発見するものです。
- 障害モードに名前が付けられている。 トラブルシューティングセクションは、「メンテナーが実際にこれを本番運用でサポートしたことがある」というプロキシです。
ドキュメントサイトの例外。 プロジェクトに、スクロールせずに見える位置にリンクされた正規のリファレンスサイトがある場合（例：
zod.dev/api、nextjs.org/docs）、このセクションは「READMEは、読者がドキュメントサイトに飛び込むべきかどうか、そしてそこで何を探せばよいかを理解するのに十分な知識を教えているか？」に対して評価します——「完全なメンタルモデルを教えているか？」ではありません。READMEに完全なリファレンスを複製することは、セクション4の「重複情報は危険」のルールに違反します。その場合のREADMEの役割は、百科事典ではなく、橋渡しです。
6. 段階的な開示
各読者が、自分に必要なセクションで読み終えることができるかどうか。
- クイックスタートで動作するようになる。リファレンスで行き詰まりを解消する。例で慣用的な使い方を示す。
- 高度な機能が初心者をブロックしない。 一括API、プロバイダーコールバック、カスタムアダプター——これらはすべて、動作する検索に至る最小限のパスより後ろに配置する。
- 必須/任意の列がある設定テーブルにより、読者は読む代わりにスキャンできる。
7. メンテナンスシグナル
プロジェクトが企業内で生きており使用可能に見えるかどうか。
- 変更履歴へのリンクがある。 変更履歴がない = プロジェクトがメンテナンスされているというシグナルがない。
- ライセンスが明記されている。 ライセンスがない = ほとんどの企業で使用不可。
- コントリビューションの道筋が見える。 1行（「最初にIssueを立ててください」）でも、何もないよりはましです。
- トーンが成熟度に合っている。 アルファ版プロジェクトがv3のように読めるべきではありません。安定版プロジェクトがハッカソンの提案のように読めるべきではありません。
8. 制限事項について正直である
メンテナーが読者の時間を尊重しているかどうか。
- アダプターの互換性、プラットフォームサポート、既知のギャップが明示されている、GitHub Issueに隠されていない。
- READMEで制限事項を見つけた読者は情報を得たと感じます。同じ読者が2時間のデバッグ後に制限事項を見つけると、騙されたと感じます。
最良の単一ヒューリスティック
READMEの読者に応じて、2つのヒューリスティックを適用します。
ユーザー契約: 新しいユーザーがREADMEを初見で開き、ソースを読むことなく、小さな正しいインテグレーションをデプロイできるか？ すべてのREADMEに必要です。
コントリビューター契約: 新しいコントリビューターがREADMEを初見で開き、メンテナーと話すことなく、小さな正しいPRをデプロイできるか？ READMEがコントリビューターのエントリーポイントである場合に必要です。READMEから
CONTRIBUTING.mdがリンクされている場合は任意——その場合、コントリビューター体験はREADMEではなく、そのファイルに対して評価します。
コントリビューター契約には、README（またはCONTRIBUTING.md）がアーキテクチャを説明していることが必要です。表面だけではありません。ほとんどのプロジェクトはこのテストに失敗します。そしてそれが、通りすがりのコントリビューションを得られるプロジェクトとそうでないプロジェクトの違いであることがよくあります。
ユーザー契約が不合格の場合、それはセクション1～7の表面的な洗練よりも優先されます。コントリビューター契約のみが不合格で、かつCONTRIBUTING.mdがリンクされていない場合でも、それは依然として実際の欠陥です——フラグを立ててください。ただし、ユーザー向けの強みを無効にするものではありません。
アンチパターン（自動減点）
見つけたら明示的にマークしてください——それらはより大きな問題を示しています。
| アンチパターン | なぜ悪いのか |
|---|---|
| リファレンスドキュメントがあるべき場所にマーケティングコピー | 読者に必要なのは事実であり、売り込み文句ではない |
| コードブロックの代わりにコードのスクリーンショット | コピーペースト不可、検索不可、アクセシビリティ不可 |
| ドキュメントとしての「ソースを参照」 | メンテナーの仕事をすべての読者に押し付ける |
| セクション見出しに対応しない絵文字駆動の機能リスト | ナビゲーション価値のない飾り |
| 目的のないバッジ——約6個以上、または明確なシグナル（CI、ライセンス、ダウンロード数、バージョン、カバレッジ、サポートチャネル）に対応しないバッジ | 品質のカルゴカルトシグナル。5個の意味のあるバッジは問題ないが、10個の装飾的なバッジは問題 |
| 優先順位やタイムラインに関するシグナルなしに実際にはウィッシュリストである「ロードマップ」 | プロジェクトが満たせない期待を設定する |
| 「vXに対して記録済み」という免責事項なしにリンクされた動画/ブログ記事 | 読者は古いコンテンツで時間を無駄にする |
読者に送り出されるプレースホルダーテキスト（your-repo、TODO、lorem ipsum、壊れたアンカーリンク） | スクロールせずに見える位置での最大の信頼殺し——公開前に誰も校正しなかったことを示す |
逆順のレイヤリング——必要なヘルパー（例：embedQuery）がそれを使用するクイックスタートの後で定義されている | 「最小パス」のコピーペーストでReferenceErrorが発生する。サンプルブロックが実際には自己完結していない |
| 設定で終了し、「動作確認」スニペットがないクイックスタート | 読者はインストールが実際に何かをしたか確認する方法がない。ドキュメントは取り込みをカバーしているが、検索はカバーしていない |
出力フォーマット
READMEを評価する際は、以下を生成します。
- 評決——1行。（例：「インストールは強いが、メンタルモデルは弱い。新規ユーザーは10分でデプロイできるが、新規コントリビューターはできない。」）
- セクションごとの所見——8つの軸のそれぞれについて、何が機能していて何が欠けているか、行/見出しの参照を添えて。
- 該当するアンチパターン——上記の表から該当するものを列挙。
- 最良ヒューリスティックの回答——ユーザー契約とコントリビューター契約の両方について、理由を添えて「はい/いいえ」。
CONTRIBUTING.mdがリンクされている場合は、コントリビューターテストがそのファイルにスコープされていることに言及する。 - 修正リスト——優先順位順の修正（影響が最大のものから）。