自分で書いたWebアプリのREADMEを、自分の頭の記憶を一切使わずに「文字に書いてあることだけ」で上からたどって、まっさらな環境で動かせるか試したことはありますか。
私は Next.js + Supabase で作った個人アプリで、これを実際にやってみました。別のディレクトリに git clone し直して、README の文章だけを頼りに頭から実行する。ルールはひとつだけ。「自分の環境の記憶を使わない。READMEに書いていないことはやらない」。
結果、アプリが動くまでに「READMEに書いていないのに、当たり前のようにやっていた手順」が 4つ 出てきました。この記事はその4つを1つずつ潰して、再現に必要な手順の"抜け"を 4 → 0 にするまでの実測記録です。
未経験の方が「作ったのに、なぜか他の人（や明日の自分）が動かせない」で詰まる原因のほとんどが、この"暗黙の前提"です。狭く、そこだけを深掘りします。
なぜ「自分の環境」ではREADMEの抜けに気づけないのか
自分が普段使っている環境には、READMEに書いていない前提が大量に住み着いています。
- Node のバージョンはとっくにインストール済み
-
.env.localは最初に一度書いたきり、中身を忘れている - Supabase のテーブルは開発中に手で作ったので、SQL がどこにも残っていない
-
npm run devを叩けば動くのが「体に染みついている」
この状態で自分の環境でもう一度動かしても、当然すべて動きます。抜けているのに気づけない。だから「クリーンな環境で、記憶を使わずに再現する」という縛りが要ります。
やり方はシンプルです。
# 普段の作業ディレクトリとは別の場所に、まっさらに clone し直す
cd ~/tmp
git clone https://github.com/自分/自分のアプリ.git clean-test
cd clean-test
# ここから先は「READMEに書いてあること」だけを実行する
そして README を上から1行ずつ実行し、詰まった瞬間にメモを取る。これだけです。以下、実際に詰まった4箇所です。
抜け① Node のバージョン指定がない
READMEには npm install としか書いていませんでした。私の環境は Node 20 系ですが、それはどこにも書いていない。
クリーンな環境（別バージョンの Node が入っている前提）で npm install すると、こういう警告や失敗が出ることがあります。
npm warn EBADENGINE Unsupported engine {
npm warn EBADENGINE package: 'next@...',
npm warn EBADENGINE required: { node: '>=18.18.0' },
npm warn EBADENGINE current: { node: 'v16.20.0', npm: '8.19.4' }
}
install は通っても、後で npm run dev した時に別のエラーで落ちる、という一番たちの悪いパターンです。原因が Node のバージョンだと、初心者はまず気づけません。
直し方は2つ。まずリポジトリに .nvmrc を置いて、使うバージョンを1行で宣言します。
20
これで nvm use がバージョンを合わせてくれます。あわせて package.json に engines を書いて、意図を明示します。
{
"engines": {
"node": ">=20.0.0"
}
}
そして README にこの1行を足します。
## 前提
- Node.js 20 系（`.nvmrc` あり。`nvm use` で切り替えてください）
「動く Node のバージョン」は、あなたの頭の中では確定していても、READMEには存在しない情報です。
抜け② .env.local に何のキーが要るか書いていない
Supabase を使うので .env.local に接続情報が要ります。ところがREADMEには「.env.local を作ってください」としか書いておらず、中に何のキーを、どこから取ってくるのか が一切ありませんでした。
クリーンな環境では .env.local そのものが存在しない（.gitignore で除外しているので当然）ため、npm run dev するとこうなります。
Error: Your project's URL and Key are required to create a Supabase client!
これは「接続先が空だよ」というエラーですが、初心者には何を埋めればいいのか分かりません。
直し方は、.env.example という「答えの入っていない見本」をリポジトリにコミットしておくことです（値は空にする＝秘密は絶対にコミットしない）。
# .env.example （これはコミットしてよい。中身は空）
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
そして README に「どこから取るか」まで書きます。ここが一番抜けやすい。
## 環境変数
1. `cp .env.example .env.local`
2. Supabase ダッシュボード → 対象プロジェクト → Settings → API を開く
3. `Project URL` を `NEXT_PUBLIC_SUPABASE_URL` に貼る
4. `anon public` キーを `NEXT_PUBLIC_SUPABASE_ANON_KEY` に貼る
「キー名」だけでなく「取得場所（画面のどこ）」まで書いて、初めて他人が再現できます。
抜け③ テーブルを作る SQL の適用手順がない
これが一番大きな抜けでした。私は開発中、Supabase の画面から手作業でテーブルを作っていました。だから git clone しただけの環境には テーブルが1つも存在しません。
READMEの手順どおり npm run dev してアプリを開き、データを表示しようとするとこうなります。
{
"code": "42P01",
"message": "relation \"public.todos\" does not exist"
}
42P01 は「そのテーブル無いよ」という PostgreSQL のエラーコードです。clone しただけでは DB が空なので、当然こうなります。
直し方は、テーブルを作る SQL をファイルとしてリポジトリに残し、適用手順を書くことです。まず supabase/schema.sql にスキーマを置きます。
-- supabase/schema.sql
create table if not exists public.todos (
id uuid primary key default gen_random_uuid(),
title text not null,
is_done boolean not null default false,
created_at timestamptz not null default now()
);
そして README に「このSQLをどこで流すか」を書きます。一番かんたんなのは、Supabase ダッシュボードの SQL Editor に貼って実行する方法です。
## データベースの準備
1. Supabase ダッシュボード → SQL Editor を開く
2. `supabase/schema.sql` の中身をコピーして貼り付ける
3. `Run` を押して実行する（これでテーブルが作られます）
自分の頭の中にしかない「手で作ったテーブル」を、ファイル + 適用手順として外に出す。これで初めて再現できます。
抜け④ 初期データ・起動後の手順がない
テーブルまで作れても、アプリを開くと真っ白でした。理由は、1件もデータが入っていないから。私の環境には開発中に自分で入れたデータがあって、それが「動いている」感覚を作っていただけでした。
またポート番号（http://localhost:3000 を開く、など）もREADMEに書いておらず、初見の人は「起動したあと、どこを見ればいいの？」で止まります。
直し方は、動作確認用の最小データを流すSQLと、起動後にどこを見るかを書くことです。
-- supabase/seed.sql （動作確認用の最小データ）
insert into public.todos (title) values
('最初のタスク'),
('動作確認用のサンプル');
README にはこう足します。
## 起動
1. `npm run dev`
2. ブラウザで http://localhost:3000 を開く
3. （任意）`supabase/seed.sql` を SQL Editor で流すと、サンプルが表示されます
「起動したその先、何が見えたら成功なのか」まで書いて、ようやく他人が「動いた」と判断できます。
抜けを洗い出すのに使ったプロンプト
この4つの抜けは、私が全部自力で見つけたわけではありません。詰まるたびに、Claude Code に READMEそのものをレビューさせる と一気に洗い出せました。コピペできる粒度で置いておきます。
まず、こういう漠然とした頼み方だと表面的な指摘しか返ってきません。
悪い例:
このREADMEを分かりやすくして
これだと「見出しを整えました」で終わって、肝心の"抜け"は埋まりません。次のように、再現テストという行為で・観点を指定して 頼むと精度が上がります。
良い例:
このREADMEを、リポジトリを一切知らない人がクリーンな環境で
上から実行して動かせるかどうか、という観点でレビューして。
特に、私が暗黙の前提にしていそうな次の4点が README に明記されているか
チェックして、抜けていたら「READMEにこう1行足す」という追記案を出して:
1. Node など実行環境のバージョン指定
2. .env.local に必要なキー名と、その取得場所（画面のどこか）
3. DBスキーマ（テーブル作成SQL）の適用手順
4. 起動後にどこを見れば成功か / 動作確認用の初期データ
追記案は、そのまま README に貼れる Markdown で出して。
観点を4つに絞って渡すのがポイントです。「良い感じにして」ではなく、チェック項目を自分で指定する。何がREADMEから抜けやすいかを言語化して渡すほど、返ってくる追記案の質が上がります。
再現テストは「抜け0になるまで」1回では終わらない
大事なのは、修正したら もう一度クリーンな環境で頭からやり直す ことです。1回直して満足すると、直したつもりで別の抜けが残っています。
# 修正を push したあと、また別のまっさらな場所で clone し直す
cd ~/tmp
rm -rf clean-test
git clone https://github.com/自分/自分のアプリ.git clean-test
cd clean-test
# READMEの文字だけで、また上から実行する
私の場合、抜け4個を直した後の2周目で「seed の手順の順番が env より前に書いてあって流せない」という5個目が見つかり、順番を直しました。詰まりが0回になるまで回す。ここまでやって「再現できるREADME」になります。
指標にすると分かりやすいです。
- 1周目: 詰まり 4回（Node / env / スキーマ / 初期データ）
- 2周目: 詰まり 1回（seed の順番）
- 3周目: 詰まり 0回 ← 完成
まとめ
- 自分のアプリのREADMEを クリーンな環境 + 記憶を使わない縛り で再現すると、暗黙の前提が数で見える
- よく抜けるのは4点: ①実行環境のバージョン ②環境変数のキー名と取得場所 ③DBスキーマの適用手順 ④初期データ・起動後の確認方法
- 各抜けは「READMEにこの1行を足す」で潰せる。
.nvmrc/.env.example/schema.sql/seed.sqlをリポジトリに残すのが効く - Claude Code には「クリーンな環境で他人が再現できるか」という観点＋チェック項目を指定してレビューさせると洗い出しが速い
- 1回で終わらせず、詰まり0回になるまでクリーン再現を回す
「動くものを作れた」の次にある壁が、この「自分以外が動かせる状態にする」です。ここを一度きちんと通しておくと、明日の自分も、チームの誰かも、同じ手順で動かせるようになります。
未経験者向けの講座を運営しています
未経験から Next.js + Supabase + Claude Code で Webアプリを作って公開するまで を、全20セッションで体系化した教材です。Claude Code を学習パートナーにする CLAUDE.md / Skills 設計までセットで含みます。
- 無料体験版（git clone してすぐ動く・最初の数セッション分・⭐ Star もよろしくお願いします）→ https://github.com/ayies128/next-ai-camp-trial
- 教材完全版＋月5,500円のメンタリング（全20セッション＋チャット質問し放題）→ https://menta.work/plan/20251?ref=qiita
- YouTube『AIエンジニア情報局』（AI×開発ニュースを1本5分でキャッチアップできる別運営チャンネル・無料）→ https://www.youtube.com/channel/UC1rXVD9WYsQPQEWZyd-A1KA/?ref=qiita
※ Qiita 読者の方には易しすぎる内容なので、初心者の知り合いへの紹介や社内研修の参考としてどうぞ。新メンバーのオンボーディングでも、この「クリーン環境で再現できるREADMEか」を1本通すだけで初期セットアップの詰まりがかなり減らせます。