ポートフォリオが完成した。あとはREADMEを書くだけ。

……この「だけ」で手を抜くと、作品そのものが読まれずに終わります。

READMEは作品の入口です。
見る側は最初の10秒で、読み進めるかどうかを決めています。

1行目で決まります

添削していて、いちばんもったいないと思うのがここです。

✕「Laravelで作成したWebアプリです」

これだと、何のアプリなのか分かりません。
技術名から始まっていて、読む側が知りたいことが1つも書かれていないんですよね。

○「資格の勉強をしている人が、間違えた問題だけを集めて復習できるWebアプリです」

誰の、何を解決するのか。これを1行目に書きます。

中身が良くても、開かれなければ無いのと同じです。
作品の出来より先に、入口を直してください。

見る側の動き方

  1. GitHubを開く（最初の10秒）→ 何のアプリか分からなければ閉じる
  2. 概要と画面を見る（次の1分）→ 触ってみるか決める
  3. 技術と工夫した点を読む（3分）→ 面接で何を聞くか決める

3番目が大事です。READMEは、面接で聞かれる内容を決めている文書でもあります。
ここに書いたことは、必ず突っ込まれると思ってください。

そのまま使えるテンプレート

以下をコピーして、自分の内容に置き換えてください。
例は、僕が転職活動のときに作った自問自答クイズアプリで書いています。

# アプリ名

（1〜2行で「誰の何を解決するか」）
例：資格の勉強をしている人が、間違えた問題だけを集めて
オリジナルの問題集を作れるWebアプリです。

## URL

https://example.com

### テスト用アカウント
- メールアドレス：test@example.com
- パスワード：password

## 開発の背景

（誰の、どんな困りごとから作ったのか。自分の経験を書く）
例：身近に管理栄養士を目指して勉強している人がいました。
紙の問題集だと、間違えた問題を後から探すのに時間がかかり、
復習が後回しになっていました。
そこで、自分で問題を登録できて、間違えた問題だけを
集めて解き直せる形にしました。

## 主な機能

| 機能 | 説明 |
| --- | --- |
| ユーザー登録・ログイン | Laravel Breezeを使用 |
| 問題の登録・編集・削除 | 問題文と答えを自分で登録できる |
| 間違えた問題だけの出題 | 不正解の問題を集めて再出題 |
| お気に入り登録 | 画面を切り替えずに登録・解除（非同期） |

## 使用技術

- PHP 8.2
- Laravel 11
- MySQL 8.0
- Blade / Tailwind CSS

## ER図

（画像を貼る）

## 工夫した点

- 復習が続かない原因は「探す手間」だと考えたので、
  間違えた問題を自動で集める部分を最優先で作りました。
- お気に入りの登録は、画面全体を読み込み直すと
  勉強のテンポが止まると思い、非同期で処理しています。

## 苦労した点

- お気に入りボタンを押しても反映されない状態が続きました。
  値が届いているか、保存まで来ているかを順番に確認したところ、
  送信先のURLの書き方が間違っていることが分かりました。

各項目のポイント

1. テスト用アカウントは必ず書く

これが無いと、ログイン画面で止まります。
見る側は忙しいので、そこで閉じられて終わりです。

2. 開発の背景に、身近な話を書く

ここが教材のコピーではない証明になります。

大したアイデアである必要はありません。
僕の場合も「彼女が資格の勉強で困っていた」というだけの話です。それで十分です。

3. 機能は4つほどに絞る

機能を10個並べても、評価は上がりません。全部を説明できなくなるだけです。
4つほどに絞って、そのぶん深く作ってください。

4. 苦労した点は、具体的に書く

ここが一番読まれます。採用する側が見たいのは「過程」だからです。

✕ 弱い書き方○ 強い書き方
エラーが多くて大変でしたボタンを押しても反映されず、値が届いているか・保存まで来ているかを順番に確認して、送信先の書き方が原因だと分かりました

詰まらずに作れる未経験なんていません。
詰まった話を書けるほうが、信用されます。

書いてはいけないこと

書かないほうがいいもの理由
技術名から始まる1行目何のアプリか分からない
盛った表現（大幅に効率化など）根拠を聞かれて詰まる
使っていない技術を書く面接で聞かれて即バレる
説明できない機能書いた時点で質問の的になる
長すぎる説明読まれない。要点だけでいい

READMEに書いたことは、全部聞かれると思ってください。
説明できないことは書かないほうが安全です。

READMEを整えても、面接では「動き」を聞かれます

ここは正直に書いておきます。

僕が面接を受けたとき、コードは軽く見られただけでした。
その代わりに聞かれたのがこれです。

このボタンを押したら、どうなっているんですか？

僕は答えられませんでした。「ルートからコントローラーで…」という話しかできませんでした。

つまり、READMEは入口を作るためのもので、そこから先は口頭で説明できるかどうかです。

だからREADMEを書き終えたら、そこに書いた機能について「押したら何が起きるか」を声に出して説明してみてください。
詰まる機能があれば、それが面接で落ちる場所です。

画面のスクリーンショットは入れる

入れてください。文字だけのREADMEは、それだけで読む気が下がります。

  • 一覧画面と、メインの機能が分かる画面の2〜3枚でいい
  • スマホ表示の画像もあると、対応していることが伝わる

完成後のチェックリスト

  • 1行目に「誰の何を解決するか」が書いてある
  • URLとテスト用アカウントが書いてある
  • 開発の背景に、身近な話が書いてある
  • 機能は4つほどに絞ってある
  • 苦労した点が、具体的な手順で書いてある
  • 画面の画像が入っている
  • 書いた機能すべてについて、動きを口で説明できる

よくある質問

Q. ER図は必須ですか？
A. 必須ではありませんが、あると強いです。テーブル設計は面接で必ず聞かれるので、図にしておくと自分の整理にもなります。

Q. 英語で書くべきですか？
A. 日本語で問題ありません。読む相手は日本の採用担当です。

Q. どれくらいの長さがいいですか？
A. スクロール2〜3回で読み切れる程度です。長いと読まれません。

まとめ

  • 1行目に「誰の何を解決するか」を書く。技術名から始めない
  • テスト用アカウントは必ず書く
  • 開発の背景は、身近な話で十分
  • 苦労した点は具体的に。ここが一番読まれる
  • READMEに書いたことは全部聞かれる。説明できないことは書かない

READMEは、作品を読んでもらうための入口です。
中身が良くても、開かれなければ無いのと同じです。

次に読む記事

ポートフォリオの無料添削をしています。READMEも一緒に見ています。LINEから送ってください。