/brag-more
あなたはプロジェクトを作り上げました。今度はリポジトリも自慢させましょう。READMEはGitHubで誰もが最初に目にするものです。それを、5秒でプロジェクトを売り込み、見知らぬ人が1分で実行開始できるフロントページに変えましょう。
プロジェクトの種類を問わず、結果は、よく愛されているオープンソースプロジェクトのREADMEのように感じられるべきです。自信に満ち、スキャンしやすく、視覚的で、そして真実であること。ページ上に、その場所に値しないものは何も置かないでください。
使用方法: /brag-more [オプション]。オプション(フラグまたは平文):
| オプション | デフォルト値 |
|---|---|
--style clean|bold|minimal|showcase | プロジェクトから推論(スタイル参照) |
--preview | オフ: README.mdを直接上書き。有効の場合、brag-output/repo/にのみ書き出し、README.mdは変更しない |
--no-banner | バナー表示 |
--no-video | オフ: プロジェクトに自慢動画がない場合、最初に作成する(動画参照) |
--no-demo | 表示するものがある場合、デモはオン |
作業ファイルは brag-output/repo/ に配置されます(brag-output/が既に存在し、今回の実行によるものでない場合、brag-output-YYYY-MM-DD-HHmmss/repo/ のようにタイムスタンプが付与されます)。READMEが参照するアセットは、リポジトリ内の .github/readme/ に配置され、一緒に配布されます。
1. 調査
古いREADMEだけでなく、プロジェクト全体を読んでください:
- 既存のREADME、すべての行。ユーザーが書いたものです。真実で有用なもの(インストール手順、設定テーブル、クレジット、ライセンス注記、スポンサーリンク、謝辞)は保持し、スタイルを変更しても、捨てないでください。
- アイデンティティ: スタイルシートやテーマ設定から、正確なブランドカラーとフォント、ロゴまたはファビコン、既存のヒーロー画像やOG画像。
- プロジェクトの概要: パッケージマニフェスト(
package.json、pyproject.toml、Cargo.toml、go.mod、…)から、名前、説明、バージョン、ライセンス、バイナリとスクリプトを取得。実際の機能のためのエントリポイントとメインルートまたはコマンド。 - 実行方法: マニフェストスクリプト、
Makefile、justfile、Dockerfile、またはCIワークフローから、実際のインストールおよび起動コマンド。プロジェクトが固定するランタイムバージョンをメモ。 - バッジの手がかり:
LICENSE、.github/workflows/*、パッケージが公開されているかどうか(npm、PyPI、crates.io — マニフェストの名前とprivateフラグを確認)、gitリモート(git remote get-url origin)からowner/repoを取得。 - 既存の自慢出力:
brag-output*/brag.mp4とbrag.jpgが存在する場合、それらがマシン上の最良のデモ素材です。最新のものを使用してください。ない場合は、次のステップで作成します。
ビルド出力、ロックファイル、.git/、envファイルとシークレットファイル(.env、.env.*)、キーと認証情報、および.gitignoreがこれらの理由で除外するものはスキップしてください。
書き始める前に、次の質問に答えてください: それは何か(見知らぬ人が理解できる一文)?誰のためのものか?競合より優れている点は何か?視覚的なフックは何か — スクリーンショット、GIF、またはバナーで、誰かのスクロールを止めるものは?本当の機能は3〜5個?クローンから実行までの最短パスは?
READMEは公開されます。シークレット、トークン、内部ホスト名、実際の顧客名やユーザー名、メールアドレス、その他の個人データをREADMEやその画像に決して持ち込まないでください。スクリーンショットにそのようなデータが表示されている場合は、もっともらしい架空の代役と交換してください。
動画(計画の前、まだない場合)
READMEの最良のデモはプロジェクトのローンチ動画です。そのため、brag-moreはそれが欠けている場合に作成します。--no-demo または --no-video が設定されている場合、または brag-output*/brag.mp4 が既に存在する場合は、このステップをスキップしてください。
/bragスキルがインストールされている場合(スキルリストを確認)、このプロジェクトに対してSkillツールを通じて実行し、--toneやフォーマットの希望があれば渡します。ユーザーに「まだローンチ動画がないので、/bragで先に作成します」と一言伝えます。- そうでない場合は
<skill-dir>/video.md(ここにバンドルされている、brag-slimのリーンな動画ワークフロー)を読み、それに従います。必要なのはマシンに既にあるツールのみです。 - 完了すると、動画、ポスター、共有コピーが
brag-output/に配置されます。それらをデモとしてREADMEの作成を続行します。
動画の作成に失敗した場合、またはユーザーが待ちたくない場合は、動画なしで続行し、デモのフォールバックを使用します。
2. 計画
brag-output/repo/readme-plan.md を書きます: キャッチフレーズ、選択したスタイル、セクションの順序、作成するビジュアルとそれぞれが示す内容、正当化されるバッジ(とその根拠)、そして古いREADMEから保持するもの。
形状: テンプレートではなく、開始形状。空になったりパディングになるセクションは削除します。
- ヒーロー — アニメーションSVGヒーロー(ビルドを参照)、次に中央揃えで: キャッチフレーズ、短いバッジ行、リンクのナビゲーション行(デモ · インストール · ドキュメント · …)。
- デモ — 使用中の製品、ヒーローのすぐ下に、フレーム化: 自慢動画のループ、実際のUIのGIF、またはターミナル録画。1つのビジュアル、大きく。
- なぜ — 2〜4文: ユーザーにとって何をするのか、何が他と違うのかを、プロジェクト自身の言葉で。開発ツールの場合、段落よりも3〜5行のコードブロックが売りになります(
bun run index.tsx # TSとJSXをそのまま実行)。 - 機能紹介 — 3〜6個の実際の機能、それぞれに小さなビジュアル: 実際のUIの切り抜きスクリーンショット、コマンドごとのターミナルGIF、またはコードスニペットとその出力。視覚的なものは横並びのカードとして配置します(ビルド参照)。テキストのみの機能には、太字のリードインと1行を付けます。
- クイックスタート — コピー&ペースト可能で、順序通り、すべてのコマンドがプロジェクトに対して検証済み。前提条件を最初に。
- 使用方法 — 1つまたは2つの実際の例: コマンドとその出力、コードスニペット、または設定ブロック。
- 仕組み — オプション。アーキテクチャが興味深い部分である場合、短い段落またはMermaid図。
- 古いREADMEからのその他すべて — 設定、FAQ、ロードマップ、貢献、クレジット — 整理し、長い場合は
<details>に折りたたむ。 - フッター — ライセンス行、およびクロージングアートストリップ(ビルド参照)。
READMEの法則
- 真実であること。 すべての主張、数値、機能、バッジはプロジェクトに裏付けられていなければなりません。でっち上げのスター、ダウンロード数、ベンチマーク、推薦の言葉、「使用実績」ロゴは禁止です。バッジは、それが指すもの(公開されたパッケージ、実際のワークフロー、ライセンスファイル)が存在する場合にのみ表示されます。
- 実行可能であること。 QuickstartとUsageのすべてのコマンドは、書かれたとおりにプロジェクトに存在します。安全に実行できる場合(インストール、ビルド、
--help、テスト)、実行してください。ステップにシークレットや有料サービスが必要な場合は、隠すのではなく、その旨を明確に述べてください。 - 5秒テスト。 ツイートからリポジトリにたどり着いた人が、それが何であるかを理解し、動作しているのを見て、最初の画面をスクロールせずにインストールコマンドを見つけられること。
- 実際のものを表示すること。 デモはロゴアニメーションや抽象的なアートではなく、実際の製品の使用状況を示します。実際のUI、実際のCSS、実際のコピーを再利用してください。
- リポジトリが何であるかを明確にすること。 リポジトリが製品のウェブサイト、ランディングページ、またはデモである場合は、キャッチフレーズでその旨を述べてください。リポジトリが提供しないアプリをダウンロードしたり、パッケージをインストールしたりできると暗に示さないでください。
- 具体的であること。 この特定のプロジェクトのために書かれたように感じられなければなりません。「爆速」「シームレス」「次世代」「ワークフローを効率化」は、プロジェクトが測定可能にそれを証明しない限り禁止です。
- スキャン可能であること。 短い段落、何かを語る見出し、箇条書きは1つのアイデア。絵文字を見出しに使用するのは、プロジェクト自身の声がそれらを使用している場合のみ、そして控えめに(
showcaseスタイルは例外: セクション見出しごとに1つの絵文字、設計上)。 - 両方のテーマ対応。 GitHubの読者はライトモードとダークモードを使用します。すべての画像は
#ffffffと#0d1117の上で正しく表示される必要があります: 可視エッジのある透明PNG、またはテーマごとにprefers-color-schemeソースを持つ<picture>。 - カラム幅に合わせること。 READMEカラムはデスクトップで約830px、電話ではかなり狭くなります。バナーテキストは電話幅にスケーリングしても読みやすいこと。テーブルは少数のカラムにすること。モバイルで壊れる幅広の生のHTMLレイアウトは避けてください。
- すべてのリンクが解決すること。 相対リンクは存在するファイルを指し、アンカーは実際の見出しと一致します。
スタイル
| スタイル | 雰囲気 | 使用する場面 |
|---|---|---|
clean | 控えめな動きのアニメーションヒーロー、フレーム化されたデモ、整頓されたカード | ほとんどのプロジェクト; デフォルト |
bold | ブランドカラーのフルブリードヒーロー、より大きなアニメーションモーメント、パンチの効いたキャッチフレーズ、デモが前面中央 | 消費者向けアプリ、遊び心のあるプロジェクト、ローンチ |
minimal | 小さなアニメーションロゴと名前+キャッチフレーズ、シンプルなセクション | ライブラリ、CLI、インフラストラクチャ、真面目なツール |
showcase | 絵文字セクションで構成された密度の高い技術的なREADME(ハッカソン優勝や研究プロジェクトを想像してください): 上部に製品の実際のスクリーンショット、受賞やステータス行、次にトピックごとに1つの絵文字で始まるセクション | ハッカソン、研究、ML、データ、サイエンスプロジェクト; 披露する価値のある実際の深みがあるもの。ユーザーが「Find My Sharkみたいなもの」や詳細なドキュメントスタイルのREADMEを求めた場合に選択 |
showcase レシピ
オーナーのFind-My-Shark READMEをモデルにしています。うまく機能している部分を維持し、機能していない部分を修正します:
- 1つの絵文字と達成ライン を持つタイトル(「NASA Space Apps 2025、Galactic Impact Winner」)、プロジェクトが本当に獲得した場合のみ。古いREADMEから尋ねるか読み取ってください。決してでっち上げないでください。
- タイトルのすぐ下に実際のスクリーンショットまたはデモGIF、フレーム化(デモ、フレーム化を参照)。アニメーションヒーローは、何かを追加する場合のみ保持してください。ここでは実際の製品が主役です。
- 2〜3行のピッチと「なぜ重要か」の行、次にそれぞれ1つの絵文字で始まるセクション: 機能、地域/範囲または入力、データソース(テーブル)、仕組みまたは数学モデル、クイックスタート(インストール、基本的な使用法、APIの使用法)、プロジェクト構造(注釈付きツリー)、設定(実際の設定)、出力ファイル、コマンドラインオプション、背景、将来の拡張、テスト、ロギング、クロージングタグライン。
- プロジェクトに実際のコンテンツがあるセクションのみを含めてください。ハッカソン級の詳細さがポイントなので、具体的な内容(パラメータ、数式、閾値、データセット名、プロジェクトツリー)を保持してください。
- よくある間違いを修正: 実際のクローンURLを使用し(決して
your-usernameではない)、プロジェクトツリーコードブロックの古くなったエントリを実際に存在するものと交換し、6つ以上のセクションがある場合は目次またはクイックリンク行を追加し、長い参照セクション(CLIオプション、完全な設定、科学的背景)を<details>で囲み、実際のスタック(Pythonバージョン、ライセンス、主要ライブラリ)のバッジと、両方のテーマに対応した<picture>またはフレーム化されたスクリーンショットを追加し、配信時にリポジトリの説明とトピックを設定します。 - 絵文字付きアンカー: GitHubは見出しのスラッグから絵文字を削除しますが、ハイフンは保持するため、
## 🚀 Quick Startは#quick-startではなく#-quick-startになります。すべてのナビゲーションリンクとバッジリンクをその方法で書き、それぞれを見出しと照合してください。<details>のsummaryは見出しではなく、アンカーはありません。 - それでもすべてのREADMEの法則(真実、実行可能、両方のテーマ)とチェックステップに従ってください。
3. ビルド
GitHub上の最高のREADME(Excalidraw、Scalar、Supabase、Charm、Rich、Bun)は、いくつかの共通した手法を共有しています。これらをすべて使用してください。それが、このREADMEをスクロールを止めるものにするのです。
ヒーロー: アニメーションSVG
これが特徴です。静的なバナーはテンプレートのように読めます。動くヒーロー — プロジェクト自身の色、フォント、UIで — は、このプロジェクトのために作られたように読めます。GitHubは<img>タグ内のSVGを、そのCSS @keyframes を実行した状態でレンダリングするため、ヒーローはGIFのバンディングや重さなしにアニメーションできます。
.github/readme/hero.svg(viewBoxは約1600×800、width="100%"でレンダリング)をビルド:
- シーンは製品です。 プロジェクトの実際のヒーローまたはキースクリーンをSVG形状で再現: 背景画像、独自のフォントの見出し、そして仕事をしている実際のUI要素(スワイプするカード、タイピングするコマンド、描画するチャート、着地するトースト)。1つのアイデア、1つのループ。
- モーション: SVG内の
<style>ブロック内のCSS@keyframes、transformとopacityのみ、スケールまたは回転するものにはtransform-box: fill-box; transform-origin: centerを適用。6〜10秒のループで、開始フレームにシームレスに戻り、エントランスはずらし、すべてのテキスト行は読むのに十分な時間落ち着いていること。背景にはゆっくりとしたドリフトを追加(ループ全体で1.0→1.05のスケール)、フレームが決して静止しているように感じられないように。CSSのtransformは要素のSVGtransform属性を置き換えるため、外部の<g transform=…>で配置し、内部の要素をアニメーションさせます。 - モーション軽減:
@media (prefers-reduced-motion: no-preference)でキーフレームをラップし、軽減を選択した読者には完成した落ち着いたフレームが表示されるようにします。落ち着いたフレームはそれ自体で投稿可能で、製品を表示している必要があるため、ループの途中でしか表示されないもの(マッチオーバーレイ、トースト)はopacity="0"属性で非表示にして開始し、キーフレームによってのみ表示されるようにします。 - 自己完結型。
<img>を通じてロードされたSVGは何もフェッチできません: URLによるWebフォント、外部画像、スクリプトは不可。フォントはbase64@font-faceとして埋め込む(Google Fontsのlatinファイルはすでに約20 KBで、全体を埋め込めます。他のフォントはpyftsubset … --text="…" --flavor=woff2でサブセット化。これには最近のfontToolsが必要です)。またはテキストをパスに変換します。写真は、ヒーローに必要なサイズにリサイズしたbase64 JPEGとして埋め込みます。<foreignObject>は避けてください(Safariは<img>内でレンダリングしません)。ファイルサイズは約1.5 MB未満に保ちます。 - 両方のテーマ対応。 ヒーローがフルブリードで不透明であれば、両方のテーマで機能します。そうでない場合は
hero-dark.svgも作成し、<picture>または#gh-dark-mode-only/#gh-light-mode-onlyURLフラグメントで切り替えます。 - テキスト: プロジェクト名とキャッチフレーズ、大きく(ヒーローは電話では約40%に縮小)。それ以外は何もありません。
<p align="center">
<a href="<サイトまたはデモリンク>"><img src=".github/readme/hero.svg" alt="<プロジェクト> — <キャッチフレーズ>" width="100%"></a>
</p>
また、落ち着いたフレームを1280×640で .github/readme/social-preview.png(不透明)にキャプチャし、リポジトリのソーシャルカードとして使用します。モーション軽減を有効にして、ヘッドレスブラウザでSVGをレンダリングします。
プロジェクトにアニメーションさせる価値のある視覚的アイデンティティがない場合(UIのないライブラリなど)、代わりにアニメーションワードマークを作成します: 適切なフォントの名前、それが何をするかを示す1つのモーション(パイプを通る値、フォーマットされるテキスト、緑色に変わるテストなど)。
デモ、フレーム化
優先順位:
- 自慢動画。 調査で見つかったもの、または動画ステップで作成されたもの。
brag.mp4が存在する場合、その最も強い4〜8秒からループプレビューGIFまたはアニメーションWebPを作成します。
…(以下、続く)