他人は5分しか見ない — READMEと技術選定

READMEと技術選定。READMEの書類とアプリのスクリーンショット、設計のメモ。

この回は、ほとんどが文章を書く作業です。 コードはほぼ書きません。作業場所はVMの中(Ubuntu Server)、確認はホストの Windows のブラウザから GitHub を見ます。

前回: 公開の前に、戻せることを確かめる — デプロイと運用の入口

hitokoto は動いています。

ブラウザで開けば本が並び、ログインでき、引用が保存され、再起動しても消えません。サーバーは systemd で自動起動し、nginx の後ろにいて、バックアップも回っています。

あなたにとっては、完成しています。

ところが、ここで起きることは、だいたい決まっています。誰かに「作ったものを見せて」と言われて、あなたはリポジトリのURLを渡します。相手はそれを開きます。そして、こういう画面を見ます。

hitokoto

src/  client/  migrations/  seeds/  package.json  package-lock.json
knexfile.js  ecosystem.config.js  .gitignore  note.txt  test.js
memo_20260901.md  screenshot.png  hitokoto.service

No description, website, or topics provided.

相手はここで、何も分かりません。

  • これは何をするものなのか — フォルダ名からは読めません
  • 動いているものが、どこかで触れるのか — 書いてありません
  • 自分の手元で動かせるのか — npm install の次に何をするのか分かりません
  • どういう考えで作られているのか — コードを全部読むしかありません

そして、相手はコードを全部読みません。 読む時間が無いからです。開いて、上から下まで眺めて、分からなければ閉じます。

かかる時間は、だいたい5分です。

これは冷たい話ではなく、あなた自身が他人のリポジトリにしていることでもあります。GitHub で知らないライブラリを開いたとき、あなたはまずREADMEを読み、書いていなければ、たいてい別のものを探します。同じことをされる側に回っただけです。

だからこの回でやることは、1つです。

リポジトリを開いた人が、5分で「何なのか・どこで触れるのか・どう作られているか」を理解できる形にする。

これは就職活動の話ではありません。 そう読まれがちなので先に書いておきます。READMEを書くのは、半年後の自分のためでもあり、バグを報告してくれる誰かのためでもあり、「これ使っていい?」と聞いてくる人のためでもあります。就職はそのうちの1つの使い道にすぎません。

そして、この回でいちばん強く言うことは、これです。

盛らないでください。嘘を書かないでください。

「テスト完備」と書いてテストが3本しかない、「Docker対応」と書いて動かない、「認証機能」と書いてパスワードが平文。これは全部、読んだ人が5分で確かめられます。 そして、確かめられた瞬間に、書いてある他の部分も全部疑われます。

できていないことを自分から書いたほうが、強いです。 理由は最後に書きます。

対象レベル: 中級 / 区分: 必修

目次

この記事でわかること

  • README が無いリポジトリは「未完成」ではなく「読めない」として扱われること。動くかどうかとは別の軸であること
  • 「なぜその技術を選んだか」が説明できないと、技術構成の一覧は意味を持たないこと。「流行っているから」は理由にならない
  • できていないことを書かないと、代わりに全部聞かれること。先に書いたほうが有利であること
  • リポジトリは中身だけでなく、ファイルの散らかり方とコミット履歴も見られていること
  • AIを使ったことは隠すものではないこと。書くべきなのは「何を自分が判断したか」であること
  • ライセンスを書かないと「自由に使える」ではなく「使えない」になること

この記事でやること

  1. hitokoto の README を、決まった順番で最後まで書く(全文を載せます)
  2. スクリーンショットを1枚撮って README に貼り、デモ用アカウントを用意する
  3. リポジトリから不要ファイルを消し、.gitignore とコミット履歴を見直す
  4. 技術選定の5つの問いに、それぞれ1行で答える練習をする
  5. LICENSE ファイルを置いて、GitHub に認識させる

先に知る言葉

この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。

言葉意味
READMEリポジトリを開いたときに最初に表示される説明ファイル。README.md という名前で置くと GitHub が自動で表示する
デモ用アカウント誰でもログインして触れるように用意した、中身を壊されても困らないアカウント
シード(seed)データベースに初期データを入れるためのスクリプト。第8段階で ORM と一緒に出てきた仕組み
ライセンスそのコードを他人がどう使ってよいかを決めた文章。書かないと「使ってはいけない」が初期値になる
MIT ライセンスもっとも短く、もっとも制限が少ないライセンスの1つ。著作権表示を残せば、あとは自由という内容
ADRArchitecture Decision Record。「なぜそう決めたか」を1件1ファイルで残した記録。前に書いた回で作った docs/adr/ のこと
バッジREADME の上部に並ぶ小さな画像。ビルド状況やライセンスを示す。飾りとしても使われるので、意味のあるものだけ置く
GIF短い動画のように動く画像形式。音が無く、再生ボタンも要らないので、GitHub のREADMEにそのまま貼れる

① 「5分で伝わるか」を基準にする

READMEの書き方を調べると、「テンプレート」がたくさん出てきます。テンプレートから入ると、たいてい失敗します。 空欄を埋める作業になって、埋まっているのに何も伝わらないREADMEができるからです。

先に基準を1つ決めます。

知らない人がこのページを開いて、5分後に「これは何で、どこで触れて、どう作られているか」を人に説明できるか。

この基準で見ると、READMEに書くべきことの順番は、ほぼ自動的に決まります。相手が知りたい順に並べればいいからです。

順番相手の頭の中READMEの項目
1これは何?1行でなにか
2どんな見た目?スクリーンショット1枚
3触れるの?触れる場所(URL・デモ用アカウント)
4どう使うの?使い方
5何でできてるの?技術構成
6なんでそう作ったの?設計判断
7どこまでできてるの?既知の問題
8この先どうするの?これから

逆にすると読まれません。 「開発の背景」から始まるREADMEは、相手がまだ「これは何?」で止まっているのに、いきなり事情を語り始めている状態です。

そして、この順番には副作用があります。 上から書いていくと、自分が説明できないところで必ず手が止まります。 「なぜMySQLにしたのか」が書けない、というのはよくあります。そこが、あなたがまだ言葉にできていない場所です。 READMEを書く作業は、それを見つける作業でもあります。


② README を、決まった順番で書く

ここが山場です。hitokoto の README を、最後まで書きます。

まずファイルを作ります。VMの中、~/hitokoto/ のいちばん上です。

bash
$ cd ~/hitokoto
$ code README.md

code が使えるのは、VS Code の Remote SSH で繋いでいるときだけです。 繋いでいないときは nano README.md で構いません。

全文

下が hitokoto のREADMEの全文です。 このあと、1項目ずつ「なぜそう書くか」を説明します。

注: 下のブロックの中で、コマンドを囲むのに ~~~ を使っています。~~~ と ``` はどちらも同じコードブロックの書き方で、GitHub でも同じように表示されます。ここでは入れ子になって読みにくくなるのを避けるために使い分けています。実際のREADMEでは、どちらで書いても構いません。

# hitokoto

**読んだ本と、そこから引いた一文を残すWebアプリです。**
「あの本のあの一節」を探し直す時間をなくすために作りました。

![本の一覧画面。3冊の本がカードで並び、それぞれに引用が1〜2件ぶら下がっている](docs/screenshot.png)

## 触れる場所

- **公開URL**: https://hitokoto.example.com
- **デモ用アカウント**: `demo@example.com` / `demo-please-change-me`

デモ用アカウントのデータは、**毎日 04:00(JST)に初期状態へ戻ります。**
消しても壊しても構いません。自分のメールアドレスは登録しないでください。

## 使い方

1. ログインする(デモ用アカウントで構いません)
2. 「本を追加」から、タイトルと著者を登録する
3. 本を開いて、「引用を追加」で本文と、あればページ番号を書く
4. 一覧から、本ごとに引用をまとめて読み返す

引用は本に紐づきます。本を消すと、その本の引用もまとめて消えます。

## 自分の環境で動かす

必要なもの: Node.js 20 以上、MySQL 8

~~~bash
git clone https://github.com/USERNAME/hitokoto.git
cd hitokoto
cp .env.example .env      # 中身を自分の環境に合わせて書き換える
npm install
npm run migrate           # テーブルを作る
npm run seed              # デモ用のデータを入れる
npm run dev               # http://localhost:3000
~~~

`.env` に何を書くかは `.env.example` にすべて並べてあります。
**`.env` そのものはリポジトリに入っていません。**

## 技術構成

| 何に | 使ったもの | なぜそれにしたか |
|---|---|---|
| サーバー | Express | 最初に覚えた道具で、この規模なら足りると判断したため |
| データベース | MySQL | 本と引用が1対多で、崩れると困る関係だから。表で持つのが素直だった |
| DBの操作 | Knex | SQLを自分で書きつつ、テーブル変更を履歴に残したかったため |
| ログイン | セッション + Cookie | 使うのがブラウザ1つだけで、サーバー側で即座に無効化できるほうが安全だと考えたため |
| パスワード | bcrypt | ハッシュが速いと総当たりも速くなるため、意図的に遅いものを選んだ |
| 画面 | React + Vite | 一覧と詳細で同じ本のデータを使い回すので、状態を1か所に置きたかったため |
| 公開 | nginx + systemd | 80/443 を受けるのと、プロセスを起動し続けるのは別の仕事なので分けた |
| バックアップ | cron + mysqldump | 復元手順を自分で書けるものにしたかったため |

## 設計判断

なぜそう決めたかは `docs/adr/` に1件1ファイルで残しています。

- [0001 — CSS変数でトークンを持つ](docs/adr/0001-design-tokens.md)
- [0002 — 認証はセッションにする](docs/adr/0002-session-auth.md)
- [0003 — コンテナを使わずVMに直接置く](docs/adr/0003-no-container.md)

## 既知の問題

**できていないこと・分かっていて直していないことです。**

- **引用の全文検索ができません。** 部分一致の `LIKE` で引いているので、件数が増えると遅くなります
- **画像を登録できません。** 本の表紙は文字だけです
- **テストはサーバー側の12本だけです。** 画面側の自動テストはありません
- **スマートフォンでの表示が崩れます。** 幅600px以下を想定していません
- **同時に使えるのは実質1人です。** 負荷を測っていません
- **エラー画面が雑です。** 失敗すると英語のメッセージがそのまま出ます

## これから

1. 引用の全文検索(`LIKE` をやめる)
2. 画面側のテストを、まず一覧画面から
3. スマートフォン幅の対応

## この作り方について

**AIを使って書いています。** 使い方と、自分が判断した部分は
[docs/how-this-was-built.md](docs/how-this-was-built.md) に書きました。

## ライセンス

MIT License — [LICENSE](LICENSE) を見てください。

これで全文です。 長すぎないはずです。上から読んで、5分かかりません。

1行でなにか

いちばん難しいのが、実はここです。

**読んだ本と、そこから引いた一文を残すWebアプリです。**
「あの本のあの一節」を探し直す時間をなくすために作りました。

2行目が重要です。 1行目は「何をするか」ですが、2行目は「何のために」です。この2行目が無いと、読んだ人は「ふーん、メモアプリか」で終わります。

やってはいけない書き方を並べます。

ダメな1行なぜダメか
Express + React + MySQL で作ったWebアプリです技術構成は「何か」の説明ではない。読んだ人は何のアプリか分からないまま
モダンな技術スタックで構築した高機能な読書管理システム「モダン」「高機能」に中身が無い。何ができるのか1つも書いていない
ポートフォリオとして作成しました相手が知りたいのは、あなたの目的ではなくアプリの機能
読書記録アプリ短すぎる。「一文を残す」という、このアプリ固有の部分が消えている

基準は「これを読んだ人が、使う場面を想像できるか」です。

スクリーンショット1枚

![本の一覧画面。3冊の本がカードで並び、それぞれに引用が1〜2件ぶら下がっている](docs/screenshot.png)

1枚です。 5枚並べたくなりますが、READMEの上のほうが画像で埋まると、その下の文章が読まれません。

  • いちばん「このアプリらしい」画面を選びます。ログイン画面ではありません。中身が入っている画面です
  • ![] の中は代替テキストです。何が写っているかを書きます。画像が出ないときに表示され、読み上げソフトも読みます
  • 画像は docs/ に置きます。リポジトリのいちばん上に画像ファイルが散らかるのを避けるためです

[スクリーンショット: 01_トップ画面.png] hitokoto の本の一覧画面を、ブラウザで撮ってください。デモ用のデータが入っている状態で撮ります。

撮る前に、画面に写っているものを確認してください。 自分の本名、本物のメールアドレス、ブラウザのブックマークバー、開いている他のタブ。READMEに貼った画像は、全世界から見えます。 ブラウザは新しいウィンドウで開き、ブックマークバーは隠して撮るのが安全です。

触れる場所

ここが、READMEでいちばん効く場所です。

- **公開URL**: https://hitokoto.example.com
- **デモ用アカウント**: `demo@example.com` / `demo-please-change-me`

読んだ人は、コードより先に動いているものを見たいからです。ここにURLがあれば、その場でクリックされます。

ログインが必要なアプリで、いちばんもったいない失敗がこれです。

URLを開く → ログイン画面が出る → 登録するほどではない → 閉じる

アカウントを作らせてはいけません。 だからデモ用アカウントを用意します。

デモ用アカウントの作り方

シードに入れます。 手で作ると、消えたときに復旧できません。

bash
$ cd ~/hitokoto
$ npx knex seed:make 002_demo_user

中身は、パスワードをハッシュ化してから入れます。第7段階でやったとおり、平文で保存はしません。

// seeds/002_demo_user.js
const bcrypt = require('bcrypt');

exports.seed = async function (knex) {
  await knex('users').where({ email: 'demo@example.com' }).del();

  const [id] = await knex('users').insert({
    email: 'demo@example.com',
    password_hash: await bcrypt.hash('demo-please-change-me', 12),
    display_name: 'デモ'
  });

  await knex('books').insert([
    { user_id: id, title: '銀河鉄道の夜', author: '宮沢賢治' },
    { user_id: id, title: '人間失格', author: '太宰治' }
  ]);
};

そして、1日1回、元に戻します。 誰かが全部消しても、翌朝には戻っている状態にします。

bash
$ sudo crontab -e
0 4 * * * cd /home/USER/hitokoto && /usr/bin/npm run seed >> /var/log/hitokoto-seed.log 2>&1

確かめ方: デモ用アカウントでログインし、本を1冊消して、npm run seed を手で実行し、消した本が戻っていれば成功です。

デモ用アカウントに、本物の鍵を置かないでください。

– 自分が他で使っているパスワードを、絶対に使い回さない – デモ用アカウントに管理者権限を付けない。他人のデータが見える設定にしない – APIキー・トークン・クラウドの認証情報を、デモ環境に置かない – README に本物のパスワードを書かない。ここに書いてよいのはデモ用アカウントのものだけです

[スクリーンショット: 02_デモログイン.png] デモ用アカウントでログインし、シードで入れた本が並んでいる画面を撮ってください。

動く場所が無いとき

公開していない場合もあります。 ドメインを取っていない、サーバー代を払い続けたくない、VMの中でしか動いていない。それは普通のことです。

そのときは、代わりに「動いているところ」を見せます。

代替どういうとき
短い動画(30秒以内)操作の流れを見せたいとき。YouTube の限定公開に上げてリンクする
GIFいちばん手軽。READMEにそのまま貼れて、クリックせずに動く
スクリーンショット3枚動きが要らないアプリのとき。登録 → 一覧 → 詳細のように、流れの順に並べる

GIF の作り方は、Linux 側で完結します。VMのデスクトップではなく、ホストのWindowsで撮った動画を変換するのがいちばん簡単です。

bash
$ sudo apt install -y ffmpeg
$ ffmpeg -i demo.mp4 -vf "fps=10,scale=800:-1" -loop 0 docs/demo.gif
  • fps=10: 1秒10コマ。GIFは30コマにしても人の目にはほぼ変わらず、ファイルだけ3倍になります
  • scale=800:-1: 横800px。-1 は「縦は比率を保って自動」という意味です

そして、必ずサイズを見てください。

bash
$ ls -lh docs/demo.gif

10MB を超えたら、貼らないでください。 読んだ人のスマートフォンで、READMEが数秒間まっ白になります。長さを削るのがいちばん効きます。 30秒を10秒にすれば、それだけで3分の1です。

使い方 と 自分の環境で動かす

この2つは別物です。 混ぜているREADMEが非常に多いです。

項目誰のため書くもの
使い方アプリを使う人画面の操作。コマンドは1つも出てこない
自分の環境で動かすコードを触る人git clone からの手順

「使い方」の欄が npm install から始まっているREADMEは、アプリを使いたいだけの人を追い返しています。

そして「自分の環境で動かす」のほうには、必ず前提を書きます。

必要なもの: Node.js 20 以上、MySQL 8

これが無いと、読んだ人は Node.js 18 で試して、動かなくて、閉じます。 自分の環境に入っていたものを、相手も持っているとは限りません。

手順は、上から順に打てば動く形にします。 途中に「適宜設定してください」と書かないでください。何を設定するのか分からないからです。 代わりに .env.example を置いて、「中身は全部そこにある」と書きます。

確かめ方: 別のディレクトリに clone し直して、READMEの手順だけを見ながら、自分でもう一度動かしてください。

bash
$ cd /tmp
$ git clone ~/hitokoto hitokoto-test
$ cd hitokoto-test

ここで必ず1つか2つ足りません。 「先に MySQL でデータベースを作る必要があった」「npm run seed の前に migrate が要る」。それがREADMEに足りていない行です。

技術構成 — 1行の理由を必ず書く

ここがこの記事のもう1つの山場です。

技術構成を、こう書いているリポジトリが山ほどあります。

## 使用技術
Node.js / Express / MySQL / Knex / React / Vite / nginx / systemd

これは、情報としてほぼ0です。 読んだ人が知りたいのは「何を使ったか」ではなく、「なぜそれなのか」だからです。名前の一覧は、package.json を開けば分かります。

だから、表にして、右端に理由を1行ずつ書きます。

何に使ったものなぜそれにしたか
データベースMySQL本と引用が1対多で、崩れると困る関係だから

この1行が書けるかどうかが、境目です。

そして、理由として認められないものがあります。

書きがちな理由なぜ理由にならないか
流行っているから流行は理由ではありません。 来年には別のものが流行っています。「なぜ自分の問題に合うのか」が1つも入っていません
モダンだから同じです。「モダン」は中身のない言葉で、聞き返されたときに続きが出ません
多くの企業で採用されているからその企業の問題と、あなたの問題が同じである説明が抜けています
チュートリアルがそうだったから正直ではありますが、それは「選んだ」ではなく「そうなった」です
学習のため理由としては成立しますが、必ずそう書いてください。 「本番でも最適です」と書くと嘘になります

そして「学習のため」は、書いてよい理由です。

| 画面 | React | 一覧と詳細で同じ本のデータを使い回すため。加えて、学習のために意図的に選んだ |

これは弱くありません。 「一覧と詳細でデータを使い回したい」という、このアプリ固有の事情が先に書いてあるからです。弱いのは、固有の事情が1つも無いまま「学習のため」だけが書いてあるときです。

既知の問題 — できていないことを書く

ここでほとんどの人の手が止まります。 「わざわざ弱点を書く必要があるのか」と思うからです。

書いてください。理由は3つあります。

1つ目。書かないと、代わりに全部聞かれます。

READMEに「できていないこと」が無いと、読んだ人は自分で探し始めます。 そして必ず見つかります。そのとき、あなたは「気づいていなかった人」になります。

先に書いてあれば、同じ事実が「気づいていて、優先順位を決めた人」になります。同じコードで、評価が逆になります。

2つ目。書ける項目の数が、そのまま理解の深さです。

「引用の検索が LIKE なので件数が増えると遅い」と書けるのは、インデックスが部分一致に効かないことを知っているからです。知らない人は、この行を書けません。弱点の一覧は、理解の一覧でもあります。

3つ目。半年後の自分が助かります。

書き方には型があります。

悪い書き方良い書き方
テストが不十分ですテストはサーバー側の12本だけです。画面側の自動テストはありません
パフォーマンスに課題があります引用の検索が LIKE の部分一致なので、件数が増えると遅くなります
一部未実装です本の表紙画像を登録できません。文字だけです

違いは「具体的かどうか」です。 曖昧に書くと、隠そうとしているように読めます。 具体的に書くと、分かっていることの証明になります。

ただし、セキュリティの穴は「既知の問題」に書かないでください。

「認証にバグがあって他人のデータが見えます」は、公開している状態で書くと、攻撃の手順書になります。 これは書くのではなく、公開を止めて直してください。 直せないなら、公開URLを外して「ローカルでのみ動きます」にします。

設計判断・これから・ライセンス

設計判断は、READMEに全部書きません。 リンクにします。

- [0002 — 認証はセッションにする](docs/adr/0002-session-auth.md)

デザインシステムの回で docs/adr/ を作りました。あれの回収です。 READMEにはタイトルだけを並べて、詳しくはそのファイルに送ります。READMEを長くしないためです。

「これから」は3つまでにします。 10個並んでいると「やる気だけある人」に見えます。3つに絞る作業は、優先順位を決める作業です。


③ リポジトリの見た目を整える

READMEを書き終えても、その下に並んでいるファイル一覧は見られています。

[スクリーンショット: 03_リポジトリ一覧.png] GitHub でリポジトリのトップを開き、READMEとファイル一覧が両方見えている状態を撮ってください。

消すべきもの

まず、いま何が入っているかを見ます。

bash
$ cd ~/hitokoto
$ git ls-files

この一覧に、こういうものが混ざっていないか見てください。

見つかりがちなものどうするか
note.txt memo_20260901.md やること.txt消す。 作業メモはリポジトリに要らない
test.js test2.js aaa.js消す。 試した残骸
index.html.bak server.js.old消す。 Gitがあるのに手でバックアップを作っているのは、Gitを信じていない印です
node_modules/消す。 .gitignore に入れる。以前の回のとおり、npm install で戻せる
dist/ client/dist/消す。 ビルド結果は作れるもの
.env消す。次の項を必ず読んでください
screenshot.pngdocs/ に移す。トップに画像が散らからないように
.DS_Store Thumbs.db消す。 OSが勝手に作るファイル

消し方です。ファイルは手元に残したまま、Gitの管理から外すなら --cached を付けます。

bash
$ git rm -r --cached node_modules
$ git rm note.txt test.js

.gitignore はこうなります。

bash
$ cat .gitignore
node_modules/
dist/
.env
*.log
.DS_Store
Thumbs.db

そしてコミットします。

bash
$ git add -A
$ git commit -m "chore: 作業用ファイルを整理し .gitignore を見直す"

.env は、消しても履歴に残る

ここは最も重要です。

bash
$ git rm --cached .env
$ git commit -m "chore: .env を管理から外す"

これで、いまのリポジトリからは .env が消えます。 しかし、過去のコミットには残っています。

確かめます。

bash
$ git log --all --oneline -- .env

ここに1行でも出たら、あなたのパスワードは履歴に入っています。 中身も見えます。

bash
$ git show $(git log --all --format=%H -- .env | tail -1):.env

GitHub に push 済みなら、他人も同じことができます。

やるべきことは、履歴を消すことではありません。

履歴の書き換え(git filter-repo など)は可能ですが、その前に、漏れた鍵を無効にしてください。 履歴を消しても、すでにコピーされたものは消せません。

1. DBのパスワードを変える 2. セッションの署名鍵(SESSION_SECRET)を作り直す 3. 外部サービスのAPIキーがあれば、そのサービス側で失効させる 4. そのうえで、履歴を書き換えるか、リポジトリを作り直して1コミット目から出し直す

学習用のリポジトリなら、作り直すのがいちばん速くて確実です。 履歴を惜しんで鍵を残すより、はるかに良い判断です。

コミット履歴も読まれている

READMEの隣に、コミット数と最新コミットのメッセージが出ています。 開けば全部読めます。

bash
$ git log --oneline | head -30

こうなっていませんか。

a1b2c3d wip
9f8e7d6 fix
5c4b3a2 update
2e1d0c9 wip2
8b7a6f5 いろいろ
3d2c1b0 修正

これを読んだ人に伝わるのは、1つだけです。 「この人がどう作ったか、追えない」ということです。コードが良くても、そこに至る過程が読めません。

レビューの回で Conventional Commits に触れました。あれの回収です。

feat(quotes): 引用にページ番号を持たせる
fix(auth): ログアウト後もCookieが残っていたのを修正
docs: READMEに技術選定の理由を追加
chore: node_modules を .gitignore に入れる
refactor(books): 一覧の取得をクエリ1回にまとめる

すでにある wip を、いまから書き換えないでください。

git rebase で過去のメッセージは変えられますが、push 済みの履歴を書き換えると、他の環境と食い違います。 それに、「途中から丁寧になった履歴」は、正直で、悪くありません。

やるのは、今日から次のコミットを変えることです。

そして、main に直接コミットせずPRを通していれば、履歴はさらに読めます。 PRのページに「何をしようとして、何を変えたか」が文章で残るからです。

[スクリーンショット: 04_コミット履歴.png] GitHub の Commits ページで、コミットメッセージが並んでいるところを撮ってください。


④ AIを使ったことを、どう書くか

このアプリ、AIを使って書きましたか。 使ったなら、書いてください。

AIを開発に使う回で、AIが書いた差分を1行ずつ読んで、3つの間違いを見つけました。あの作業が、ここで効きます。

隠す理由がありません。 そして、隠しても分かります。

  • 自分のコードに、説明できない部分がある — 聞かれた瞬間に止まります
  • 書き方が場所ごとに違う — ある関数だけ極端に丁寧、ある関数だけ極端に凝っている
  • 使っていない依存が入っている — AIの回で実際に見つけたやつです

では何を書くか。「AIを使いました」だけでは足りません。

書くべきなのは、何を自分が判断したかです。

docs/how-this-was-built.md を作ります。

bash
$ mkdir -p docs
$ code docs/how-this-was-built.md
# この作り方について

このアプリは、AIアシスタントを使って書きました。
**何をAIに任せ、何を自分で決めたかを書いておきます。**

## AIに任せたこと

- 定型的なコードの下書き(ルーティング、バリデーション、マイグレーション)
- エラーメッセージの意味を調べること
- テストの1本目の骨組み

## 自分で決めたこと

- **テーブルの持ち方**。引用を本に紐づけるか、独立させるかを迷い、
  「本を消したら引用も消える」ほうが自分の使い方に合うと判断して1対多にした
- **認証をセッションにしたこと**。JWT を提案されたが、
  ログアウトで即座に無効化できるほうがこのアプリには合うと判断した(docs/adr/0002)
- **コンテナを使わなかったこと**。nginx と systemd を自分で理解することを優先した(docs/adr/0003)
- **提案された依存を2つ入れなかったこと**。標準機能で足りたため

## 自分で確かめていること

- **入れた差分は、必ず `git diff` を1行ずつ読んでから commit しています**
- **テストが通ることを確認してから push しています**
- **意味の分からないコードは、入れずに書き直しています**

この文章の価値は、「AIを使った」の告白ではありません。 読んだ人に伝わるのは、こちらです。

この人は、選択肢を知っていて、その中から選んでいる。

「JWT ではなくセッションにした」と書ける人は、両方を知っています。 AIに言われたまま JWT にした人は、この行を書けません。同じコードでも、判断の記録があるかどうかで別物になります。

逆に、書いてはいけないこともあります。

書いてはいけないなぜ
「AIは一切使っていません」(嘘)1つでも嘘があると、READMEの他の記述も全部疑われます
「全部AIが書きました」(投げやり)事実だとしても、あなたが何を分かっているかが1つも伝わりません
AIとの会話ログをそのまま貼る長すぎて読まれません。要るのは結論と判断だけです

⑤ 技術選定を、5つの問いで説明する

READMEに1行ずつ理由を書きました。次は、口で説明できるようにします。

紙に書いてください。1問1行です。 長く書けたら、それはまだ整理できていない印です。

問い1: なぜ MySQL か

本1冊に引用が何件もぶら下がる関係で、後から引用だけ消えると困る。
表と外部キーで持つのが素直だと判断した。

弱い答え: 「よく使われているから」「無料だから」。どちらも、このアプリの事情が入っていません。

さらに聞かれます。「PostgreSQL ではなぜダメでしたか?」

ダメではない。この規模なら差は出ない。先に触っていたのが MySQL だった。

「差は出ない」と言えることが、答えです。 無理に MySQL の優位性をひねり出すと、知らないことがばれます。

問い2: なぜセッション認証か

使うのがブラウザ1つだけで、他のサービスからAPIを叩く予定が無い。
ログアウトでサーバー側から即座に無効化できるほうが安全だと考えた。

さらに聞かれます。「JWT だとどうなりますか?」

JWT は「発行済みのものを取り消せない」。ログアウトさせるには
別で無効リストを持つことになり、結局サーバー側に状態が戻る。
複数サービスにまたがるなら JWT が効くが、このアプリにはその相手がいない。

問い3: なぜ React か

本の一覧と詳細で同じデータを使い回すので、状態を1か所に置きたかった。
素のDOM操作だと、更新したときの反映漏れが起きる。

「Vue や Svelte ではなぜダメですか?」

ダメではない。日本語の資料が多く、詰まったときに調べやすいのが決め手だった。

「他でもよかった」と言えるのは、弱さではありません。 他を検討したことの証明です。

問い4: なぜコンテナにしなかったか

nginx と systemd を自分で理解することを優先した。
1台で1アプリなので、環境の差を吸収する必要が無かった。

これは、いちばん聞かれる問いです。 そしていちばん誤解されている問いです。 「Docker を使っていない = 遅れている」ではありません。「なぜ要らなかったか」が言えるかどうかです。

「では、どういうときに使いますか?」

同じものを複数台に配るとき。開発環境と本番の差を消したいとき。
いまは1台で、手順もREADMEに書いてあるので、必要になっていない。

問い5: 次に作り直すなら、何を変えるか

これがいちばん差が出ます。 何も出てこないなら、作っただけで、振り返っていません。

テーブル設計を先に紙で決める。作りながら3回 ALTER TABLE したので。
テストを画面側も最初から書く。あとから足すのが一番つらかった。

この答えは、作った人にしか書けません。 借りてきた知識では出てきません。

練習の仕方: 5つの答えを紙に書いたら、声に出して読んでください。 詰まるところが、まだ言葉になっていない場所です。


⑥ ライセンスを付ける

リポジトリを公開するなら、LICENSE を置いてください。

「特に決めていない = 自由に使える」ではありません。逆です。

ライセンスが書いていないコードは、著作権法上「使ってはいけない」が初期値です。

公開しても、それは「見てよい」だけです。コピーすること、改変すること、自分の製品に組み込むことは、許可されていません。 「自由に使ってほしい」と思っているのに、書いていないせいで逆の意味になっています。

MIT ライセンスを置きます。 いちばん短く、いちばん制限が少ないものの1つです。

bash
$ cd ~/hitokoto
$ code LICENSE
MIT License

Copyright (c) 2026 YOUR NAME

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHER DEALING IN THE
SOFTWARE.

MIT が言っていることは、2つだけです。

  1. 著作権表示とこの許諾文を残せば、あとは何をしてもよい(コピー・改変・販売も含む)
  2. 保証はしない。何か起きても作者は責任を負わない

2つ目が大事です。 「動かなくて損害が出た」と言われても、作者は責任を負わない、と書いてあります。これが無いライセンスは、置かないでください。

Copyright (c) 2026 YOUR NAME の名前は、必ず書き換えてください。 ここが YOUR NAME のまま公開されているリポジトリは、実際によく見ます。

GitHub に認識させます。

bash
$ git add LICENSE
$ git commit -m "docs: MITライセンスを追加"
$ git push

確かめ方: GitHub でリポジトリを開き、右側のサイドバーに「MIT license」と表示されれば成功です。 ファイル名が LICENSE(拡張子なし)や LICENSE.md・LICENSE.txt(大文字・小文字は問いません)で、中身が既知のライセンス文と一致したときに認識されます。ライセンス.md のように名前そのものを変えると認識されません。

[スクリーンショット: 05_ライセンス表示.png] GitHub のリポジトリ画面右側に「MIT license」と出ているところを撮ってください。

MIT 以外を選ぶとき

ライセンスひとことで
MITほぼ何でもよい。 迷ったらこれ
Apache-2.0MITに近いが、特許についても明記されている
GPL-3.0これを使った側も、同じライセンスで公開する義務が生じる

GPL を「強くて安全そう」という理由で選ばないでください。 使う側に義務を課すので、かえって使われなくなります。 学習用のアプリなら MIT で十分です。


⑦ やりすぎない

ここまで書くと、もっと足したくなります。 それを止めます。

READMEに入れないものを並べます。

入れたくなるものやめる理由
バッジを10個並べる見た目が賑やかになるだけで、読む人は1つも見ません。CIの状況とライセンスの2つで十分です
APIの全エンドポイント一覧READMEが3画面ぶんになります。別ファイル(docs/api.md)に出します
DBのテーブル定義を全部同じです。マイグレーションを読めば分かることは書きません
開発の経緯・日記「これは何?」を知りたい人が、いちばん邪魔に感じる部分です。ブログに書きます
絵文字で飾った長い目次短いREADMEに目次は要りません。 目次が必要な長さになったら、切り分ける合図です
「Contributing」「Code of Conduct」一人の学習用リポジトリには不要です。貢献者がいないのにガイドだけあるのは不自然です

目安を1つ。

画面をスクロールして、6回以上動かすなら長すぎます。

長くなったぶんは、docs/ に切り出してリンクします。READMEは目次ではなく、玄関です。


つまずいたところ

この回で実際に詰まったところです。

1. スクリーンショットに、本物のメールアドレスが写っていた

最初に撮った画像は、自分のアカウントでログインした状態でした。画面の右上に、自分のメールアドレスがそのまま出ていました。しかも、それに気づいたのが push した後でした。

画像を差し替えても、Gitの履歴には残ります。 .env と同じです。結局、リポジトリを作り直しました。

いまは、こうしています。

  1. ブラウザを新しいウィンドウで開く(ブックマークバーも他のタブも写らない)
  2. 必ずデモ用アカウントでログインする
  3. 撮った画像を、貼る前に自分で開いて隅々まで見る

2. デモ用アカウントのデータを、自分で壊した

デモ用アカウントで動作確認をしていて、テストのつもりで本を全部消しました。そのまま忘れていました。

数日後、READMEのURLを見た人が開いたら、空の一覧が出ていました。「これは何なのか」が、いちばん伝わらない状態です。

だから cron でシードを毎日流すようにしました。 「気をつける」では、必ずまた起きます。

3. GIF が 38MB になった

ffmpeg でそのまま変換したら、1分の動画が 38MB の GIF になりました。GitHub には上げられましたが、スマートフォンで開くと数秒間まっ白でした。

削り方の効き目は、この順でした。

やったこと結果
長さを 60秒 → 12秒38MB → 8MB。いちばん効く
fps=30 → fps=108MB → 3MB
scale=1280 → scale=8003MB → 1.4MB

「全部の機能を見せる」のをやめたら解決しました。 見せるのは1つの流れだけで足ります。

4. 「使ったもの」を全部書こうとして手が止まった

技術構成の表を書き始めたら、package.json に入っているものを全部書こうとして、20行を超えました。そして、半分は理由が書けませんでした。

書けなかったのは、自分で選んでいないものでした。 チュートリアルで入ったもの、AIが提案したまま入れたもの。

やったこと: 理由が書けないものは、表から消しました。 そして、そのうち3つは、実際に使っていませんでした。

bash
$ npm uninstall <使っていないパッケージ名>

READMEを書く作業が、依存を減らす作業になりました。 これは想定外の副産物でした。

5. LICENSE.txt では認識されない、と思い込んでいた

拡張子を付けると認識されないと思い込み、LICENSE.txt を避けていました。実際には、GitHub は LICENSE.txt も LICENSE.md も認識します。 サイドバーに「MIT license」が出ないときは、名前より先に、中身が既知のライセンス文から書き換わっていないかを確かめてください。

機械が見ているのは、ファイル名の規則と中身の一致です。 どちらも、思い込みではなく現物で確かめます。


まとめ — 理解できたこと

この回で分かったことです。

  • README が無いリポジトリは「未完成」ではなく「読めない」。 動くかどうかとは別の軸で判断されます。そして、判断にかかるのは5分です
  • 順番は「相手が知りたい順」で決まる。 これは何 → どんな見た目 → 触れるか → どう使うか → 何でできているか → なぜそう作ったか → どこまでできているか → この先どうするか
  • 技術の名前を並べても情報にならない。 package.json を開けば分かることだからです。要るのは「なぜそれなのか」の1行で、「流行っているから」は理由にならない
  • 他を選ばなかった理由が言えると、選んだ理由が強くなる。 そして「差は出ないので、先に触っていたほうにした」は、正しい答えです
  • できていないことを書かないと、代わりに全部聞かれる。 具体的に書けば「分かっていて優先順位を決めた人」に、書かなければ「気づいていない人」になります。同じコードで、評価が逆になります
  • リポジトリは中身だけでなく、散らかり方とコミット履歴も見られている。 wip が並ぶ履歴からは、作った過程が読めません
  • .env は消しても履歴に残る。 そして最初にやるのは履歴の削除ではなく、鍵の無効化です
  • AIを使ったことは隠すものではない。 書くべきなのは「何を自分が判断したか」で、それは選択肢を知っている証明になります
  • ライセンスが無いと「自由に使える」ではなく「使えない」になる。 MIT が言っているのは「表示を残せば自由」と「保証しない」の2つだけ
  • READMEは長くしない。 6回スクロールしたら切り出す合図です

ここまでの9段階で、何を持っているか

この記事で、作品を1つ作って公開し、人に見せられる形にするところまでが、ひと区切りつきます。 第9段階はこのあとも続きます(次は CLIツールを配る回です)。

いま、あなたが持っているものを並べます。

段階持っているもの
1. LinuxVMを立てて、コマンドで操作し、権限とプロセスとネットワークを切り分けられる
2. インターネットと道具DNSとHTTPSが何をしているか説明でき、Gitでコードを管理してGitHubに上げられる
3. フロントエンドHTML・CSS・JavaScript が別々の仕事をしていると分かり、Reactで画面を組める
4. バックエンドサーバーが「待ち続けるプログラム」だと分かり、REST APIを設計して認証を付けられる
5. データベーステーブルを設計し、マイグレーションで変更を履歴に残し、トランザクションを使える
6. ミドルウェアnginx・Docker・Kubernetes・Redis を、それぞれ何のためのものか説明できる
7. インフラとDevOpsCIを組み、クラウドに1台立て、監視とログを集め、構成をコードで残せる
8. 深掘り型・テスト・セキュリティ・性能・設計を、道具ではなく判断として扱える
9. 作品企画から公開・運用まで、1つのアプリを自分で通した

いちばん大きいのは、最後の1行です。

チュートリアルを何本やっても、これは手に入りません。「動かないときに、どこを見るか」の勘は、自分のアプリで詰まった回数からしか出てこないからです。

そして、忘れないでほしいことがあります。

未経験のときに一番怖かったのは、「何を知らないかが分からない」ことでした。

いまは違います。知らないものに名前が付いています。 「Kafka はまだ触っていない」「gRPC は1回だけ試した」と言えます。名前が付いていれば、必要になったときに調べられます。


次に何をするか

「完成」は、終わりではありません。

hitokoto は動いています。READMEも書けました。では明日から何をするか。 3つの方向があります。

A. 同じものを、もう一度作り直す

いちばん地味で、いちばん効きます。

「次に作り直すなら何を変えるか」に、あなたはもう答えを持っています。それを実際にやります。

同じ題材だからこそ、差が見えます。 「前より速く作れた」ではなく、「前より迷わなくなった」が分かります。

B. 別のものを作る

題材を変えます。 ただし、知っている技術で作ってください。

新しい題材と新しい技術を同時にやると、詰まったときに、どちらが原因か分かりません。 1つずつです。

C. 深く掘る

1つ選んで、底まで行きます。

やってはいけないこと

やりがちなことなぜ
hitokoto を寝かせたまま、新しい流行を追い始める完成させたものが1つもない状態に戻ります。それが一番もったいない
機能を足し続けて、終わらせない「あと1つ足したら公開する」を繰り返すと、永久に公開されません
全部を同時に始める3つのリポジトリが同時に wip で止まります

1つだけ選んでください。 そして、また README を書けるところまで持っていってください。


参考リンク

最後に1つ。 READMEは、書いて終わりではありません。アプリを直したら、READMEも直してください。 中身と食い違ったREADMEは、無いより悪いです。 読んだ人が、書いてあるとおりに動かして、動かないからです。


次に読む

この記事は 【第9段階】作品を1つ完成させる の 5 / 10 本目です。

記事
← 前の記事公開の前に、戻せることを確かめる — デプロイと運用の入口
→ 次の記事npm publish は取り消せない — CLIツールを配る

上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。

全体の順路は はじめに にあります。

roadmap.sh のどこをやっているか

作品づくりの締め。README と技術選定の説明は roadmap.sh の範囲外。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

コメント

コメントする

目次