第3章 ― アプリ工場という発想(後編): CLAUDE.mdの細則は、すべて失敗から生まれた
“「ネイティブダイアログ禁止」と書く前に、何回ユーザーを失った?”
前編で「CLAUDE.mdは憲法」と書いた。後編は、その憲法の細かい条文がどう生まれたかの話だ。一見奇妙な細則の裏には、必ず1つ以上の失敗事例が隠れている。
細則1. 「画像生成は gpt-image-2 のみ」
CLAUDE.md にはこう書いてある。
“「全ての画像は gpt-image-2 のみで生成する。gemini / flash / exp / imagen / dall-e / gpt-image-1 など他モデルへの変更・フォールバックは理由を問わず完全禁止」”
この異様に強い禁止条項の背景には、Gemini / Imagen / DALL-E を行ったり来たりしてた時期がある。エラーが出るたびに別モデルに切り替えるんだが、結果として画風がバラバラのアセットがリポジトリに散らかった。スクショの統一感が崩れて、App Store審査でも視覚的一貫性が無くなった。
解決策は単純だが強力だった。「全部 gpt-image-2 で行く。500エラー出ても同じモデルでリトライ。代替禁止」。これによって、リポジトリ内の画像のトーンが揃い、審査の視覚的整合性問題が消えた。
細則2. 「ネイティブダイアログ禁止 → トースト通知」
「ネイティブダイアログ(alert/confirm/prompt)禁止」もCLAUDE.mdの絶対ルールだ。
理由はUX的には自明で、ネイティブダイアログはモーダル全画面を奪い、ユーザーの操作を止める。トースト通知は非モーダルで、ユーザーの作業を止めない。AppStore レビュアーに「クラッシュしたかと思った」と書かれてリジェクト食らったことがある(これは NFCTool 時代)。
iOS 側では `iOS App Default UX` スキル(`~/.claude/skills/ios-app-default-ux.md`)で「エラー: ネイティブalert禁止 → トースト or 赤字footnote」と明記されている。Web 側でも同じ。
細則3. 「Opus禁止(『フルパワー』明示時のみ)」
コスト最優先ルールの中に「通常は claude-sonnet-4-6 または Haiku を使用。Opusは禁止」とある。
理由は単純で、Opus は Sonnet/Haiku の数倍のトークン課金が来る。アプリ工場が「月10本量産」を続けるための前提条件は、AI のランニングコストが青天井にならないこと。Opus を多用してると、月のClaude API 課金が10万円超える。Sonnet/Haiku なら月2万円台で収まる。
「フルパワー」と明示したときだけ Opus 解禁、というエスケープハッチを残してあるのは、本当に難しいデバッグや、書き込み量が多い設計で必要になることがあるから。明示が必要なのは、無意識に高コストモードに入らないため。
細則4. 「1工程につき内部反復は最大1回」
コスト最優先ルールの中で一番効いているのが、これ。
「失敗時は最小修正案(diff)を1つ提示して即適用し、完了させてから続行する」「自動リトライ/再解析/無限ループは禁止」。これがないと、AIは延々と「もう1回試してみます」を繰り返す。1回の作業が30分で終わるはずが、リトライ地獄で2時間になる。コストは4倍。
1回でダメなら、ユーザーに最小修正案を提示して、人間が判断する。この「1回ルール」が、コスト爆発を防ぐガードレールになっている。
細則5. 「Vercel CNAMEは rank 1 値必須」
これは奇妙な細則だが、`agents/22_domain_master.md` と CLAUDE.md のメモリに必ず書かれている。
“「バリュードメインでCNAME追加時、`cname.vercel-dns.com.` は使わない。必ずVercel APIから recommendedCNAME[0].value (rank 1) を取得すること」”
rank 2 の `cname.vercel-dns.com` を使うと、Vercel が SSL 証明書を発行できないことがある。rank 1 の `xxxx.vercel-dns-016.com.` を使う必要がある。これに気づくまでに、サブドメインのSSLエラーで2日溶かした。
二度と踏まないために、ルール化して残してある。
細則6. 「バリュードメインAPI PUT は curl必須(python urllibだと403)」
もう1つ、奇妙な細則。「バリュードメインAPI PUTはpython urllibだと403になる → curl subprocessで実行」。
これは、バリュードメインのAPIが特定のUser-Agent や Header の組み合わせで 403 を返す挙動の罠。urllib デフォルトで投げると引っかかる。curl 経由ならOK。これも気づくのに半日かかった。
MEMORY.md に書いて、22_domain_master.md に書いて、CLAUDE.md にも書いて、3重に残してある。
細則7. 「テーブルプレフィックス必須」
「Supabase: 共有インスタンス — テーブル名に必ずプレフィックス(`mm_`, `sp_` 等)」。
アプリ工場では Supabase インスタンスを複数アプリで共有することがある(コスト最適化のため)。プレフィックス無しでテーブルを作ると、別アプリのテーブルと名前衝突して上書きする事故が起きる。CareFam は `app_carefam_*`、cat-litter-log は別プレフィックス。
これは1回テーブル名衝突して、別アプリのデータを上書きしかけてから入れたルール。
細則の正体 ― 失敗の集積回路
CLAUDE.md の細則は、すべて過去の失敗から生まれている。これは個人開発ナレッジの積層化だ。
例えるなら、職人の「自分用メモ」が、AIに適用可能な形式で書き出されたもの。3年分の失敗が、180行の憲法に圧縮されている。
そして重要なのは、Claude Code がそれを読んでくれること。同じ失敗を AI と共有できる。これが、AI と協業する個人開発の真髄だ。同じ穴を二度落ちない。落ちる前に、CLAUDE.md が止めてくれる。
4コマ漫画 ― 「細則は失敗の墓標」
- 1コマ目ネイティブalertでリジェクト → 「alert禁止」と書く
- 2コマ目Geminiに切り替えて画風崩壊 → 「gpt-image-2のみ」と書く
- 3コマ目Opus多用で月10万 → 「Opus禁止」と書く
- 4コマ目180行の憲法は、3年分の失敗の墓標だった
次回、第4章は「22人のAIエージェント組織」。経営2人/市場4人/制作5人/品質4人/売上3人 + i18n/research/carefam/domainの4人専門職、合計22人を1人ずつ紹介する。