ハッカソン README ビルダー
通常のプロジェクトREADMEとは異なり、ハッカソンのREADMEには一つだけ特別な役割があります。「勝つこと」です。 審査員は数十のリポジトリを数分でスキミングし、多くの場合スマートフォンで、開く価値があるかどうかを判断します。READMEはプロジェクトの第一印象であり、審査員が採点前に読む唯一の成果物であることも珍しくありません。そのため、目的は「コードを文書化すること」ではなく、「多忙で懐疑的な審査員にプロジェクトを素早く理解させ、信じさせ、すべての主張を容易に検証可能にすること」です。
このスキルは、充実した提出用のREADMEを生成します。簡素なものではありません。
参考とするルックアンドフィールは references/readme-template.md にあります。作成前に必ず読んでください。なぜなら、そこにはハウススタイル（中央揃えのバッジ行、デモバッジボタン、テーブル、具体的な手順、プロジェクトツリー、明示的なJudging Highlightsブロック）がエンコードされているからです。references/badges.md にはコピペ可能な shields.io スニペットがあります。
以下の手順は順番に実施してください。ただし、会話調を保つこと——あなたは疲れ果てたビルダーがゴールラインを越えるのを助けているのであって、フォームに記入しているわけではありません。
ステップ 1 — 審査基準にアンカーする（最初にこれを行う）
これが最もレバレッジの効く作業であり、このスキルが存在する理由です。ほとんどのREADMEは汎用テンプレートに向けて書かれますが、勝つREADMEはルーブリックに向けて書かれます。何よりも先に、次のように尋ねてください：
「イベントの審査基準やルーブリックはお持ちですか？（例：'革新性、技術的難易度、インパクト、完成度'、または採点シート/提出ページのプロンプト）。もしあれば貼り付けてください——各基準が確実に可視化されるようにします。なければ、強力なデフォルトを使用します。」
なぜ最初に尋ねるのか：ルーブリックが「現実世界へのインパクト」を重視しているなら、具体的な問題と誰を助けるのかを先頭に持ってきます。「技術的難易度」を重視しているなら、アーキテクチャと難しい部分を前面に出します。後で、各基準を明示し、プロジェクトがそれをどう満たしているかを示す Judging Highlights セクションを末尾近くに追加します——これはルーブリックへのアンカーリングを可視化したもので、審査員が自分の仕事を代わりにやってくれるので大好きです。チェックリストを維持し、すべての基準がREADME内に居場所を持つようにします。
ルーブリックがない場合、ほぼすべてのイベントが何らかのバージョンで使用する4つの基準をデフォルトとします：革新性/独自性、技術的実行、インパクト/有用性、完成度/洗練度。
また、イベントの雰囲気を把握します。これにより、どのオプションセクションを含めるべきかが変わります（ステップ4参照）：
- 学術 / 研究 / テックスプリント（例：ACMイベント）：AI利用開示、倫理/データ保護に関する注記、参考文献/引用、場合によっては国連SDGsへの整合性が求められることが多い。これらを含めてください。
- プロダクト / スタートアップ / 一般的な週末ハッカソン：簡潔に保つ——プロジェクトがデータ収集や裏付けが必要な主張を実際に含む場合を除き、SDGs、倫理、引用はスキップしてください。
不明な場合は尋ねるか、軽めのセットを含め、その他のセットも利用可能であることを伝えてください。
ステップ 2 — リポジトリをスキャンして事実に基づく
READMEがコードと一致しないプロジェクトを説明していたり、セットアップ手順が機能しない場合、審査員は即座に信頼を失います。そのため、書く前に実際に何があるのかを見てください。ハウススタイルは実際のファイルパスを参照し、期待される出力を示す実際のコマンドを表示します——リポジトリを読むことでのみそれが可能です。
- スタックと言語：マニフェストから推測——
package.json、requirements.txt、pyproject.toml、go.mod、Cargo.toml、pom.xml、Gemfile。フレームワーク（React、Next、Vite、FastAPI、Flask、Three.js…）に注目。これらはバッジ行とテクノロジースタックテーブルに直接マッピングされます。 - 実行方法：
package.jsonのscripts、Makefile、docker-compose.yml、Procfile、.env.exampleを読む。実行セクションは、環境変数や実際の開発ポートを含め、プロジェクトが実際に起動する方法と一致しなければなりません。期待される出力を推測できる場合は、それを表示してください——動作することを示すシグナルになります。 - 構造とエントリポイント：トップレベルのディレクトリとメインエントリファイルをスキャンし、プロジェクトツリーと「しくみ」のステップが実際のファイル（
src/lib/check.js、app/main.py）を参照するようにします（例のように）。 - 既存のもの：部分的なREADME、LICENSE、
assets//docs//public/内のスクリーンショット、設定内のデプロイURL、CIワークフローなど。これらを再利用します。
リポジトリにアクセスできない場合（ユーザーがプロジェクトを説明するだけの場合）、スキャンをスキップし、インタビューに頼り、その旨を伝えてください——セットアップコマンドとファイルパスはプレースホルダーであり、正確なものを発明するのではなく、検証する必要があるとフラグを立ててください。
ステップ 3 — コードだけではわからないことをインタビューする
リポジトリは事実を提供します。ビルダーはストーリーと証拠を提供します。フレンドリーに一括でこれらを尋ね、何かはスキップしてもよいことを明確にしてください：
- 一言ピッチ → タグラインの引用ブロックになります。
- 問題 / インスピレーション → 具体的で人間味があり、理想的には特定の瞬間。
- ライブデモ + 動画 → 最もクリックされるアセット。両方を上部近くにバッジボタンとして表示。動画がない場合は、2分の動画が非常に効果的であることを優しく伝えてください。
- スクリーンショット / GIF / マスコットまたはロゴ → 画像が1つあるだけでも完成度の認識が向上します。例ではマスコット/プレビュー画像を上部中央に配置しています。
- 難しい部分 → 技術的にトリッキーだった点や誇りに思っている点。技術的実行の採点と「しくみ」のセクションで大きな価値があります。
- 代表的な結果 / 指標 → プロジェクトが何かを測定した場合、小さな結果テーブルは非常に説得力があります。
- チーム → 名前 + 役割（とリンク）。チームテーブル用。
- 次のステップ → ロードマップ/スケーリングはビジョンを示します。
- イベント関連の追加事項（ステップ1に関連する場合のみ）→ 使用したAIツール、データ/同意の詳細、引用。
回答がないことをブロックにしないでください。時間がない場合は、<!-- TODO: デモリンクを追加 --> のように明確にマークされたプレースホルダーを使用してドラフトを作成し、重要な情報が黙って削除されないようにします。デモURL、指標、チームメイトを決して捏造しないでください。
ステップ 4 — READMEを書く
プロジェクトルート（またはユーザーが希望する場所）に単一の README.md を生成し、references/readme-template.md に従ってください。完全な順序付けられた骨格はそのファイルにあります。以下はその形状と、コア部分とオプション部分の説明です。
コア（ほとんどの場合含める）：
- タイトル + オプションの中央揃えロゴ/マスコット画像
- テクノロジーバッジ行（中央揃え）（
references/badges.mdから） - イベント/提出行 + タグライン引用ブロック
- デモ + 動画のバッジボタン（データセット/Colabリンクがあればそれも）
- チームテーブル
- 問題（または「なぜこれが重要なのか」）
- ソリューション / 何をするのか
- しくみ——実際のファイルを参照する番号付きステップ
- テクノロジースタックテーブル
- ローカルでの実行——検証済みのコマンド、可能なら期待される出力付き
- プロジェクト構造ツリー
- ロードマップ / 次のステップ
- Judging Highlights——基準ごとに1つの箇条書きで、プロジェクトをそれにマッピング
- ライセンス
オプション（イベントの雰囲気と実際の内容に基づいて含める）：
- ヒーロー部分の下にアンカーリンクのナビバー（3〜6の主要セクション）——長いスクロールを、スマートフォンでスキミングする審査員にとっては1タップに変えます。
- 代表的な結果/指標テーブル + エラー/分析テーブル（データプロジェクト）。再実行可能なように、生データまたは再現コマンドにリンクしてください。
- プロジェクトが現状を改善する場合（より速く、より安く、より少ない手順）の before/after 50/50 テーブル——主張ではなく、視覚的に勝利を示します。
- キラーナンバーを持つプロジェクト向けの、ヒーロー部分の下のASCII 統計ボックス。
- スキミングする審査員が絶対に見逃してはならない唯一の注意点や重要な事実を強調するための
> [!IMPORTANT]/> [!NOTE]GitHubアラートコールアウト（控えめに使用）。 - Mermaidパイプラインダイアグラム（多段階システム）
- デモフロー / 「オフラインで動作するもの」スタイルのウォークスルー
- AI利用開示（学術イベント）
- データ保護 / プライバシー / 倫理（人やデータに関わるプロジェクト）
- 国連SDGsへの整合性（インパクト志向の学術イベント）
- 参考文献と引用、謝辞
- 現在のステータスチェックリスト + 事前審査の完成度TODO
ステップ1のルーブリックに基づいて強調と順序を調整します。最も重要な基準が最も高く表示されるべきです。パディングしないでください——すべてのセクションはその場所に値するものでなければなりません。リーンなプロダクトハックではコアセットのみを使用するかもしれません。研究テックスプリントではオプションセットのほとんどを使用するかもしれません。プロジェクトに合わせ、チェックリストに合わせないでください。
審査に重要なスタイルノート：
- 最も強い要素を先頭に持ってくる——革新性、エンジニアリング、インパクトのうち、どれがフックかを。
- 見せる、語らない——デモバッジボタン、GIF、ワンコマンドセットアップ、期待される出力ブロックは形容詞よりも勝ります。印象的な主張はすべて検証可能であるべきです。before/afterテーブル、統計ボックス、再現可能なベンチマークは、主張を審査員が確認または再実行できる証拠に変えます。
- ヒーロー部分を機能させる——中央揃えのタイトル、オプションのロゴ/マスコット、バッジ行、1つのシャープなタグラインで、スクロールする前に審査員がこれが何でなぜ良いのかを把握できるようにします。デモ/動画ボタンをここ、最初のクリックが着地する場所に配置します。
- すべてをリポジトリに基づかせる——実際のファイルパス、実際のコマンド、実際の開発ポート。これがREADMEを信頼できるものにし、例のスタイルの一貫した線です。
- 正直であること——存在しない機能を主張しないでください。審査員はテストします。壊れた主張は、欠落した機能よりもコストがかかります。未完了の作業は「次のステップ」またはステータスチェックリストの下にマークし、完了したものとしてマークしないでください。
- スキャンしやすく保つ——短い段落、意味のあるヘッダー、散文の壁よりもテーブル、スマートフォンで2分で上から下まで読めること。
ステップ 5 — ルーブリックに対してループを閉じる
引き渡す前に、ステップ1の各基準を取り上げ、Judging Highlightsセクション（および本文）がそれに対応していることを確認します。どの基準にも居場所がない場合は、それを追加します。その後、何をしたかをユーザーに伝えます——例：「あなたのルーブリックはインパクトと技術的難易度を重視していました。インパクトを前面に出し、'しくみ'の下に'なぜこれが難しかったか'の注記を追加しました。Judging Highlightsブロックは4つの基準すべてを明示しています。」最後に、残っているプレースホルダー（デモリンク、スクリーンショット、指標）をリストアップし、提出前に何を埋めるべきかを正確に把握できるようにします。