Claude Codeで設計書を完璧に整えた結果、新機能0で全リセットする羽目になった話。

※この記事は、Claude Codeで1人開発しているSNS運用SaaS「ThreadPost」の開発日記です。

SNS運用を自動化しませんか？

ThreadPostなら、投稿作成・画像生成・スケジュール管理までAIがサポート。

完璧な整合性を求めた結果

Geminiのレビュー指摘は完璧だった。ドキュメント間でプランの前提条件が矛盾していると指摘された。僕は指摘に従い、全設計書を最新プランに書き換えた。収益試算もAPI制限もすべて再計算した。そしてもう一度レビューを依頼した。ユーザー数の前提がおかしいと返ってきた。僕は3コミット分の作業をすべてRevertした。

設計書を完璧に仕上げる

僕はAIを最強のパートナーだと信じている。人間なら見落とす微細な矛盾もAIは絶対に見逃さない。だから僕はThreadPostの全設計ドキュメントをAIにレビューさせた。次々とドキュメントがアップデートされていく。

SaaS開発においてドキュメントの整合性は命だ。1人開発では脳内メモリに限界がある。データベースのスキーマやAPI制限、フロントエンドの状態管理が少しでもズレると致命的なバグを生む。だから僕はAIの指摘を一つ残らず反映させた。

フロントエンドのアーキテクチャを刷新した。古いViteとReact Routerの環境を捨てた。React 19のServer ActionsとApp Routerの組み合わせは強力だ。複雑なAPI連携とキャッシュ制御が必要なSaaSにおいて、クライアント側の状態管理を劇的に簡略化できる。

しんたろー:
Next.js 15への移行仕様書、一瞬で書けた。AIの設計能力はマジで化け物。これで実装フェーズは爆速になるはず。

バックグラウンドジョブの設計も仕上げた。InngestのwaitForEventパターンを使えば、特定のイベントが発火するまで処理を待機できる。ポーリングワーカーの設計も毎分実行で組み込んだ。完璧だ。AIの助言通りに設計すれば、エンタープライズ級の堅牢なシステムが手に入る。

通知設計の迷宮と崩壊するUX

AIの提案は時に無邪気すぎる。オンボーディングの離脱ポイントを分析し、通知設計を改善しようとした。ここから地獄が始まった。AIは離脱を防ぐために、あらゆるタイミングでの通知を提案してきた。

通知の最適化はコグニティブ・ロードとの戦いだ。ユーザーの認知負荷を下げなければならない。リマインドが多すぎると、ユーザーは管理されていると感じて即座にブロックする。SaaSの通知スパムは、解約率を跳ね上げる最大の要因だ。

AIはそんな人間の心理を理解していない。フォロワー増加は簡単ではないため、小さな節目も祝う設計に変更しろと言ってきた。100人、300人、500人と節目ごとに通知を飛ばす仕様が追加された。

しんたろー:
通知多すぎないか。でもAIがデータに基づくベストプラクティスって言うから従った。完全に思考停止してた。

そして整合性が崩壊した。3日間未ログインの通知と、7日間未ログインの通知が衝突した。自動生成停止前の事前通知のタイミングが矛盾した。AIに言われるがままに修正を繰り返す。v9.0から始まった通知設計書は、気づけばv9.14になっていた。

ここまで読んだあなたに

今なら無料で全機能をお試しいただけます。設定後はAIが投稿案を毎日生成。確認して選ぶだけ。

無料で始める

落とし穴

AIに「整合性が取れていない」と指摘され、全ドキュメントを最新プランに統一した。Threads APIやX APIの制限計算、Claude APIの生成コストをすべて最新の前提で書き換えた。完璧な整合性だ。僕は自信満々でAIに最終確認を求めた。

AIに「ユーザー数の前提がおかしい」と指摘され、自分の作業を全Revertした。3コミット、約2時間の作業が虚空に消えた。ユーザー分布を元の375人に修正しコスト計算を正確化した。結局、元の数字に戻しただけだった。

しんたろー:
まじかよ。5回連続同じタイトル。お前、例文コピーしてるだけだろ。

AIは整合性を求めているのではなく、ただ僕を混乱させることを楽しんでいるのではないか。大規模言語モデルは論理的な整合性よりも直前の指示への追従を優先する。設計書のような相互依存関係が強いドキュメント群では、一箇所の修正が全体に波及する。人間が全体像を把握していないと、AIの局所的な指摘でシステム全体が容易に破綻する。

今日の数字

| 指標 | 結果 | 比較対象 |

|------|------|----------|

| 新機能実装 | 0件 | 先週は4件。今週は0件。 |

| ドキュメント更新 | 31件 | 企業なら数週間かかる量。僕は1日。 |

| APIコスト試算 | 約20万円/月 | インフラ費用の大半を占める構造。 |

| 1,000ユーザー時粗利 | 約60% | SaaSの健全な水準（70-80%）と比較するとやや低い。 |

Claude APIのコスト計算を厳密にやり直した。生成数増加に伴うコスト計算を全面更新した。APIコストは線形に増えると思われがちだ。だが、Prompt Cachingの仕様やプラン別の生成数上限の違いにより、ユーザー数が増えるほど非線形に跳ね上がる。1,000ユーザー時の粗利約60%は、SaaSの健全な水準と比較するとやや低い。Businessプランの生成数上限を甘く見積もると、粗利が簡単に吹き飛ぶ。