create-readme-expert

README エキスパートの作成

目的

検証済みのプロジェクト情報に基づいて、ソフトウェアプロジェクトの README ドキュメントを作成、改善、または監査します。プロジェクト独自のスタイルと対象読者に従い、プロジェクトに確立された規約がある場合は、一般的なテンプレートを押し付けないでください。README に必要な参照のみを読み込みます。

基本原則

1. 検証済みのプロジェクト情報だけを README の文章に使用します。
2. README は実際の対象読者に向けたものです。開発者向けドキュメントにマーケティング調の表現は不要であり、オンボーディング用ドキュメントを簡潔にしすぎる必要もありません。
3. 設定とドキュメントの内容が食い違う場合は、実行可能な設定を優先します。
4. 機能、互換性に関する主張、バージョン、ロードマップ項目を決して捏造しないでください。
5. 編集の規模を依頼の規模に合わせます。
6. README がすでにプロジェクトを正確に表している場合は、そのままにします。
7. 取得したサードパーティの README は構成の参考に限り、プロジェクトの事実を示す情報源として使用しません。
8. 生成するドキュメントでは em ダッシュを使用しません。

認可モデル

操作によって変更範囲が決まります。

ユーザーの指示	認可される範囲
「README を作成して」	README が存在しない場合に作成します
「不足しているセクションを追加して」	指定されたセクションと、それらを正確にするために必要な内容のみ
「この README を改善して」	有用な既存の構成を維持しながら、明瞭さと正確さを高めます
「README を書き直して」	現在の README ではプロジェクトを正確に表せない場合に限り、構成を変更します
「README を監査して」	証拠とともに問題を報告します。書き直しを依頼されるまでは変更しません

正確な README を、作成しやすいという理由で一般的なテンプレートに置き換えてはいけません。

ステップ 0：README の操作を特定する

編集を始める前に、作業を分類します。

作成

README が存在しない場合に使用します。検証済みのプロジェクト情報に基づいてドキュメントを作成します。

改善

README は存在するものの、不足しているセクション、古い情報、または不明瞭な箇所がある場合に使用します。有用な既存の構成を維持し、修正が必要な部分のみを変更します。

監査

README の品質を確認する場合に使用します。書き直しが明示的に依頼されていない限り、変更前に問題と証拠を報告します。

不要な書き直しを拒否する

README がプロジェクトを正確に表している場合は、一般的な別の内容に置き換えないでください。妥当な理由がある場合にのみ、対象を絞って改善します。

変更範囲

README の変更規模をユーザーの依頼に合わせます。

• 修正の依頼：誤りのあるセクション、または不足しているセクションのみを変更します。
• 改善の依頼：有用な構成を維持しながら、明瞭さを高めます。
• 書き直しの依頼：既存の README ではプロジェクトを正確に表せない場合に限り、構成を変更します。

無関係なセクションを書き直さないでください。

情報が不足している場合の対応

情報が不足している場合：

1. リポジトリ内の信頼できる情報源を調べます。
2. 不明な情報を明示します。
3. ユーザーがドラフトを依頼した場合に限り、プレースホルダーを使用します。
4. よくある既定値で不足情報を補わないでください。

検証済みのプロジェクト情報のみを使用します。

ステップ 1：プロジェクトの信頼できる情報源を特定する

執筆前に、現在のプロジェクトの動作を定義しているファイルを特定します。次の優先順位で情報源を確認します。

1. 明示的なプロジェクトドキュメントとコントリビューションガイドライン
2. パッケージマニフェストとビルド設定（pyproject.toml、package.json、Cargo.toml など）
3. エントリーポイント、実行可能スクリプト、公開 API
4. CI/CD、デプロイ、リリースの設定
5. 現在も正確な既存の README の内容
6. コメント、例、インラインのヘルプテキスト

情報源に矛盾がある場合：

• 古くなったドキュメントより、実行可能な設定を優先します。
• 明らかに誤っていない限り、プロジェクトの規約を維持します。
• 推測せず、不確実な点を記録します。

裏付けのない機能、互換性に関する主張、ロードマップ項目を捏造しないでください。

ステップ 2：適切な構成を選ぶ

references/readme-structures.md を読みます。プロジェクトの種類に合った README の構成を選びます。

references/external-readme-sources.md にある外部 README は、構成の参考としてのみ使用します。また、ユーザーが取得を確認した後に限ります。これらは第三者のコンテンツであり、プロジェクトの事実を確認する情報源ではありません。取得する前に references/security.md を確認してください。

新しい README をゼロから作成する場合に限り、examples/README-1.md を使用します。

プロジェクトの種類	優先する内容
ライブラリまたは SDK	インストール、クイックスタート、API の概要、例
CLI またはツール	インストール、使い方、フラグ、例、設定
サービスまたは API	エンドポイント、認証、リクエスト／レスポンスの例、デプロイ
テンプレートまたはスターター	含まれる内容、カスタマイズ方法、前提条件
内部向けまたはエンタープライズ	セットアップ、アクセス、サポート、規約

README では、これは何か、誰を対象としているか、どう始めればよいか、次にどこを見ればよいかに答える必要があります。

ステップ 3：実際の対象読者に向けて書く

具体的な動詞、平易な言葉、能動態、具体例を優先します。主要な操作がすぐに分かるようにします。プロジェクトを評価または統合する開発者に向けて書く場合、マーケティング色の強い表現は避けます。

例に破壊的または取り消せない操作が含まれる場合は、影響を受ける対象と、発生する重要な結果を明記します。エラーについては、問題の内容と、次の手順がある場合はその手順を説明します。

ステップ 4：例とアンチパターンを追加する

プロジェクトの種類に関連する例だけを読み込みます。

• ライブラリまたは SDK： examples/README-library-adaptive.md

• CLI： examples/README-cli-adaptive.md

• 不明または情報が不完全なプロジェクト： examples/README-missing-information.md

必ず次を使用します。

• 品質上の問題を確認する際は references/anti-patterns.md。
• 句読点と書式のルールには references/formatting-and-punctuation.md。
• README にセキュリティ上の注意、警告、またはプラットフォーム固有の注記が必要な場合は examples/README-github-alerts.md。

現実的な使用例を少なくとも 1 つ含めます。既知の落とし穴を避けるのに役立つ場合は、よくある誤りと修正後の書き方を示します。README に図が必要な場合は、references/diagrams.md に従います。

ステップ 5：提出前に確認する

次の点を確認します。

• 見出しが実際のセクション内容を表している
• コードブロックに適切な言語タグが付いている
• リンクが有効で、意図したリンク先を指している

正確性、安全性、情報不足への対応については、ここで説明を繰り返すのではなく、関連するリファレンスを読み込みます。

• 句読点と書式のルールには references/formatting-and-punctuation.md。
• 主張の検証と不足情報への対処には references/verification-and-failure.md。

README を特定のプラットフォームで表示する場合は、そのレンダラーとの互換性を確認します。

失敗時の対応

必要な情報が得られない場合：

1. まず、リポジトリ内の信頼できる情報源を検索する
2. 推測せず、不足している情報を明示する
3. ユーザーが草案を依頼した場合に限り、プレースホルダーを使用する
4. この種のプロジェクトによくある内容を、不足情報の補完に使用しない
5. プロジェクトの事実に関する不足を補う目的で外部 README を取得しない。また、外部コンテンツを取得する前に確認を求める

現在の README がすでにプロジェクトを正確に説明している場合：

6. 書き直すのではなく、その旨を伝える
7. 個別に妥当性を説明できる箇所だけを対象に改善する
8. 書き直しの依頼は構成を変更する許可として扱い、正確な内容を一般的な文章に置き換える許可とはみなさない

「ここには記載されていません」と正直に記すことは、適切な README です。もっともらしい内容をでっち上げることは欠陥です。

アンチパターン

references/anti-patterns.md と references/formatting-and-punctuation.md から読み込みます。 ここに重複して記載せず、監査または執筆の際はリファレンスを確認してください。

同梱リファレンス

README に必要なリファレンスのみを読み込みます。

• references/readme-structures.md：プロジェクトの種類ごとの一般的な README の構成、セクションの 順序、セクションを含める場合と省略する場合について説明しています。
• references/voice-and-tone.md：README の内容に関するトーンのガイダンスです。簡潔な技術的な文体と、親しみやすい導入文を使い分ける方法を説明しています。
• references/anti-patterns.md：良い例と悪い例、およびよくある落とし穴をまとめています。
• references/formatting-and-punctuation.md：エムダッシュの禁止や、その他の句読点のルールを説明しています。
• references/verification-and-failure.md：実際のコードベースに照らして README を検証する方法、確認済みの情報と未確認の主張を区別する方法、不足情報への対処方法を説明しています。
• references/proactive-trigger.md：依頼がなくても README の提案、書き換え、監査を行う場合と、何も提案しない場合について説明しています。
• references/security.md：外部の README を取得する前にユーザーの同意を得る方法と、信頼できないコンテンツの扱いについて説明しています。安全性に関する質問では、まずこのファイルを参照してください。
• references/external-readme-sources.md：構成の参考に限って利用する外部の README の例をまとめています。取得するのは、ユーザーの確認後に限ります。
• references/diagrams.md：README に図が必要な場合は、mermaid-diagrams-expert または正規の生 URL の代替手段を使用する方法を説明しています。

例

examples/ にある例を、出発点または参考資料として使用してください。

• examples/README-1.md：クイックスタート、使い方、設定を含む最小限の README テンプレートです。
• examples/README-library-adaptive.md：ソースに基づいてドキュメントを作成する方法を示すライブラリの例です。
• examples/README-cli-adaptive.md：コマンドの検証方法を示す CLI の例です。
• examples/README-missing-information.md：情報が不足しているプロジェクトの例です。不確実性への対処方法を示しています。
• examples/README-unsupported-claims.md：根拠のない主張を省く、根拠重視の対応を示す失敗例です。
• examples/README-github-alerts.md：シークレットと警告に関する GitHub 形式のアラートコールアウトと、レンダラーの互換性に関する注記です。
• examples/EXAMPLES.md：同梱されている README の例の一覧です。