Project README
READMEはパラメータマニュアルでも広告でもありません。新しい読者がプロジェクトを信頼し、最初の結果を得るための最短経路です。
セクションを埋めるためだけに埋めてはいけません。読者は次の3つの質問に答えられるべきです：これは何か？自分に合っているか？最初の結果を得られ、リスクの範囲を理解できるか？
核となる原則
- すべての主張には証拠が必要です。リポジトリで検証できない主張やユーザーが確認できない主張は省略し、推測を曖昧な表現でごまかしてはいけません。
- クイックスタートは必須です。インストールから有用な結果に至る最短の現実的な経路を提供してください。そのコマンドが検証できない場合は、空白のままにしたり、でっち上げたりせずに質問してください。
- READMEがすでに存在する場合は、置き換えるか、一部を保持するか、そのまま拡張するかを確認してください。ユーザーが作成したコンテンツを推測したり上書きしたりしてはいけません。
- アイデンティティとエントリポイントを「アバブ・ザ・フォールド」に配置します。公開プロジェクトの場合は、プロジェクト名/ロゴ、1行の説明、実際のバッジ、ナビゲーションを使用し、その直後にクイックスタートを配置します。GIF/スクリーンショットは、テキスト以上の情報を伝える場合にのみ使用します。
- 主張するよりも示す：ターミナル出力、スクリーンショット、コード、検証された数値は形容詞よりも強力です。
- パラメータではなくタスクで整理します。「何をしたいか → どのコマンドか」を説明し、完全なオプションリストは
--helpに任せます。 - 読者の意思決定、信頼、行動に役立たない行はすべて削除します。
- プロジェクトがローカルファイル、データベース、認証情報、ネットワーク、モデル呼び出しに触れる場合は、何を読み取り、書き込み、デバイス外に送信するか、およびデフォルトの読み取り専用/確認/バックアップ/フェイルクローズの方針を説明してください。コードの証拠なしにセキュリティを約束してはいけません。
- READMEを玄関として保ち、詳細は
docs/やCONTRIBUTING.mdにリンクし、READMEをマニュアルにしないでください。 - プロジェクトに合わせること。CLI、MCP、ライブラリ、アプリ、研究リポジトリに1つのテンプレートを強制しないでください。
- 「業界をリードする」「本番環境対応」「極限のパフォーマンス」などの未検証の誇大表現を避けてください。
content-writingのガードレールを参照してください。
対象読者の選択
READMEの読者を分類して詳細度を設定します：
- Solo（個人用）（個人プロジェクト、内部ツール、個人スクリプト）：読者は主にあなた自身であり、未来の自分も含みます。必須：1行の説明、クイックスタート、既知の制限事項。バッジ、貢献ガイド、コミュニティチャンネル、スター履歴、ロードマップはオプションです。基本は、3ヶ月後でも実行できることです。
- Public（公開用）（オープンソース、配布ソフトウェア、チーム共有）：読者は見知らぬ人です。説明、価値、クイックスタート、使用方法、設定、ドキュメントインデックス、貢献、ライセンスを含めてください。実際に存在する場合にのみバッジやコミュニティ情報を追加します。
リポジトリが公開されている場合、パッケージマネージャーに公開されている場合、または外部ユーザーがいる場合はデフォルトで公開用にします。プライベートな個人プロジェクトや一度きりの作業の場合はデフォルトで個人用にします。混合の場合は公開用の詳細を使用します。
モードの選択
| モード | 使用するタイミング | 最初のステップ |
|---|---|---|
| create | READMEが存在しない、またはユーザーが明示的に書き換えを要求した場合 | リポジトリを調査し、事実を収集する。 |
| improve | READMEが存在し、改善が必要な場合 | 読み、既存コンテンツの扱い方を確認し、進める。 |
| audit | ユーザーが診断のみを要求した場合 | READMEの各主張をリポジトリに対して検証し、結果を報告する。 |
ゲート： READMEが存在する場合は、ユーザーの選択を待つ：(1) 完全に置き換える、(2) 指定された部分を保持して書き直す、(3) そのまま拡張する。「READMEを書くのを手伝って」はオプション1を意味しません。
アバブ・ザ・フォールドと開発者ツールスタイル（公開プロジェクト）
読者は1画面を見た後で継続するかを判断します。最初の画面にはプロジェクトが何をするかが示されるべきです。
CLI、MCP、ローカル開発ツールの場合は、控えめで検証可能な開発者向けドキュメントを優先します：
<div align="center">
任意のロゴ
# プロジェクト名
**1行の説明**
実際のバッジのみ
言語切り替え（他のREADMEが存在する場合のみ）
アンカーナビゲーション（ドキュメントが100行を超える場合）
</div>
---
機能概要：実際のコマンド/ツール、入力、出力、デフォルトのセキュリティポスチャ
3つのルール：
- 1行の説明： 覚えやすく、おおよそ1行に収める：何であり、誰のためであり、最も重要な事実上の差別化点。原則や背景は後回しにします。
- 機能概要： 実際のコマンド/ツール、入力、出力、読み取り/書き込みオブジェクト、デフォルトのセキュリティポスチャをリストします。「高速、安全、インテリジェント」のような一般的な主張は避けます。
- クイックスタートを次に： 1～3の最短ステップを優先します。最後のステップはインストールまたはサービスディスカバリを検証する必要があります。複雑な設定は後に回します。
ビジュアル素材はオプションです。情報を追加する場合にのみGIF/asciinema、スクリーンショット、実際のターミナル出力を選択します。デモアセットがない場合は、でっち上げずに、実際のコマンド、期待される出力、検証手順を提供します。
個人プロジェクトではロゴ、バッジ、ナビゲーションを省略しても構いませんが、1行の説明と目に見える出力は依然として有用です。
証拠の階層
各主張を書く前に、その証拠を分類します：
| レベル | ソース | 使用方法 |
|---|---|---|
| 1 | リポジトリ内： ソース、テスト、例、設定、CI、タグ、スクリーンショット | 直接記述します。 |
| 2 | ユーザーが確認： ポジショニング、差別化、指標、スクリーンショット、事例 | 直接記述します。 |
| 3 | 外部で検証可能： パッケージページ、リリース、公開ベンチマーク | リンク付きで記述します。 |
| 4 | ソースなし | 省略します。重要な場合は質問します。そうでなければ削除します。 |
インストールコマンド、CLIパラメータ、APIシグネチャ、設定キー、環境変数、パス、パフォーマンス数値、互換性の主張、ライセンス条項、コミュニティリンクを決してでっち上げてはいけません。
リポジトリスキャンと証拠ルールについては references/evidence.md を参照してください。
ワークフロー
- 対象読者とモードを分類： solo/public と create/improve/audit。READMEが存在する場合は、変更前に扱い方を尋ねます。
- リポジトリの証拠を収集： パッケージメタデータ、エントリポイント、構造、設定、ドキュメント、Git/CI、アセット、読み取り/書き込みパス、認証情報、ネットワーク、モデル呼び出し、エラーコードを調査します。この段階では事実を収集し、結論を導き出しません。
references/evidence.mdを参照してください。 - プロジェクトと読者を分類： CLI、MCP、ライブラリ、アプリ、研究プロジェクト、Agent Skill、モノレポ。これを使用してセクションを選択します。
references/structure.mdを参照してください。 - クイックスタートを検証： インストール後に有用な結果を生成する最初のコマンドを見つけて検証します。検証できない場合は質問し、このゲートを通過してはいけません。
- セクションを計画： プロジェクトタイプに合わせてセクションを選択し、各セクションの証拠を特定します。サポートされていないセクションは省略します。また、アバブ・ザ・フォールドのレイアウト、クイックスタートの検証、セキュリティ/データフロー、エラーコード、トラブルシューティングが必要かどうかを決定します。
- ドラフト： アイデンティティと機能 → クイックスタート → 機能 → インストール/設定 → タスクベースの使用方法 → 根拠/背景 → セキュリティ/プライバシー境界 → エラー/トラブルシューティング → 既知の制限事項 → 開発/詳細ドキュメント。読者が動作可能な経路を得た後に根拠を説明し、その前に説明してはいけません。
- 品質ゲートを実行：
references/checklist.mdの各項目、特に事実の正確性と実行可能な手順を確認します。 - 成果物を提供： デフォルトでは会話内でドラフトを提供し、明示的に要求された場合のみディスクに書き込みます。書き込み前にチェックリストを再実行します。
出力
簡潔に述べます：(1) 対象読者とモード、(2) プロジェクトタイプとターゲット読者、(3) セクション計画と各セクションの証拠ソース、(4) READMEドラフト、(5) 証拠がないためにユーザーの確認が必要な主張、(6) 既知の省略。推測を決して「検証済み」とラベル付けしてはいけません。曖昧な言葉で偽装するのではなく、サポートされていない主張を明示的にリストします。
レッドフラグ
- クイックスタートが欠落または空白、またはリポジトリのエントリポイントがないコマンドをでっち上げている。
- 既存のREADMEの扱い方を確認せずに上書きしている。
- 未確認のパフォーマンス、互換性、ユーザー数、スター数の主張。
- 存在しないCI、パッケージ、ライセンスを指すバッジ。
- 空の見出しや「TODO/近日公開」でテンプレートセクションを埋めている。
- リンクする代わりに完全なAPIマニュアルを埋め込んでいる。
- タスクベースのコマンドを示さずに長い
--helpテーブルを再現している。 - スローガンや原則だけで、実際のエントリポイントや検証可能な結果のない最初の画面。
- ローカルデータ、認証情報、ネットワーク、モデル呼び出しに触れるツールについてセキュリティ/データフロー情報を省略している。
- コード/テストの証拠なしに、読み取り専用動作、データ漏洩なし、フェイルクローズ動作、ゼロ設定を約束している。
- 症状、エラーコード、原因、対処法なしに「再起動」とだけ書かれたトラブルシューティング。
- 段落になっている1行の説明、または最初の実行可能な経路の前に現れる根拠。
- 「強力」「エレガント」「極限」「すぐに使える」などの形容詞が証拠に取って代わっている。
- 存在しない貢献ガイド、行動規範、コミュニティリンクを個人プロジェクトに強制している。
- 存在しないコンポーネントや呼び出し関係を含むアーキテクチャ図。
- ユーザーの許可なくファイルに書き込んでいる。
参考文献
必要なものだけを読んでください：
references/structure.md：読む流れ、プロジェクトタイプによるセクション選択、セクション作成ガイダンス。references/evidence.md：リポジトリスキャン、証拠レベル、でっち上げてはいけない主張。references/checklist.md：事実、ユーザビリティ、プレゼンテーション、言語に関する書き込み前の品質ゲート。