关于 fix-sentry-issues
fix-sentry-issues 是一项按根因排查并修复 Sentry 问题的编码 Agent 技能，适合处理应用错误的开发者。它规定逐条调查事件、追踪上游输入、复现问题并以测试验证修复。
主要功能
- 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 安静下来？” 切勿把更改日志级别当作修复方案。备用路径意味着用户体验降级；请追查主路径失败的原因，并从上游修复。
反模式（不要这样做）
- 未经调查就批量归类为“符合预期”。 看到备用路径并不意味着你了解失败原因。追踪完整的输入路径。
- 把“有备用路径”当成“没有问题”。 主路径为什么会失败？我们能否在上游避免这种情况？
- 把多个问题合并到一个 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：调查（一次处理一个问题）
按顺序完成以下步骤。不要跳过步骤，也不要批量处理问题。
-
提取事件级数据 — 问题摘要会隐藏细节。使用
get_issue_details和search_issue_events，并设置naturalLanguageQuery: "all events with extra data"。提取：URL、参数、堆栈跟踪、状态码、时间戳。 -
交叉查验 Axiom — 事件包含
traceId。使用axiom query "['shiori-events'] | where traceId == '<traceId>'" -f json获取周边上下文（authMethod、client_version、请求元数据）。 -
阅读失败的代码路径 — 沿着堆栈跟踪追查。阅读所有相关文件。理解代码后再提出更改建议。
-
向上游追踪输入路径 （最常被跳过、也最重要） — 哪些数据传入了失败的函数？这些数据本该进入这条路径吗？是否缺少过滤条件？输入是否有误（二进制 URL、重定向、格式错误）？能否在上游拦截错误输入？
-
复现 — 使用 Sentry 中实际失败的输入。用完全相同的数据调用函数。对超时的 URL 使用
fetch()。验证你的理解。 -
找出根本原因 — 为什么这个输入会失败？它为什么会进入这条路径？正确的修复方案是什么？（例如：“在 Firecrawl 之前过滤二进制 URL”，而不是“屏蔽日志”）
| 模式 | 真正的修复方案 |
|---|---|
| 外部 API 在某些 URL 上失败 | 发送前过滤或验证输入 |
| 超时 | 查明耗时原因；调整超时时间或输入大小 |
| 数据库报“无效 json” | 插入前清理数据 |
| 定时任务中引用过期 | 检测过期引用并自动清理 |
第 3 阶段：修复
每个问题创建一个分支。git checkout main && git pull && git checkout -b fix/<descriptive-name>
- 先写测试 — 使用实际 Sentry 事件中的数据。修复前测试失败，修复后测试通过。
- 实现 — 修复根本原因，而非表面症状。如果修复主要是调整日志级别，请停下来：你是否调查了失败的原因，还是只是在压制问题？
- 验证 — 测试通过，lint 通过，修复能处理实际失败的输入。
- PR — 写明 根本原因（上游原因）和 修复（改了什么，以及为什么能防止失败）。合并后再在 Sentry 中解决问题。