「話題のClaude Code、実際どんな感じなんだろう？」

そう思った私は、まずは概要をつかむテストとして、ターミナルでこんなプロンプトを投げてみました。

「Astroで多言語（3言語以上）のサイトを構築したい。Claude Codeで開発する上でやっておいたほうがよい設定なども含めて一緒に進めて」

私としては、「1ステップずつ内容を確認しながら、対話形式で一緒に進めていこう」というつもりだったのです。

※ 本記事の検証は、以下のバージョンに基づいています。

しかし、Claude Codeの解釈は違いました。「一緒に進めて」という言葉を受け取ったClaude Codeは、気を利かせてくれたのか、プロジェクトの初期化から多言語設定、ファイル生成まで、こちらの確認を挟むことなく猛スピードで作業を進めていきます。

途中で止める（Ctrl + C等）こともできたのですが、今回はテストだし「これもこれで勉強か」と思い、一旦最後まで走らせてみることにしました。

結果、画面の中を駆け抜けて完成したのは、自分の理解が一切追いついていない巨大なコード群。「完成しました！」と言われてブラウザを開いてみても、どの設定がどう効いているのかさっぱりわからず、やはり自分が思っていた開発体験とは全く違いました……。

「これじゃ開発の主導権が握れないし、修正したいときの『手戻り』がすさまじいことになる……！」

この体験を経て、「なぜAIが勝手に最後まで進んでしまったのか」「どう指示を出せば自分がハンドリングしながら段階的に作れるのか」を調べてみました。今回は、私と同じようにAIの挙動に戸惑った人に向けて、「1歩ずつ確認しながら手戻りを防ぐ」実践的な設定とプロンプトの工夫を共有します！

1. Claude Codeで手戻りが起きた原因と対策

調べてみてわかったのですが、手戻りが発生する最大の原因は「一気に完成させようとしたこと」と「AIが今何をしているかわからなくなっていたこと」でした。

AIは会話（コンテキスト）が長くなると、最初に出した指示やルールを忘れてしまう癖があります。これらを防ぐために効果的だとわかったのが PLAN.md（プラン・エムディー） を使う方法です。

PLAN.md とは？AIと共有する旅のしおり

PLAN.md は、プロジェクト内に置く「やることリスト（タスクメモ）」のことです。いきなりコードを書かせるのではなく、まず「どんな手順でサイトを作るか」の計画書をAIに書かせるのがよさそうです。

# サイト構築プラン

- [x] Step 1: プロジェクトの初期設定
- [ ] Step 2: ヘッダーとフッターの作成
- [ ] Step 3: 多言語ルーティング（i18n）の設定
- [ ] Step 4: メインページのレイアウト作成

作業を進める際、AIに「1つのタスクが終わるごとに、PLAN.mdのチェックボックスを更新してね」と指示するようにしてみます。これなら、AIも自分も「いま全体のどこにいて、次は何をするか」を見失わずに進められそうです。

2. 手戻りを防ぐための3つのガードレール

開発に入る前に、AIが変な方向に暴走しないための「ガードレール」を設定しておくのが大切だとわかりました。次にサイトを作る時は、以下の3つを準備して挑もうと思っています。

① CLAUDE.md の作成（ルールのメモ帳）

CLAUDE.md は、Claude Codeが作業を開始するときに自動で読み込むルールブックです。プロジェクトのルート（一番上のフォルダ）に置いておくことで、毎回ルールを守らせることができるようです。

【書いておこうと思っているルールの例】

  • 使用するフレームワークやツール（例：Astro, Tailwind CSS）
  • 「一度に全部作らず、1つの機能を作ったら必ず確認を取ること」という命令
  • エラーが出たときの対処法

② Skills の活用（安全チェックボタン）

「Skills（スキル）」は、AIに『このコマンドを実行して安全チェックを行って』と教えておく仕組みです。

本来なら自分でターミナルを叩いてコードの文字間違い（型チェックなど）を確認する必要がありますが、これを設定しておくとAIが自らエラーがないか確認してくれるようになります。壊れたコードの放置を防ぐために、ぜひ取り入れてみたい機能です。

③ 1機能ごとの保存（Gitコミット）

AIに「1つの作業が終わったら、必ずファイルを保存（コミット）してね」と頼むルールも徹底してみます。こうしておけば、もしAIが失敗しても「1分前の正常な状態」に一瞬で巻き戻せるので、安心して任せられそうです。

3. 次回試したいプロンプトテンプレート

調べた情報をもとに、手戻りを防ぐためのプロンプトを4つのステップに分けて準備してみました。次回はこの手順で指示を出してみる予定です。

Step 1: PLAN.md（計画書）を作成させる

いきなりコードを書かせず、まずは設計と計画だけを依頼してみます。

【試してみるプロンプト】
今からAstroを使った多言語サイトを構築します。
まだコードは書かないでください。
まずは要件を整理し、開発手順を小分けにした PLAN.md を作成してください。
各タスクは30分〜1時間程度で完了する小さな単位（チェックボックス形式）に分割してください。

Step 2: 1ステップだけ実行させる

計画ができたら、あえて1回につき1タスクだけを進めさせてみます。

【試してみるプロンプト】
PLAN.md の最初の未完了タスク（例：Step 1 プロジェクトの初期化）だけを実行してください。
注意ルール:

  • 今回指示したタスク以外は絶対に手を出さないでください。
  • 完了したら、変更内容の解説と動作確認手順を教えてください。
  • 完了後、PLAN.md のチェックボックスを更新してください。

Step 3: 安全確認（型チェック・ビルド）をさせる

コードを書いてもらった直後に、エラーが起きていないか検証させます。

【試してみるプロンプト】
実装ありがとうございます。
コードに構文エラーや型の不整合がないか、npm run build（または astro check）を実行して確認してください。
エラーが発生した場合は勝手にコードを書き換え改悪せず、エラー原因と修正方針をまず私に説明してください。

Step 4: 状態を保存（コミット）させる

問題なく動作することが確認できたら、状態を固定します。

【試してみるプロンプト】
動作確認が完了しました。
変更内容をわかりやすいコミットメッセージとともに Git にコミットしてください。
（例：git commit -m "feat: i18nの基本ルーティングを設定"）

4. まとめ：AIを新人エンジニアとして伴走させる

一つのプロンプトでAIに完成まで一気に走られてしまった経験から、Claude Codeとの付き合い方が少し見えてきました。

AIは魔法の道具ではなく、「指示出しと確認が不可欠な新人エンジニア」のように捉えるのがよさそうです。

  1. ルールを共有する (CLAUDE.md)
  2. 作業計画を立てる (PLAN.md)
  3. 1タスクずつ任せて、そのつど確認・保存する

このステップを意識して、次回のWebサイト構築にチャレンジしてみようと思います。
実際にこの方法でうまく構築できたところは継続、改善すべきところは改善して、より良い開発体験を目指していきます。