クラッシュ報告を毎回ゼロから読ませない

壁紙アプリのクラッシュ報告が数件たまった朝、私は過去の不具合メモを開いて、同じ原因の報告を何度も読み直していることに気づきました。個人開発では、解析の手間の大半が「これは前にも見た」と確かめる作業に消えます。

そこで今は、調べる順番を決めています。先に「既知バグ早見表」を grep し、ID から詳細の 1 行へ進み、ヒットしないときだけ新規として記録する、という順です。Gemini CLI に調査を任せるときも、この順番をそのまま渡しています。

以下では、その早見表の作り方と、Gemini CLI の GEMINI.md に何を書き、何を書かないかを順に整理します。なお、ここで述べる運用は私自身が Dolice のアプリ保守で続けているもので、Gemini CLI 上での所要時間やトークン数の比較は計測していません。数字での効果はお示しできない点をご了承ください。

早見表は「1 不具合 1 行」にします

詳細を書いた文書とは別に、検索専用の 1 行表を作ります。列は次の 5 つに絞りました。

BW-009 | android | release でのみ起動時に落ちる | 難読化で必要なリソースが削除される | keep 指定を追加 | detail:bugs/BW-009.md
BW-014 | ios     | 画面を戻すと全画面広告が出ない | 破棄済みの画面を静的に保持     | 参照のみ最新に更新 | detail:bugs/BW-014.md

（行は書式の例です。ID と症状の対応は、読者の環境に合わせて置き換えてください。）

列を絞る理由は、grep の一致が「症状の言葉」でも「原因の言葉」でも拾えるようにするためです。1 行に収まる長さなら、ヒットした行をそのまま会話に貼れます。詳細は別ファイルに置き、必要なときだけ開きます。

引く手順は 3 段にします

クラッシュのログから、例外名・クラス名・症状の語を 2〜3 個取り出して grep します。
ヒットした行の ID で、詳細ファイルを開きます。
どれにも当たらないときだけ、新規として ID を振り、早見表に 1 行足します。

3 の「足す」までを手順に含めるのが肝心です。調べた結果が早見表に戻らないと、次回も同じ読み直しが起きます。

新規行を足すときの書き方

ヒットしなかった調査を表に戻すときは、原因の確定前でも仮の 1 行を足し、末尾に ? を付けます。確定したら ? を外して原因列を直します。確定を待ってから書くと、その間に届いた同種の報告を新規として数えてしまうためです。ID は種別の接頭辞と通し番号だけにし、意味のある単語は入れません。後から原因の見立てが変わっても、ID を振り直さずに済みます。

そのまま使える grep 関数

# ~/.zshrc などに置きます。早見表のパスは環境に合わせて変更してください。
BUGS="$HOME/work/known-bugs.txt"
 
bugfind() {
  # 引数が複数なら AND 検索。大文字小文字は区別しません。
  [ $# -eq 0 ] && { echo "usage: bugfind <word> [word...]" >&2; return 2; }
  local out; out=$(cat "$BUGS")
  for w in "$@"; do out=$(printf '%s\n' "$out" | grep -iF -- "$w"); done
  if [ -z "$out" ]; then
    echo "NO_HIT: 新規として記録してください" >&2
    return 1
  fi
  printf '%s\n' "$out"
}

ハマりどころが 2 つあります。grep -F は固定文字列として探すため、Foo.bar() のような記号を含む語もそのまま使えます。もう 1 つは終了コードで、ヒットなしを 1 で返しておくと、後から「ヒットなしなら新規記録の手順へ進む」という分岐を書きやすくなります。

GEMINI.md には「索引」と「規則」だけを置きます

Gemini CLI は GEMINI.md を複数の場所から集めて連結し、プロンプトに付けて送ります。公式のドキュメントでは、読み込み元はホームの ~/.gemini/GEMINI.md、作業ディレクトリから親をたどったプロジェクト内、そして配下のサブディレクトリの 3 か所と説明されています。連結後の全文は /memory show で確認できます（Gemini CLI のドキュメント）。

つまり GEMINI.md に書いたものは、毎回の質問に付いていく前提で考えるのが安全です。そこで、早見表そのものは置かず、次のような短い規則だけを書いています。

## クラッシュ調査の手順
- 原因を推測する前に、`known-bugs.txt` を grep すること（`bugfind` 関数、または `grep -iF`）。
- ヒットした ID の詳細ファイルだけを読むこと。早見表全体や bugs/ 配下を一括で読まない。
- ヒットしないときだけ新規 ID を提案し、早見表への追記行を出力すること。

@file.md の書式で別ファイルに分けることもできますが、分けた内容も読み込まれる点は変わらないはずです。大きな表は取り込まず、「検索して引く」手順だけを渡すほうが、会話に載る量を抑えられると考えています。この点も、手元で量を測って確かめたわけではありません。

実際に効いた点と、効かなかった点

効いたのは、調査の入口が揃ったことです。誰が（あるいは何が）調べても、最初に早見表を引くので、既知の不具合を新規と取り違えることが減りました。

効かなかったのは、症状の言葉が揺れる場合です。同じ原因でも、報告者によって「落ちる」「固まる」「真っ白になる」と書き方が違います。早見表の症状列に言い換えを併記する運用を足しましたが、完全には防げていません。ヒットなしのときは、近い語で 1 回だけ引き直してから新規にするよう、規則に一文加えています。

まとめて試すときの順番

過去の不具合を 1 行表に起こします（最初は直近 10 件ほどで十分です）。
bugfind を置き、実際の報告で 1 回引いてみます。
GEMINI.md に 3 行の手順を足し、/memory show で載り方を確認します。
ヒットなしだった調査は、その日のうちに表へ 1 行戻します。

MCP ツールが増えすぎて文脈が膨らむ問題とは別に、「毎回付いてくる指示」の整理は効いてきます。ツール側の絞り込みは MCP ツールの include/exclude の決め方に、Gemini CLI の基本は Gemini CLI ガイドにまとめています。

クラッシュ報告を毎回ゼロから読ませない — 既知バグ早見表を先に grep して、GEMINI.md には索引だけ置く