开发工具CLIAI 技能/插件测试人工智能AI 评测【免费下载链接】SuperClaude_FrameworkA configuration framework that enhances Claude Code with specialized commands, cognitive personas, and development methodologies.项目地址https://gitcode.com/gh_mirrors/su/SuperClaude_Framework点击查看免费下载本篇技术指南围绕 SuperClaude Framework 内置的/sc:troubleshoot斜杠命令展开系统讲解其触发时机、命令行参数、五步行为流、四类排查模式代码缺陷、构建失败、性能劣化、部署异常以及诊断优先、修复需确认的安全边界设计。读完本文你将掌握如何在 Claude Code 会话中一键发起结构化根因分析、阅读并利用诊断报告并在用户确认后安全应用修复。命令定位SuperClaude 的问题诊断入口/sc:troubleshoot是 SuperClaude Framework 三十个斜杠命令中负责质量与排查的核心命令之一官方定义为诊断并解决代码、构建、部署与系统行为中的问题Diagnose and resolve issues in code, builds, deployments, and system behavior。从命令的元数据src/superclaude/commands/troubleshoot.md可以看到它的分类属性元数据字段值含义nametroubleshoot命令名最终以/sc:troubleshoot形式调用descriptionDiagnose and resolve issues in code, builds, deployments, and system behavior命令用途描述供模型识别调用时机categoryutility工具类命令complexitybasic基础复杂度不依赖额外 MCP 服务器或人格personasmcp-servers[]默认不强制绑定任何 MCP 服务器personas[]默认不激活任何专属人格在命令体系中的位置可参见 docs/reference/commands-list.md它归属于测试与质量类别与/sc:test、/sc:analyze、/sc:reflect并列。在何时用什么命令的决策树中/sc:troubleshoot对应的是SOMETHING BROKEN? → /sc:troubleshoot (find the cause)这一环节——它只负责找原因不负责重构这是理解该命令的关键前提。命令的定义文件同时存在于两处src/superclaude/commands/troubleshoot.md包内源文件与 plugins/superclaude/commands/troubleshoot.md插件分发副本两者内容一致。安装机制由 src/superclaude/cli/install_commands.py 实现默认将命令文件复制到~/.claude/commands/sc/目录从而获得/sc:命名空间。触发时机什么情况下应该调用它原文档明确列出了四类典型触发场景当 Claude Code 会话中出现以下需求时应优先考虑调用/sc:troubleshoot代码缺陷与运行时错误调查请求例如空指针异常、非法参数、逻辑错误的定位与分析构建失败分析与解决需求例如编译错误、打包失败的根因排查性能问题诊断与优化需求例如接口响应变慢、资源占用异常的定位部署问题分析与系统行为调试例如服务无法启动、配置不生效等生产环境问题。这四类触发场景与命令的--type参数一一对应详见下文实际使用时可以直接将问题描述作为命令参数传入。命令语法与参数详解/sc:troubleshoot [issue] [--type bug|build|performance|deployment] [--trace] [--fix]各参数含义如下参数取值作用[issue]任意问题描述文本要诊断的问题建议用引号包裹完整描述问题现象与上下文--typebug/build/performance/deployment指定问题领域决定采用对应的排查模式详见关键排查模式--trace布尔开关启用栈追踪级别的深度分析适用于需要查看错误上下文与调用链的场景--fix布尔开关授权修复模式。缺省时命令只诊断不改动任何文件带上该标志后仍须先征得用户明确确认才应用修复补充说明--type默认值由问题描述内容推断当问题描述足够明确例如直接提及编译错误时可以省略。--trace与--fix可独立使用例如深度诊断但不修复用--trace诊断并准备修复用--fix两者可以组合为--trace --fix。五步行为流从现象到结论的规范路径命令执行时遵循固定的行为流每一步都有明确的产出Analyze分析解析问题描述收集相关系统状态信息错误信息、运行环境、最近变更等Investigate调查通过系统性模式分析定位潜在根因形成候选假设Debug调试执行结构化调试流程包括日志检查与状态审查逐一验证假设Propose提议验证解决方案的可行性评估影响面与风险等级Resolve解决应用适当的修复方案并验证修复是否真正生效。这五步并非线性空转其背后有三大核心行为准则系统性根因分析坚持假设—验证—取证循环而不是盲目重试多领域排查能力覆盖代码、构建、性能、部署四个域安全修复应用任何修复都伴随验证环节与文档记录。值得一提的是框架在更底层还提供了一份独立的排查协议——plugins/superclaude/skills/troubleshoot/SKILL.mdtroubleshoot 技能。它定义了一条更严格的心智流程STOP不重跑相同命令→ Observe观察实际与预期差异→ Hypothesize列出 2-3 个可能原因→ Investigate查文档、日志、栈追踪、配置→ Root Cause找到根本原因而非症状→ Fix针对根因修复→ Verify确认修复生效→ Learn沉淀解决方案。同时它明确列出了一系列严格禁止的反模式出错了那就再试一次Got an error. Lets just try again重试第 1 次……第 2 次……第 3 次……不做任何原因分析的无脑重试超时了那就把等待时间调大忽略根因的侥幸处理有警告但能跑那就算了为未来埋技术债。该技能还规定了标准输出格式——每次排查必须产出如下结构化的根因分析报告## Root Cause Analysis **Error**: [Exact error message] **Expected**: [What should have happened] **Cause**: [Root cause with evidence] **Fix**: [Solution addressing root cause] **Prevention**: [How to prevent recurrence]/sc:troubleshoot命令的行为流与该技能协议相互呼应命令负责流程编排与多域排查技能负责底层的心智纪律与反模式约束共同保证诊断出根因而非掩盖症状。工具协调排查过程中的工具矩阵诊断过程并非空谈命令会协调 Claude Code 的四大基础工具完成取证Read日志分析、系统状态检查——读取错误日志、配置文件、状态文件Bash诊断命令执行与系统调查——运行测试、检查进程、抓取系统信息Grep错误模式检测与日志分析——在日志与代码中检索错误签名、重复出现的异常模式Write诊断报告与解决方案文档的落盘——输出结构化的排查结论。这套读文件—跑命令—搜模式—写报告的组合保证了每一个诊断结论都有可复核的证据链支撑。关键排查模式四类问题的标准打法原文档给出了四类问题的模式化排查路径这也是--type参数的实战意义所在问题类型排查路径对应--typeBug 调查错误分析 → 栈追踪检查 → 代码审查 → 修复验证bug构建问题构建日志分析 → 依赖检查 → 配置验证build性能诊断指标分析 → 瓶颈识别 → 优化建议performance部署问题环境分析 → 配置验证 → 服务验证deployment选择正确的--type能让排查聚焦在正确的证据源上例如bug类问题优先看栈追踪与相关代码路径build类问题优先看构建日志与依赖树performance类问题优先看指标与热点deployment类问题优先看环境差异与配置一致性。实战示例四类问题的完整调用以下四个示例完整保留自原文档展示了真实会话中的调用方式与预期产出1. 代码缺陷调查/sc:troubleshoot Null pointer exception in user service --type bug --trace # Systematic analysis of error context and stack traces # Identifies root cause and provides targeted fix recommendations--trace让分析深入错误上下文与栈追踪目标是定位空指针的真正来源例如未初始化的依赖、空集合遍历而不是表层报错行。2. 构建失败分析/sc:troubleshoot TypeScript compilation errors --type build --fix # Analyzes build logs and TypeScript configuration # Automatically applies safe fixes for common compilation issues注意这里带了--fix命令会先分析构建日志与 tsconfig 配置然后在征得用户确认后对常见编译问题应用安全修复。带--fix的调用路径是诊断 → 向用户确认 → 应用修复 → 用测试验证。3. 性能问题诊断/sc:troubleshoot API response times degraded --type performance # Performance metrics analysis and bottleneck identification # Provides optimization recommendations and monitoring guidance未带--fix因此只做指标分析与瓶颈定位输出优化建议与监控指引不擅自改动任何代码。4. 部署问题解决/sc:troubleshoot Service not starting in production --type deployment --trace # Environment and configuration analysis # Systematic verification of deployment requirements and dependencies--type deployment引导排查聚焦环境差异与依赖验证--trace加深对启动日志与配置链的分析。边界与安全能做什么不能做什么原文档用两节Boundaries 与 CRITICAL BOUNDARIES清晰划定了命令的行为边界。Will会做使用结构化调试方法论执行系统性问题诊断提供经过验证的解决方案与全面的问题分析应用带验证环节与详细解决文档的安全修复。Will Not不会做不做充分分析与用户确认就应用高风险修复未经明确许可与安全验证就修改生产系统在未完全理解系统影响的前提下进行架构级变更。关键边界诊断优先修复必须显式授权/sc:troubleshoot最核心的安全设计是DIAGNOSE FIRST诊断优先原则——该命令默认只诊断不修复默认行为不带--fix标志诊断问题定位根因给出解决方案选项在此停止将发现呈现给用户——不应用任何修复。带--fix标志时完成诊断后先向用户确认是否应用修复只有在用户明确批准后才应用修复修复后用测试验证有效性。明确禁止不带--fix标志不应用任何代码变更不修改任何文件不自动执行修复。输出物诊断报告必须包含四部分问题描述Issue description根因分析Root cause analysis按优先级排序的解决方案Proposed solutions, ranked每个方案的风险评估Risk assessment for each solution。下一步Next Step用户审阅诊断报告后二选一继续重新运行并加上--fix标志以应用推荐修复使用/sc:improve参见 src/superclaude/commands/improve.md进行更大范围的代码改进/重构。这套诊断—报告—确认—修复的闭环设计在框架的命令输出分类中也得到了印证/sc:troubleshoot被明确归类为文档型命令Document-Only Commands——它默认只产出诊断报告修复必须依赖--fix标志加用户确认参见 docs/reference/commands-list.md。这与/sc:implement、/sc:improve等执行型命令形成鲜明对比。与其他能力的配合与 Introspection 模式配合当排查结果与预期不符或需要复盘为什么上次的解决方案没有生效时可结合--introspect模式src/superclaude/modes/MODE_Introspection.md进行元认知分析。该模式专门用于错误恢复与结果与预期不符的场景输出带 ⚡ 等透明化标记的推理过程帮助把一次失败排查转化为可复用的经验。与 Serena MCP 安装排查配合若问题出在 SuperClaude 自身的 MCP 环境例如 Serena 无法启动可参考 docs/troubleshooting/serena-installation.md 中的专项排查指南。该文档记录了Failed to spawn: serena错误的典型场景安装器曾错误地使用uv run serena而非uvx安装 Serena MCP。解决方案依次为移除损坏安装claude mcp remove serena用uvx方式直接安装uvx --from githttps://github.com/oraios/serena serena --help重新注册claude mcp add serena -- uvx --from githttps://github.com/oraios/serena serena start-mcp-server --context ide-assistant验证claude mcp list。其核心教训是uv run serena依赖本地项目依赖而uvx直接运行远程 GitHub 仓库中的工具后者才是 Serena 的正确安装方式。手动配置时需在~/.claude.json的mcpServers中写入对应命令与参数。与常见问题快速参考配合文档 docs/reference/common-issues.md 提供了另一层快修视角——它汇总了覆盖约 90% 场景的五个高频问题命令不生效、安装验证、权限问题、MCP 服务器异常、组件缺失及对应的一行命令解法可作为/sc:troubleshoot深度诊断之前的快速检查清单。当快速方案不奏效时再进入系统性根因分析流程。总结/sc:troubleshoot是 SuperClaude Framework 中一个小而严谨的基础排查命令它用--type参数覆盖代码、构建、性能、部署四大问题域用--trace提供深度追踪能力用五步行为流保证诊断过程的系统性而诊断优先 --fix显式授权的边界设计则确保它永远把用户安全与代码库完整性放在第一位。配合框架底层的 troubleshoot 技能协议反模式约束与根因分析报告格式以及 Introspection 模式的复盘能力它构成了一条完整的发现问题 → 定位根因 → 确认修复 → 验证生效 → 沉淀经验的闭环链路。无论你是想排查一次诡异的运行时异常还是分析构建失败、定位性能瓶颈、解决生产部署问题都可以从一句简单的/sc:troubleshoot 问题描述 --type 对应类型 --trace开始让 Claude Code 先给出有证据支撑的诊断报告再决定是否以--fix授权修复。赞分享开发工具CLIAI 技能/插件测试人工智能AI 评测【免费下载链接】SuperClaude_FrameworkA configuration framework that enhances Claude Code with specialized commands, cognitive personas, and development methodologies.项目地址https://gitcode.com/gh_mirrors/su/SuperClaude_Framework点击查看免费下载相关推荐SuperClaude Framework 的 /sc:troubleshoot 命令从问题诊断到安全修复的完整实战指南SuperClaude Framework 的 /sc:troubleshoot 命令从问题诊断到安全修复的完整实战指南 导读 /sc:troubleshoo开发工具CLIAI 技能/插件测试人工智能AI 评测SuperClaude Framework 故障排查指南从快速修复到高级诊断的完整实战手册SuperClaude Framework 故障排查指南从快速修复到高级诊断的完整实战手册 SuperClaude Framework 是一个通过 CLI 将开发工具CLIAI 技能/插件测试人工智能AI 评测SuperClaude Framework 常见问题排查实战指南从快速修复到源码级诊断SuperClaude Framework 常见问题排查实战指南从快速修复到源码级诊断 SuperClaude Framework 是一套为 Claude C开发工具CLIAI 技能/插件测试人工智能AI 评测创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考