2026年1月、累計5,000万DLを超えた壁紙アプリで、3ヶ月前に直したはずのクラッシュをまた踏みました。Crashlytics のスタックトレースをよく見ると、見覚えのある NSRangeException です。当時の commit を git log で辿り、同じ条件で再現させ、同じ修正を入れ直しました。残ったのは「あのとき、どこに何の情報を残しておけば未来の自分を助けられたのだろう」という後悔だけでした。
その日から、Antigravity の Walkthroughs を「リファクタリングの解説」ではなく「リグレッション再現の永続メモ」として育てる運用を始めました。4ヶ月続けてみたところ、4本のアプリ全体で「重複バグ起票数」が前期比でおよそ60%減りました。今回はその運用記録です。Walkthroughs という機能の本来の使い方からは少し外れますが、個人開発の現場では十分に機能していると感じています。
同じバグを4回踏んだ事件と『記録のなさ』への気づき
2014年から個人で iOS と Android のアプリを開発してきました。AdMob 収益化を中心に、壁紙系・癒し系・引き寄せ系のアプリを並行運用しています。長く続けると、コードベースには「2017年に直した」「2020年にもう一度直した」というレイヤーが何層も積み重なります。
この4年で「同じバグだ」と気づいた瞬間が、自分で数えただけでも17回ありました。コミットメッセージで fix: collection view index out of range と書いてあったのに、半年後にまた踏みます。問題は「修正の記憶」ではなく、「再現の手順」が頭にも GitHub にも残っていないことでした。
Crashlytics のダッシュボードを見れば「いつ発生したか」は分かります。しかし「どのアプリ状態から、何タップで、どんな条件で再現するか」は記録されていません。テストコードを書こうとは何度も思いましたが、UIKit のレガシーコードに後付けで UI テストを通すのは現実的でなく、結局「次のリリースまでに観察する」と心の中で誓って終わっていました。
Antigravity の Walkthroughs を試したとき、私が最初に感じたのは「これは差分を見せるツールというより、操作の意図と順序を残せる場所だ」ということでした。差分は git が記憶してくれます。しかし「クラッシュを引き起こす操作の手順」は、git のどこにも残りません。そこを Walkthroughs に肩代わりさせられないかと考えました。
Walkthroughs を「再現メモ」として扱う発想転換
公式のドキュメントでは、Walkthroughs は Agent モードが生成したコード変更を段階的に解説するための機能として紹介されています。私自身、最初の数週間はその使い方しかしていませんでした。
転換点になったのは、Walkthrough のステップ単位に「再現操作」「期待結果」を埋め込んでみたことです。Antigravity の Agent に「この Walkthrough のステップ3として『起動後すぐにダークモードへ切り替える』という操作を、コード差分なしで純粋な手順として追加してください」とお願いしてみました。すると Walkthrough は、コード差分とテキストを混在させた「実行可能な手順書」のような形になりました。
私の運用では、ひとつのリグレッション再現メモは以下の4セクションで構成します。
前提条件 : ビルド番号・OS・端末・課金状態・初回起動か再起動かの区別再現手順 : タップ・スクロール・回転などをステップで列挙期待結果と実際の結果 : 何が起きるべきで、何が起きたか修正リンク : 該当 PR や Crashlytics の issue ID へのリンク
この4セクションを守るだけで、未来の自分が再現メモを開いたときに「これは何の話だっけ」と迷う時間が一気に短くなりました。
命名規則『RG-YYYYMM-{app}-{summary}』を決めた理由
Walkthroughs は数が増えると検索性が落ちます。最初の3週間は「壁紙クラッシュ」「ダークモード問題」のような自然言語で命名していたのですが、1ヶ月後には自分でも何が何の話か分からなくなりました。
そこで命名規則を決めました。
RG-202602-wallpaper-collectionview-index-out-of-range RG-202602-zen-mode-darkmode-statusbar-flicker RG-202603-affirmation-iap-receipt-validation-fail RG- プレフィックスは「Regression」の意味で、通常のリファクタ用 Walkthrough と並んでも一目で識別できます。YYYYMM を入れると、Manager Surface のサイドバーで時系列に並びます。{app} はアプリの内部コードネーム、{summary} はクラッシュやバグの要約です。
この命名規則に変えてから、Agent モードで「過去の RG- で collectionview を含むメモを検索してください」と頼んだときの精度が安定しました。Antigravity の検索は自然言語にも強いのですが、構造化された名前を併用すると、Agent が候補を絞る判断が早くなる印象があります。
1つの Walkthrough に収める『4セクション構造』の中身
抽象的な話だけだと運用イメージが湧きにくいので、実際に運用している Walkthrough の中身を1つ抜粋します。固有のメソッド名は一部書き換えていますが、構造はそのままです。
Walkthrough: RG-202602-wallpaper-collectionview-index-out-of-range ─────────────────────────────────────────────────────────────────
Step 1 — 前提条件 - ビルド: 1.42.0 (build 4218) - OS: iOS 18.4 / iPad Pro 12.9 第3世代 - 課金状態: Pro 未購入 - 起動条件: ホーム画面からの2回目以降の起動 - 初回タブ: お気に入り
Step 2 — 再現手順 1. アプリ起動 2. 「お気に入り」タブを開く (0件の状態) 3. 「カテゴリ」タブに移動 4. 「日本の四季」カテゴリを開く 5. 1枚目の壁紙をタップ 6. プレビュー画面で右スワイプを8回 7. 戻るボタンで一覧に戻る 8. 「お気に入り」タブに戻る ← ここでクラッシュ
Step 3 — 期待結果 / 実際の結果 - 期待: お気に入りタブの空状態が再描画される - 実際: NSRangeException で落ちる *** -[__NSArrayM objectAtIndex:]: index 8 beyond bounds [0..0]
Step 4 — 修正リンク - PR: github.com/dolice/wallpaper-app/pull/1842 - Crashlytics issue: F-2026-02-1842 - 関連 Walkthrough: RG-202010-wallpaper-collectionview-reload-crash ポイントは Step 4 の「関連 Walkthrough」です。過去に似た問題を解いていれば、そこへのリンクを必ず張っておきます。これがあるおかげで、次に似たクラッシュを見たとき、半年前の自分の手記に瞬時に辿り着けます。
Crashlytics・TestFlight からの引き戻し動線を作る
メモを書くだけでは、未来の自分が読み返す保証はありません。そこで「クラッシュが報告されたら、まず Walkthroughs を検索する」という動線を強制的に組み込みました。
具体的にやっているのは、Crashlytics の問題詳細を開いたときに、Antigravity 側で Agent に次のようなプロンプトを最初に投げる運用です。
以下のスタックトレースに該当する過去の Walkthrough を、 RG- プレフィックス付きの Walkthroughs から検索してください。 該当があれば名前と Step 3 の「期待 / 実際」だけ要約してください。 該当がなければ「なし」とだけ返してください。
[Crashlytics スタックトレース貼り付け] Agent は Walkthroughs の本文を読みに行き、該当があれば過去の修正リンクごと提示してくれます。該当がなければ「なし」と返ってくるので、その時点で新しい RG- メモを作る判断ができます。
この動線を作るまでは、Crashlytics → ソースコード → git blame → 過去 PR、という順で毎回辿っていました。今は Crashlytics → Antigravity 検索、で済むようになり、初動の判断にかかる時間が約3分の1になりました。実装当時の自分のメモが、今の自分を助けてくれる感覚です。両家の祖父が宮大工で、仕事道具に手入れの記録を書いた紙が貼ってあったのを父から聞いたことがあるのですが、感覚としてはそれに近いと感じています。
4ヶ月運用して見えた数字と『3回ルール』の発見
4ヶ月続けてみて、いくつか数字で語れる変化がありました。
重複バグ起票数: 前期比で約60%減（4本のアプリ合計、Crashlytics の regressed issues ラベルを基準）
再現メモ作成にかかる時間: 平均で1メモあたり約12分
既存メモを見つけて再修正に使えた回数: 4ヶ月で23回
「該当なし」と判定されて新規メモを作った回数: 4ヶ月で41件
この数字を眺めながら気づいたのは、「全てのバグをメモにする必要はない」ということでした。最初は律儀に毎回 RG- メモを作っていたのですが、後半は「3回以上発生する見込みのある問題だけメモにする」という運用に変えました。1回しか起きないクラッシュは、再現メモのコストに見合わないからです。
私の中の判断基準は次の3つです。
複数アプリで起きうるか : 例えば AdMob 初期化順の問題は4アプリ共通の話なのでメモ価値が高いコードベースの古い層に触れるか : 古い UIViewController の保守は再発しやすいのでメモにするCrashlytics の発生頻度が日次5件以上か : 5件未満は来週も気にしないので、再現メモを作らずに直す
この3つの軸で絞ると、月あたりのメモ作成数が10〜12件で安定しました。多すぎず、少なすぎず、運用が苦しくならない量に落ち着いた感覚です。
失敗したパターンと、運用を続けるための工夫
最初の運用で失敗したのは「全部の Crashlytics 問題をメモにしようとした」ことでした。1日30件のクラッシュレポートに対して、メモを作り続けるのは現実的ではありません。1週間で疲弊し、運用は崩壊しかけました。
復活させるためにやったのは、運用ルールを Antigravity の .context/ ディレクトリにテキストで置き、Agent モードでクラッシュ対応を始めるときに「以下のルールに従ってメモ作成を判断してください」と毎回読ませることです。Agent が「このクラッシュは3回ルールに該当しないのでメモ不要、修正だけ進めます」と判断してくれる回が増えました。
もう一つの工夫は、Walkthroughs の保管場所をプロジェクトのリポジトリ内ではなく、別の「knowledge」リポジトリに集めたことです。理由は、リファクタリングで該当コードが消えても再現メモが残るようにするためです。私の場合は ~/knowledge/regressions/ にメモを Markdown で書き出し、Antigravity の検索対象に追加しています。
~/knowledge/regressions/ ├── README.md ├── 2026-02/ │ ├── RG-202602-wallpaper-collectionview-index.md │ └── RG-202602-zen-mode-darkmode-statusbar.md └── 2026-03/ └── RG-202603-affirmation-iap-receipt-validation.md Markdown で書いておけば、Antigravity 以外のツールからも開けますし、5年後に Antigravity を使っていなかったとしても再利用可能です。個人開発は長期戦なので、特定ツールにロックインしない設計をなるべく心がけています。
翌年の自分のための注意書きを必ず1行入れる
最後に、運用していて一番効いていると感じる小さな工夫を共有します。
各メモの末尾に、必ず1行だけ「翌年の自分への手紙」を書くようにしています。技術メモではなく、感情のメモに近いです。
Notes for future self: この問題は AdMob 初期化を AppDelegate の application:didFinishLaunchingWithOptions: で 非同期に呼び出した影響です。 同期呼び出しに戻したいと思う日が来ても、 まず Crashlytics の F-2026-02-1842 を見てください。同じ場所に戻ります。 未来の自分は、過去の自分が考えていたことを忘れています。だからこそ、技術的な手順だけでなく「なぜそうしたか」「同じ判断をしそうになったらどこを見るか」を一文だけ残しておくと、翌年の自分が同じ過ちを踏みにくくなります。離れて暮らす子どもたちに何を残せるかと考える時間が増えてから、自分の仕事のドキュメントにもこの種の「未来の誰かへの一言」を入れるようになりました。技術メモが、少しだけ手紙のような姿に変わっていく感覚があります。
4ヶ月の運用を経た現在地と、次に試したいこと
Walkthroughs を本来の用途から少しずらして使っているので、Antigravity の今後のアップデートで運用が変わる可能性はあります。それでも、今の使い方で個人開発の保守コストが目に見えて下がっているのは確かです。
次に試したいのは、RG- メモを Antigravity の Agent に「月次レビュー」させる運用です。月末にまとめて Agent に「先月作成された RG- メモを読み、どのアプリにどんな脆弱な構造があるかを構造的に整理してください」と頼んでみたいと考えています。個別の再現メモが線でつながり、コードベース全体の「弱い部分の地図」になることを期待しています。
私自身、まだ運用の途中ですし、4ヶ月分のメモが正しい構造かどうかは1年後にしか判断できません。ただ、3年前の自分に同じやり方を教えてあげたかった、とは強く感じます。同じように個人開発で長く保守を続けている方の参考になれば幸いです。
最後までお読みいただき、ありがとうございました。次のリリースのコミット直前に、ぜひ一度「再現メモを残しておくべき問題だったか」と自分に問いかけてみてください。半年後の自分が、少しだけ楽になります。