readme

README

リポジトリの実際の動作に基づき、実際の読者に必要な README を作成してください。宣伝としての網羅性よりも、正確さと初回利用の成功を優先してください。

モードと読者の目的を選ぶ

• 監査 — 正確性、網羅性、使いやすさに関する問題を報告します。依頼があった場合にのみ編集します。
• 修正 — 問題のある特定のセクションを更新します。
• 作成 — README が存在しない場合、または明示的に書き直しを依頼された場合に README を作成します。

リポジトリの種類と、主な読者の目的を特定します。

• ライブラリまたは SDK の導入
• CLI のインストールと最初のコマンドの実行
• ホスト型アプリケーションのセットアップまたはコントリビューション
• サービスの運用とローカル開発
• モノレポの構成把握とパッケージの管理主体の確認
• 標準、データセット、研究、ドキュメントに関するプロジェクト
• 内部プロジェクトの概要把握

コードと信頼できるファイルを確認し、製品の目的、対象読者、パッケージマネージャー、コマンド、サポート対象バージョン、設定、サンプル、リポジトリのポリシー、ライセンスを明らかにします。リポジトリから判断できない意図がある場合にのみ質問してください。

正確性を最優先に監査する

README の重要な記述を、マニフェスト、ソースコード、CI、サンプル、設定、ライセンスファイルと照らし合わせて確認します。インストールの失敗、安全でない操作、誤った API の使用、セキュリティに関する誤解、法的な曖昧さにつながる問題を優先します。

問題ごとに、以下を報告してください。

[severity] [section or line]
Claim or omission:
Repository evidence:
Reader impact:
Recommended repair:
Verification:

数値スコアによって、リリースを妨げる問題が見えなくならないようにしてください。ユーザーが採点を依頼した場合は、読者の目的に適した観点で採点し、重み付けを説明してください。

情報への導線を設計する

固定のテンプレートではなく、読者のニーズに合わせてセクションを選びます。多くの公開ソフトウェアの README には、以下の一部が必要です。

1. プロジェクトの概要と簡潔な目的
2. 対象者と解決する課題
3. 前提条件とインストール方法
4. 期待される結果を含む、最小限の動作する使い方
5. 主な機能、制約、互換性
6. 設定と運用要件
7. 詳細なドキュメントへのリンク
8. 関連する場合は、開発、コントリビューション、サポート、セキュリティ、ライセンスに関する情報

内部サービスでは、管理主体、依存関係、ローカル環境のセットアップ、一般的な操作、運用手順書を重視する場合があります。モノレポでは、インストール方法より前にパッケージ一覧が必要な場合があります。研究またはデータのリポジトリでは、バッジや販促用のビジュアルよりも、手法、データの来歴、引用方法、再現性が必要な場合があります。

最初に成功するまでの手順を早い段階に示します。README の閲覧性が損なわれる場合は、参照情報を専用のドキュメントにまとめます。ただし、前提条件や重要な警告をリンクの先に隠してはいけません。

確認済みの動作に基づいて書く

冒頭を読めば、読者がスローガンに頼らず、プロジェクトの内容と用途を把握できるようにします。正確さに必要な補足まで削って、恣意的な文字数に合わせる必要はありません。

インストールコマンドは、リポジトリのパッケージマネージャー、サポート対象のランタイム、ワークスペースの構成、環境要件に合致させます。実際の API または製品を代表する、最も簡単に動作する使い方を、確認可能な結果とともに示します。

機能の一覧は、選定の役に立つ場合にのみ使用します。性能、人気、顧客の実績を捏造せず、機能と関連する成果を明記します。

バッジ、バナー、スクリーンショット、GIF を必須要素として追加してはいけません。

• 継続的に保守され、意味のあるエンドポイントのステータスバッジのみを追加します。
• UI、CLI の結果、アーキテクチャ、ワークフローを実質的に分かりやすくする場合は、ビジュアルを追加します。
• 既存のブランド素材とリポジトリの慣例を使用します。
• 監査スコアを上げるために、装飾的なメディアやノイズになるバッジの列を作成してはいけません。

リポジトリに実際に適用されているライセンスを説明し、そのファイルへのリンクを設定します。ライセンスが存在しない場合は、断定的な法的助言をせず、実務上どのような曖昧さがあるかを報告します。

コマンドと例を安全に扱う

コマンドを、実行済み、一部検証済み、文書化のみ、利用不可に分類します。可能かつ安全な場合は、インストールやクイックスタートの検証に、クリーンな一時環境を優先して使用します。ローカルで取得した秘密情報、個人用パス、環境変数の値は公開しないでください。

プロジェクトで実行が現実的であれば、例をコンパイル、型チェック、または実行します。例が実行可能ではなく説明用の場合は、その旨を明記し、現在の API と整合させてください。

出力要件

生成モードまたは修正モードでは、更新した README.md と、以下を含む簡潔なレポートを提出します。

• 主な対象読者と、読者が達成したい作業。
• 使用した信頼できる情報源。
• 実際に実行したコマンドと例。
• 追加、削除、または意図的に省略したセクション。
• 確認したリンク、アセット、バッジ、ライセンスの状況。
• 未検証の制約事項やセットアップ方法。

監査モードでは、優先度を付けた指摘事項と、最も重大な問題に対する修正案を提出します。スコアが最も低い、見た目だけのセクションのみを書き直してはいけません。

検証

1. 想定読者の新規参加者として README を先頭から順に読み、最初の利用手順を見つけられることを確認します。
2. プロジェクトの証拠に照らして、プロジェクト名、パッケージ名、バージョン、パス、環境変数、ポート、想定される出力を確認します。
3. 可能であれば、クリーンな環境でインストールと最小限の利用手順を実行します。実行していない項目には、その旨を明記します。
4. 利用可能な場合は、プロジェクトのコンパイラー、インタープリター、リンター、または doctest の手順を使ってコードブロックを検証します。
5. 利用可能なツールを使って、相対リンク、アンカー、参照ファイル、画像、バッジのエンドポイント、外部ドキュメントへのリンクを確認します。
6. 前提条件、破壊的な操作、マイグレーション、セキュリティ上重要な設定、既知の制約事項が、使用箇所で明示されていることを確認します。
7. コントリビューションとテストのコマンドが、CI およびリポジトリのスクリプトと一致していることを確認します。
8. ライセンスの記述がリポジトリのライセンスファイルと一致していることを確認するか、ファイルがないことを明確に報告します。
9. プレースホルダー、根拠のない主張、古いスクリーンショット、特定した読者の作業に役立たないセクションを削除します。
10. 「準備完了」という表現が未実施の検証を意味しないよう、使用した環境と実施した確認事項を報告します。