メインコンテンツへスキップ
AMPL/ dev
開発系講座一覧

README を仕上げる

README は、審査員が作品のリポジトリを開いて、最初に読む説明書です。初めて見る人が試す順に並べ、実際の画面のスクリーンショットを添え、まだできないことも書きます。

佐藤さん(会社員で、実家の和菓子店を手伝う、架空の人物)は、第5部で書いた README の最初の版を開きました。作品の名前と3行の説明、手元での動かし方。その後に足した写真の読み取りも、置いた URL も、まだ書いてありません。

問い

佐藤さんの疑問

初めて見る審査員のために、README には、何を、どの順に書けばいいんだろう。

写真の枠と文の線だけが描かれた、開いた三つ折りの案内の挿絵。

前の回で、迷ったときの聞き方を見ました。この回からは、提出物を仕上げていきます。まずは README(作品の説明書)です。

README に、ふつう書くこと

README は、GitHub のリポジトリ(作品の置き場)を開いた人が、ファイルの一覧の下で最初に読む説明書でした(第5部の第11回)。GitHub の公式の説明には、こう書かれています。

DOCUMENTATION

“通常、README ファイルには以下の情報が含まれています: このプロジェクトが行うこと このプロジェクトが有益な理由 このプロジェクトの使い始め方 このプロジェクトに関するヘルプをどこで得るか このプロジェクトのメンテナンス者とコントリビューター”

GitHubREADME について(GitHub Docs)

プロジェクトは、ここでは作品のことです。メンテナンス者は手入れを続ける人、コントリビューターは作るのに加わった人のことです。

docs.github.com/ja/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes
GitHub の公式の説明のページ「README について」。README には、ふつう、このプロジェクトが行うこと、有益な理由、使い始め方、ヘルプをどこで得るか、メンテナンス者とコントリビューター、が含まれる、と箇条書きになっている。
GitHub の公式の説明のページ(日本語、2026年11月11日に撮影)。README にふつう書く5つが並んでいます。ログインしなくても読めます。

初めて開く人の順に並べる

審査員は、作っている途中を知りません。README は、初めての人が試す順に並べると、迷わずに進めます。大会の指定があれば、その項目も入れます。

  1. 誰の、どの場面を助ける作品か
  2. 開く URL と、最初に試す1つの作業
  3. 入れてよい試しの情報と、入れないでほしい情報
  4. できること、まだできないこと、まだ確かめていないこと
  5. 作り方を試す人への手順と、使った部品や素材の条件(第8部の第2回と第6回)

佐藤さんは、こう書き出しました。「売れ残り帳は、閉店後の売れ残りの数を、ノートの写真から読み取って表にし、翌日に作る数の目安を出す道具です」。「AI でお店を変える」のような広い文だけでは、何を押せばよいかが分かりません。

スクリーンショット:実際の画面を写す

画面をそのまま画像として写したものを、スクリーンショットと呼びます。第4部の第9回で、撮り方を見ました。

README の画像は、実際に置いた作品を開いて、試しの数字(説明のために作った数字)で動かした画面から撮ります。まだ作っていない画面を、それらしく作って載せることはしません。何をしたら、何が出たかを、画像の下に一言添えます。撮ったら、通知や、ほかの窓や、アカウントの名前、鍵の値が写っていないかを確かめます。

画像を README に入れるのは、Claude Code(会話で頼むと、作品を作ったり直したりしてくれる道具)に頼めます。

README を仕上げてもらう例
README.md を、提出に向けて仕上げます。添えたスクリーンショット2枚をリポジトリに入れ、README から表示してください。並びは、1. 誰のどの場面の作品か、2. 開く URL と最初に試す作業、3. 入れてよい試しの情報と入れないでほしい情報、4. できること・まだできないこと・確かめていないこと、5. 動かし方と、使った部品や素材の条件、の順にしてください。書いてあることが、いまの作品で本当にできるかを1つずつ確かめ、できないことは「まだできません」と書いてください。

この依頼文は、説明のための架空の例です。

「まだできない」を、隠さない

たとえば、雨かどうかを自動で調べる機能がまだないなら、「天気は自動では入りません。雨の印は手で付けます」と書きます。Claude の読み取りを人が確かめる必要があるなら、それも使い方に書きます。「読み取った数は、人が確かめてください」と README にだけ書いて、作品の画面には何も出ない作りなら、画面にも、その一言を出すように直します。

README は、初めての人が試す順に並べ、実際の画面のスクリーンショットを添え、まだできないことも書きます。

注意

ただし、Claude が書いた「できます」は、自分で確かめる

Claude に README を書いてもらうと、まだ試していない操作まで、「できます」と書かれることがあります。README の通りに、自分で URL を開き、試しの数字を1つ直し、表を読むところまで通します。

最後に、制作を見ていなかった人に README だけを渡し、最初の作業まで進めるかを試してもらいます。鍵の値が README に書かれていないことも、もう一度確かめます。

次回の問い

佐藤さんの次の疑問です。作品のコードを、公開リポジトリで見せます。誰でも読める場所に置けば、誰でも自由に使ってよい、ということになるのでしょうか。

参考

README について(GitHub Docs)
README にふつう書くことと、表示される場所。日本語。2026年11月11日に確認。
docs.github.com · docs.github.com
基本的な書き方とフォーマットの構文(GitHub Docs)
README に画像やリンクを入れる書き方。日本語。
docs.github.com · docs.github.com
Vibe Coding 用語集:README
README の説明。
AMPL · Web

このレッスンは役に立ちましたか?