메뉴
系统性技术问题诊断框架。通过"边界收敛→分支诊断→假设验证→证据链→方案决策"五步法，将试错式排查变为结构化分析。当用户说"分析这个问题"、"报错了帮我看看"、"定位一下根因"、"帮我分析一下这个现象"、"这个Bug怎么查"、"内存泄漏/崩溃/性能退化/死锁怎么定位"、或描述了任何软件异常现象时触发。不用于产品需求分析或日常决策（那是 structured-thinking 的范畴）。
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
Generate comprehensive test cases from already analyzed or decomposed requirements specifications. Use when the input is a completed requirements breakdown, feature specification, PRD analysis, user story map, acceptance criteria list, or module/function requirements and the user wants test case design, scenario expansion, module-based test flows, coverage review, or exportable test case documents in Markdown, Excel/XLSX, CSV, or document formats.
Use when refining an architecture or design document based on new learnings, before a rewrite. Use when you have an existing doc and related docs to cross-check against. Use when you need systematic section-by-section validation of decisions.
项目文档的全生命周期管理。支持：初始化文档（按阶段+范围选择性生成）、更新文档（扫描代码对比，输出差异并更新）。范围可指定仅仓库级/指定子工程/全部。与 project-structure-init 配合使用但不强制依赖。当用户说"初始化文档"、"更新文档"、"生成文档"、"补文档"、"刷新文档"、"同步文档与代码"、"检查文档"、"只初始化仓库级"、"只更新某个文档"时触发。
根据《软件工程目录规范》自动创建仓库级和工程级（C++）的完整目录结构及文档骨架。自动识别当前目录所属级别，仓库级则逐级向下完成全部初始化。当用户说"初始化项目结构"、"创建仓库目录"、"搭建工程结构"、"按规范创建目录"、"初始化docs"、"创建C++工程"时触发。增量创建，已存在的文件和目录不会覆盖。
编写 C++ 项目的详细设计文档和设计变更影响面分析。当用户说要写详细设计、生成设计文档、做影响面分析、描述功能需求要写设计、或者说"把这个需求的设计写出来"时触发。也用于增量更新已有设计文档、以及清除迭代标记输出最终版。
在代码提交（svn commit / git commit）前，自动执行一套完整的审查与提交辅助流程： 1. 阅读项目 CLAUDE.md 了解项目功能模块背景； 2. 阅读编码规范约束（统一编码约束、Qt 命名规范、日志规范）； 3. 自动调用 code-review-skill 对已完成的改动进行结构化评审； 4. 输出评审报告+修改说明，提交给用户进行确认； 5. 用户确认修复完成后，输出本次修改说明。 使用时机：用户说"要提交代码了"、"帮我审一下改动"、"看看这些改动有什么问题"、"准备 commit / svn ci"、或者直接描述需要提交评审的场景时，**必须**触发本 skill。 注意：本 skill 不直接执行 commit / push 等命令，仅输出报告和提交说明，由用户手动执行提交。
| name | structured-analyze |
| description | 系统性技术问题诊断框架。通过"边界收敛→分支诊断→假设验证→证据链→方案决策"五步法，将试错式排查变为结构化分析。当用户说"分析这个问题"、"报错了帮我看看"、"定位一下根因"、"帮我分析一下这个现象"、"这个Bug怎么查"、"内存泄漏/崩溃/性能退化/死锁怎么定位"、或描述了任何软件异常现象时触发。不用于产品需求分析或日常决策（那是 structured-thinking 的范畴）。 |
structured-thinking 解决决策类问题（做什么、值不值得做），本 skill 解决诊断类问题（哪里出了问题、怎么最快修）。
核心思路：不是拿到问题就开始翻代码或抓 dump，而是先分边界，再定策略，再并行验证。把试错循环变成收敛过程。
辅助工具：需要深入分析日志时可用 log-analyze skill，但本框架不强制依赖它。
输入侧 — 参数值/操作序列/输入数据本身是否合理？
软件侧 — 参数的流转路径是否正常？（加载→传递→生效→存储）
算法侧 — 在给定参数下，算法内部计算是否符合预期？
硬件侧 — 物理设备/环境是否正常？
判定优先级：输入 > 软件 > 算法 > 硬件。输入问题最常见也最快确认，硬件问题最耗时。
这是最关键的阶段。一个常见陷阱是：拿到问题直接翻代码。正确做法是先用现有证据判定归属。
分析前必须确认用户手头有什么。不要假设有日志。
逐项询问：
- 有问题描述吗？（现象、时间、频率、操作步骤）
- 有软件日志吗？（应用运行日志、配置日志、错误日志、操作审计日志）
- 有算法日志吗？（匹配过程、评分、中间状态、候选输出）
- 有其他可用数据吗？（截图、现场照片、dump、硬件SDK日志、性能监视器）
然后标注每层判定受限于什么：
| 有完整日志 | 该层判定置信度高 |
|---|---|
| 只有问题描述 | 该层可以基于现象推理，但置信度低 |
| 什么都没有 | 所有分析基于现象推理，标注置信度低，同时输出"需要收集的最小证据集" |
一个例子：如果用户只描述了现象但无日志，那你仍然可以做推理（像 RMS case 里基于因果关系推断输入侧问题），但必须标注"置信度：中，待日志验证"。
按输入→软件→算法→硬件的优先级逐层检查：
┌─ 输入侧检查 ─────────────────────────────────────────────────┐
│ │
│ 关键词：参数值、配置项、操作序列、输入数据 │
│ │
│ 查什么： │
│ - 被修改的参数/配置值本身是否合理？ │
│ - 操作序列是什么？谁在什么时候做了什么？ │
│ - 输入数据本身是否合法？（格式、范围、编码） │
│ │
│ 判定信号： │
│ - 参数值不合理（min > 正常值 → 排除正确结果） │
│ - 操作序列有误（改了值但语义理解错了） │
│ - 输入数据异常（格式错误、超范围） │
│ │
│ → 命中任一 → 归属"输入侧"，跳至阶段一输入分支 │
└──────────────────────────────────────────────────────────────┘
┌─ 软件侧检查 ─────────────────────────────────────────────────┐
│ │
│ 关键词：参数传递、配置加载、状态机、生效规则 │
│ │
│ 查什么： │
│ - 参数从输入到使用的完整链路：UI → 存储 → 加载 → 算法 │
│ - 配置变更后是否立即生效？是否需重启？ │
│ - 多个配置源之间是否一致？（UI/配置文件/数据库） │
│ - 状态机是否在合法状态下接收了参数变更？ │
│ - 软件日志中的错误/告警/异常状态 │
│ │
│ 判定信号： │
│ - 配置加载失败或加载了错误的值 │
│ - 配置变更未生效（依赖重启但未重启） │
│ - 多配置源不一致（UI 显示值 ≠ 算法使用值） │
│ - 状态机处于异常状态导致参数处理错误 │
│ │
│ → 命中任一 → 归属"软件侧"，跳至阶段一软件分支 │
└──────────────────────────────────────────────────────────────┘
┌─ 算法侧检查 ─────────────────────────────────────────────────┐
│ │
│ 关键词：匹配评分、中间结果、错误码 │
│ │
│ 查什么： │
│ - 算法日志中的候选评分/迭代次数/中间状态 │
│ - 给定输入（含参数约束），输出是否符合算法设计预期？ │
│ - 是否有错误码或异常状态？ │
│ │
│ 判定信号： │
│ - 给定合理输入和正确参数，算法输出错误 │
│ - 边界条件未处理（空输入、极值、重复执行） │
│ - 算法输出了错误码或异常状态 │
│ │
│ → 命中任一 → 归属"算法侧"，跳至阶段一算法分支 │
└──────────────────────────────────────────────────────────────┘
┌─ 硬件侧检查 ─────────────────────────────────────────────────┐
│ │
│ 关键词：相机状态、通信链路、信号时序、驱动版本 │
│ │
│ 查什么： │
│ - SDK日志中的设备状态/错误码/心跳 │
│ - 系统事件日志（设备断开、驱动错误） │
│ - 已知的驱动/固件兼容性问题 │
│ │
│ 判定信号： │
│ - SDK报告设备异常或断开 │
│ - 通信超时/丢包 │
│ - 信号时序异常 │
│ │
│ → 命中任一 → 归属"硬件侧"，跳至阶段一硬件分支 │
└──────────────────────────────────────────────────────────────┘
用户补充新证据后，重新执行判定。边界越来越清晰，直到锁定归属。
## 阶段零：边界收敛
### Step 0: 已有证据确认
- 问题描述：[有/无] — [概括]
- 软件日志：[有/无] — [概括]
- 算法日志：[有/无] — [概括]
- 其他数据：[有/无] — [概括]
- 数据限制：[哪些层的判定因缺数据置信度降低]
### 逐层判定
- 输入侧：[通过/可疑/排除] — [理由] — 置信度: [高/中/低]
- 软件侧：[通过/可疑/排除] — [理由] — 置信度: [高/中/低]
- 算法侧：[通过/可疑/排除] — [理由] — 置信度: [高/中/低]
- 硬件侧：[通过/可疑/排除] — [理由] — 置信度: [高/中/低]
### 结论
- 问题归属：[输入/软件/算法/硬件/待定]
- 置信度：[高/中/低]
### 进一步收集建议（如果待定）
- [精确的日志/数据收集建议，含时间点、关键字段]
根据阶段零的归属，进入对应分支。四个分支的诊断策略完全不同。
目标：确认是操作失误、配置缺陷还是输入数据本身有问题。
诊断路径：
1. 参数传递链路追踪
→ 输入端 → 存储位置 → 读取时机 → 使用位置
→ 关键词：config/param/setting/limit/threshold
2. 变更时间线重建
→ 从日志时间点倒推：谁在什么时刻改了什么值
→ 对比修改前后的运行结果
3. 默认值与生效规则
→ 未配置时使用什么默认值？默认值是否合理？
→ 配置变更后是否立即生效？是否需重启？
4. 多配置源一致性
→ 同一个参数是否有多个配置入口（UI/配置文件/数据库/命令行）？
→ 不同入口的值是否一致？哪个优先级最高？
输出: 非Bug（操作/配置问题）或 输入校验缺陷
目标：确认参数的完整流转路径是否正常。即使输入值本身是合理的，软件在加载/传递/生效过程中也可能出问题。
诊断路径：
1. 参数传递链路追踪
→ 输入端(UI/配置文件/数据库) → 存储位置 → 读取时机 → 使用位置(算法入口)
→ 关键词：config/param/setting/limit/threshold
2. 变更生效规则
→ 配置变更后是否立即生效？是否需重启或触发重载？
→ 如果需重启，操作员是否知晓？
3. 多配置源一致性
→ 同一个参数是否有多个配置入口（UI/配置文件/数据库/命令行）？
→ 不同入口的值是否一致？哪个优先级最高？
→ 操作员在UI上改的值和算法实际读到的值是否相同？
4. 状态机上下文
→ 参数变更时系统是否在合法状态？
→ 是否在运行中/暂停/停止等状态下有不同的参数处理逻辑？
5. 默认值与回退逻辑
→ 未配置时使用什么默认值？默认值是否合理？
→ 非法值时是否回退到默认？回退逻辑是否被正确触发？
输出: 配置加载缺陷 / 参数传递断裂 / 多源不一致 / 生效时序问题
目标：定位到具体的算法步骤、状态或逻辑。
诊断路径：
1. 日志对比（最快）
→ 同一输入，正常场景 vs 异常场景的算法日志对比
→ 找到第一个分叉点：在哪里输出开始不同？
2. 中间状态检查
→ 算法各阶段的中间结果是否在预期范围？
→ 状态机是否在合法状态？
3. 版本影响评估
→ 最近有算法变更吗？diff 了什么？
→ 回退到旧版本能否复现？
4. 边界条件覆盖
→ 空输入、极端值、重复执行 → 是否触发未知路径？
5. 控制变量（兜底）
→ 只改一个参数/输入，其余不变，观察输出
→ 二分法缩小可疑代码范围
输出: 逻辑Bug / 边界条件缺陷 / 异常路径未处理 / 版本引入
目标：确认是硬件故障，还是驱动/环境问题。
诊断路径：
1. SDK/驱动日志
→ 设备状态码、错误计数、心跳中断时间点
→ 重连次数、超时频率
2. 系统事件日志（evtx / dmesg / syslog）
→ 设备断开/重连事件
→ 驱动加载失败/崩溃事件
3. 环境交叉对比
→ 同一硬件在不同机器/不同版本的同一软件上的表现
→ 同型号其他设备是否有相同现象？
4. 性能监视器（blg / perf）
→ CPU/内存/磁盘/网络趋势
→ 资源耗尽时间和问题出现时间的对齐
5. 现场环境检查
→ 线缆、电源、交换机端口统计
→ 温度、振动、EMC干扰
输出: 硬件故障 / 驱动兼容性 / 环境干扰 / 间歇性连接
## 阶段一：分支诊断 — [输入/软件/算法/硬件]
### 诊断路径
[根据具体情况选择1-N个路径]
### 发现
- [证据1]：来源 + 说明
- [证据2]：来源 + 说明
### 判定
- 类型：[操作问题 / 配置缺陷 / 参数传递断裂 / 算法Bug / 边界条件 / 硬件故障 / ...]
- 置信度：[高/中/低]
- 是否终止（非Bug）：[是/否]
当阶段一无法直接锁定根因时，进入假设驱动验证。分两步：先发散（列出所有可能根因，不急于收敛）→ 后验证（并行排查、逐个排除）。
核心原则：互不依赖的假设并行验证，不串行试错。
在列出假设之前，先用几个角度做脑力激荡，确保不遗漏。不要在这一阶段就自我审查——"不太可能"的想法也先列进来。
从以下角度逐一扫一遍，遇到可能相关的就生成一个假设：
实践提示：发散阶段不要急于评判假设的合理性。列出所有候选后，再按可能性排序。一个不成立 → 立即检验下一个。
将发散阶段产生的每个可能根因具象化为可验证的假设卡片：
## 假设1: [简短描述]
- **可能性**: [高/中/低] — [依据]
- **排除条件**: [什么证据可以证明此假设不成立]
- **验证实验**: [最小验证动作 — 可以是一次日志查询、一次重放测试、一次参数修改]
- **互不依赖**: [是/否] — [与哪些假设互斥]
每个验证实验完成后：
## 阶段二：假设验证
### 发散脑力激荡
[从常规原因/历史类比/时序/多因素/隐藏假设/最近变更角度，列出所有可能根因]
### 假设池
假设1: [描述] — 可能性: [高/中/低]
假设2: [描述] — 可能性: [高/中/低]
...
### 验证结果
- 假设1: [存活/排除] — [证据]
- 假设2: [排除] — [证据]
...
### 存活假设
[未排除的假设列表，按置信度排序]
汇总所有证据，锁定单一根因。
验证结果汇总
↓
排除不成立的假设（记录排除原因）
↓
存活假设排序（置信度从高到低）
↓
单一根因被证据链锁定？
├── 是 → 输出根因
└── 否 → 标注"待补充证据"
→ 建议下一轮要收集什么
→ 退回阶段零
## 阶段三：证据链收敛
### 根因
[一句话描述根本原因]
### 证据链
1. [证据1] — 来源: [日志文件:行号/时间戳/工具输出]
2. [证据2] — 来源: [...]
3. [证据3] — 来源: [...]
### 已排除假设
- 假设X: 排除原因 — [证据]
### 待补充（如果无法锁定）
- [需要进一步收集的证据]
根因锁定后，梳理修复方案池。同时回答两个问题：
修复方案池 → 风险/工作量/效果评分 → 推荐路径 → 第一步动作
每个方案评估维度：
- 风险: 引入新问题的概率（低/中/高）
- 工作量: 人天估算
- 效果: 根除(解决所有场景) / 规避(解决当前场景) / 减轻(降低概率)
- 验证: 如何确认修复有效
## 阶段四：方案决策
| 方案 | 描述 | 风险 | 工作量 | 效果 | 验证方式 |
|------|------|------|--------|------|----------|
| A | ... | 低 | 0.5天 | — | ... |
| B | ... | 中 | 2天 | — | ... |
### 推荐
- **立即**: [方案A]
- **后续**: [方案B/C]
- **预防**: [防止类似问题再出现的措施]
### 第一步
[今天/本周立即可以执行的最小动作]
仅在用户明确说"总结"、"归档"、"沉淀"、"写报告"时触发。报告模板：
【问题名称】：...
【问题表象】：...
【原因解析】：...
【影响范围】：...
【修改方式】：...
【排查过程】：...（按时间或逻辑顺序，引用实际日志/证据）
【经验总结】：...