writing-a-readme

README の作成

最初の応答

このスキルが呼び出されたら、まず「このプロジェクトについて、一文で説明するとどうなりますか？」と尋ねます。

重要な理由

README を読む人は、読み進めるかどうかを1分もかけずに判断します。GitHub のエコシステムでは、何千ものテンプレートリポジトリを通じて、かなり一貫した構成が定着しています。これは、「高度なオプションの設定方法」よりも先に「これは何で、なぜ注目する価値があるのか」を伝える構成が効果的だからです。内容が優れていても、この順序から外れると、README は流し読みしにくくなり、途中で読むのをやめられる可能性が高まります。

テンプレートの全体像を形作る主要な流れは3つあります。それぞれ重視するものが異なるため、すべて知っておく価値があります。

• othneildrew/Best-README-Template とその数多くのフォーク — バッジやロゴを多用し、見た目の洗練と、コントリビューターやスターを集めたいプロジェクト向けに作られています。個人プロジェクト、ポートフォリオ、幅広い読者を対象とするオープンソースライブラリで人気があります。
• richardlitt/standard-readme — セクション名や順序、必須項目と任意項目を定めた厳格な仕様で、組織やエコシステム内の多数のリポジトリに一貫性をもたらします。歴史的に Node/npm の世界でよく使われてきました。派手さは控えめですが、予測しやすい構成です。
• makeareadme.com — 厳格なテンプレートではなく、説明を重視した、より軽量なガイドです。最小限の出発点となる骨組みと、各項目の理由を添えた任意セクションのチェックリストで構成され、npm パッケージに限らず、あらゆるプログラミングプロジェクトを手早く妥当な水準に整えることを目的としています。他の2つの流れでは省かれがちな Support（ヘルプを得る場所：Issue トラッカー、チャット、メール）と Project status（プロジェクトの進行が遅れている、アーカイブ済み、またはメンテナーを募集中であることを冒頭に記す項目）の2つのセクションは、関連する場合には、他の流れをベースのテンプレートに使う場合でも追加する価値があります。

どんな場合でも反射的に同じテンプレートを使うのではなく、依頼に合った流れを選びましょう（または組み合わせましょう。Best-README-Template のバッジ、standard-readme のセクション順の規律、makeareadme.com の Support／Project status の習慣など）。各バリエーションの詳しいテンプレート例は references/templates.md を参照してください。

ステップ1：README の種類を見極める

そのプロジェクトが実際には次のどれに当たるのかを、自分自身に（またはユーザーに簡潔に）問いかけます。種類によって、重要なセクションが変わります。

• ライブラリ／パッケージ（npm、pip、gem、crate など） — パッケージマネージャーを使ったインストール、実行可能なコード例、API リファレンスが中心です。バージョン、ダウンロード数、ビルド状況のバッジも、ここでは実際に役立つ情報を伝えます。
• CLI ツール — インストール方法に続けて、実際のコマンドやフラグを示す 使用方法 のブロックを載せます。多くの場合、--help の出力や GIF／asciinema の録画も含めます。「API リファレンス」は省きます。
• アプリケーション／サービス（ウェブアプリ、セルフホスト可能なツール） — コードスニペットよりも、スクリーンショットやデモへのリンクが重要です。「はじめに」は通常、「インポートする方法」ではなく「デプロイまたは実行する方法」を意味します。
• GitHub プロフィール README（ユーザー名と完全に同じ名前のリポジトリ） — まったく異なる形式です。短く、個人的な内容で、コードベースではなく本人について書きます。ライブラリ向け README の構成を当てはめないでください。
• モノレポ／組織レベルの README — 主に案内図としての役割を果たします。ここには、どのパッケージが含まれているか、各パッケージの README へのリンク、プロジェクト全体のビルド／テスト方法を記載します。

文脈から判断しにくい場合は、草案を作る前に「npm install して使うライブラリですか、それとも実行／デプロイするアプリですか？」と簡単に確認する価値があります。種類によって必要なセクションが実際に大きく異なるため、誤って推測すると書き直しが必要になります。

ステップ 2：素材を集める

プロジェクトについて、事実をでっち上げないでください。執筆を始める前に、次の情報を探し（見つからないものはユーザーに尋ねてください）。

• 実際のプロジェクト名、説明、ライセンス、依存関係を確認できる既存の package.json／pyproject.toml／Cargo.toml／go.mod など。
• エコシステムにおける実際のインストールコマンド（npm install <name>、pip install <name>、cargo add <name> など）。パッケージ名を推測してはいけません。
• 実際に実行できる使用例を 1 つ。テストや examples/ から取得するか、正式な「Hello World」のユースケースをユーザーに尋ねてください。README の信頼性は、主に最初のコードブロックを貼り付けたときに実際に動くかどうかで決まります。
• ライセンス（LICENSE ファイルを確認）とコントリビューションの慣例（既存の CONTRIBUTING.md があるか）を確認してください。デフォルトで「MIT」や「PR 歓迎」と断言してはいけません。
• 再利用できるロゴ、スクリーンショット、デモ GIF がリポジトリにすでにあるかどうかを確認してください。存在しないファイルへの images/logo.png 参照をでっち上げてはいけません。

これらの情報が不足しており、見つけられない場合は、もっともらしい詳細を作り上げず、明確なプレースホルダー（``）を残してください。自信満々に間違ったインストールコマンドを書くより、正直に空欄を示すほうがよいです。

ステップ 3：構成

どちらの形式でも、README の各セクションには慣例的な順序があります。各セクションが読者の次の疑問に答えるためです。適用されないセクションは空のまま残さず省略し、これを標準の構成として使ってください。

# Project Name

[badges: build status, version, license, ...]

One or two sentences: what this is and who it's for.

[optional: screenshot, GIF, or logo]

## Table of Contents
[only for READMEs long enough to need one — roughly 200+ lines / 5+ sections]

## About / Features
What it does and why it exists. What makes it different from the obvious alternative.

## Getting Started
### Prerequisites
### Installation

## Usage
The real, runnable example. This is the section people actually read.

## Configuration / API Reference
[if applicable — options, environment variables, exported functions]

## Support
[optional — where to get help: issue tracker, chat/Discord, email]

## Roadmap
[optional — link to Issues instead if the roadmap lives there]

## Contributing
[can be one paragraph + a link to CONTRIBUTING.md instead of inlining the whole process]

## Authors and Acknowledgment / Contact
[optional — trim if it's just a list of unrelated link dumps]

## License

## Project Status
[optional — only if development has slowed or stopped; say so explicitly and
mention if you're open to someone forking or stepping in as maintainer]

2 つの系譜に共通する、順序に関する注意事項：

• インストールは必ず使用方法の前に置き、使用方法は必ず API／設定リファレンスの前に置きます。読者は「使えるかどうか」を「カスタマイズ方法」より先に判断します。
• ライセンスは上部ではなく末尾近くに置きます。重要ではありますが、読み続けるかどうかを決める情報ではありません。
• プロジェクトの状況は末尾に置きます（プロジェクトが停滞している場合は、上部近くに注意書きとして記載します）。これは makeareadme.com の慣例です。プロジェクトが保守されていない場合は、Issue を投稿しても返答がないと気付くまで明かさずにいるのではなく、その旨を明確に記載してください。
• 目次は standard-readme の慣例で、長い README には取り入れる価値があります。短い README では、最初に見える範囲を散らかすだけなので省略してください。
• makeareadme.com の経験則は、内容を削る際（下記のステップ 5）にも覚えておく価値があります。長すぎる README でも、短すぎる README よりはましです。冗長に感じる場合、通常は内容を削除するのではなく、Wiki やドキュメントサイトに分割するのが適切です。
• テンプレートにあるという理由だけでセクションを追加してはいけません。週末に一人で作るプロジェクトにロードマップや行動規範へのリンクは不要ですし、社内ツールにコントリビューター向けのバッジは必要ありません。空のセクションや定型文だけのセクションは、よりプロフェッショナルではなく、テンプレートを使った印象を強めます。

ステップ 4：バッジ（バッジを多用するスタイルの場合）

バッジ（shields.io）は、装飾ではなく、ビルド状況、公開バージョン、ライセンス、ダウンロード数など、実際の最新情報を示す場合に最も効果を発揮します。ガイドライン：

• https://shields.io/ またはエコシステム固有のバッジを使ってください（npm、PyPI、crates.io では、それぞれ独自のバッジを生成できます）。SVG を独自に作成してはいけません。
• バッジは 3～5 個が一般的です。10 個以上並べるとノイズに見えやすく、カスタマイズせず Best-README-Template からそのままコピーした定型文だと思われることもよくあります。
• 納品する README に、プレースホルダーのバッジ（どこにもリンクしていない build-shield や contributors-shield）を残してはいけません。実際の CI／パッケージに接続するか、削除してください。
• 順序は、ビルド／CI 状況、パッケージのバージョン、ライセンス、ソーシャルの順です。ソーシャルバッジは、関連性がある場合でも通常は Discord や LinkedIn へのリンクなど 1 つまでにします。

ステップ 5：書いてから、削る

README を最後まで書き上げたら、懐疑的な第三者になったつもりで読み返し、次の内容を削ります。

• 裏付けとなるベンチマークや実績がないのに使われている、内容のない宣伝文句（「驚異的な速さ」「本番環境対応」など）。
• 見出しの内容を文章で言い換えているだけのセクション（「## Contributing \n We welcome contributions!」だけで何もない場合など）。具体的なガイドを書くか、CONTRIBUTING.md にリンクして先に進みます。
• テンプレートそのものからコピーしたコメント（Best-README-Template にある、テンプレートの使い方を説明する HTML コメントは削除するものであり、残すものではありません）。
• 実際にはリンク先が存在しない参照形式のリンク定義、画像パス、バッジ URL。README の最初の画面にリンク切れがあると、残りの内容への信頼も損なわれます。

参考資料

references/templates.md には、ライブラリの README、CLI ツールの README、GitHub プロフィールの README の実用的なテンプレート一式に加え、standard-readme の必須セクション一覧と makeareadme.com の最小限のひな形および全セクションのチェックリストがまとめられています。ユーザーがガイダンスではなく、コピーして使えるものを求めている場合や、これらの形式のいずれかに取り組む場合は、下書きを始める前に読んでください。