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

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

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

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に「整合性が取れていない」と指摘され、全ドキュメントを最新プランに統一した。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プランの生成数上限を甘く見積もると、粗利が簡単に吹き飛ぶ。

FAQ

Q: Claude APIのコスト計算で最も注意すべき構造的リスクは何ですか？

A: ユーザー数の増加に対してコストが非線形に跳ね上がる点だ。Prompt Cachingの料金体系と上位プランの生成数上限が掛け合わさる。ここを甘く見積もると売上が増えても粗利が吹き飛ぶ。

Q: なぜViteからNext.js 15 App Routerへの移行を決断したのですか？

A: 複雑なAPI連携とキャッシュ制御が必要なSaaSにおいて、クライアント側の状態管理を劇的に簡略化できるからだ。React 19のServer Actionsを使えばデータフェッチングのたびにローディング状態を管理する手間が消える。

Q: 離脱を防ぐための通知設計で、UX的に陥りやすい限界はどこですか？

A: コグニティブ・ロードの増大だ。非アクティブユーザーへのリマインドを増やしすぎると、ユーザーは管理されていると感じて完全に離脱する。Cronジョブによる非同期通知は状態管理が複雑化しやすく、二重通知のスパム化リスクが常につきまとう。

最後に

AIの指摘を盲信して完璧な設計書を目指した結果、数時間の作業をすべてRevertして元の場所に戻ってきた。ThreadPostは今日も進化した。次は実装を進める。

👉 ThreadPostでSNS運用を自動化する