個人開発でモバイルアプリを90本以上リリースしてきました。最近はClaude CodeなどのAIコーディングエージェントに実装を任せる比率がかなり上がっています。ただ「エージェントに丸投げすれば量産できる」というほど単純ではなく、運用してみて初めて分かった落とし穴がいくつもありました。この記事では誇張なしで、実際にハマった点と対処法をまとめます。

1. 「ビルド成功」は「提出成功」の証拠にならない

CIやローカルビルドがexit 0で終わっても、それは審査に出せる状態を保証しません。実際に何度もやらかしたのが以下のパターンです。

バージョンコードが前回と同じまま署名済みビルドが生成されていた
中間生成物（未署名のAAB）を提出用と勘違いした
隔離環境用のビルドスクリプトが .env* を除外していて、環境変数から読むはずのAPIキーが空文字のまま焼き込まれていた（起動はするが課金機能だけ死ぬので発見が遅れる）

対策として、ビルドの終了コードではなく「実際にストア側の管理画面を読み戻して中身を確認する」工程を必ず挟むようにしました。エージェントに「ビルドして」と頼むときは、「ビルド後に成果物の中身を検証するステップ」まで含めて指示するのがポイントです。

2. 複数レーンを並走させるなら、共有リソースを疑う

Claude Codeを複数プロセスで並走させて複数アプリを同時に作業させていた時期がありました。ここで踏んだ地雷が2つあります。

.gitのロック衝突: 同じリポジトリ配下で複数レーンが同時にgitコマンドを叩くと.git/config.lockで衝突し、exit code 255のような一見無関係なエラーで落ちる。原因は排他制御の欠如で、レーンごとにロックを取るようにして解決。
一時ディレクトリの共有: TMPDIRを複数レーンで共有していたら、あるレーンの後片付け処理が他レーンの作業中ファイルをrm -rfしてしまい、package.json does not existという誤解を招くエラーで止まった。レーンごとにTMPDIRを分離してから再発していません。

並列化は速度は上がりますが、「ファイルシステム上で何を共有しているか」を先に洗い出さないと、エラーメッセージが原因と無関係な顔をして出てくるので調査コストが跳ね上がります。

3. ルールファイルは「量」より「エージェントが実際に読む場所」

CLAUDE.mdやプロジェクトルールを書き込んでも、エージェントの挙動がなかなか変わらないことがありました。原因を追うと、ルールの中身より「どのタイミングで読み込まれるか」の設計ミスであることが多かったです。

PostToolUseフックでフォーマッタ・リンタ・型チェックを自動実行する方が、「〜のスタイルで書いて」と自然文で頼むより確実に効く
「絶対にこうして」と書いた禁止事項は、コードレビュー用のサブエージェントに独立してチェックさせる方が、実装担当のエージェント自身に守らせるより漏れが少ない

自然文の指示は解釈の余地が残るので、機械的に強制できる部分（フォーマット、型チェック、禁止パターンのgrep）はできる限りフックやスクリプトに落とす、という役割分担が地味に効きます。

4. サブエージェントは「役割」より先に「渡す情報」を設計する

タスクを丸ごとサブエージェントに渡すと、前提を推測で埋められて事故ります。特に「なぜその作業が必要か」を渡し忘れると、字面だけ合っていて意図とズレた実装が返ってくることがありました。ファイルパスや既知の制約（「このAPIは1日100回まで」「この関数は他の3箇所から呼ばれている」など）を先に渡すだけで、手戻りがかなり減ります。

まとめ

AIコーディングエージェントは実装速度を確実に上げてくれますが、量産体制を組むと「エージェントの外側」——ビルド検証、リソース競合、ルールの実効性、情報設計——で躓くことの方が多い、というのが実感です。

こうした個人開発×AIエージェントの実務的なノウハウは、学習サイト AI Craft Campus でも整理しています。12週間のロードマップ形式で、今回のような運用Tipsも含めて記事化しているので、興味があれば覗いてみてください。