README ライター は何をしますか?
README の仕事はただ一つ:訪問者を「これは何?」から最初のコマンドの実行まで1分以内に導き、さらにその先へ進む方法とプロジェクトへの貢献方法を示すことです。
使用するタイミング
- 新しいプロジェクトの README を作成する、または薄い・冗長な README を書き直すとき
- 公開前や 1.0 リリース前に README をレビューするとき
- ユーザーが「プロジェクトにアクセスはあるがスターやインストール、コントリビューターが増えない」と言ったとき
使用しないタイミング
- API リファレンスドキュメント(コードから生成し、README からリンクする)
- 長いチュートリアルやアーキテクチャドキュメント:
docs/に入れてリンクする
ワークフロー
-
書く前に事実を収集する。 マニフェスト(
pyproject.toml、package.json、composer.json、Cargo.toml...)、CLI の--helpやメインエントリポイント、既存のドキュメント、ライセンスを読む。実際のインストールコマンドと実際の例を見つける。フラグ、出力、ベンチマーク、機能を決して作り出さない。 -
コードからわからないことだけをユーザーに質問する: プロジェクトの対象者、解決する1つの問題、明らかな代替手段より優れている理由。ユーザーが利用できない場合は、コードから中立的なピッチを書き、レビュー用にマークする。
-
現在の README を lint する(存在する場合)。
scripts/はこのスキルからの相対パス:python3 scripts/readme_lint.py README.md python3 scripts/readme_lint.py README.md --json --strict -
structure.md の構造に従い、テンプレート から書き始める。順序が重要: タイトル+バッジ、ピッチ、(デモ画像)、クイックスタート、機能、使用法/例、設定、FAQ、ロードマップ、コントリビュート、ライセンス。
-
ライティングルールを適用する:
- ピッチ:一文、200文字未満、誇大広告なし。パターン:
「
<名前>は、<対象>のために<X>を行う<カテゴリ>であり、<主な差別化要因>。」 - 最初のコードブロックは 60 行目より上に。すべてのコマンドはコピペ可能で実際のもの。
- コマンドの後には役立つ出力を示す(
# => ...または別ブロック)。 - オプションや比較にはテーブル、機能にはリストを使用(利点を先に)。
- リンクする、貼り付けない:長いドキュメント、変更履歴、API リファレンスは別の場所に。
- すべての画像に代替テキストを設定する;メインフローは SVG または短い GIF を推奨。
- ピッチ:一文、200文字未満、誇大広告なし。パターン:
「
-
バッジ。 実際に存在し維持されているバッジのみを使用し、順序は次の通り:CI ステータス、最新バージョン(PyPI/npm/Packagist/リリース)、ダウンロード数(任意)、ライセンス。structure.md に例あり。
-
再 lint する エラーがなくなるまで。警告は解決するか、ユーザーに理由を説明する。
-
リンターがチェックできないリンクを確認する: 絶対 URL とアンカー。クリックテストするか、検証できなかったものを説明する。
出力
- 新規または更新された README.md(書き直しの場合は差分サマリーを表示)。
- 最終的な lint 結果。
- 検証できなかった事実と、ユーザーが埋める必要のあるプレースホルダーの短いリスト(デモ GIF、スクリーンショット、ベンチマーク数値)。
Lint ルール
| ルール | レベル | 意味 |
|---|---|---|
| title | エラー/警告 | 正確に1つの H1 |
| pitch | エラー/警告 | タイトルの下にある短い最初の段落 |
| badges | 警告 | バッジが見つからない |
| install | エラー/警告 | インストール(またはクイックスタート)セクション、コードブロック付き |
| quickstart | エラー/警告 | 使用法、クイックスタート、または例のセクション、コード付き |
| code | エラー | コードブロックがまったくない |
| scroll | 警告 | 最初のコードブロックが --max-scroll 行(デフォルト 60)より後にある |
| contributing, license | 警告 | セクションが欠けている |
| faq, toc | 情報 | 推奨 |
| alt-text | 警告 | 代替テキストのない画像 |
| broken-link | エラー | 存在しないファイルへの相対リンク、または空のリンク |
| broken-anchor | エラー | GitHub のスラッグルールに基づき、見出しや HTML の id/name と一致しない #anchor リンク(目次) |
| placeholder | 警告 | TODO、TBD、または lorem ipsum が残っている |
エラーがある場合は終了コード 1(--strict の場合は警告も)。