# 常见陷阱和故障排除

## 陷阱 1：过度分析

**症状**：每个模块产生 20+ 发现，issue 长达数千行，审查者不知所措

**原因**：没有应用置信度 + ROI 分诊，或设置了过低的分诊阈值

**解决**：
- 提高分诊阈值 — 只保留高置信度 + 高/中 ROI 的发现
- 专注于每个方面最重要的 2-3 个问题，而不是所有问题
- 记住：目标是可操作的改进，不是完整的代码审计报告

## 陷阱 2：误报

**症状**：创建的 issue 后来被标记为"有意设计"或"不会修复"

**原因**：低置信度发现被包含，或缺乏对模块设计意图的上下文

**解决**：
- 严格执行置信度评估 — 低置信度发现应该被丢弃，而不是创建 issue
- 在 issue 中注明"可能是设计选择" — 让审查者决定
- 查看模块的测试文件以理解预期行为

## 陷阱 3：低 ROI 发现

**症状**：issue 创建后数月无人处理，或被标记为"good first issue"但优先级低

**原因**：发现了真实问题，但修复投入太大或影响太小

**解决**：
- 在创建 issue 前问："这值得花费工程时间吗？"
- 大投入 + 小影响 = 丢弃，除非是安全/数据丢失问题
- 专注于"快速获胜" — 小改动产生大影响的发现

## 陷阱 4：缺少代码示例

**症状**：issue 中只有描述性文字，审查者要求"请展示代码示例"

**原因**：跳过了代码片段指南，或示例太冗长/太模糊

**解决**：
- 每个发现必须包含 before/after 代码片段（5-15 行）
- 显示具体问题模式，不只是"重构使用接口"
- 对于设计问题，显示提议的接口签名

## 陷阱 5：进度文件损坏

**症状**：`.claude/arch-analysis/progress.json` 格式错误，skill 无法加载

**原因**：手动编辑或并发写入冲突

**解决**：
- 不要手动编辑进度文件 — skill 会管理它
- 如果损坏，删除文件让 skill 重新初始化
- 使用 `jq` 验证 JSON：`jq . .claude/arch-analysis/progress.json`

## 陷阱 6：模块边界不清

**症状**：分析覆盖了不该包含的代码，或遗漏了相关文件

**原因**：模块发现逻辑与实际代码结构不匹配

**解决**：
- 优先使用 CLAUDE.md 中的 STRUCTURE 部分
- 对于大型模块（>1500 行），拆分为子模块
- 在进度文件中手动调整模块列表

## 陷阱 7：/loop 执行中断

**症状**：`/loop` 在中途停止，或重复分析同一模块

**原因**：未处理的错误或进度文件更新失败

**解决**：
- 检查最近的 `recent_activity` 日志以查找失败模式
- 确保每次调用都更新 `last_analyzed` 时间戳
- 如果卡住，手动增加模块的 `analysis_count` 以跳过它

## 陷阱 8：Issue 格式错误

**症状**：GitHub 错误渲染 issue，或数字变成链接

**原因**：使用了 `#` 数字或违反了其他格式规则

**解决**：
- 严格遵循 issue 模板
- 使用"cycle N"而不是"cycle #N"
- 验证：创建测试 issue 检查渲染

## 陷阱 9：重复创建 Issue

**症状**：同一问题出现多个 issue，审计时发现大量重复

**原因**：不同分析方面（SOLID + DRY）发现同一代码模式的不同表现，或重新分析时再次发现已跟踪的问题

**解决**：
- 严格执行步骤 4.8 的去重检查 — 每次创建 issue 前必须搜索
- 重点关注跨方面的重叠：DRY 和 SOLID 经常发现同一问题的不同角度
- 重新分析模块时，先列出该模块的所有已有 issue 作为上下文
- 使用进度文件中的 `issues_created` 作为第一道防线（快速排除已知问题）
