good-readme

good-readme

哲学

基本原則：README はプロジェクトへの入り口です。「これは何か、なぜ関心を持つべきか、どう使えばよいか」に30秒以内で答えられる内容にします。各セクションは、読者の実際のニーズに応えることで存在意義を示すべきです。定型文で水増ししないでください。

優れた README は、ざっと目を通しやすく、誠実で、読者層を意識しています。明確な価値提案を最初に示し、実際の使用例を紹介し、読者の時間を尊重します。プロジェクトを評価する開発者は、さらに時間をかけるかどうかを1分もかけずに判断します。README はプロジェクトの売り込み資料です。

優れていない README は、構成のない長文、誰も読まない自動生成の定型文、または読者がソースコードを調べなければならないほど情報の少ない一行だけの説明です。同じくらい問題なのは、/docs の内容を重複させたり、あらゆる API メソッドを本文に含めたりする、過剰に詳細な README です。

セクションごとのガイダンスについては anatomy.md、評価の高いプロジェクトのパターンについては examples.md、よくある間違いについては anti-patterns.md、Cloudflare エコシステムの慣例については cloudflare.md を参照してください。

モード

このスキルは2つのモードで動作します。

1. 作成 — 新しい README

README がないプロジェクトや、一から作成する必要があるプロジェクト向けです。

書き始める前に：

• プロジェクトのソースコードを読んで、何をするものか理解する
• 対象読者を特定する（エンドユーザー、開発者、またはその両方か）
• プロジェクトの慣例がわかる既存ドキュメント、設定ファイル、CI の設定を確認する
• package.json / Cargo.toml / pyproject.toml / go.mod などを確認し、プロジェクトのメタデータを把握する
• ソースコードに基づく事実の一覧を作成する：パッケージ名、エントリーポイント、エクスポートされた関数／クラス、CLI コマンド／フラグ、設定キー、必須のランタイムバージョン
• ドキュメントに記載する API、コマンド、インポートはすべて、名前を記載する前に現在のソースコードまたはマニフェストと照合する
• ユーザーに尋ねる：「この README は誰に向けたもので、何を一番理解してほしいですか？」

執筆手順：

• タイトルと一行の説明（読者を引きつける要素）を下書きする
• 簡潔な「概要と目的」セクションを書く（最大2〜4文）
• 読者が最小限の手順で何もない状態から使える状態になる、クイックスタートを追加する
• 実際にテストしたコード例を含める。疑似コードは使わない
• エコシステムに適したインストール手順を追加する
• このプロジェクトに必要なセクションだけを追加する（anatomy.md を参照）
• 最終版にする前に、下書きをユーザーに提示してレビューを依頼する

2. 改善 — 既存の README

改善が必要な README があるプロジェクト向けです。

まず監査する：

• 現在の README を最初から最後まで読む
• プロジェクトのソースコードを読み、README が正確かつ最新か確認する
• API／CLI の差異を確認する：README に記載されたインポート、関数、コマンド、フラグ、設定キーを抽出し、それぞれを現在の公開エクスポート、エントリーポイント、スキーマと比較する
• quality checklist に照らして評価する
• 不足している情報、古くなった内容、不要なセクション、ソースコードに基づいて確認できる差異を特定する
• 事実の修正を裏付けるソースファイルやマニフェストを示し、具体的な推奨事項とともに調査結果をユーザーに提示する

次に改善する：

• まず事実の誤りを修正する（誤ったインストールコマンド、古い API の例など）。修正を裏付けるソースファイルまたはマニフェストを示す
• 構成上の問題に対処する（不足しているセクション、適切でない順序）
• 明瞭さと読みやすさを高める（見出し、コードブロック、リスト）
• 価値を加えない定型文を削除する
• 古い例を書き換える場合は、現在のインポート、関数、シグネチャ、コマンドを、エクスポートまたは定義されていることを確認したうえで使う。存在しない名前に対する互換性ラッパーを作り出さない
• すべてのコード例が動作することを検証する。または、実行できなかった検証項目を明記する
• 変更内容をユーザーに提示し、承認を得る

主要原則

1. 価値を先に伝える — 最初の3行で、読み続けてもらえるかどうかが決まります
2. 説明するより、実例を示す — コード例は文章での説明より効果的です
3. 対象範囲を正直に伝える — プロジェクトができることと、できないことの両方を明記します
4. エコシステムの慣習を尊重する — npm のプロジェクトと Rust のクレートでは、見せ方が異なります
5. メンテナンスを続ける — 誤った情報が載った README は、README がないよりも悪いものです
6. 重複させず、リンクする — 詳細な説明は docs/ に案内し、README の内容は要点に絞ります
7. 例をテストする — 動かないコード例は、すぐに信頼を損ないます
8. 記憶よりソースを優先する — README の例、以前のドキュメント、モデルの記憶は、現在のソースコードやマニフェストと照合するまでは、正しいと決めつけないでください

ソースに基づく API の不整合対応プロトコル

README に関数、クラス、インポート、CLI コマンド、フラグ、設定キー、またはコード例が記載されていて、コードから乖離している可能性がある場合は、このプロトコルを使用します。

1. ドキュメントに記載されたシンボルを抽出する — 編集前に、README にあるすべてのインポート、公開 API 名、コマンド、フラグ、オプション、設定キーを列挙します。
2. 権威ある定義を見つける — パッケージのマニフェスト（exports、bin、エントリーポイント）、公開エクスポートファイル（__init__.py、index.ts、lib.rs、go.mod のモジュールパス）、CLI パーサー、設定スキーマ、型宣言を確認します。
3. 存在とシグネチャを確認する — 文字列の出現箇所だけでなく、定義を検索します。インポートパス、パラメーター名、必須オプション、戻り値や出力の形式、非推奨の注記を確認します。
4. 不整合を明確に分類する — 各不一致を、名称変更、削除、移動、シグネチャ変更、未文書化、または不明確として記録します。src/package/__init__.py や package.json#bin など、根拠となるソースファイルも記載します。
5. 推測ではなくソースに基づいて書き換える — 古くなった例を、現在エクスポートされている API に置き換えます。以前の名称に触れる場合は、不整合や移行に関する注記としてのみ記載し、ソースで互換性が確認できない限り、現在の名称として示さないでください。
6. 不確実性には正直に対応する — ソースから置き換え先がわからない場合は、その旨を伝えてユーザーに確認するか、メンテナー向けのプレースホルダー注記を残します。ラッパー、エイリアス、ベンチマーク、互換性に関する主張、実装を捏造しないでください。
7. 修正したスニペットを検証する — 可能であれば、記載したコマンドや例を実行します。実行できない場合は、検証していない内容を具体的に示します。

監査結果を報告する際は、API の不整合に関する調査結果を簡潔な「確認したソース」の注記または表にまとめます。古くなった README のシンボル、現在のソースにあるシンボル、根拠となるファイル、修正後のスニペットを記載してください。

セクションごとのチェックリスト

[ ] Title is clear and descriptive (not clever)
[ ] One-liner explains what + why in plain language
[ ] Quick-start gets reader to "it works" in ≤5 steps
[ ] Code examples are real, tested, and copy-pasteable
[ ] Installation covers the project's actual ecosystem
[ ] No orphan sections (every section serves a purpose)
[ ] Badges are useful, not decorative
[ ] License is stated
[ ] Contributing section exists if accepting contributions