はじめに
以前「バイブコーディングで静的サイトを作って気づいたこと」という記事を書きました。「作れることと保守できることは別の話」という内容で、Zennにも投稿しています。
あれを書いた後も開発を続けていて、もう少し踏み込んだところでハマりました。今回はその話です。
「うまくいった話」の続きなので、失敗談になります。3つあります。
失敗パターン①：Claudeがだんだん記憶をなくす
長いセッションを続けていると、Claudeが前に決めたことを忘れ始めます。
具体的にはこういう症状が出ます。
修正したはずのミスが再発する
直したと確認したコードが、次の作業でまた同じ状態に戻っている。
以前確認したファイルパスやクラス名を間違える
セッション序盤で決めたルールを、後半で参照するときに誤って読み取る。
「このルールはこうでしたっけ？」と聞き直してくる
すでに決定済みの事項を再確認してくる。会話の前半の情報が薄れているサイン。
最初は「なんか今日の精度おかしいな」と感じる程度です。でもよく考えると、1時間以上同じ会話を続けていて、直前の作業しか覚えていない状態になっていました。
理由は単純で、AIには「コンテキストウィンドウ」という会話の記憶の上限があります。会話が長くなると、序盤の内容は自動的に圧縮されていく。最初に決めたルールや判断が、知らないうちに薄まっていく。
対策は2つです。1つ目は、1つの作業で会話を区切る習慣をつけること。「今日は全部終わらせよう」と長引かせるほど状態が不安定になります。
2つ目は、CLAUDE.md を「記憶の補強ファイル」として育てること。毎回の会話の冒頭でClaudeが読むので、セッションが変わっても重要なルールは引き継がれます。コンテキストが失われても、ファイルが補完してくれる仕組みです。
Claudeのせいにしていたミスが、実は「会話の長さ」の問題だったと気づいてから、作業の区切り方を変えました。
失敗パターン②：ルールファイルは育てないと腐る
最初にCLAUDE.mdを作ったとき、「ルールを一度書いておけば大丈夫」と思っていました。でも実際は、ファイルやページが増えるにつれて、仕様書の方がだんだん現実と食い違ってきます。
このサイトではCLAUDE.mdはあくまで入口で、具体的なルールはテーマごとに別ファイルに分けています。ページのレイアウト規約、デザイン方針、SEO対策、カテゴリー定義…と複数のMDファイルが存在しています。問題はこのファイル群全体で起きます。
あるタイミングで全体を読み直したら、こんな問題が出てきました。
CSSのパス名が古いファイル名のまま誤記されていた
途中でファイルを整理してパスが変わったのに、ルールファイルの記述が更新されていなかった。
コメントの意味が逆になっていた
「やってはいけない」という意図で書いたコメントが、読むと「やること」に読めてしまう文章になっていた。
同じルールが複数のファイルに分散して矛盾していた
片方を更新したときにもう片方が古いまま残り、2つのファイルで内容が矛盾する状態になっていた。
ルールファイルだけでなく、実際のHTMLページにも影響が出ていました。リニューアル前の旧方式で作られたページが数ページそのまま残っていて、新方式のページと混在していた。ルールが古いままだったので、Claudeも古い方式を参照して作り続けていました。
どれも「書いた時点では正しかった」ものです。でもサイトが育つにつれて、その後の変更が追いつかなくなっていた。
構造的な原因は「ルールファイルが増えるほど、全体を把握しにくくなること」です。細かくファイルに分けるのは正しい方向ですが、管理コストも一緒に増えます。気づかないうちに同じルールが複数の場所でバラバラに管理されて、少しずつズレていく。
AIはルールファイルを忠実に読んで動くので、ファイルに間違いがあればその通りに間違えます。「Claudeがおかしな動きをする」と思ったら、実はルールファイルの方がおかしかった、というケースが何度もありました。
対策は「節目での読み直し」です。毎回やる必要はないし、ページを追加するたびに見直すのも現実的ではありません。
自分の場合、こういうタイミングで入れました。
30ページ前後
ルールファイル全体を通し読みして、現状との食い違いを修正。
50ページ前後
SEO対策の見直しとあわせてルールも再確認。
開発18日目
ルールMDファイルだけを対象に「矛盾していないか」の専用チェックを実施。コードは一切見ずにルールファイルだけを読んで矛盾を探すもので、「コメントの意味が逆になっていた」「2つのファイルで内容が矛盾していた」問題がここで見つかりました。
ページ数でも経過日数でも、区切りを決めてしまえばいい。「なんか最近Claudeの動きがおかしい」と感じたときも見直しのサインです。
失敗パターン③：デモとサンプルコードが静かにズレる
このサイトの事例ページには「デモ」と「サンプルソース」の2つがあります。デモは実際に動くもの、サンプルソースはコピペ用のコードです。
AIは複数の箇所を独立して生成するので、この2つが知らないうちに乖離します。
発覚のきっかけは、自分でサンプルコードをコピペして使おうとしたときでした。デモは動く。でもコードをコピーして貼り付けると動かない。
よくあったのがJSONデータの読み込みパスのズレです。ルールでは data/data.json という場所にデータファイルを置くことになっていて、サンプルソースもそのパスで書かれていました。でも実際のデモは違うパスの、別のファイル名のJSONを読み込んでいた。デモの中だけで完結する動きになっていて、サンプルコードとは別物になっていました。
ページを眺めているだけでは気づきません。実際に使おうとして初めてわかる。
これの厄介なところは、事例ページが増えるほど確認が追いつかなくなることです。
対策として check-sample.js というスクリプトを作りました。サンプルコードをファイルに書き出して、実際のデモのソースと diff 比較するものです。一気に全ページをチェックできるので、ズレているページをまとめて発見できます。
解決方法がコードになったのは、この問題だけです。自動化できない問題は手順で解決してきましたが、これは「目視で追いきれなくなった量の問題」だったので、スクリプトで補いました。
まとめ
3つ並べてみると、共通点があります。どれも「AIに任せきりにしていた部分」で起きました。
会話の管理をAIに任せていた
→ コンテキスト喪失。1つの作業で会話を区切る、CLAUDE.mdで補強する。
仕様書のメンテをAIに任せていた
→ ルールファイルが腐る。節目で人間が読み直す。
コードの整合性チェックをAIに任せていた
→ デモとサンプルのズレ。スクリプトで機械的に検出する。
バイブコーディングは「作る速度」を上げてくれますが、「確認・管理・整合」は人間側の仕事として残ります。
うまくいっている今は「どこを自分がやるかを最初から決めている」状態です。AIに全部やらせようとするほど、後で手戻りが増えます。任せる範囲を絞って、止まって確認する場所を設計に組み込む。
最初の記事で「作れることと保守できることは別の話」と書きました。この3つはその続きで、「保守するために自分がやるべきことを決めた話」です。
最後まで読んでいただきありがとうございました。