mcpField
T
troubleshooting-regression

troubleshooting-regression

github.com/oimiragieo测试与质量4448 次安装17 周前更新
代码仓库

关于 troubleshooting-regression

供框架维护者排查卡顿、钩子异常和回归问题的故障诊断 Skill。它要求结合 trace、日志和测试复现问题、实施针对性修复并验证结果。

主要功能

  1. 01Trace 与调试日志分析
  2. 02将错误定位到钩子或模块
  3. 03可复现的回归排查流程
  4. 04针对性测试与修复验证
  5. 05结构化发现和后续操作

适用场景

  1. 01诊断 Agent 会话卡顿
  2. 02调查钩子意外阻止操作
  3. 03检查记忆或搜索约束执行不一致
  4. 04复现并验证框架回归问题

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/oimiragieo/agent-studio --skill troubleshooting-regression

安装后在 Claude Code 中输入/troubleshooting-regression确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

commands/
troubleshooting-regression.md
hooks/
post-execute.cjs
pre-execute.cjs
references/
.gitkeep
research-requirements.md
rules/
troubleshooting-regression.md
schemas/
input.schema.json
output.schema.json
scripts/
main.cjs
templates/
implementation-template.md

详细介绍

回归故障排查

当框架似乎过时、卡住或出现回归，并且你需要进行确定性诊断和验证修复时，使用此技能。

适用场景

  • Claude 调试会话在启动 Agent 后停滞。
  • Hook 意外阻止预期操作。
  • 内存、搜索或节省 token 的强制机制表现不一致。
  • 需要可重复的复现和验证运行来排查回归。

铁律

未满足以下条件时，不得宣称回归已修复：

  1. 可复现的触发提示词，
  2. pnpm trace:query 的跟踪证据，
  3. 调试日志中的 Hook／工具证据，
  4. 针对修改范围的测试通过。

工作流

  1. 确定会话和日志来源。
  2. 首先运行跟踪查询（pnpm trace:query --trace-id <traceId> --compact --since <ISO-8601> --limit 200）。
  3. 提取高信号错误（排除已知的 MCP 身份验证／启动噪声）。
  4. 将每个错误映射到负责的 Hook／模块。
  5. 修改最小代码路径，并添加或更新回归测试。
  6. 运行针对性检查（测试，以及对已更改文件运行 lint／format）。
  7. 重新运行调试提示词，并确认该错误类别不再复现。
  8. 在记忆中记录经验和问题。

证据模型

  • 事实来源：C:\\Users\\<user>\\.claude\\debug\\*.txt
  • 跟踪事实来源：同一事件时间段的 pnpm trace:query 输出
  • 筛选：忽略外部 MCP 传输／身份验证噪声；保留框架／运行时错误
  • 错误类别：
    • 路由／任务生命周期
    • 内存／搜索／节省 token 的防护机制
    • Hook 契约／架构违规
    • 工作流阶段／幂等性故障

命令入口

主要封装命令：

node .claude/skills/troubleshooting-regression/scripts/main.cjs --prompt "search the codebase for any issues or bugs"
pnpm trace:query --trace-id <traceId> --compact --since <ISO-8601> --limit 200

可选的直接日志分析：

node .claude/skills/troubleshooting-regression/scripts/main.cjs --log-path "C:\\Users\\<user>\\.claude\\debug\\<session>.txt"

输出约定

  • ok：布尔值
  • logPath：已分析的日志路径
  • findings[]：标准化发现，包含严重性和负责文件提示
  • nextActions[]：具体的修复／验证操作

相关产物

  • 工作流：.claude/workflows/troubleshooting-regression-skill-workflow.md
  • 工具：.claude/tools/troubleshooting-regression/troubleshooting-regression.cjs
  • 命令：.claude/commands/troubleshooting-regression.md

示例

# Analyze latest log
node .claude/skills/troubleshooting-regression/scripts/main.cjs --mode quick

# Analyze specific log and fail when critical findings exist
node .claude/skills/troubleshooting-regression/scripts/main.cjs --log-path "<path>" --strict

铁律

  1. 始终先收集证据（日志、跟踪 ID、错误消息），再进行任何配置更改
  2. 绝不在确定性复现故障之前修改 Hook 或路由配置
  3. 始终在每次更改后运行完整回归测试套件，以验证修复
  4. 绝不在确切的故障场景未通过端到端测试之前，将回归标记为已解决
  5. 始终在 issues.md 中记录根本原因、修复和验证证据，供日后参考

反模式

反模式失败原因正确做法
未复现故障便进行更改无法验证更改是否修复了正确的问题先以确定性方式复现，再修复
只修复症状，不分析根本原因问题会在不同条件下再次出现使用 5 Whys 追查根本原因
修复后跳过回归测试套件修复可能会破坏其他功能每次更改后运行完整测试套件
修复未记录相同回归会在未来会话中再次出现在 issues.md 中记录根本原因、修复和验证
未经端到端验证就标记为已解决集成问题会被遗漏对确切的故障路径进行端到端验证

记忆协议

开始之前：

cat .claude/context/memory/learnings.md

完成之后：

  • 回归模式 -> .claude/context/memory/learnings.md
  • 未解决的缺陷或风险 -> .claude/context/memory/issues.md
  • 新的强制执行决策 -> .claude/context/memory/decisions.md

假定会被打断：你的上下文可能会重置。如果没有记入记忆，就等于没有发生。

评论

支持 Markdown