readme-wizard

README ウィザード

リポジトリをスキャンし、実際のプロジェクトデータに基づいて洗練されたプロフェッショナルな README を作成または改善します。

ワークフロー

1. プロジェクトをスキャンする

scipts/scan_project.sh <project-directory> を実行して、構造化された JSON メタデータを収集します。

• プロジェクト名と説明
• ライセンスの種類
• Git リモート（オーナーとリポジトリ名）
• パッケージマネージャー（npm、yarn、pnpm、pip、cargo、go など）
• CI の設定（プロバイダーとワークフローファイル）
• ソーシャルリンク（YouTube、Discord、Twitter、LinkedIn、Bluesky、Twitch）
• ディレクトリ構造（最初の 2 階層）

参照スクリプトは、まずローカルファイルを確認し、次に GitHub API を使ってホームページの URL を調べ、そのホームページをクロールして追加のソーシャルリンクを取得します。最初のバージョンはローカルファイルのみを対象にし、必要に応じて後からこの補完機能を追加してもかまいません。

データが見つからない場合の処理： スキャンでは、検出できなかった項目は空文字列として返されます。メタデータを捏造してはいけません。フィールドが空の場合は、関連するセクションやバッジを省略してください。たとえば、CI ワークフローがなければビルドバッジを表示せず、ソーシャルリンクがなければソーシャルセクションを表示しません。

2. ベストプラクティスガイドを読む

作成する前に references/readme-best-practices.md を読んでください。このファイルでは、構成、文体、プロジェクトの種類に応じた調整、よくある落とし穴を説明しています。この内容は出力の品質を大きく左右します。各セクションの背景にある考え方を解説しているため、定型的ではなく、意図の伝わる README を作成できます。

3. README を作成する

基本構成として assets/readme-template.md を使用します。{{PLACEHOLDER}} マーカーを、スキャンで取得した実際のプロジェクトデータに置き換えてください。

プロジェクトツリーを表示する際は、リポジトリを閲覧する人にとって自然な順序にします。ファイルより先にディレクトリを並べ、グループごとにアルファベット順で並べ、ディレクトリには末尾に / を付けてください。

そのままコピーせず、調整してください。 テンプレートは出発点です。該当しないセクション（個人用メモのリポジトリに Contributing セクションを設けるなど）は削除し、プロジェクトに合った文体に調整してください。

• ライブラリ／フレームワーク：インストール、API、使用例を中心にします
• アプリケーション：セットアップ、設定、スクリーンショットを中心にします
• ドキュメント／学習用リポジトリ：構成とナビゲーションを中心にします
• 小規模なユーティリティ／スクリプト：簡潔にまとめます。概要、機能、使い方があれば十分です

4. バッジを追加する

assets/badges.json を読み、動的な値を示す {{PLACEHOLDER}} マーカーを含む、カテゴリ（ステータス、ソーシャル、その他）別のバッジ一覧を確認します。すべてのバッジに style=for-the-badge を使用してください。

最重要ルール： 実際に存在するものだけにバッジを付けてください。存在しない CI ワークフローや、推測した npm パッケージのバッジは、バッジがないよりも悪い結果になります。

5. 出力を検証する

生成した README を evals/evals.json のアサーションに照らして確認します。次の点を検証してください。

• プレースホルダーテキスト（{{PROJECT_NAME}}、TODO など）が残っていない
• すべてのバッジが、実際に存在するものを示す有効な shields.io URL を参照している
• セクションの分量がプロジェクトに見合っている（単純なスクリプトに 200 行の README は不要）
• ソーシャルバッジは、スキャンでソーシャルリンクが見つかった場合にのみ表示されている
• 文体が簡潔で直接的であり、宣伝文句に偏っていない

6. 必要に応じて図を追加する

プロジェクトに複数のコンポーネントがある場合や、明確なデータフロー（API、モノレポ、コンテンツパイプラインなど）がある場合にのみ、assets/diagrams.md を読んでください。単純なプロジェクトでは、完全に省略します。図は実際のプロジェクト構成に基づいて作成してください。ファイル内のテンプレートは適宜調整するための出発点であり、そのままコピーするものではありません。