「動いた」と「公開できる」の間には深い谷がある
Claude Codeで自分のサイトを作り始めたとき、私は「AIに任せれば簡単だろう」と思っていました。確かに最初のプロトタイプは驚くほど早く形になりました。しかし、実際に公開可能なサイトにするまでには、想定外の壁が次々と現れました。
今回は「Claude Code × AI駆動開発を学ぶ実用書5冊」で紹介したような理論ではなく、実際に私が遭遇した5つの具体的な障害と、どうClaudeと対話して解決したかを記録します。これから同じ道を歩む方の参考になれば幸いです。
壁その1：Content Collectionsの型定義エラー
AstroのContent Collectionsを使い始めて最初にぶつかったのが、型定義とMarkdownフロントマターの不一致でした。Claudeが生成したスキーマとMarkdownファイルのフィールド名が微妙にずれており、ビルド時に大量のエラーが出ました。
解決までの対話：
- 「エラーログをそのまま貼り付けて原因を聞く」
- 「既存のMarkdownファイルをすべて示し、共通のスキーマを提案してもらう」
- 「slug生成ルールを明示的に定義してもらう」
非エンジニアの私には「型安全性」という概念自体が新鮮でしたが、Claudeとの対話を通じて「フロントマターは契約書」という理解に至りました。この段階で、AIに「なぜこうなるのか」を説明させることが重要だと学びました。
壁その2：画像最適化とビルド時間の爆発
記事に画像を追加し始めたとき、ビルド時間が10分を超えるようになりました。原因はAstroの画像最適化機能がすべての画像を毎回処理していたこと。開発サーバーの起動すら苦痛になりました。
解決までの対話：
- 「ビルドログから画像処理の部分を抽出して見せる」
- 「開発環境では最適化をスキップする設定を提案してもらう」
- 「Sharp（画像処理ライブラリ）のキャッシュ設定を調整してもらう」
Claudeは最初、公式ドキュメント通りの回答をしてきましたが、「実際のビルド時間とファイル数を示して、実用的な妥協点を探してほしい」と伝えたところ、環境変数で切り替える現実的な設定を提案してくれました。
壁その3：カテゴリフィルタリングのロジック
当初、記事のカテゴリは単一選択の想定でコードを書いていました。しかし運用を始めると「ndtとbizの両方に該当する記事」が頻出し、配列対応が必要になりました。すでに公開済みの記事があったため、後方互換性を保ちながらの移行が課題でした。
解決までの対話：
- 「既存の全記事のフロントマターを例示し、移行方針を相談」
- 「文字列と配列の両方を受け入れるスキーマを提案してもらう」
- 「カテゴリページのフィルタリングロジックを配列対応に書き換えてもらう」
このとき、Claudeに「段階的な移行プラン」を立ててもらったのが正解でした。一気にすべてを変更せず、まずスキーマを柔軟にし、次に新規記事から配列形式に移行、最後に古い記事を更新という流れで無事に完了しました。
壁その4：RSS フィードの文字化けと日時フォーマット
RSSフィードを実装したとき、日本語のタイトルが文字化けし、pubDateのフォーマットもRFC 822に準拠していないエラーが出ました。ブラウザでは問題なく表示されていたので、最初は気づかずにいました。
解決までの対話：
- 「RSSバリデーターのエラーメッセージをそのまま貼る」
- 「Astroの@astrojs/rss の公式ドキュメントを参照しながら修正を依頼」
- 「日本語タイトルのエンコーディングをUTF-8で明示的に設定してもらう」
この問題は、私が「動いているから問題ない」と思い込んでいたケースでした。Claudeに「標準仕様に準拠しているか確認して」と依頼したことで発覚し、修正できました。AIの強みは「仕様書を正確に参照できること」だと実感しました。
壁その5：Vercelデプロイ時の環境変数とビルドコマンド
ローカルでは完璧に動くサイトが、Vercelにデプロイした瞬間にビルドエラーを起こしました。原因はNode.jsのバージョン違いと、環境変数の設定漏れでした。
解決までの対話：
- 「Vercelのビルドログ全文を貼り付けて診断を依頼」
- 「package.jsonにNode.jsバージョンを明記してもらう」
- 「必要な環境変数のリストと、Vercel設定画面での設定方法を説明してもらう」
この段階で、私は「ローカル環境とデプロイ環境は別物」という基本を学びました。Claudeには「チェックリスト形式でデプロイ前の確認項目をまとめて」と依頼し、以降のデプロイでは同じミスを繰り返さずに済みました。
AIとの対話で学んだ「質問の技術」
これらの壁を乗り越える過程で気づいたのは、「エラーをそのまま投げる」だけでは不十分だということです。効果的だった質問パターンは以下の通りです：
- エラーログ + 期待する動作 + 現在の設定ファイル全体
- 「なぜこうなるのか」の説明を求める
- 複数の解決策を提示してもらい、それぞれのメリット・デメリットを聞く
- 段階的な移行プランを立ててもらう
非エンジニアだからこそ、「わからないことをわからないまま進めない」姿勢が重要でした。Claudeに教師役を担ってもらうことで、単なるコピペ実装ではなく、理解を伴った構築ができました。
まとめ — 壁は学習の機会になる
Claude Codeで自サイトを作る過程は、予想以上にトラブルの連続でした。しかし、それぞれの壁が新しい知識を身につける機会になりました。
「非エンジニアに毛が生えたVT検査員」だった私が、型定義やビルドプロセス、標準仕様について語れるようになったのは、これらの壁を一つずつ乗り越えたからです。
もしあなたがこれからClaude Codeでサイト構築を始めるなら、壁にぶつかることを恐れないでください。そのたびにClaudeに質問し、説明を求め、理解を深めていけば、確実に前進できます。
次回は、これらの経験を踏まえた「Claude Codeとの効果的な対話パターン」について書く予定です。