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

README の最初の版

README は、リポジトリを開いた人が最初に目にする説明書です。Markdown という書き方で書きます。最初の版には、何を、誰のために作ったかと、動かし方を書いておきます。仕上げは第8部で行います。

佐藤さん(会社員で、実家の和菓子店を手伝う、架空の人物)は、GitHub の自分の置き場を、スマホで開いてみました。index.html、style.css、app.js。ファイルの名前が並んでいるだけです。父がこれを見ても、何の作品か分からないでしょう。

問い

佐藤さんの疑問

置き場を開いた人に、最初に何を伝えればいいんだろう。

何も書いていない折りたたみの案内と、包んだお菓子の箱の挿絵。

前の回までで、佐藤さんの作品は、記録とともに GitHub に置けるようになりました。

GitHub で作品のページを開いた人は、ファイルの名前が並んでいるだけでは、何の作品か分かりません。第5部の最後のこの回では、その人に最初に読んでもらう説明書を作ります。

README:作品の説明書

リポジトリ(作品の置き場)のいちばん上に置く、作品の説明書を、README(リードミー)と呼びます。英語の read me、「私を読んで」という意味です。GitHub の公式の説明には、こう書かれています。

DOCUMENTATION

“A README is often the first item a visitor will see when visiting your repository.”

README は、リポジトリを訪れた人が、最初に目にするものであることが多いものです。

GitHubAbout READMEs(GitHub Docs)

同じ説明によると、README には、ふつう、何をする作品か、なぜ役に立つか、どう使い始めるか、困ったときどこに聞けばよいか、誰が作っているか、を書きます。

大会の審査をする人も、作品のリポジトリを開けば、まず README を目にすることが多いはずです。

Markdown:記号で形を付ける書き方

README は、多くの場合、README.md という名前のファイルです。最後の .md は、Markdown(マークダウン)という書き方で書かれていることを表す拡張子(ファイルの種類を表す印)です。

Markdown は、ふつうの文に、少しの記号を足して、見出しや箇条書きの形を付ける書き方です。

書き方GitHub での見え方
# 売れ残り帳大きな見出し
## 動かし方少し小さな見出し
- 豆大福箇条書きの1行
**大事**太字

GitHub の公式の説明にも、見出しは、文の前に1つから6つの「#」を付けて作り、「#」の数で、見出しの大きさが決まると書かれています。

最初の版に書くこと

README は、提出の前に仕上げます(第8部の第5回)。でも、最初の版は、いま作っておきます。あとから思い出して書くより、作りながら育てるほうが楽だからです。

最初の版には、第3部で用意したものが、そのまま使えます。

  • 作品の名前と、3行の説明(第3部の第7回)
  • 誰の、どの場面を変えるか(第3部の第6回)
  • 動かし方
  • 例に出てくるお店や数字は、架空であること

佐藤さんは、こう頼みました。

README の最初の版を頼む例
このリポジトリの README.md の最初の版を、日本語の Markdown で作ってください。入れることは次のとおりです。
・作品の名前「売れ残り帳」
・3行の説明:
 1. 商店街の和菓子店を手伝う私は、閉店後に売れ残りを数える場面で、ノートへの書き写しに20分かかり、翌朝、父が字を読めずに電話してくることに困っている。
 2. 似たものに在庫の管理アプリがあるが、お菓子の名前を毎回打ち込むのが面倒で、父がスマホの小さな字を読まないから広がっていない。
 3. 今は AI でノートの写真から数を読み取れるようになったので、写真を撮るだけで、父が読める大きな字の表と、翌日に作る数の目安が出る道具を作る。
・使う人と場面:閉店後、店の奥で、父がスマホで、あすの目安を読む
・手元での動かし方
・お店の名前や数字は、すべて架空の例であること
書いたあと、README に書いてあることが、いまの作品で本当にできるかを、1つずつ確かめて教えてください。

この依頼文は、説明のための架空の例です。3行は、第3部の第7回で佐藤さんが書いたものです。

たとえば、3行目にある「写真から数を読み取る」は、まだ作っていません(第6部で作ります)。Claude が確かめれば、「まだできていないこと」として分けてくれるはずです。

できた README は、ほかの変更と同じように、画面で中身を確かめてから、コミットして(第5部の第3回)、GitHub にプッシュします(第5部の第8回)。GitHub のリポジトリのページを開くと、ファイルの一覧の下に、README の中身が表示されます。

README は、ファイルの一覧の下に出る

GitHub のリポジトリのページ(形だけ)

urenokori index.html style.css app.js README.md 売れ残り帳 何を、誰のために作ったか README.md の中身がここに出る urenokori index.html style.css app.js README.md 売れ残り帳 何を、誰のために作ったか README.md の中身がここに出る
図1ページを開いた人が、ファイルの名前の次に読むのが README です。

README は、リポジトリを開いた人が最初に読む説明書です。Markdown で書き、最初の版は、作りながら用意しておきます。

注意

ただし、書いてあることが本当か、確かめる

Claude に README を書いてもらうと、まだ作っていない機能や、実際より大きな言い方が混ざることがあります。依頼文の例の最後で、「本当にできるかを確かめて」と頼んでいるのは、そのためです。

できていないことを書いた README は、審査をする人の信頼を失います。まだできていないことは、「これから足したいこと」として、分けて書きます。

次回の問い

佐藤さんの次の疑問です。作品の中で、Claude に答えを書かせるには、何が要るのでしょうか。

参考

README について(GitHub Docs)
README に書くこと。日本語。
GitHub Docs · docs.github.com
基本的な書き方とフォーマットの構文(GitHub Docs)
Markdown の見出し、箇条書き、太字などの書き方。日本語。
GitHub Docs · docs.github.com

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