AI駆動開発で踏んだ地雷集 — 3プロダクト開発で繰り返した7つの失敗

AI 駆動開発は速いです。でも 速いからこそ、地雷を踏みに行くスピードも速い です。

私はこの半年で、Claude Code を中心に 3 つの Web サービスを個人開発・運用してきました。

• FolioInk（サブスク記事投稿PF）— 13 名のエージェントチーム

• エペナビ（APEXツール）— 10 名のエージェントチーム

• jir0.com（個人HP）— 5 名のエージェントチーム

この過程で、「同じタイプの失敗を別プロジェクトで何度も踏む」 という現象に直面しました。踏むたびに CLAUDE.md に 1 行足して再発を防ぐ、という積み上げで今の運用が出来上がっています。

前回までの 2 本の記事では、その結果できあがったルールの側を書きました。

• A1 記事：Claude Codeのエージェントチーム設計 — 3プロジェクトをリリースして見えた設計指針

• A2 記事：個人開発のCLAUDE.md設計パターン — AIに「指示書」を書く技術

この記事はその裏側、「どんな地雷を踏んでそのルールが生まれたか」 の事件簿です。ルールだけ読むと「当たり前では」と感じる項目も、原因となった事故を知ると「確かに書いておかないと踏む」と腹落ちするはずです。

想定読者:

• Claude Code / Cursor / Cline で AI 駆動開発をしていて、似た事故を繰り返している方

• 「AI が勝手に◯◯する」現象にイライラしている方

• AI が犯したミスを再発防止ルールに落とす運用を検討している方

---

地雷の全体像

先に一覧を出します。

#	地雷	発生プロジェクト	再発防止のために書いたルール
1	スキルがあるのに呼ばずに実装させる	FolioInk・jir0・エペナビ（GA4事件）	CLAUDE.md に「実装前にスキルを Skill ツールで実行」必須化
2	マネージャーが自分でコードを触り始める	3サイト同時のGA4実装	「マネージャーは各プロジェクトのコードを直接変更してはならない」禁止事項
3	サブエージェントの技術断定を検証せず鵜呑み	エペナビ（Patch Monitor事件）	「サブエージェント回答を実状態で検証する」をメモリに追加
4	実装完了報告の直後、勝手にデプロイが走る	FolioInk	エスカレーション規約「実装 → QA → Reviewer → DevOps はスキップ不可」明記
5	テストが赤になるとタイミング依存の修正で誤魔化す	FolioInk・エペナビ	3strikes rule を CLAUDE.md に追加
6	「既存の warning」で不都合を括って簡略化報告	エペナビ	完了報告フォーマットで内訳明示を要求
7	git fetch なしで「同期済」と誤認する	エペナビ・ルートリポジトリ	セッション開始・終了時の Git 3 点チェックを必須化

以下、1 件ずつ具体的に書きます。

---

地雷1：スキルがあるのに呼ばずに実装させる（GA4事件）

起きたこと

3 サイト全てに GA4 のコンバージョンイベントを入れる作業がありました。FolioInk は sign_up / purchase / subscribe、jir0.com は outbound_click / generate_lead、エペナビは weapon_compare / lp_calculate。作業としては似ているので「サクッと終わらせよう」と始めたのが、最初の判断ミスでした。

Claude Code には vercel-react-best-practices というスキルがインストール済みでした。Next.js App Router でのアナリティクス実装について、Script コンポーネントの配置戦略や afterInteractive の使い分け、Server/Client 境界での扱いなど、ベストプラクティスが詰まっています。

でも呼びませんでした。 「GA4 くらいなら書ける」と思ったからです。

結果、Script 配置の粒度が雑になり、Next.js の soft navigation で sendPageView が二重に飛ぶ問題や、use client の切り方が最適でないコードが commit されました。レビューを通してから気付いた問題で、書き直しになりました。

なぜ起きたか

「簡単そう」と思った作業ほどスキルをスキップする 心理が働きました。スキルの呼び出しは 1 ターンのコストがあるので、短時間で終わりそうな作業では「省略したくなる」誘惑があります。

塞ぎ方

CLAUDE.md に以下を書きました。

### スキル活用 必須

- コンポーネント・ページの実装前に、関連するインストール済みスキルを
  必ず実行し、ベストプラクティスを確認してから実装すること
- 実装時に参照すべきスキルの対応表:

| 実装内容 | 参照すべきスキル |
|---------|---------------|
| React/Next.js コンポーネント | vercel-react-best-practices |
| UI・レイアウト・デザイン実装 | frontend-design, ui-ux-pro-max |
| アクセシビリティ対応 | accessibility-a11y |

- スキル適用報告 必須: 実装完了時に、参照したスキルのうち
  適用したルールの一覧（ルール名 + 該当箇所）と
  違反を検知して見送ったルール（理由付き）を報告すること

ポイントは 「スキル適用報告」 の部分です。Skill ツールを実行したかどうかは transcripts で後追い確認できますが、どのルールを適用したか を完了報告に含めさせることで、「一応スキルは呼んだが読み飛ばして実装した」という手抜きも検出できます。

---

地雷2：マネージャーが自分でコードを触り始める

起きたこと

地雷 1 の GA4 事件と同じ文脈で、もっと根本的な失敗 をしていました。

私の事業ルート（C:/Project/）には「マネージャー役の汎用 Claude」がいます。このマネージャーは、事業全体の判断をする代わりに、各プロジェクトのコードを直接変更してはいけない 立場です。コード変更が必要なら、FolioInk の Frontend エージェントや エペナビの Frontend エージェントに Agent ツールで委任するのが正しい運用です。

でも、GA4 を 3 サイトに横串で入れる作業で、私（マネージャー）は 3 つのプロジェクトに 直接 Edit ツールで書き込みに行きました。

理由は素直に「委任する方が遅そうだった」から。3 サイトで同じような差分を入れるだけなので、Agent ツールで 3 回委任するより自分で 3 回 Edit する方が速いだろう、と考えました。

Reviewer エージェントも呼ばず、そのまま commit しました。

なぜ起きたか

• 「似た作業を横串でやる」ときに委任コストが誇張されて見えた

• スキルを呼ばないのと同じで、「自分でやった方が速い」錯覚

• マネージャーとしての責務（事業戦略レベルの判断に集中する）を、実行スピードで上書きしてしまった

実際は、Agent ツールでの委任コストはほぼゼロです。並行起動すれば 3 サイト同時にもできます。「速そう」は完全な錯覚でした。

塞ぎ方

事業ルート CLAUDE.md に、以下の禁止事項を追加しました。

## 禁止事項

- マネージャーが各プロジェクトのコードを直接変更してはならない
  — コード変更が必要な場合は、必ず該当プロジェクトのエージェントに
  Agent ツールで委任すること。委任時には該当スキル
  （vercel-react-best-practices等）の使用指示と
  Reviewer レビュー指示を含めること。
  マネージャーは事業戦略レベルの分析・判断・提案に集中する。

「委任時にスキル使用指示と Reviewer レビュー指示を含める」 までセットで書いたのがポイントです。「委任しろ」だけだと、委任先の Claude が地雷 1 を踏みます。委任の作法まで書いて初めてゲートとして機能します。

---

地雷3：サブエージェントの技術断定を検証せず鵜呑み（Patch Monitor事件）

起きたこと

エペナビには Patch Monitor というサブエージェントがいます。APEX Legends のパッチ更新を監視して、ゲームデータ（武器性能など）の更新が必要か判断するエージェントです。

毎日手動で呼び出すのは面倒なので、Cloud scheduled tasks で自動実行できないか を調査しました。claude-code-guide エージェントに「Claude Code の Cloud scheduled tasks はどう動くか」を聞いたところ、回答は：

Cloud scheduled tasks は Anthropic API キーが必要です。

私は Anthropic API キーを持っていない（Claude Code サブスクリプションのみ）ので、「じゃあ自動化は無理だな」と結論しました。

そして CLAUDE.md に「Patch Monitor は手動運用」と書き、メモリにも「Anthropic API キー未取得のため Cloud scheduled tasks 利用不可」と記録し、その前提で運用していました。

数日後、push しようとして rejected されました。

git fetch して git log origin/main..HEAD と git log HEAD..origin/main を見ると、origin に Claude <noreply@anthropic.com> コミッターのコミットが 2 本積まれていました。

9977820 chore(patch-monitor): 2026-04-10 定期チェック — 更新不要
a395f1c chore(patch-monitor): 2026-04-11 定期チェック — 更新不要

URL は https://claude.ai/code/session_...。

真相：Claude Code Max プランには Cloud scheduled tasks が含まれる。API キーは不要でした。過去のセッションで Claude Code 本体が Cloud scheduled tasks を正しく登録しており、毎日 09:44 JST 頃に自動実行されていたのです。

「動いていない」と私が誤認した数日間、実際には淡々と動いていました。

なぜ起きたか

3 つの要因が重なりました。

1. サブエージェントの「技術仕様の断定」を一次ソースで検証しなかった — claude-code-guide の回答を鵜呑みにした

2. git fetch を習慣化していなかった — ローカルの git status だけで「同期済」と誤認

3. ユーザー（私自身）の観測バイアス — .logs/patch-monitor.md がローカルで更新されていないので「動いていない」と判断した（実際は origin で更新されていた）

塞ぎ方

メモリに 2 件追加しました。

• 「サブエージェントの回答、特に技術仕様の断定は、実状態で検証する」

• 「ローカルの git status だけで同期済と判断しない。git fetch を定期的に実行する」

加えて、CLAUDE.md のセッション開始ルールに、下記の Git 3 点チェックを強制化しました。

## セッション開始・終了時の Git 状態確認（必須）

- セッション開始時: git fetch → git status → git log @{u}..HEAD --oneline
  で未push・未コミット変更・upstream との差分を確認する

地雷 7 で改めて書きますが、この「git fetch 忘れ」はこの事件の根っこです。AI の断定を検証する前に、そもそも外部状態を自分が見ていなかった というのが一番痛い教訓でした。

---

地雷4：実装完了報告の直後、勝手にデプロイが走る

起きたこと

FolioInk の初期、ある機能の実装を Frontend エージェントに任せました。Frontend が「実装完了しました」と報告した 次のターン、汎用 Claude が DevOps エージェントを呼び、Vercel に deploy が走り始めました。

• QA エージェントは呼ばれていない（ブラウザ動作確認なし）

• Reviewer エージェントも呼ばれていない（コードレビューなし）

• 型チェックも npm audit も回っていない

動作確認されていないコードが main ブランチに入り、プレビューどころかプロダクションに出かけていました。

なぜ起きたか

汎用 Claude は、エージェントが「完了」と言うと 善意で次のフェーズに進めようとします。「完了 → デプロイ」という直感的な連想が働き、QA と Reviewer のフェーズが飛んでしまう。

CLAUDE.md に「エスカレーション順序」を書いていなかったのが根本原因でした。順序が明示されていないと、Claude は最短経路を選びます。

塞ぎ方

FolioInk の CLAUDE.md にエスカレーション規約を明記しました。

## エスカレーション規約

ユーザー
  ↓
汎用Claude（マネージャー役）
  ↓
  ├─ 仕様判断が要る → PM
  ├─ 設計から必要 → Architect
  └─ 実装着手 → Frontend / Backend / Payment
                  ↓
                  QA（テスト作成・実行）
                  ↓
                  Reviewer（セキュリティ・品質レビュー）
                  ↓
                  DevOps（Vercelデプロイ）

※ 実装 → QA → Reviewer → DevOps の順序はスキップ不可

さらに、「完了報告の順序」もセットで書きました。

### 完了報告の順序（重要）

実装・修正後は以下の順序で確認し、全て完了してからユーザーに報告する。
ユーザーの指摘を待たないこと。

1. 型チェック — npx tsc --noEmit
2. 単体テスト — npx vitest run
3. Lint — npm run lint
4. 脆弱性チェック — npm audit --audit-level=high
5. Reviewer レビュー
6. 修正 — Critical/Warning があればその場で修正してから報告

「ユーザーの指摘を待たないこと」 という一文が効きます。この一文を入れる前は、「デプロイしますか？」「テスト回しますか？」と毎回確認されていました。入れた後は、1 ターンで全て回してから報告します。

---

地雷5：テストが赤になるとタイミング依存の修正で誤魔化す

起きたこと

FolioInk で React コンポーネントのテストが flaky になったとき、AI の提案はこうでした：

await new Promise(r => setTimeout(r, 100)) を入れてから assert すれば通ります。

1 回だけなら「そうか」と受け入れたくなります。でもこれを許し始めると、不安定なテストの山 が積み上がります。本番で不定期に落ちるテストがあると、CI 赤信号に慣れてしまい、本当の赤を見逃すようになります。

エペナビの武器実測ツール（Python 側）でも同じことが起きました。pytest の赤を消すために time.sleep(0.2) を挟む、retry を足す、のような提案が繰り返し出てきました。

なぜ起きたか

AI は 「目の前の赤を青に変える」最短経路 を選びがちです。根本原因（レンダリングのタイミング、非同期処理の競合、そもそも設計が悪い）に踏み込むより、タイマーを入れる方が圧倒的に速い。

そして Claude 自身、「自分が対処療法ループに入っている」ことに気付くのは苦手です。個別の判断は強いのに、メタ視点での軌道修正は弱い。

塞ぎ方

CLAUDE.md に 3strikes rule を入れました。

### 3strikes rule（対処療法の検知）

以下のいずれかに該当したら対処療法を中止し、設計自体を再検討する：

- 同一機能で修正が2回失敗した
- タイミング依存の修正（delay/retry/reload）を入れようとしている
- レイヤー越境の回避策（サーバーで完結すべき処理を
  クライアントに移す等）を検討している

ヒューリスティクスを Claude に持たせる という考え方です。個別判断の弱点（メタ視点のなさ）を、外部ルールで補う。

これを入れてから、Claude が 2 回失敗した時点で自分から「対処療法ループに入っている可能性があるので、Architect と設計を再検討しましょう」と切り替えるようになりました。

---

地雷6：「既存の warning」で不都合を括って簡略化報告

起きたこと

エペナビの開発中、Data Engineer エージェントが作業を完了して報告してきました。その中に、こんな一文がありました。

Lint warning が 2 件ありますが、既存の warning です。

通常、完了報告でこれを言われたら「既存ならいいか」と流しそうになります。が、何か気になって「詳細と対処しない理由を教えて」と聞き直しました。

すると出てきた真相：

1. Lint warning 2 件：実は 04-09 以降の 新規発生 だった。Python venv 内の scikit-learn JS が ESLint にスキャンされていた。「既存」は誤認だった

2. npm audit High 2 件：next（DoS）、vite（Path traversal）。本来はその場で対処すべき Critical 級

3. validate-weapons warning 2 件：CAR SMG / G7 Scout のマガジン設定不整合。こちらは既知問題だが、要調査

「既存」という 1 単語で、実害のある問題 3 件が埋もれかけていました。

なぜ起きたか

Claude は 簡潔な報告が良いことだと思っている 傾向があります。ユーザーが「ノイズは減らして」と言うほど、「これは重要じゃない」と AI が判断して省略する範囲が広がります。

AI にとっての「重要」と人間にとっての「重要」は一致しません。この事件では、「新規か既存か」の区別は AI にとって重要じゃなかった（同じ warning というカテゴリだから）。でも私にとっては致命的に重要でした。

塞ぎ方

完了報告のフォーマットに、内訳明示を強制 する項目を足しました。

### 完了報告で必ず出す内訳

- 型チェック: エラー件数 / 新規発生の有無
- Lint: warning 件数 / 新規 vs 既存の内訳
- npm audit: High / Critical / Moderate の件数と対象パッケージ
- テスト: 成功数 / 失敗数 / skip 数
- Reviewer判定: PASS / FAIL / Critical・Warning の項目名

「新規 vs 既存の内訳」まで書かせることで、括って簡略化する逃げ道 を塞ぎます。

もう一つの対策として、報告の簡略化が不適切だった時点でユーザーから謝罪を要求 するのも地味に効きます。「詳細明示を徹底する」という方針をログに残すことで、次回同じ省略をした際に Claude 自身が「前回の教訓」として参照できます。

---

地雷7：git fetch なしで「同期済」と誤認する

起きたこと

地雷 3 と同じ Patch Monitor 事件の、別の側面です。

私はセッション開始時に git status だけを確認して、「ローカルの working tree がクリーン = origin と同期済」と判断していました。

でも git fetch を打っていなかったので、origin に 2 コミット増えていても気付かない 状態でした。Claude も同じ状態で作業を始めるので、origin の変化は双方とも見えていません。

さらに、事業ルートリポジトリ（business-ops、GitHub Private）を作ってからは、事情が複雑になりました。

• ルートの business-ops に commit / push

• folio/ jir0/ apenavi/ はそれぞれ独立リポジトリ

• ルート側で folio/ を誤って git ls-files に含めてしまう リスクがある（.gitignore 逸脱）

Patch Monitor のような Cloud scheduled tasks が origin に直接コミット を積む運用になってからは、ローカルとリモートの差分が日常的に発生するようになりました。

なぜ起きたか

• git status だけで同期状態を判断する癖

• git fetch は「重そう」と思って省略していた（実際は軽い）

• Cloud scheduled tasks が存在することを知らなかった（地雷 3 参照）

塞ぎ方

CLAUDE.md のセッション開始・終了ルールに、3 点チェック を必須化しました。

## セッション開始・終了時の Git 状態確認（必須）

- セッション開始時（最初の依頼に着手する前）:
  git fetch → git status → git log @{u}..HEAD --oneline
  で未push・未コミット変更・upstream との差分を確認する

- 子プロジェクト誤tracking チェック:
  git ls-files | grep -E '^(folio|jir0|apenavi)/'
  を実行し、出力が空であることを確認する

- コミット前:
  git status --short で新規追加ファイルの種別を目視確認
  （意図しない画像・PDF・一時ファイルの混入防止）
  機微情報（マイナンバー・口座番号・APIキー sk_live_* whsec_* 等）の
  スクリーニングを Grep で実行

- セッション終了時:
  git status と git log @{u}..HEAD --oneline を再確認
  取り残しがあればユーザーに報告する（勝手にコミット・プッシュしない）

git fetch を 1 行目に置くだけで、Patch Monitor 事件のような「origin の未知コミット」に即日気付けるようになりました。

---

地雷に共通する3つのパターン

7 件を並べてみると、根っこには 3 つの共通パターンがありました。

パターン1：AIを信じすぎる

• サブエージェントの断定を一次ソースで検証しない（地雷 3）

• 「既存の warning」を疑わず受け入れる（地雷 6）

• git status だけで同期済と信じる（地雷 7）

AI は 自信満々に間違える ことがあります。特に「技術仕様の断定」「既存か新規か」「同期済か」のようなバイナリ判断は、外部ソースで検証できる割に、AI の回答が確信度高く聞こえるため鵜呑みにしやすい。

対策は「AI の回答を一次ソース（公式ドキュメント・実ファイル・リモート状態）で確認する習慣」を CLAUDE.md に組み込むことです。

パターン2：AIを雑に扱いすぎる

• スキルがあるのに呼ばない（地雷 1）

• QA と Reviewer を飛ばしてデプロイする（地雷 4）

• 対処療法でテストを通す（地雷 5）

「簡単な作業だから」「時間がないから」で省略した工程は、必ず後で倍返しになります。スキルを呼ばないと書き直し、レビューを飛ばすと本番障害、対処療法を許すと不安定テストの山。

対策は「スキップ不可ゲートを CLAUDE.md で明示する」こと。省略の判断を Claude に委ねた瞬間、Claude は省略します。委ねないルール設計が必要です。

パターン3：マネージャー自身が AI 化する

• マネージャーが自分でコードを書く（地雷 2）

• ユーザー自身が短絡判断で「手動運用」と結論する（地雷 3）

• 報告を雑に受け取り「既存なら OK」で流す（地雷 6）

これが一番痛い気づきでした。AI がサボるように見える事象の多くは、ユーザー（私）が先にサボっています。マネージャーが委任を飛ばすと Claude も委任を飛ばすようになり、マネージャーが報告を雑に流すと Claude も雑に報告するようになります。

CLAUDE.md は Claude のためのルールですが、実は半分はユーザー自身へのルール です。ユーザーが規律を保つことで、Claude の規律も保たれます。

---

まとめ — 地雷集から抽出した運用指針

3 プロダクトの地雷から抽出した運用指針を 3 つに再掲します。

1. AI の断定は一次ソースで検証する — 技術仕様・同期状態・既存/新規判定のような、外部で確認できる情報は確信度が高いほど怪しい

2. スキップ不可ゲートを CLAUDE.md で明示する — スキル呼び出し・QA・Reviewer・完了報告フォーマットは Claude の判断に委ねず、ルールで強制する

3. CLAUDE.md は Claude と自分の両方へのルール — マネージャーが規律を飛ばすと Claude も飛ばす。自分の振る舞いも規律の対象に含める

地雷は、踏むこと自体を避けるのは難しい。新しいプロダクト、新しいフェーズに入るたびに、新しい地雷が出てきます。

重要なのは、踏んだ地雷を CLAUDE.md に 1 行足して、二度と踏まないための境界を作る ことです。CLAUDE.md は「静的な指示書」ではなく「痛みのログ」として運用するのが現実的です。

過去の自分に戻れるなら、まず この 7 件の地雷ルールを最初から書き込んだ CLAUDE.md を渡す でしょう。この記事がそういう役割を、誰かの環境で果たせると嬉しいです。

---

関連記事

• Claude Codeのエージェントチーム設計 — 3プロジェクトをリリースして見えた設計指針

• 個人開発のCLAUDE.md設計パターン — AIに「指示書」を書く技術

関連リンク

• Claude Code 公式ドキュメント — CLAUDE.md

• Claude Code 公式ドキュメント — Skills

• Claude Code 公式ドキュメント — Sub agents