Next.js + Supabase + Claude Code で初めてのアプリが動いた。うれしいですよね。でも、そのリポジトリを別のPCにcloneして、READMEだけ見て手順どおりに動かしたら、ちゃんと立ち上がりますか？

たぶん、立ち上がらないです。

READMEを「自分があとで思い出すためのメモ」だと思っている人は、実はそこで実績を1つ損しています。せっかく作ったアプリが「書いた本人のPCでしか動かないもの」になってしまうからです。逆に言うと、READMEを「初めて見た他人が手元で動かすための最短手順書」に書き直すだけで、同じアプリが「人に渡せる実績」に変わります。

実際に自分は毎日Claude Codeを回してアプリを作っていますが、他人に渡す前に READMEだけは必ず「他人視点」で書き直させています。今日はその書き直しを、悪いREADME → 良いREADMEへの Before/After で1本、実際の手順どおりに見せます。網羅はしません。狙いは「clone → ローカルで動く」の一点だけです。

Before：自分だけが動かせるREADME

まず、未経験のうちに書きがちな「悪いREADME」を見てください。実際にこれをコピペしている人、かなり多いです。

# ToDoアプリ

npm run dev で動きます。

これ、書いた本人は動きます。もう環境が全部そろっているからです。でも初めてcloneした人は、

  • Nodeのバージョンが古くてエラー
  • .env.local が無くてSupabaseに接続できず画面が真っ白
  • そもそも npm install を先にやると書いていない

……で、ほぼ100%動きません。前提が全部「あなたの頭の中」にあって、READMEに出ていないからです。

そしてこのREADMEには、もっと本質的な問題があります。他人（レビューする人、採用担当、勉強仲間）は、コードより先にREADMEを見るということです。ここで動かせなかったら、中身を見てもらう前に離脱します。「後で書けばいい」の「後で」に来たとき、その人はもう帰っています。READMEは、あなたのアプリに他人が最初に触れる唯一の入口なんです。

After：初めての他人が動かせるREADME

同じアプリのREADMEを、他人視点で書き直すとこうなります。

# ToDoアプリ

Next.js + Supabase で作ったToDoアプリです。

## 必要なもの
- Node.js 20 以上
- Supabase のプロジェクト（無料枠でOK）

## 環境変数
プロジェクト直下に `.env.local` を作り、以下を設定してください。
値は Supabase の「Project Settings → API」から取得できます。

NEXT_PUBLIC_SUPABASE_URL=（あなたのProject URL）
NEXT_PUBLIC_SUPABASE_ANON_KEY=（あなたのanon key）

## セットアップ手順
1. npm install
2. 上記のとおり .env.local を作成
3. npm run dev
4. ブラウザで http://localhost:3000 を開く

## 動かないときに最初に見る場所
画面が真っ白なら、まず .env.local の2つの値が入っているか確認してください。

Before との違いは、派手なことは何もしていません。埋めたのは3つだけです。

  • 前提：Nodeのバージョン、Supabaseのプロジェクトが要る、と最初に書いた
  • 値の取得場所：環境変数を「どこから取ってくるか」まで書いた（.env.local が無いと真っ白、が一番ハマる）
  • 手順の順番：npm install → .env.local → npm run dev と、実行する順にそのまま並べた

この3つが埋まっているかどうかだけで、他人のPCで動くか動かないかが決まります。

やりすぎ注意：After を「盛りすぎ」て壊さない

ここで一度、逆方向のワナに触れておきます。「丁寧にしよう」と思うと、今度はこう膨らませたくなります。

  • なぜSupabaseを選んだか
  • 認証の設計思想
  • 今後の拡張予定

……これを上のほうに足すと、肝心の「で、どうやって動かすの？」が埋もれて、結局また他人は動かせません。READMEの主役は設計背景ではなく、再現手順です。

判断基準はシンプルで、「これを消したら、他人が動かせなくなるか？」だけ。

  • 動かせなくなる → 残す（Nodeのバージョン、環境変数、コマンドの順番）
  • 動かせても関係ない → 消すか、READMEの下のほう・別ファイルへ（設計思想、将来の構想、こだわりポイント）

未経験のうちは「詳しさ＝親切」と思いがちですが、他人にとっての親切は「迷わず動かせること」です。設計を語りたくなったら、それは動かす手順を全部書き終えた後、下のほうに回します。

この書き直しを、Claude Codeに一番速くやらせるプロンプト

Before → After を自分で1から書いてもいいのですが、自分で書くと、どうしても「自分の環境では動くこと」が前提に混ざります。だから他人視点を持っているClaude Codeに書かせるのが速くて、抜けも少ないです。

ただし丸投げすると「詳しく全部書く」方向に膨らむので、視点と範囲を指定するのがコツです。実際に自分が投げているプロンプトの骨子がこれです。コピペして使えます。

このリポジトリを「初めてcloneした人」が、手元で動かせるREADMEを書いてください。

条件:
- 前提の Node.js バージョンを明記
- 必要な環境変数を列挙（値は伏せ字にして、取得場所も書く）
- セットアップ手順を番号付きで、コマンドを実行する順番どおりに
- 最後に「動かないときに最初に確認する場所」を1つだけ添える

設計の背景や将来の構想は書かないでください。「動かすために必要なこと」だけに絞ってください。

このプロンプトが効くポイントは3つです。

  1. 「初めてcloneした人が」 と主語を他人にする → 自分の環境前提が消える
  2. 「値は伏せ字・取得場所を書く」 と指定する → キーの漏洩を防ぎつつ、他人が自分の値を入れられる
  3. 「設計背景は書くな」 と範囲を切る → 手順だけの読みやすい After になる

最後の1手：別フォルダにcloneして自分で踏む

出てきた After を、最後に自分でもう一度だけ検証します。ここを飛ばす人が多いのですが、一番効きます。

やることは1つ。いま作業しているフォルダとは別の場所に、そのリポジトリをcloneし直して、READMEの手順だけを上から順に踏む。同じフォルダで確認すると node_modules も .env.local も残っているので「動いてるつもり」になりますが、それは他人のPCの状態ではありません。まっさらな別フォルダで踏むと、「あ、環境変数の取得場所を書き忘れてた」がここで必ず1個出ます。

cd ~/tmp
git clone <あなたのリポジトリURL> readme-check
cd readme-check
# ここから先は README に書いた手順だけを、上から順にやる

これで詰まらず http://localhost:3000 まで行けたら、はじめて「他人が動かせるREADME」です。詰まったら、詰まった場所がそのまま README の抜けなので、そこを1行足して終わりです。

まとめ：READMEは「実績を渡せるかどうか」の分かれ道

やったことを振り返ると、たったこれだけです。

  • Before（自分だけ動かせる）→ 前提・値の取得場所・手順の順番が全部「頭の中」にある
  • After（他人が動かせる）→ その3つを外に出し、盛りすぎず、動かす手順だけに絞る
  • 書くのは Claude Codeに「初めてcloneした人視点で」 指定して任せる → 速くて抜けが少ない
  • 最後に 別フォルダでcloneして自分で踏む → 残った抜けが1個必ず見つかる

全部つながっているのは、「書いた本人だけが動かせる」状態のままだと、そのアプリは実績として人に渡せないということです。逆に、READMEを他人視点で書き直すだけで、同じ成果物が「渡せる実績」に変わる。手を動かす量はほんの数十分、でも損得の差は大きいです。

今日アプリが1つ動いたなら、上のプロンプトでREADMEを1回書き直して、別フォルダでcloneして踏んでみてください。それだけで、そのアプリの価値が変わります。

面談なしで、今日から始められます

この講座は 未経験から Next.js + Supabase + Claude Code で Webアプリを作って公開するまで を全20セッションで体系化した教材付きプランです。無料相談を挟まず、申し込んだその日から教材で学習を始められます。AIが学習パートナーになって何度でも質問でき、つまずいた所だけチャットで直接サポートします。

  • 今日から始める（教材完全版＋月5,500円・チャット質問し放題・いつでも解約OK）→ https://menta.work/plan/20251?ref=menta-knowledge
  • いきなりは不安な方へ：無料の教材体験版もあります（最初の数セッション分）→ プラン詳細をご覧ください