「動きません」だけ投げると解決が遠回りになる — 未経験がAIに渡す"最小再現手順"の作り方

Claude Code と一緒に Next.js + Supabase でアプリを作っていると、ボタンを押しても何も起きない、一覧が更新されない、そういう場面に必ずぶつかります。

そこで多くの未経験者がやってしまうのが、これです。

動きません。直してください。

この一文を投げると、AI はあなたの環境も、あなたが何をしたかも、何が起きたかも分からないまま返事をすることになります。結果、返ってくるのは「どんなエラーが出ていますか？」「どのファイルですか？」「ボタンのコードを見せてください」という質問の連打です。

つまり、AI が答えを出す前に、足りない情報を埋めるための往復が何回も発生します。体感で 4〜5 往復してから、やっと原因の話に入れる。これが「AI に聞いてるのに全然進まない」の正体です。

この記事は、バグの直し方そのものではなく、その一歩手前の 「AI に渡す再現手順（最小再現手順 / MRE）を自分で組み立てる」 スキルに絞って解説します。ここを押さえると、同じ AI でも返ってくる答えの質が変わります。

「動きません」が遠回りになる理由

AI は魔法ではなく、渡された情報から推測して答えるツールです。情報が足りなければ、足りない分を「たぶんこうだろう」で埋めるか、あなたに聞き返すしかありません。

動きません だけの場合、AI 側から見ると分かっているのは次の 1 つだけです。

何かがうまくいっていない（らしい）

これだけで正しい原因を当てるのは、症状を一言も言わずに医者に「治してください」と言うのに近い状態です。だから最初の数往復は、まるまる「状況の聞き取り」に消えます。

一方、後で紹介する 4 項目の再現手順を最初にまとめて渡すと、AI は推測ではなく事実をもとに答えられるので、いきなり原因の候補提示から入れます。

ざっくり傾向で言うと、こういう差になりがちです（往復回数は環境や運によって上下するので、正確な統計ではなく「多い／少ない」の傾向として読んでください）。

動きません だけ → 状況の聞き取りに数往復かかってから、ようやく原因の話（体感 4〜5 往復）
再現手順つき → 1 回目の返信で原因候補が返ってくる（体感 1〜2 往復）

再現手順をまとめる数分が、結局いちばんの近道というのが、この記事で言いたいことの全部です。

AI に渡す「最小再現手順」4項目テンプレ

では何を渡せばいいのか。難しく考えず、次の 4 項目を埋めるだけです。これがそのまま AI へのメッセージになります。

環境（何を使って開発しているか）
やったこと（操作を順番に。番号つきで）
期待した結果（本当はどうなってほしかったか）
実際の結果（実際どうなったか＋出たメッセージをそのまま）

ポイントは 2 と 4 です。「やったこと」は自分の言葉で操作を順番に書く。「実際の結果」はコンソールやターミナルに出た文字をそのままコピペする（要約しない）。この 2 つが、AI が推測で埋めていた穴をふさぎます。

「最小」というのは、その症状を再現するのに必要な最低限の操作だけを書くという意味です。関係ない機能の話まで盛り込むと、逆に AI が混乱します。

悪い例 → 良い例（Supabase insert で一覧が増えない場面）

具体的なシーンで比べます。「追加ボタンを押すと一覧に 1 行増える」はずが、増えない、という未経験あるあるです。

まず、動かそうとしていたコードはこんな感じだとします。App Router のページに追加ボタンを置いて、onClick で Supabase に insert する典型的なパターンです。

// app/page.tsx
'use client'

import { createClient } from '@supabase/supabase-js'

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
)

export default function Page() {
  const handleAdd = async () => {
    // title を渡さずに insert してしまっている
    const { data, error } = await supabase.from('todos').insert({})
    console.log('data:', data)
    console.log('error:', error)
  }

  return <button onClick={handleAdd}>追加</button>
}

悪い例（再現情報ゼロ）

動きません。直してください。

これだと AI は、そもそも Supabase を使っているのか、ボタンを押したのか、エラーが出ているのかすら分かりません。返ってくるのは「エラーメッセージはありますか？」「どのコードですか？」で、あなたはそこから 1 つずつ答えることになります。往復が増える典型です。

良い例（4項目の最小再現手順）

同じ状況を、4 項目で埋めるとこうなります。このまま 1 メッセージで送ります。

【環境】
- Next.js（App Router）/ Node 20 / Supabase
- Claude Code で開発中の未経験です

【やったこと（順番）】
1. /app/page.tsx に「追加」ボタンを置いた
2. ボタンの onClick で supabase.from('todos').insert(...) を呼んだ
3. ブラウザで「追加」ボタンを押した

【期待した結果】
- 押すと一覧に1行増える

【実際の結果（そのままのメッセージ）】
- 一覧は増えなかった
- ブラウザのコンソールに error として次が出た:
  null value in column "title" of relation "todos" violates not-null constraint

【お願い】
上の再現手順で「実際の結果」になる原因の候補を、可能性が高い順に3つ。
それぞれ「確認する場所」と「直し方」をセットで教えてください。

この 1 通が渡ると、AI は推測を挟まずに答えられます。実際、上のメッセージのエラー文（null value in column "title" ... violates not-null constraint）は Supabase（PostgreSQL）が返す代表的なもので、意味は 「title 列は空にできない設定なのに、空のまま insert しようとした」 です。

だから返ってくる答えも、いきなり本題に入れます。

候補1：insert に title を渡していない → insert({ title: '入力値' }) のように値を渡す
候補2：そもそも title に入れる入力欄がない → フォームの value を state で管理して渡す
候補3：title を任意にしたい → Supabase 側で列の NOT NULL 制約を外す or デフォルト値を設定する

動きません では数往復かけてやっとここに着いたのに、4 項目テンプレなら最初の 1 返信でここまで返る。差はテンプレを埋める数分だけです。

慣れてきたら：期待と実際を「1行ずつ」書く

もう一歩だけ精度を上げるコツがあります。「期待した結果」と「実際の結果」を、同じ粒度で 1 行ずつ対応させて書くことです。

【期待】ボタンを押す → todos テーブルに1行 insert される → 一覧の再取得で1件増える
【実際】ボタンを押す → insert が error を返す（title の not-null 制約）→ 一覧は0件のまま

こう書くと、どのステップで期待と現実がズレたかが AI にも自分にも一目で分かります。今回なら「insert される」で止まっていて、その先の「一覧が増える」まで到達していない、と特定できます。ズレた場所が分かれば、AI に「そのステップだけ」を深掘りしてもらえるので、さらに往復が減ります。

これは AI のためだけじゃなく、自分がバグを言語化する練習にもなります。慣れると、テンプレを埋めている途中で「あ、title 渡してないわ」と自分で気づくことも増えてきます。

まとめ

動きません だけ渡すと、AI は状況を推測で埋めるしかなく、聞き取りの往復が増える
遠回りを防ぐのは、最小再現手順（MRE）を 1 メッセージで渡すこと
テンプレは 4 項目：環境／やったこと（順番）／期待した結果／実際の結果（メッセージそのまま）
「やったこと」は操作を番号で、「実際の結果」は出た文字をコピペで。要約しない
慣れたら「期待」と「実際」を 1 行ずつ対応させて、ズレたステップを名指しする
再現手順を作る数分が、結局いちばんの近道

バグを直すテクニックより先に、**「AI に渡す再現手順を自分で組み立てる」**という前段のスキルを身につけると、これから先どんなエラーに当たっても、AI との往復がぐっと短くなります。

未経験者向けの講座を運営しています

未経験から 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 読者の方には易しすぎる内容なので、初心者の知り合いへの紹介や社内研修の参考としてどうぞ。