Vibe Codingで作ったPoCを引き継ごうとしたら、1週間溶けた話

 はじめにVibe Coding、楽しいですよね。
Claude Codeに「こんな感じで作って」と伝えるだけで、AWSのリソースを使ったアプリがサクサク出来上がっていく。自分でコードを書く量は激減して、PoCなんてあっという間に完成する。
…と思っていた時期が、僕にもありました。
一人で作ったPoCを別の担当者に引き継ごうとしたら、新環境でアプリが動かない。原因を調べようにも、Vibe Codingで作ったからコードの中身を自分でも把握していない。結局、原因解明に約1週間溶かしました。
この記事では、何が起きたのか、なぜ時間がかかったのか、そしてどうすれば防げたのかを共有します。
 何を作っていたかClaude Codeを使って、一人でPoCを開発していました。
構成はこんな感じ：
Amazon DynamoDB – データストア
Amazon Bedrock Agent – LLMを使った処理
Amazon Cognito – 認証
典型的なサーバーレス構成です。Vibe Codingでガンガン作って、旧環境（開発用AWSアカウント）ではちゃんと動いていました。
 事件：新環境で動かない引き継ぎのタイミングで、新環境（別のAWSアカウント）にデプロイして動作確認をしました。
動かない。
エラーは出るけど、原因がよくわからない。Claude Codeにデバッグさせても、的を射た回答が返ってこない。
「コードを読めばわかるでしょ」と思うかもしれませんが、Vibe Codingで作ったので自分でもコードの詳細を把握していないんですよね。どこを見ればいいかすらわからない。
 原因：AIが勝手に書いたフォールバック値結局、新環境と旧環境のデプロイ後の挙動の違いをClaude Codeに分析させて、やっと原因がわかりました。AWSのリソースやCloudWatchログを片っ端から参照させた結果です。
原因は環境変数のフォールバック値でした。
// ※ 以下はAIが生成した例示コードです。実際のコードとは異なります。

// config.ts
export const config = {
  dynamoTableName: process.env.DYNAMO_TABLE_NAME || "dev-user-table",
  bedrockAgentId: process.env.BEDROCK_AGENT_ID || "ABCD1234EF",
  cognitoUserPoolId: process.env.COGNITO_USER_POOL_ID || "ap-northeast-1_XyZ123",
  cognitoClientId: process.env.COGNITO_CLIENT_ID || "1a2b3c4d5e6f7g8h9i0j",
};
AIが「環境変数が設定されていない場合に備えて」と気を利かせて、フォールバック値を書いていたんです。
旧環境では、たまたまこのフォールバック値が指すリソースが存在していたので動いていた。でも新環境では別のAWSアカウントなので、当然そんなリソースは存在しない。だから動かない。
しかもエラーメッセージを見ても「リソースが見つかりません」としか出ないから、環境変数の問題だと気づけなかった。
 なぜ1週間もかかったのか正直に言います。
自分がコードをほとんど読まなかったからです。
Vibe Codingの快適さに甘えて、AIが生成したコードをちゃんと確認していませんでした。だから問題が起きたときに「どこを見ればいいか」がわからない。
Claude Codeにデバッグさせても、ピンポイントで原因に辿り着けない。結局、新旧環境の挙動の違いをCloudWatchログレベルで比較させて、やっと「あ、ここか」となりました。
Vibe Codingで楽をした分、トラブル時のツケを払わされた感じです。
 引き継ぎ相手も困っていた自分だけじゃなく、引き継ぎ相手も困っていました。
コード量が多くて、全体像を把握する時間が足りない
どこが重要なコードなのかわからない
ドキュメントもない
最終的にAIにアーキテクチャ図を生成させて、やっと自分でも全体像がなんとなくわかった状態でした。コードだけ渡されても、正直自分でも説明できない。
これは引き継ぎとして完全に失敗です。
 教訓：Vibe Codingで引き継ぎを壊さないためにこの経験から得た教訓を共有します。
 1. AIには必要最小限の仕事だけさせる「あると便利かも」でコードを追加させない。依頼していない機能を勝手に実装されると、把握できないコードが増えるだけ。
 2. Agent.md（CLAUDE.md）で余計なことをさせない制御プロジェクトルールを明文化しておく。特に「やってはいけないこと」を書いておくのが重要。
 3. コードレビューを徹底するAIが生成したコードであっても、人間によるレビューは不可欠です。これにより、不要なコードや潜在的な問題を早期に発見し、コードの品質を維持することができます。
<!-- ※ 以下はAIが生成した例示です。プロジェクトに応じてカスタマイズしてください。 -->

# プロジェクトルール

## 環境変数
- 環境変数にフォールバック値（デフォルト値）を絶対に書かない
- 環境変数が未設定の場合は明示的にエラーを出すこと
- 環境変数の一覧は `.env.example` に記載し、常に最新化する

## コード規模
- 実装は必要最小限にする。「あると便利かも」で追加しない
- 1ファイル300行を超えたら分割を検討する
- 使われていないコードは即削除する

## ドキュメント
- アーキテクチャ図（`docs/architecture.md`）を常に最新に保つ
- 新しいAWSリソースを追加したら、必ずアーキテクチャ図を更新する
- READMEのセットアップ手順は、新環境で動くことを前提に書く

## やってはいけないこと
- ハードコードされた認証情報・リソースID
- 「とりあえず動く」ための回避策（後で必ず負債になる）
- 依頼されていない機能の追加
 3. 環境変数はフォールバック値なしで即エラーにする今回の問題を防ぐなら、こう書くべきでした：
// ※ 以下はAIが生成した例示コードです。実際のコードとは異なります。

// config.ts
const requireEnv = (key: string): string => {
  const value = process.env[key];
  if (!value) {
    throw new Error(`環境変数 ${key} が設定されていません`);
  }
  return value;
};

export const config = {
  dynamoTableName: requireEnv("DYNAMO_TABLE_NAME"),
  bedrockAgentId: requireEnv("BEDROCK_AGENT_ID"),
  cognitoUserPoolId: requireEnv("COGNITO_USER_POOL_ID"),
  cognitoClientId: requireEnv("COGNITO_CLIENT_ID"),
};
これなら環境変数が未設定のとき、すぐにエラーで気づける。
 4. ドキュメントを自動生成・自動更新する仕組みを作るコードだけでは引き継ぎできない。アーキテクチャ図やREADMEは必須。
できればコードの変更に合わせて自動更新される仕組みを作りたい。完璧は無理でも、「コードとドキュメントがズレている」状態は避けたい。
 まとめ まとめVibe Codingは楽しいし、生産性も上がる。でも引き継ぎという観点では落とし穴がある。
AIが「気を利かせて」書いたコードが、別環境で問題を起こす
自分でコードを把握していないから、トラブル時に対応できない
引き継ぎ相手もコードを理解できない
100%コントロールするのは無理でも、できるだけ手綱を握っておくのが大事だと痛感しました。
Vibe Codingをやるなら：
Agent.mdで「やってはいけないこと」を明文化する
AIには最小限の仕事だけさせる
ドキュメントは最初から用意しておく
AIが生成したコードも必ず人間がレビューする
この記事が、同じ轍を踏む人を一人でも減らせたら嬉しいです。