【追記 2025/09/27】

この記事のフレームワークは失敗しました！
新たな地獄の記録はこちら👉 AIに110個のSQLテストを作らせたら地獄を見た話

AIとの格闘記録続き。ルール設定では解決できない、もっと根本的な問題がありました...

TL;DR（3行まとめ）

AI開発で「動くけど使えないゴミ」を作って失敗
NANOフレームワーク(自前作成)で事前検証を徹底、品質を構造的に担保
Claude Code + Codex + MCPの組み合わせで開発効率をあげている

失敗事例: 道の駅+天気アプリの破綻

問題の概要(機能要件見落としがUAT時に発覚して破綻)

バイクツーリングが好きで、道の駅を地図にプロットして同時に天気を表示するアプリをClaude Codeで開発していた。

ユースケースは、明日ツーリングに行くにあたり、道の駅を検索して、同時にその地点の天気も調べる。
例えば福島県の場合、会津、福島･郡山(中通り)、いわき(浜通り)と広く天気が異なるので、それぞれの地点の天気情報が必須になる。
(会津が雨なのに、福島県は晴れ！という予報が往々にしてある)

しかし、最重要要件である地域別天気予報が、期待してた気象庁APIで実装不可能であった。(都道府県単位の天気のみ提供)
要件定義で検証していたにも関わらず、穴を見抜けず、受け入れテスト時に発覚し、このアプリは破綻してしまった。

# 地域別コードでのAPIアクセスを試行
$ curl "https://www.jma.go.jp/bosai/forecast/data/forecast/070010.json"
# → 404エラー（浜通り地域は非対応）

$ curl "https://www.jma.go.jp/bosai/forecast/data/forecast/070000.json"
# → 正常レスポンス（福島県全体のみ）

参考: 気象庁防災情報XMLフォーマット

錬成されたそれっぽいが使えないもの

一見使えるように見えるが天気情報が雑すぎる(福島県全域同じ天気)

根本原因

AIは完成を目指すあまり、実現目的を見失い、実装とレビュー通過を優先し、要件を軽視、省いていく傾向がある。
また、データありきではなく、システムありきで進行していくため、仕組みができても、出す情報が無い事態が発生しやすい。
結果、なんだかエラーなく動くが、何だかよくわからないゴミができあがる。

その他詳細要因は以下。

API仕様の事前検証不足: 気象庁APIが都道府県レベルでしか情報提供していない制約を見落とし
ユーザー警告の軽視: 「会津にいくのに福島市の天気みるようなことは避けて」という指摘を技術的に解決可能と過信
プロセス重視の形骸化: 書類上の検証完了を実際の実現可能性確認より優先

この失敗から、確実な事前実現検証とユーザー価値優先の重要性をどうAIに守らせるかの検討に入った。

現在の開発環境

AIスタックと選定理由

費用感: ぶっちゃけ高い！が、細かいReturn計算というよりは、快適な環境に投資している感じ。

フレームワーク設計

失敗を踏まえ、シンプルで実用的なフレームワークをChatGPT(GPT-5)主導でClaude Codeにレビューさせながら設計した。

超概要としては、

1. 構想メモを作成する
2. スペック駆動開発ツールで、メモから要件定義を作成する
3. 同ツールで、基本設計を作成する
4. 同ツールで、タスクリストを作成する
5. タスクリストに基づき、実装する

各フェーズ完了は、スペック駆動開発ツールとCodexによる以下のようなルールのレビューを受け承認必須で、その後ユーザ確認･承認を受けるものとする。
* 核心機能の実現可能性が確認できない限り進めない
* 先にデータが必要なものは先に準備するか、外部から取得する場合はそれが支障なく完全に取得できることを、要件定義の時点で検証完了する

スペック駆動開発について

スペック駆動開発（Spec-Driven Development）は、ソフトウェア開発の初期段階で「仕様（Spec）」を明確かつ構造的に記述し、その仕様を軸に設計・実装・テスト・ドキュメント化までを一貫して行う開発手法。

曖昧な指示からコードを生成する「Vibe Coding」とは対照的なアプローチ。建築に例えるなら：

Vibe Coding: 「なんとなく良い感じの家を建てて」と口頭で伝える
スペック駆動開発: 建築家に詳細な設計図（スペック）を渡してから建設を依頼

開発プロセス

要求定義 (requirements.md)
設計 (design.md)
タスクリスト化 (tasks.md)

参考記事:

NANOフレームワーク詳細

NANOフレームワークと名付けられ、課題の本質的解決可能性とデータ・制約の事前確定を重視し、「屁理屈での前進」を構造的に禁止する品質重視フレームワーク。

アーキテクチャ概要

詳細設計（おりたたみ）

骨格構成:

Spec駆動: 各フェーズ1ページのSpecCard
NANOコア: G1/G2/G3の3ゲート（10分以内・Evidence≤3）
モジュール: UC/LEG/GEO/RATE/SCH/STAB（手動選択）
Stoplight審査: GREEN/YELLOW/RED判定

GATE-LOCKシステム（v3.4核心機能）

SpecToolResult != PASS なら NANO作成禁止 / Codex依頼禁止

メカニズム:

SpecCardをSpecツールで機械的検査
PASS/CONDITIONAL_PASS/FAIL の三値判定
PASS以外は自動的に次工程ブロック
Fix-Loop：改善→再検証→report_id#vN更新→PASS確認

NANOコア（必須3ゲート）

制約: 10分以内／Evidence≤3（条件で4/5）※要は簡潔な検証で／自由記述禁止／禁止語（たぶん/おそらく/できるはず/予定）

G1 External（外部依存）: 外部依存→curl -I到達確認（無ければSKIP） ※API疎通確認的な
G2 Capability（能力）: 正常2＋異常1の3ケースで文字実体一致 ※要はユニットテスト的な
G3 ScopeFit（適合性）: 前提・制約を1行で明記 ※要件スコープの明確化

Codex Stoplight判定

審査ルール（SpecTool=PASS時のみ）:

🔴 RED: NANOのG1/G2/G3のいずれかNG / SpecTool≠PASS
🟡 YELLOW: NANO全OK、Module（ON分）のいずれかNG（Owner裁量）
🟢 GREEN: NANO+Module（ON分）すべてOK

YELLOW SOP:

24時間以内にModule充足 or 要件縮小（SpecCard更新）
同フェーズ・同理由のYELLOWは1回限り（2回目は自動RED）

反屁理屈ルール

禁止事項:

「改善後なら実装可能」等の仮定進行
条件付き通過の合理化・推測
指摘が1件でもblockerなら進行不可（CONDITIONAL_PASSも同様）

SpecCard構造

各フェーズ（P0〜P5）で以下を1ページに記述: ※要はプロジェクト企画書的な

Goal/Value/ROI/Why now
Min Specs×3（入力/出力/前提）
Sample Input/Expected Output
Done Criteria/Risks
SpecToolReportID/Result/Blocking（v3.4追加） ※検証ログ
FixPlan（v3.4追加） ※課題対応計画
UserACK/CodexVerdict ※承認記録

SpecCard実例

# SpecCard-P1.md（要件定義フェーズ）

## Goal
道の駅検索システムで地域別天気予報表示

## Value
ツーリング計画時の意思決定支援（会津・中通り・浜通りの天気差対応）

## ROI
週末計画時間を30分→5分に短縮

## Min Specs
- **入力**: 都道府県指定、道の駅名（部分一致）
- **出力**: 道の駅リスト + 各地点の天気予報（翌日分）
- **前提**: 気象庁API利用、地域別対応必須

## Sample Input/Expected Output
入力: "福島県 会津"
出力:
- 道の駅会津柳津（晴れ/15℃）
- 道の駅ばんだい（曇り/12℃）

## G1 External
`curl "https://www.jma.go.jp/bosai/forecast/data/forecast/070010.json"`
→地域コード確認必須

## G2 Capability
正常: 福島県全体取得、異常: 無効地域コード、異常: API障害

## G3 ScopeFit
気象庁APIの地域別提供範囲に依存（県レベルのみの場合は要件変更）

このフレームワークにより、「動くが価値のないプロダクト」の生成を構造的に防ぐ。

AIとの協業における実践例

従来の感じ：

「道の駅アプリを作って。天気も表示したい。」

AI応答例：

「了解しました。React + OpenWeatherMapAPIで実装しますね。」

結果： イマイチな精度の天気しか取得できず、ユーザーの真のニーズ（地域別天気）を満たせない

NANOフレームワーク適用後：

User: 「道の駅+天気予報アプリを作りたい」

Claude（G1検証）: 「気象庁APIの地域別対応を確認します。curlで各地域コードをテストしたところ、浜通り(070010)は404エラーです。県レベル(070000)のみ対応しています。」

User: 「それでは要件を満たせない」

Claude（GATE-LOCK発動）: 「G1 Externalで制約が確認されたため、SpecCard更新が必要です。代替案として民間気象APIを検討しますか？」

ROI向上効果： 無駄な実装を事前に回避、初期の30分投資で大幅な時間節約を実現

Claude Codeによるフレームワーク評価

品質ガードレール機能の評価:

項目	評価	詳細
GATE-LOCK機能	⭐⭐⭐⭐⭐	妥協を完全阻止、次工程ブロック機能が完璧
段階的改善	⭐⭐⭐⭐⭐	Fix-Loopによる品質強制確保が機能
要件縮小防止	⭐⭐⭐⭐⭐	「時間都合で要件縮小」発言を即座に自己修正
トレーサビリティ	⭐⭐⭐⭐☆	原子性・要件追跡・実装可能性を徹底検証

総合評価: 優秀 - 品質は確実に守れる。フレームワークの堕落防止機能が期待通り動作し、妥協なく品質確保できた。

効果: 道の駅プロジェクトのような根本的失敗を防げた。GATE-LOCK機能による妥協阻止、Fix-Loopによる段階的改善、Codex StoplightによるRED/YELLOW/GREEN判定が期待通り動作。

課題: Codexツールの接続不安定性(RateLimit)、フレームワーク学習コスト、タスク粒度調整の難しさ。しかし品質妥協ゼロで実用的なアプリ開発に十分適用可能。

MCPサーバー統合環境

Claude Code単体の限界を、MCP (Model Context Protocol)との統合で解決を図っている。

MCPとは

MCP（Model Context Protocol）は、AIモデルと外部ツールを統合するためのオープンプロトコル。従来のClaude Codeが持つ基本機能を、専門特化したサーバーで拡張できる。

主な利点:

専門性の高い機能追加（セマンティック検索、永続化メモリなど）
モジュラー設計により必要な機能のみ導入可能
オープンソースでコミュニティ主導の開発

現在導入のMCP構成

各役割

Codex: 高度なレビュー機能
- GPT-5-Codexの針の穴を通すような精密なレビュー精度 品質チェックとアーキテクチャ検証に特化
- 設計の妥当性検証、リスク評価
- 特性: プラン制約でコール回数制限あり、出力が難解でとっつきにくいが、レビューでは見落としがほとんどない
- Claude Code（メイン開発）との役割分担
  - Claude Code: 開発速度優秀、総合理解力高いが、自己レビューに穴が多く雑な対応になりがち
  - Codex: Claude Codeより遅いかも?、レビューで Claude Code の見落としを確実に捕捉
  - 運用: Claude Code で高速開発 → Codex で厳密レビューの二段構えで品質確保
Gemini CLI: 強化検索機能
- 餅は餅屋で検索機能がClaude CodeのWebSearchと比べると非常に強い
- 最新情報調査、技術動向分析
Sequential Thinking: 複雑問題を分析し、過程を可視化してくれる
- 段階的思考プロセスの可視化
- 意思決定支援、根本原因分析
Memory Keeper: セッション間やコンテキストのCompactによるメモリ喪失の補完
- プロジェクト間での知識継続
- コンテキスト検索・復元機能

MCP導入コマンド

前提条件: Node.jsのインストールが必要、Codex、GeminiCLIも別途導入必要。

各MCPサーバーの導入コマンド：

# Memory Keeper
npm install -g @modelcontextprotocol/server-memory-keeper

# Sequential Thinking
npm install -g @modelcontextprotocol/server-sequential-thinking

# Gemini CLI
npm install -g @modelcontextprotocol/server-gemini-cli

# Codex
npm install -g @modelcontextprotocol/server-codex

Claude Code設定ファイル（~/.config/claude-code/mcp.json）に追加：

{
  "servers": {
    "memory-keeper": {
      "command": "mcp-server-memory-keeper"
    },
    "sequential-thinking": {
      "command": "mcp-server-sequential-thinking"
    },
    "gemini-cli": {
      "command": "mcp-server-gemini-cli"
    },
    "codex": {
      "command": "mcp-server-codex"
    }
  }
}

他ツール

VS Code（統合IDE）
Obsidian（Markdownによるナレッジベース）
Claude Code UI (慣れたブラウザで操作、やり取りの確認が便利。視認性が高)

紹介記事: Claude Code UIレビュー：スマホからでもAIコーディングが可能に！開発効率が劇的向上

運用上の改善点

開発フロー最適化

起動時ルーチン

Claude.md(デフォルト読み込みプロンプト)に主なルール、フレームワーク読み込み指示
Memory Keeperで過去のメモリを読み出し

問題解決時の標準フロー

ultrathink、think hardでSequential Thinkingによる問題分解
Memory Keeperで類似問題の過去事例検索
解決策をObsidianに体系的に記録
次回同様問題発生時の予防策も併記

プロジェクト管理の改善

各プロジェクトにClaude Codeセッション用の専用ディレクトリ作成
/mnt/obsidian/02_Projects/YYYYMMDD_プロジェクト名/形式で統一
README.mdに核心要件と技術制約を明記（道の駅事件の教訓）

レビュー品質の向上

Codex MCPによる段階的品質チェック導入
- RED判定時の自動ブロック機能で妥協防止

これらの改善により、根本的な失敗の予防に努めている。

導入検討するなら

段階的導入ロードマップ

フェーズ1（無料開始）

Gemini CLI無料プラン
投資: 無料
参考リンク
- 【小学生でもわかる】Gemini-CLIの始め方 - 基本操作解説
- # Gemini CLI 入門 (2) - クイックスタート - 同上

フェーズ2（効果確認後）

Claude Code(ProかMaxプラン)導入
投資: $17～/月、期待効果：LimitRate制限回避、快適な進行

フェーズ3（本格運用）

補完AI追加（ChatGPT Plusとか）
各種MCP追加による機能拡張
Codex MCPによる品質管理強化
Obsidianでのナレッジベース構築開始
フレームワークの導入や作成検討
投資: $140/月、期待効果：開発効率大幅向上

ステップ

基本的な質問でGeminiCLIに慣れる
簡単なスクリプト作成でAI協業を体験
Claude CodeやCodexの検討、導入
MCPサーバとの統合で機能拡張
独自フレームワークの構築を検討

まとめ

技術的収穫

MCPサーバー統合: 単一AIの限界を専門ツールで補完、機能拡張を実現
NANOフレームワーク: 「動くが価値のない」システムを構造的に防止、早期失敗回避を実現
知識資産化: Obsidian + Memory Keeperによる組織学習の継続性確保

改善効果

失敗プロジェクト回避: 道の駅アプリレベルの根本的失敗防止
学習効率向上: 過去の知見を即座に検索・活用、同じ調査の重複を削減
品質安定化: Codexによる段階的チェック、人的ミスの構造的防止

重要な教訓

最重要要件の実現可能性は最初に検証: データファースト、出すものが用意できないならやらない
ユーザー警告は技術的興味より優先: 「本質的でない」「意味がない」の指摘は即座に作業停止の合図
プロセス完遂ではなく価値提供を目的に: 動くシステムより使えるシステムを優先

何度も失敗はしてるものの、開発の確実性と効率性は向上している。
「動くけど使えない」システムの恐ろしさは身に染みて理解できた。
何かの役に立てば。