fix-sentry-issues について
fix-sentry-issuesは、Sentryの問題を根本原因から調査・修正するコーディングエージェント向けスキルです。イベント確認、上流の入力追跡、再現、テストによる検証を1件ずつ進めます。
主な機能
- 01段階的な問題発見とトリアージ
- 02イベントデータとスタックトレースの確認
- 03上流の入力経路の追跡
- 04実際の入力を使った再現
- 05問題ごとのテストと根本修正
活用シーン
- 01未解決問題を調査対象に分類
- 02イベント詳細から失敗箇所を特定
- 03エラーを再現して入力経路を追跡
- 04個別の修正をテストして検証
MCP 対応
Sentry MCPで組織、プロジェクト、問題、イベントを検索し、問題の状態を更新します。また、Axiomとの照合も指示します。
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/fix-sentry-issuesを入力して読み込まれたか確認します。
詳細
Sentry の問題を修正する
基本方針
Sentry のエラーは問題そのものではありません。シグナルです。
目標は Sentry の問題をクローズすることではありません。根本原因を突き止め、アプリケーションの何が問題なのかを把握し、根本的な不具合を修正することです。適切に修正できれば、Sentry の問題のクローズはその副次的な結果にすぎません。
**「なぜこれが失敗するのか？」と問いかけてください。「どうすれば Sentry を静かにできるか？」**ではありません。ログレベルの変更を修正として扱ってはいけません。フォールバック経路があるということは、ユーザーエクスペリエンスが低下しているということです。主要経路が失敗する理由を追跡し、上流で修正してください。
アンチパターン（行わないでください）
- **調査せずに一括で「想定内」と分類する。**フォールバックがあるからといって、失敗の原因を理解したことにはなりません。入力経路をすべて追跡してください。
- **「フォールバックがある」ことを「問題ではない」と扱う。**主要経路が失敗するのはなぜでしょうか？上流で防げないでしょうか？
- **複数の問題を1つの PR にまとめる。**それぞれに独自の根本原因があります。個別に修正してください（調査の結果、同じ原因だと判明した場合を除きます）。
- エラーの詳細を捨てる。
catch (error)からerrorを削除したり、ステータスコードを取り除いたりしてはいけません。このデータが失敗の理解に役立ちます。 - トリアージ中に修正方法を決める。「調査」または「無視」に分類するだけにしてください。調査が完了するまでは、修正方法はわかりません。
ログレベルの引き下げが有効なのは、本当に想定内の状態の場合のみです（例：オプションのカラムがない、リソースが削除済み）。フォールバックを伴う失敗には適用しないでください。
フェーズ 1：検出とトリアージ
Sentry MCP を使用します（ツールを読み込むため、最初に ToolSearch を実行します）：find_organizations → find_projects → naturalLanguageQuery: "all unresolved issues sorted by events" を指定して search_issues を実行します。
トリアージ表を作成します。アクションは「調査」または「無視」のみです。
| ID | タイトル | イベント数 | アクション | 理由 |
|---|---|---|---|---|
| PROJ-A | 保存時のエラー | 14 | 調査 | ユーザーに影響する保存失敗 |
| PROJ-B | GM_register... | 3 | 無視 | Greasemonkey 拡張機能 |
**調査：**複数のイベントがある、ユーザーエクスペリエンスが低下している、大量に発生する警告、実行のたびに繰り返し発生するもの。
**無視：**ブラウザー拡張機能のコード、ChunkLoadError（自然に解消するもの）、単発の一時的なイベント、すでに修正済みのもの。
適用するには、mcp__sentry__update_issue(..., status: "ignored") を使用します。すでに修正済みの場合は status: "resolved" を使用します。
フェーズ 2：調査（一度に1つの問題）
次の手順を順番どおりに進めてください。手順を省略したり、問題をまとめて処理したりしないでください。
-
イベントレベルのデータを取得する — 問題の概要には詳細が隠れています。
get_issue_detailsとnaturalLanguageQuery: "all events with extra data"を指定したsearch_issue_eventsを使用します。URL、パラメーター、スタックトレース、ステータスコード、タイムスタンプを抽出します。 -
Axiom と相互参照する — イベントには
traceIdがあります。周辺のコンテキスト（authMethod、client_version、リクエストのメタデータ）を確認するには、axiom query "['shiori-events'] | where traceId == '<traceId>'" -f jsonを実行します。 -
失敗するコード経路を読む — スタックトレースをたどります。該当するファイルをすべて読みます。変更を提案する前に、コードを理解してください。
-
入力経路を上流まで追跡する (最も見落とされやすく、最も重要です) — 失敗する関数にはどのようなデータが渡されていますか？そもそも、この経路に到達するべきでしょうか？フィルターが不足していませんか？入力に問題はありませんか（バイナリー URL、リダイレクト、不正な形式など）？上流で不正な入力を防げないでしょうか？
-
再現する — Sentry の実際の失敗入力を使用します。正確なデータを関数に渡して呼び出します。タイムアウトした URL に
fetch()を実行します。理解が正しいか確認してください。 -
根本原因を特定する — この入力が失敗するのはなぜでしょうか？なぜこの経路に到達するのでしょうか？適切な修正は何でしょうか？（例：「ログを抑制する」ではなく、「Firecrawl に送る前にバイナリー URL をフィルタリングする」）
| パターン | 実際の修正 |
|---|---|
| 特定の URL で外部 API が失敗する | 送信前に入力をフィルタリング／検証する |
| タイムアウト | 遅延の原因を調査し、タイムアウトまたは入力サイズを調整する |
| DB の「invalid json」 | 挿入前にサニタイズする |
| cron で参照が古くなる | 古さを検出し、自動でクリーンアップする |
フェーズ 3：修正
課題ごとにブランチを 1 つ作成します。git checkout main && git pull && git checkout -b fix/<descriptive-name>
- テストを先に作成 — 実際の Sentry イベントのデータを使用します。修正前はテストが失敗し、修正後は成功するようにします。
- 実装 — 症状ではなく、根本原因を修正します。修正の大半がログレベルの変更である場合は、作業を止めてください。失敗する理由を調査しましたか。それとも、単に抑制しただけですか。
- 検証 — テストとリンターが成功し、実際に失敗していた入力に対して修正が機能することを確認します。
- PR — 根本原因（上流の理由）と修正内容（何を変更し、なぜそれで失敗を防げるのか）を記載します。マージ後にのみ Sentry で解決済みにします。