repository-readme-writer

リポジトリ README ライター

実装の変わりやすい詳細に過度に依存せず、人やエージェントがプロジェクトをすばやく理解できる README を作成または改善します。

判断ツリー

どの種類の README 作業ですか？

• リポジトリから新しい README を作成する 関連するリポジトリの根拠を調べます。必要に応じて references/repository-audit.md を参照し、templates/repository-readme.md を活用してください。

• 既存の README を改善する references/rewrite-patterns.md を読み、有用なセクションを残し、古くなった内容や具体的すぎる内容を削除してください。

• セットアップ手順だけを修正する references/quickstart-design.md を読み、クローンから有用なローカルのフィードバックを得るまでの、検証済みの最短経路をクイックスタートにしてください。

• まだ編集せずに README の品質をレビューする リポジトリの根拠に照らして、依頼された範囲をレビューしてください。プローブと templates/readme-review.md は、広範なレビューのための任意の補助資料であり、表現やリンクのレビューには必須ではありません。

• どの方法が該当するか分からない references/foundations.md から始め、その後、執筆前にリポジトリを調べてください。

クイックリファレンス

タスク	実施内容	参照先
新しい README の下書きを作成する	執筆前に、目的、パッケージマネージャー、コマンド、設定、チェック項目、デプロイの手がかりを調べる	references/repository-audit.md
既存の README を改善する	正確で重要度の高い内容を残し、壊れやすい一覧を削り、クイックスタートを追加または修正する	references/rewrite-patterns.md
クイックスタートを設計する	インストール、設定、実行、検証に必要なコマンドを最小限にする	references/quickstart-design.md
過剰なドキュメント化を避ける	初日の使い方を変える場合を除き、実装の詳細を記載しない	references/foundations.md
よくある失敗を見つける	バージョンの固定、パスの一覧、古いコマンド、エージェントにとって分かりにくい表現を確認する	references/gotchas.md
リポジトリの手がかりをすばやく得る	python3 scripts/repo_readme_probe.py <repo> を実行する	references/repository-audit.md

運用上の契約

1. 執筆前に調査してください。コマンド、パッケージマネージャー、ポート、デプロイ形態を推測する README は、README がない状態よりも悪いものです。
2. 読者が最初に役立つ操作を行えるように書いてください。アプリには実行可能なセットアップ手順が必要な場合があります。ライブラリには使い方、データセットにはアクセス方法とスキーマが必要です。また、アーカイブ済みのリポジトリでは、代わりにステータスや移行の案内が必要な場合があります。
3. 役割と境界を説明し、ナビゲーションに役立つ場合は、検証済みで安定したソースパスを使用してください。役に立たないパスを含め、ディレクトリを網羅的に説明するのは避けてください。
4. 有用な場合は、サポート対象のバージョン範囲を記載してください。正確なバージョンの固定には、マニフェスト、ロックファイル、バージョンマネージャーのファイル、CI を優先してください。正確な要件を文章で繰り返すことが大きな助けになる場合は、その要件を記載し、信頼できる情報源へのリンクを付けてください。
5. 実行可能な例を少数に絞ってください。README には、プロジェクト内のすべてのスクリプトではなく、基本的な手順と主要な検証コマンドを記載してください。
6. AI エージェントが安全に使える内容にしてください。将来のエージェントがそのまま従ってしまう可能性のある、壊れやすいルール、網羅的な一覧、古い前提で過度に制約しないでください。

README の標準的な構成

実行可能なアプリの場合、これは出発点であり、必須の 9 セクション構成ではありません。ユーザーが指定した形式に従い、このリポジトリに役立つセクションだけを含めてください。

1. タイトル
2. プロジェクトの概要（1 文）
3. クイックスタート
4. プロジェクトの構成またはアーキテクチャの境界
5. 設定
6. ローカル開発
7. 品質チェック
8. 判明している場合はデプロイまたはリリースに関する注意事項
9. 初日の作業でよくある問題に限ったトラブルシューティング

小規模なリポジトリでは、関連するセクションをまとめてください。大規模なリポジトリでは、ルート README を概要レベルにとどめ、内容を複製するのではなく、専用ドキュメントへのリンクを記載してください。

セクションの基準

概要

プロジェクトが何で、何のためのものかを 1 文または 2 文で説明してください。内部のツールが製品そのものである場合を除き、内部ツールの説明から始めないでください。

クイックスタート

最初の利用に実行可能な手順が含まれる場合は、クイックスタートを記載します。根拠で裏付けられたコマンドを使い、必要最小限の設定だけで、目に見える検証ポイントまで導きます。ライブラリの場合はインポート例を、データの場合はアクセス方法やスキーマの案内を示すほうが読者の役に立つのであれば、そちらを使用します。静的なリポジトリやアーカイブ済みのリポジトリに対して、コマンドやビルドシステムをでっち上げないでください。

プロジェクトの構成

境界と責務を説明します。「CMS がコンテンツを管理し、ウェブサイトはサーバーサイドの API ルートを通じてコンテンツを読み取ります」のような説明には、読者が該当コンポーネントを見つけやすくなる安定したソースリンクを含めることもできます。

設定

ローカルでの利用やデプロイに必要な場合に限り、必須の環境変数や設定グループを記載します。すべての変数を列挙するのは避けてください。

品質

まず、共通の品質チェックをひとつ記載します。一般的なワークフローに役立つ場合に限り、対象を絞ったコマンドを追加します。

デプロイ

デプロイモデルと必要なサービスを記載します。リポジトリが明確に依存している場合を除き、プロバイダー固有の細部は避けてください。

テンプレート

• templates/repository-readme.md アプリケーション向けの任意のひな型です。不要なセクションは省略、並べ替え、または置き換えてください。

• templates/readme-review.md 任意のレビュー用アウトラインです。指摘事項は依頼された範囲内に収めてください。

ガイダンスが不十分な場合

ガイダンスが古い、不完全、またはリポジトリと矛盾する場合は、まずマニフェスト、ソース、テスト、保守されているドキュメントを確認します。未解決の動作についてのみ、最新の公式ツールドキュメントを参照してください。ユーザーの権限内で検証済みのコマンドを使用し、確認したチェックと実行したチェックを区別して、不足事項を明示します。情報源と例または再現可能なチェックを添えて、標準スキルの修正を提案してください。インストール済みのコピーを黙って変更したり、日常的な表現の修正のためにウェブを閲覧したりしないでください。

注意点

1. パスの一覧は初日には役立つように見えますが、最初のリファクタリングの後には古くなります。
2. バージョンを明記した説明は、マニフェスト、ロックファイル、バージョン管理ツールのファイル、CI よりも早く古くなります。
3. コマンドを大量に並べると、新しいコントリビューターが本当に必要とするコマンドが埋もれてしまいます。
4. 人間だけを対象に書かれた README は、機械で使いやすいコマンドが欠けることがあります。エージェントだけを対象に書かれた README は、記述が細かすぎて壊れやすくなることがあります。
5. クイックスタートのコマンドを検証していない場合は、不確実性を明示するか、権威ある情報として提示する前にさらに確認してください。

読み方ガイド

必要な情報	参照先
README の基本方針とセクションのルール	references/foundations.md
リポジトリの調査手順と証拠の評価基準	references/repository-audit.md
クイックスタートの構成、コマンドの選び方、検証	references/quickstart-design.md
既存の README を書き換える方法	references/rewrite-patterns.md
失敗のパターンと復旧方法	references/gotchas.md