READMEの書き方｜最低限の4つとスクショ・GIFの貼り方

リポジトリを作ったときに自動生成された README が、「# repo-name」の1行だけのまま残ってる。あるいはどこかのテンプレを貼って「## Getting Started」が英語のまま放置されてる。

GitHubに個人開発のリポジトリを上げてる学生なら、心当たりがあると思う。

何を書けばいいか分からないから後回しにする。気持ちは分かるけど、学生の個人リポジトリの README は最低限4つ書けばいい。

概要、使用技術、動かし方、環境変数の案内。これだけ。凝ったバッジも目次も貢献ガイドも要らない。

目次 / INDEX

結論: 学生の個人リポジトリはこの4つでいい

先に全部出す。

1. 何をするアプリ/ツールか(1〜2文の概要)
2. 使用技術(言語・フレームワーク・主要ライブラリ)
3. 動かし方(クローンから起動までのコマンド手順)
4. .env.example の案内(環境変数が要るアプリなら)

README は GitHub でリポジトリを開いたとき、ファイル一覧の下に自動で大きく表示されるファイルだ。README.md という名前でリポジトリ直下に置くだけで表示される。設定は何も要らない。

つまり、リポジトリの「顔」の場所がすでに用意されてるのに空けておくのはもったいない。

書く順番もこの1から4のままでいい。読む人は「これは何?」から「何で作った?」、そして「どう動かす?」の順に知りたくなるはずだから。

なぜREADMEが要るのか。未来の自分が忘れるから

README は「他人が最初に読む説明書」だと言われる。それは正しいんだけど、学生の個人リポジトリで本当に効いてくるのはもう一つの役割で、「未来の自分へのメモ」の方だと思う。

半年後の自分は、他人と同じくらい中身を忘れてる。どのコマンドで起動するんだっけ、環境変数って何が要るんだっけ、そもそもこれ何のリポジトリだっけ。全部忘れる。

あと、就活やポートフォリオで GitHub のアカウントを見られることがある。そのとき README が空だと、リポジトリ名だけで中身を推測してもらうことになる。「todo-app」だけ見せられても何も伝わらない。

逆に、概要1〜2文と動かし方が整理されてるだけで印象は変わるはずだ。コードの中身を読み込んでもらえる保証はないけど、README は確実に開かれる場所だから。

4要素の書き方

概要: リポジトリ名で伝わると思わない

最初に「何をするアプリ/ツールか」を1〜2文で書く。リポジトリ名だけでは何のプロジェクトか分からない。

「大学の時間割を登録すると、次の授業の教室を通知するアプリ」みたいに、誰が何のために使うものかが1文で伝わればいい。ここで機能を全部列挙しなくていい。

使用技術: 読む人が「自分の環境で動くか」を判断する材料

言語、フレームワーク、主要ライブラリを箇条書きで並べる。「Python / Flask / SQLite」くらいの粒度で十分。

これがあると、読む人は自分の環境で動かせそうか、コードを読めそうかを開いた瞬間に判断できる。逆に無いと、ファイルの拡張子を眺めて推測することになる。

セットアップ手順: 上から順にコマンドを打てば動く状態にする

ここが README の本体だと思う。クローン、依存のインストール、起動、を上から順にコマンドで書く。

git clone <リポジトリのURL>
cd <プロジェクト>
npm install
npm run dev

Python なら pip install -r requirements.txt に置き換える。判断基準はシンプルで、「この通りに打てば動くか」。文章で「依存をインストールしてください」と書くより、コマンドをそのまま貼る方が親切だし、未来の自分もコピペで済む。

git clone 自体がまだ手探りなら、git／GitHub入門で1周しておくと、この手順を書く側にも回りやすい。

.env.example: 秘密は上げず、必要なキーの一覧だけ示す

APIキーなどの環境変数が要るアプリなら、必要なキーを空値で並べた .env.example をリポジトリに入れて、README で「これをコピーして .env を作り、値を入れる」と案内する。.env 本体は絶対にコミットしない。この話は.gitignoreの書き方これだけに書いた。

.env.example が無いと、クローンした人(半年後の自分を含む)は起動時のエラーを見て必要なキーを逆算する羽目になる。一覧が1枚あるだけで、その手戻りが消える。

テンプレ: これをコピーして埋めればいい

上の4要素をそのまま並べた最小テンプレを置いておく。

# プロジェクト名

一言でどんなアプリか。

## 使用技術
- 言語 / フレームワーク
- 主要ライブラリ

## セットアップ
```bash
git clone <リポジトリのURL>
cd <プロジェクト>
npm install
cp .env.example .env   # 環境変数を設定
npm run dev
```

## 環境変数
`.env.example` を参照。必要なキーは以下。
- API_KEY: 〜のAPIキー

使ってる記法は3つだけ。# で見出し、バッククォート3つで囲んでコードの枠（コードブロック）、- で箇条書き。

README はほぼこれだけで書ける。Markdown を体系的に覚えてから書こう、とはしなくていい。

盛りすぎない。バッジと長い目次は後でいい

README のうまい人のリポジトリを見ると、バッジがずらっと並んでデモGIFがあって目次があって、真似したくなる。でも個人リポジトリでそこから入ると、たぶん途中で力尽きて「飾りだけ立派で動かし方が書いてない README」になる。順番が逆で、最低限の4つを先に埋める方がいい。

あるとなお良いものは確かにある。UIがあるアプリならスクリーンショットやGIFは一目で伝わるし、ライセンスや簡単な使用例もあれば親切だ。ただそれは「最低限の次」の話で、無くても README の役目は果たせる。

スクショとGIFの貼り方

4つを埋めたら、次に足す候補はスクショだ。文字だけでは見た目が伝わらないので、UIがあるアプリならトップに1枚貼るだけで印象が変わる。

いちばん速いのはIssueの入力欄に落とす方法

自分のリポジトリで新しいIssueを開き、入力欄に画像ファイルをドラッグ&ドロップする。GitHubが画像を預かって、URLを発行してくれる。

1. リポジトリの「Issues」タブから「New issue」を開く
2. 本文の入力欄に、スクショのPNGをドラッグ&ドロップする（コピペでもいい）
3. 数秒待つと、![スクショ名](https://...) のようなMarkdownが自動で入る
4. その1行をコピーして、README.mdに貼る
5. Issueは投稿せずにそのまま閉じる

下書きの入力欄に落とした時点でURLは発行されるので、Issue一覧は汚れない。ただし公開リポジトリでは、そのURLを知っていれば誰でも画像を開ける。個人情報やAPIキーが写ったスクショは落とさない。

Pull Requestやコメントの入力欄でも同じことができる。

コミットもフォルダ整理も要らないのが、この方法の強みだ。

残すならリポジトリに置いて相対パスで参照する

もうひとつは、画像そのものをリポジトリに入れる方式だ。assets/ のようなフォルダに置き、READMEからは相対パスで参照する。

![アプリのメイン画面](assets/screenshot.png)

[] の中は代替テキストで、画像が表示できないときに代わりに出る説明文だ。空でも動くが、何の画面かを一言書いておくと親切になる。

	A: Issueに落としてURL	B: リポジトリに同梱
手間	コミット不要	フォルダを作ってコミットが要る
画像の置き場所	リポジトリの外（GitHubが預かる）	コードと一緒に管理される
クローンした手元	画像は付いてこない	オフラインでも表示できる
リンク切れ	起きうる	起きにくい
リポジトリのサイズ	増えない	増える

手早く1枚見せるだけならA、ポートフォリオとして見せるリポジトリならBの相対パスが無難だ。画像もコードと一緒にバージョン管理される。

スクショをそのまま貼ると、README上では大きすぎることが多い。素のMarkdownの ![]() には幅を指定する構文がないので、HTMLの <img> を使う。

<img src="assets/screenshot.png" width="600">

GitHubのMarkdownは <img> タグをそのまま解釈する。スマホのスクショのような縦長の画像は、幅400前後まで絞ると収まりがいい。

動きを見せるならGIFにする

静止画では、ボタンを押したら画面がどう切り替わるかまでは伝わらない。READMEに貼ったGIFは自動で再生されるので、デモ動画へのリンクより見てもらいやすい。

録画はOSの標準機能で足りる。WindowsならXbox Game Bar（Win+Gで起動）、macOSならQuickTime Playerの画面収録で、見せたい操作を1回だけ短く録る。

録った動画は、ffmpeg（動画を変換するコマンドラインツール）でGIFにする。

ffmpeg -i input.mp4 -vf "fps=10,scale=640:-1" output.gif

fps=10 は1秒あたりのコマ数を10枚に落とす指定で、scale=640:-1 は横幅を640pxにして縦は比率を保つ指定だ。この2つだけでファイルがかなり軽くなる。

色が荒れるときは、動画に合わせた256色を先に作ってから変換するときれいになる。

ffmpeg -i input.mp4 -vf "fps=10,scale=640:-1:flags=lanczos,split[a][b];[a]palettegen[p];[b][p]paletteuse" output.gif

変換が手元で完結するので、開発中の画面を外部の変換サービスに上げずに済む。

ffmpegが入っていなければ、理系大学生のMac初期設定と開発環境の手順で一緒に入れられる。GIFの貼り方は静止画と同じで、![デモ](assets/demo.gif) でもIssueに落としたURLでもいい。

GIFを軽くする4つの対策

GIFは静止画よりずっと重い。フルHDの画面を長めに録ってそのまま変換すると、数MBから十数MBになる。GitHubのIssueなどに添付できる画像とGIFは1ファイル10MBまでなので、重すぎると貼る前に弾かれる。

1. 横幅を絞る：640px前後あればデモには十分
2. fpsを落とす：10〜15あれば操作の流れは伝わる
3. 長さを切る：数秒でいい。長く録ったら変換前にトリミングする
4. 見せる操作を1つに絞る：起動からログインまで全部は見せない

上のffmpegコマンドで1と2は済んでいる。まだ重ければ長さと内容を削る、の順で進めればいい。

B方式で重いGIFをリポジトリに入れると、そのファイルはgitの履歴に残り続ける。あとで消しても、クローンは重いままだ。

そのため、静止画はリポジトリに入れ、大きいGIFだけIssueに落としたURLを使う組み合わせもある。

まとめ

学生の個人リポジトリの README は、概要・使用技術・セットアップ手順・.env.example の案内、の4つでいい。書く相手は他人だけじゃなくて、半年後の全部忘れた自分でもある。

今すぐ自分のリポジトリを1つ開いて、README の先頭に「これが何のアプリか」の1文があるか見てみてほしい。無かったら、まずその1文だけ書く。テンプレの残りはそれからで間に合う。

UIがあるなら、4つを埋めたあとにスクショを1枚足す。Issueの入力欄に落とせば1分かからずに貼れるし、動きはGIFにして640px・10fpsに絞る。