2026-05-07 · code

Claude Codeで個人サイトを2つ作って分かった「プロンプト設計の失敗パターン」3つ

Claude Codeで2サイトを作った結果、見えてきた失敗の構造

私は2024年から2025年にかけて、Claude Codeを使って2つのサイト（urisol.com と urinosuke.com）を構築しました。両サイトともAstro + Cloudflare Pages + Content Collections という構成で、ブログ記事の自動生成・投稿スクリプトまで含めて実装しています。

Claude Codeは「自然言語で指示を出せば勝手にコードを書いてくれる」という触れ込みですが、実際に使ってみるとプロンプトの設計ミスが直接的に手戻りコストになることを痛感しました。特に失敗が目立ったのは次の3パターンです。

1. 曖昧な指示による「想定外の実装」

最初のサイト構築で、私は「ブログ記事のカテゴリ分けをしたい」という指示を出しました。このとき「どのカテゴリを作るか」「カテゴリごとに色分けするか」「一覧ページにフィルタを付けるか」といった仕様を明示せず、「よしなにやって」と丸投げしてしまいました。

結果、Claude Codeは「category: string」のフィールドだけを作り、カテゴリ一覧ページもフィルタ機能もなし。後から「やっぱりカテゴリごとの一覧ページが欲しい」と追加指示を出すと、既存のルーティング設計と衝突して大幅な書き直しになりました。

『LLMのプロンプトエンジニアリング』（オライリー・ジャパン）では、この種の失敗を**「スカフォールディング不足」**と呼んでいます。つまり、AIに渡す指示の骨組み（前提・制約・期待する出力形式）が曖昧だと、AIは「最も一般的な実装」を選ぶため、後から仕様変更のコストが跳ね上がるのです。

私が学んだのは、曖昧な指示は「手戻り負債」を積む行為だということ。特にルーティング・データ構造・UIコンポーネントの設計は、最初に明示的な仕様（「カテゴリは5つ固定」「各カテゴリページのURLは /category/[slug] 形式」など）を渡すべきでした。

2. コンテキスト不足による「過去の実装の忘却」

2つ目のサイト（urinosuke.com）を作るとき、私は「1つ目のサイトと同じ構成でいい」と思い、urisol.com のコードを参照させずに「Astro + Cloudflare で動くブログを作って」とだけ指示しました。

すると、Claude Codeは urisol.com とはまったく異なるディレクトリ構成を生成しました。コンテンツの置き場所、スタイルの管理方法、ビルドスクリプトの書き方がすべて違う。結果、2サイト間でコードを使い回せず、メンテナンスコストが2倍になりました。

『実践Claude Code入門』（技術評論社）では、この問題に対して**「Claude.md によるプロジェクト固有のコンテキスト管理」**を推奨しています。つまり、プロジェクトのルートに Claude.md を置き、「このプロジェクトのディレクトリ構成はこう」「使うライブラリはこれ」「命名規則はこう」といった前提を書いておけば、Claude Codeは毎回そのコンテキストを参照して一貫性のあるコードを生成してくれます。

私は urisol.com で Claude.md を作らず、urinosuke.com でも作らなかったため、2つのサイトが「同じツールで作った別物」になってしまいました。今は両サイトに Claude.md を追加し、共通部分は明示的に参照するよう設計し直しています。

3. 検証不足による「動くけど壊れやすいコード」の積み上げ

最も痛かったのは、Claude Codeが生成したコードをそのまま信じて次の実装に進んでしまったことです。

例えば、ブログ記事の自動投稿スクリプト（generate-post.py）を作ったとき、私は「記事のメタデータをフロントマターに埋め込む」という指示を出しました。Claude Codeは期待通りのコードを生成し、1回の実行では正常に動きました。

ところが、後日「カテゴリを2つ指定したい」という要件を追加したとき、フロントマターのパース処理が壊れました。原因は、最初の実装が「カテゴリは必ず1つ」という前提でハードコードされていたため。私が最初の時点で「カテゴリが0個/1個/2個の場合をテストする」という検証をしていれば、設計段階で気づけたはずです。

『生成AIのプロンプトエンジニアリング』（オライリー・ジャパン）では、LLM生成コードに対する**「評価設計」の重要性を繰り返し強調しています。つまり、AIが生成したコードは「動く」ことと「正しい」ことが一致しないため、エッジケース・境界条件・例外処理を人間が意図的にテストしなければならない**のです。

この失敗から、私は「Claude Codeに実装させたら、必ず3パターン以上の入力でテストする」というルールを自分に課すようになりました。特にデータ構造の変更（カテゴリ追加、フィールド追加など）が絡む場合は、既存コードの前提が壊れていないか必ず確認します。

プロンプト設計の失敗は「技術的負債」そのもの

この3つの失敗パターンに共通するのは、プロンプトの曖昧さ・コンテキスト不足・検証不足が、そのまま技術的負債として積み上がるという点です。

Claude Codeは「コードを書く速度」を劇的に上げてくれますが、「正しい設計を選ぶ判断」は人間が担わなければなりません。私の場合、2サイトを作る過程で次のような対策を取るようになりました。

指示の具体化: 「よしなに」ではなく、仕様・制約・期待する出力形式を箇条書きで明示する
Claude.md の整備: プロジェクト固有のコンテキスト（ディレクトリ構成・命名規則・使うライブラリ）を文書化し、毎回参照させる
3パターンテスト: 実装後、正常系・境界条件・例外系の3パターンで動作確認する

これらは『達人プログラマー』（オーム社）が説く**「DRY原則」「直交性」「信頼性」**といった普遍的な設計原則と何も変わりません。Claude Code時代でも、プログラマが「何を書かないか」「どこまで検証するか」を判断する責任は変わらないのです。

まとめ：失敗パターンを言語化すれば次は避けられる

Claude Codeで2サイトを作って分かったのは、プロンプト設計の失敗は再現性があるということです。曖昧な指示・コンテキスト不足・検証不足は、誰がやっても同じ手戻りを生みます。

逆に言えば、失敗パターンを言語化して対策を立てれば、次のプロジェクトでは避けられます。私は今、3つ目のサイト構築を計画していますが、今度は最初から Claude.md を書き、仕様を箇条書きで明示し、実装後に3パターンテストを回す設計にしています。

Claude Codeは「書く速度」を上げてくれますが、「正しく書く判断」は人間の仕事です。失敗から学んだパターンを次に活かせるかどうかが、AI時代のプログラマの分かれ目だと感じています。

参考

← ブログ一覧へ戻る