AIに環境構築の手順を書かせる｜動かない時の切り分け方
新しく入ったプロジェクトで、まずは手元で動かすところから。README は少し古そうなので、AIに「このリポジトリの開発環境を作る手順を教えて」と聞いてみました。
きれいな手順が返ってきます。インストール、依存の取得、設定ファイルのコピー、起動。上から順にコマンドを打っていくと——4つ目あたりで、赤い文字がずらっと出て止まりました。
エラーをそのままAIに貼ると、別のコマンドを勧められる。打つと、今度は別のエラー。気づけば1時間、まだ画面は一度も立ち上がっていない。
ここで自分を責めなくて大丈夫です。環境構築は、AIがいちばん「あなたの机の上」を知らない作業です。手順が悪いのでも、あなたの腕が悪いのでもなく、AIが想定した環境と、実際の環境のあいだに差があるだけのことがほとんどです。
この記事では、AIに環境構築・セットアップの手順を書かせるときの渡し方と、動かないときの切り分け方を整理します。
結論：順番は3つです。①揃える——手順を頼む前に、OS・言語やツールのバージョン・プロジェクトの設定ファイルをAIに渡し、「どの環境向けの手順か」を先に決める。②確かめる——手順は1段ずつ実行し、段ごとに「成功したと分かる確認」を挟む。止まったら、どの段で止まったかからAIに相談する。③残す——動いた手順を、実際に打ったコマンドと確認結果のままREADMEやメモに残す。
覚え方は 揃える → 確かめる → 残す。①がないと手順が別の環境向けになり、②がないと止まった場所が分からず、③がないと次の人が同じところで止まります。
今日ぜんぶやる必要はありません。次にAIへ手順を頼むとき、自分のOSとバージョンを最初の一行に書くだけでも、返ってくる手順はかなり変わります。
何が起きているのか——AIは「どこかの誰かの机」を想定している
打ち手の前に、なぜAIの環境構築手順はつまずきやすいのかを整理します。原因の側を見ておくと、何を渡せばいいかが見えてきます。
1つ目は、AIがあなたのOSを知らないこと。Windows、macOS、Linux、それに WSL のように Windows の中で Linux を動かす形もあります。パスの書き方、パッケージの入れ方、改行コード、権限の扱いは、OSごとに少しずつ違います。何も言わなければ、AIは「よくある環境」を想定して書きます。
2つ目は、バージョンの前提がずれていること。言語本体、パッケージマネージャ、データベース、コンテナの実行環境。AIの知識は少し前で止まっているので、今は名前や手順が変わったものを、以前のやり方で書くことがあります（AIの知識は少し前で止まる｜古い情報で最新仕様を扱う注意点）。プロジェクトが古いバージョンに固定されている場合は、逆に新しすぎる手順が出てくることもあります。
3つ目は、プロジェクト固有の事情が見えていないこと。バージョンを固定するファイル、依存の一覧、コンテナの定義、.env のひな形。答えの多くはすでにリポジトリの中に書いてあるのに、それを見せずに聞くと、AIは一般論で埋めます（既存コードにAIを馴染ませる文脈の渡し方｜実務の型）。
4つ目は、全部の手順を一気に打ってしまうこと。10個のコマンドを続けて打って10個目で止まると、本当の原因が3つ目にあっても、見えるのは10個目のエラーです。途中で「成功したか」を確かめていないと、どこから崩れたのかが追えません。
5つ目は、エラーを貼るたびに手当てが上書きされていくこと。AIに言われて入れたもの、消したもの、設定を変えたもの。試したことが積み重なるほど、環境は最初の状態から離れていきます。気づくと、何が効いて何が効いていないのか分からなくなります（AIとの修正ループが終わらない｜堂々巡りから抜ける手順）。
裏を返すと、これは渡し方と進め方の問題です。前提をそろえて、1段ずつ確かめる。それだけで、止まったときに「どこで・なぜ」が見えるようになります。
具体例——つい、こうなりがちという形
どれも「早く動かして本題に入りたい」という前向きな気持ちから生まれます。心当たりのある行があれば、そこだけ見れば十分です。
- 「このリポジトリの環境構築手順を教えて」とだけ聞く：OSもバージョンも書いていないので、AIは一般的な手順を返します。あなたの環境で動くかどうかは、運しだいになります。
- バージョン固定ファイルを見ずに最新版を入れる：プロジェクトは少し前のバージョンで固定されているのに、手元には最新版が入っている。起動はするのに、テストだけ落ちる、という分かりにくい形で出ることがあります。
- エラーの最後の1行だけを貼る：いちばん下の行は結果で、原因はたいてい少し上に書いてあります（AIにビルド・実行エラーの原因を解説させる｜検索より速い直し方）。
- 管理者権限で押し切る：権限エラーが出たので、管理者権限をつけて打ち直す。その場は通っても、あとで別の場所で権限のずれが出ることがあります（AIにコマンドを書かせて事故らない｜破壊的コマンドを弾く確認の型）。
- AIに勧められたパッケージをそのまま追加する：「このライブラリを入れれば直ります」と言われて入れたら、プロジェクトの依存に余計なものが増えていた（AIが提案するライブラリを鵜呑みにしない｜依存追加前の確認）。
- 設定ファイルに本物の鍵を書いてAIに貼る：
.envをそのまま貼って相談し、APIキーや接続情報が会話に残る（AIに設定ファイルを生成させる｜秘密情報の混入を防ぐ手順）。 - 動いたあと、何をしたか覚えていない：やっと画面が出た。ただ、途中で何を入れて何を変えたのか、もう一度やれと言われても再現できない。
影響——手順が残らないと、次の人も同じ場所で止まる
急いで全部直さないと大変、という話ではありません。ただ、あとから効いてくる種類の問題なので、書いておきます。
- 本題に入る前に1日が終わる：環境構築で止まると、その日の予定がまるごと後ろにずれます。新しく入った人ほど、ここで自信を削られがちです。
- 「自分の環境だけ動く」が生まれる：試行錯誤で通した環境は、チームの他の人の環境と少しずつ違います。あとで「自分のところでは再現しない」の原因になります。
- 不具合の原因が環境なのかコードなのか分からなくなる：環境がずれていると、テストの失敗がコードのバグなのか、環境の差なのかの切り分けに時間がかかります（AIに障害の再現手順を整理させる｜報告と切り分けを速く）。
- 次に入った人が同じ場所で止まる：READMEが古いままだと、同じエラーに、同じ時間をかけることになります。
少し安心できる話をすると、この領域は打ち手がはっきりしています。高度な知識は要りません。前提を先に渡して、1段ずつ確かめて、動いた手順を書き残す。それだけで、止まる回数も、止まったときの時間も、ぐっと減ります。
明日からやること（揃える・確かめる・残す）
上から順に、小さく始められます。今日は①だけでも構いません。
1. 揃える——手順を頼む前に、環境の前提を渡す
AIに手順を頼む前に、「どの机の上で動かすのか」を伝えます。
- OSと、その版を書く。Windows なのか、WSL の中なのか、macOS なのか、Linux なのか。CPUの種類（Intel系か Apple Silicon などの ARM 系か）で入れ方が変わるツールもあるので、分かれば添えます。
- いま入っているバージョンを、実際に確かめて書く。「たぶん入っている」ではなく、言語本体やツールのバージョン確認コマンドを打って、出てきた結果をそのまま渡します。
- プロジェクトの「答えが書いてあるファイル」を見せる。バージョンを固定するファイル、依存の一覧、コンテナの定義、
.envのひな形、既存の README。AIに一般論ではなく、このプロジェクトの前提で書いてもらうためです。 - 秘密情報は伏せてから渡す。
.envの中身を見せるなら、キーや接続先の値はxxxに置き換えて、項目名だけ見せれば十分です。 - 公式の手順があるなら、それを優先する。ツールや言語の公式ドキュメントに導入手順があれば、AIの手順はそれと食い違っていないかを見る材料にします。AIには「公式手順と違う点があれば、理由を添えて」と頼めます。
2. 確かめる——1段ずつ実行し、止まった段から相談する
手順は、上から一気に打たずに段に分けて進めます。
- 段ごとに「成功したと分かる確認」をAIに書かせる。「インストールしたら、このコマンドでバージョンが表示される」「依存を入れたら、このフォルダができる」。確認があれば、どこまで進めたかが目で見えます。
- 1段打ったら、確認して、次へ。確認が通らなかったら、その段で止まって、次には進みません。原因が1段の中に閉じているうちに見るほうが、ずっと楽です。
- 止まったら、「どの段で・何を打って・何が出たか」を渡す。エラーは最後の1行だけでなく、出力をまとめて貼ります。長すぎるときは、最初と最後、それに「Error」「failed」などが出ている周辺を残します（スタックトレースをAIに読ませる｜バグ調査を速くする渡し方）。
- AIには、直す前に「原因の候補」を出してもらう。いきなり次のコマンドをもらうより、「考えられる原因を3つ、確かめ方と一緒に」と頼むと、手当てが積み重なって環境が崩れていくのを防げます。
- 消す・上書きする・管理者権限で打つコマンドは、一呼吸おく。そのコマンドが何を変えるのか、元に戻す方法はあるかを先に聞いてから打ちます。
- 2〜3回で直らなければ、いったん戻る。試したことを並べて、最初の「揃える」に戻り、前提の書き漏らしがないかを見直します。最初からやり直すほうが早いこともよくあります。
3. 残す——動いた手順を、打ったとおりに書き残す
動いたら、忘れないうちに書き残します。ここはAIが得意なところです。
- 実際に打ったコマンドを、打った順に並べる。途中で試して効かなかったものは除き、最終的に効いた手順だけにします。ターミナルの履歴を見返すと漏れが減ります。
- 段ごとの確認もいっしょに残す。「ここでこう表示されれば成功」があると、次の人が自分で進み具合を確かめられます。
- つまずいた場所と、その直し方を「よくある詰まり」として添える。自分が止まった場所は、次の人もたぶん止まります。
- AIにREADME の形へ整えてもらい、差分で見る。書き直されたREADMEが、もともとの記述を消していないか、実際にはやっていない手順を足していないかを確かめてから反映します。
- OSやバージョンを明記する。「この手順は○○の環境で確認した」と、確かめた環境と日付を一行残しておくと、古くなったときに気づけます。
AIに相談するときのプロンプト（コピーして使えます）
前提を渡さないと、AIは「よくある環境」の手順を返してきます。環境を先に書くこと、段ごとに確認を入れることを、最初に伝えるのがコツです。
開発環境のセットアップ手順を作る手伝いをお願いします。
①下の環境情報とプロジェクトのファイルをもとに、この環境向けの手順を書いてください。一般的な手順と違う点があれば、理由を添えてください。
②手順は段に分けて、各段に「成功したと確認できるコマンドと、期待される表示」をつけてください。
③プロジェクトのファイルでバージョンが固定されている場合は、それに合わせてください。分からない点は推測で埋めず、「要確認」として質問の形で挙げてください。
④削除・上書き・管理者権限を使うコマンドには印をつけ、何が変わるのかと、元に戻す方法を添えてください。
⑤公式ドキュメントの手順と食い違う可能性があるところは、「公式で確認してください」と明記してください。
OS（版・CPUの種類）：（ ） 入っているツールとバージョン（確認コマンドの結果そのまま）：（ ） プロジェクトのファイル（バージョン固定・依存一覧・コンテナ定義・READMEなど。秘密の値は伏せる）：（ ） ゴール（例：開発サーバーが立ち上がり、テストが通る）：（ ）
途中で止まったときは、こう続けます。
②の手順の○段目で止まりました。打ったコマンドと、出力をそのまま貼ります。すぐ直すコマンドではなく、考えられる原因を3つまで、それぞれの確かめ方と一緒に挙げてください。
「原因を先に」の一文が効きます。次から次へコマンドをもらうのをやめるだけで、環境が崩れていくのを防げます。
出てきた手順は、次の3点だけ自分の目で確かめます。（1）プロジェクトで固定されたバージョンと、手順のバージョンが合っているか、（2）削除・上書き・管理者権限のコマンドに、印と戻し方がついているか、（3）「要確認」の点を、推測のまま進めていないか。
環境構築をAIと進めるチェックリスト（コピーして使えます）
全部に○が要るわけではありません。気になった行だけで十分です。
① 揃える
- OS（版・CPUの種類）をAIに伝えたか
- 入っているツールのバージョンを、確認コマンドで実際に見て渡したか
- バージョン固定ファイル・依存一覧・README をAIに見せたか
-
.envなどの秘密の値は伏せてから渡したか - 公式ドキュメントの手順と食い違っていないか見たか
② 確かめる
- 手順を段に分け、段ごとの確認をつけてもらったか
- 1段ずつ実行し、確認が通ってから次へ進んだか
- 止まったとき、段・コマンド・出力をまとめて渡したか
- 直すコマンドの前に、原因の候補を出してもらったか
- 削除・上書き・管理者権限のコマンドは、何が変わるか確かめてから打ったか
- 2〜3回で直らないとき、前提に戻って見直したか
③ 残す
- 最終的に効いたコマンドだけを、打った順に残したか
- 段ごとの確認も一緒に書いたか
- つまずいた場所と直し方を添えたか
- AIが整えたREADME を差分で確かめてから反映したか
- 確かめた環境と日付を一行残したか
この記事のまとめ
AIの手順で環境構築が止まるのは、手順やあなたの腕のせいではなく、AIが想定した環境と実際の環境に差があることから生まれます。
やることは3つ。①揃える——OS・バージョン・プロジェクトのファイルを先に渡して、どの環境向けの手順かを決める。②確かめる——1段ずつ実行し、段ごとの確認を挟み、止まったらその段から原因の候補を聞く。③残す——動いた手順を、打ったとおりに確認つきで書き残す。
AIに相談するときは、「直すコマンドより先に、原因の候補を」と一言添える。それだけで、試行錯誤が積み重なって迷子になるのを防げます。
赤い文字が出て止まったとき、まず自分の打ち間違いを疑ったと思います。実際には、あなたは言われたとおりに打っていて、AIがあなたの机の上を知らなかっただけでした。
環境構築は、一度で通すことを求められる作業ではありません。前提を渡して、1段ずつ確かめて、通った道を書き残す。その書き残しが、次にこのプロジェクトに入る人の最初の1時間を、まるごと助けます。
今日は、次にAIへ手順を頼むとき、最初の一行に自分のOSとバージョンを書く。そこから始めれば、止まったときも、どこで止まったかがちゃんと見えるはずです。
よければ、こちらも
- エラーの読ませ方はAIにビルド・実行エラーの原因を解説させる｜検索より速い直し方
- 古い手順が出てきたらAIの知識は少し前で止まる｜古い情報で最新仕様を扱う注意点
- 危ないコマンドの見分け方はAIにコマンドを書かせて事故らない｜破壊的コマンドを弾く確認の型
- 設定ファイルの扱いはAIに設定ファイルを生成させる｜秘密情報の混入を防ぐ手順
- コンテナで環境をそろえるならAIに書かせたDockerfile｜イメージ肥大と脆弱性の確認
- 堂々巡りになったらAIとの修正ループが終わらない｜堂々巡りから抜ける手順
- バージョンを上げるときはAIにライブラリのバージョンアップを任せる｜破壊的変更の追い方