write-readme

write-readme

集中力が続きにくい読者のために、README を作成します。これは何か、どんなときに使うのか、どう始めるのか、何を期待すべきでないのかを説明します。

ワークフロー

1. 背景を集めます。解決する課題、対象読者、現在の代替手段、最も際立った価値や根拠、対象外のことを確認します。
2. 一度だけ分類します。ライブラリ、CLI／ツール、エージェントツールのいずれかです。不明な場合は質問します。
3. 追加する前に削ります。重複した一覧、バッジのノイズ、マーケティング上の主張、コピーした --help の表を取り除きます。
4. 重要度の高い順に下書きします。端的な価値、インストール、一般的な使い方、制約、任意のリファレンスの順です。
5. 最も一般的な呼び出し方法やインポートパスを、冒頭から30行以内に記載します。
6. REFERENCE.md はセクションを選ぶときだけ使います。必須テンプレートとしては使いません。
7. 最終確認を行います。すべての行が、読者が抱きそうな疑問に答えるか、次の行動を変える内容になっている必要があります。

冒頭のルール

• 具体的な価値から始めます。指標、明確な機能、または際立った差別化要因を示します。
• 「ライブラリ／ツールです」のような書き出しは避け、まず読者が得られる成果を示します。
• 対象読者と対象外のことを早い段階で明記します。
• 主張には根拠または方法論の注記が必要です。
• 誠実な表現にします。README で裏付けられていない限り、「シームレス」「瞬時」「強力」「再説明不要」などの広告コピーのような言葉は避けます。
• 製品紹介資料のような口調より、一般ユーザーの視点を優先します。実際の日常的な使い方を示す一人称の記述は問題ありません。ただし、好みの押しつけ、誇張、冗談に変わるなら削除します。
• ツールが解決する人間らしい場面から始め、その後で仕組みを説明します。「ここで困っていたが、これが役立った」は、「このソリューションは〜を可能にする」より効果的です。

徹底的に削る

次の内容は削除するか、簡潔にします。

• 対応プラットフォームや連携先の一覧の繰り返し。コマンド構文やインストールに関わる箇所で一度だけ示します。
• --help、生成ドキュメント、パッケージのドキュメントですでに確認できる、すべてのフラグやリファレンスの表。
• 信頼性やインストールの判断に影響しないバッジ。
• 同じ内容を繰り返す「機能」「特徴」「理由」の個別セクション。
• 長い注意書き。制約は残しつつ、短く実用的な事実として書きます。

エージェントツール

コーディングエージェントからの呼び出しを想定した CLI では、次の点に注意します。

• README をツールの関数シグネチャとして扱います。
• 正確なコマンド形式、必須引数、重要なフラグ、エージェントが作業を確認するうえで役立つ場合は、成功時とエラー時の出力形式を示します。
• エージェントが誤用しないよう、「X 向けではありません」という注意事項を加えます。
• <details> を展開しなくても、主要なインターフェースをざっと確認できるようにします。

必須事項

• アーキテクチャより先に、インストール／クイックスタートを記載します。
• 制限事項には独立した見出しを付け、注意書きの中に埋め込まないでください。
• 幅広い対応を主張する場合は、対象のプラットフォーム、形式、言語、連携先を明記します。
• トラブルシューティングを README に含めるのは、よくある問題で、かつ対処可能な場合に限ります。
• <details> は、高度な設定、生データ、方法論、または代替のセットアップ方法にだけ使います。
• マーケティング的な形容詞は使わず、数値、例、明示した根拠を使います。
• 劇的なつなぎ方を標準の文体にしないでください。ダッシュ、矢印、「X だけでなく Y も」は、使う理由がある場合に限ります。

テンプレート、バッジのパターン、スクリーンショットのガイドライン、文体に関する注記、最終確認用のプロンプトについては、REFERENCE.md を参照してください。