troubleshooting
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseTroubleshooting
故障排除
Diagnose and resolve common problems that arise during spec-driven development and feature implementation.
诊断并解决规范驱动开发与功能实施过程中出现的常见问题。
When to Use This Skill
何时使用此技能
Use troubleshooting strategies when:
- Implementation doesn't match spec expectations
- Tasks are blocked by dependencies
- Requirements are unclear during coding
- Tests are failing or hard to write
- Performance doesn't meet requirements
- Integration problems occur
在以下场景中使用故障排除策略:
- 实施结果不符合规范预期
- 任务因依赖关系受阻
- 编码期间需求不明确
- 测试失败或难以编写
- 性能未达要求
- 出现集成问题
Issue 1: Spec and Reality Diverge
问题1:规范与实际不符
Symptoms
症状
- Code structure doesn't match spec assumptions
- APIs are unavailable or deprecated
- Performance differs from expectations
- Integration points work differently than specified
- 代码结构与规范假设不符
- APIs不可用或已废弃
- 性能与预期存在差异
- 集成点的工作方式与规范描述不同
Resolution
解决方法
Immediate Actions:
- Document the gap exactly
- Assess impact (minor detail vs fundamental issue)
- Stop implementing until you understand implications
Resolution Options:
Option 1: Update Spec (Minor Deviations)
If difference is minor and doesn't affect requirements:
1. Update design section with actual approach
2. Adjust affected tasks
3. Document why change was needed
4. Continue implementationOption 2: Redesign (Major Deviations)
If core assumptions are wrong:
1. Return to design phase
2. Incorporate new understanding
3. Re-validate against requirements
4. Create new task breakdown
5. Restart with corrected planOption 3: Adjust Requirements (Fundamental Issues)
If requirements can't be met as stated:
1. Document why requirements aren't achievable
2. Propose alternative approach
3. Get stakeholder approval
4. Update entire spec
5. Restart process立即行动:
- 准确记录差异点
- 评估影响程度(细节问题 vs 根本性问题)
- 在明确影响前暂停实施
解决选项:
选项1:更新规范(微小偏差)
If difference is minor and doesn't affect requirements:
1. Update design section with actual approach
2. Adjust affected tasks
3. Document why change was needed
4. Continue implementation选项2:重新设计(重大偏差)
If core assumptions are wrong:
1. Return to design phase
2. Incorporate new understanding
3. Re-validate against requirements
4. Create new task breakdown
5. Restart with corrected plan选项3:调整需求(根本性问题)
If requirements can't be met as stated:
1. Document why requirements aren't achievable
2. Propose alternative approach
3. Get stakeholder approval
4. Update entire spec
5. Restart processPrevention
预防措施
- Validate assumptions with code exploration during design
- Prototype risky integrations before finalizing spec
- Include technical spikes in task breakdown
- 在设计阶段通过代码探索验证假设
- 在最终确定规范前对高风险集成进行原型开发
- 在任务分解中加入技术研究任务
Issue 2: Task Dependencies Block Progress
问题2:任务依赖阻塞进度
Symptoms
症状
- Can't complete task without later features
- Multiple tasks need same file changes
- Tests need features not yet built
- Circular dependencies between tasks
- 无后续功能则无法完成当前任务
- 多个任务需要修改同一文件
- 测试依赖尚未构建的功能
- 任务之间存在循环依赖
Resolution
解决方法
Strategy 1: Reorder Tasks
If dependency was missed in planning:
1. Identify the prerequisite task
2. Complete it first
3. Return to blocked task
4. Update task sequence for futureStrategy 2: Split Tasks
If task is too large:
1. Break blocked task into smaller pieces
2. Complete parts that aren't blocked
3. Queue dependent parts for later
4. Update task breakdownStrategy 3: Use Mocking/Stubbing
If dependency is complex:
1. Create minimal stub/mock of dependency
2. Complete current task against stub
3. Replace stub when real dependency ready
4. Add integration testing taskStrategy 4: Parallel Development
If dependency is in progress:
1. Define clear interface/contract
2. Implement against interface
3. Test with mock implementation
4. Integrate when dependency completes策略1:重新排序任务
If dependency was missed in planning:
1. Identify the prerequisite task
2. Complete it first
3. Return to blocked task
4. Update task sequence for future策略2:拆分任务
If task is too large:
1. Break blocked task into smaller pieces
2. Complete parts that aren't blocked
3. Queue dependent parts for later
4. Update task breakdown策略3:使用模拟/存根
If dependency is complex:
1. Create minimal stub/mock of dependency
2. Complete current task against stub
3. Replace stub when real dependency ready
4. Add integration testing task策略4:并行开发
If dependency is in progress:
1. Define clear interface/contract
2. Implement against interface
3. Test with mock implementation
4. Integrate when dependency completesPrevention
预防措施
- Map dependencies explicitly during task planning
- Order tasks to minimize blocking
- Identify tasks that can be parallelized
- 在任务规划阶段明确映射依赖关系
- 对任务进行排序以最小化阻塞
- 识别可并行执行的任务
Issue 3: Requirements Unclear During Implementation
问题3:实施期间需求不明确
Symptoms
症状
- Multiple valid interpretations
- Edge cases not addressed
- Conflicting requirements discovered
- UX details missing
- 存在多种合理解读
- 未涉及边缘情况
- 发现相互冲突的需求
- 缺失用户体验细节
Resolution
解决方法
Step 1: Analyze the Ambiguity
- What exactly is unclear?
- What are possible interpretations?
- What's the impact of each?
- Is this common or edge case?
Step 2: Propose Solution
- What's most consistent with existing requirements?
- What aligns with user needs?
- What's technically simplest?
- Make recommendation with rationale
Step 3: Get Clarification
- Update requirements with clarification
- Update acceptance criteria if needed
- Document decision rationale
- Proceed with implementation
Step 4: Update Tasks
- Adjust current task if needed
- Add new tasks if solution is complex
- Update testing tasks
步骤1:分析模糊点
- 具体哪里不明确?
- 可能的解读有哪些?
- 每种解读的影响是什么?
- 这是常见情况还是边缘情况?
步骤2:提出解决方案
- 哪种方案最符合现有需求?
- 哪种方案符合用户需求?
- 哪种方案在技术上最简单?
- 附上理由提出建议
步骤3:获取澄清
- 更新需求以包含澄清内容
- 如有需要调整验收标准
- 记录决策理由
- 继续实施
步骤4:更新任务
- 如有需要调整当前任务
- 若解决方案复杂则添加新任务
- 更新测试任务
Prevention
预防措施
- Probe for edge cases during requirements phase
- Use examples to clarify requirements
- Review requirements with developers before design
- 在需求阶段探查边缘情况
- 使用示例澄清需求
- 在设计前与开发人员评审需求
Issue 4: Technical Debt Creates Friction
问题4:技术债务导致阻碍
Symptoms
症状
- Need to refactor before adding feature
- Tests are brittle or missing
- Code is tightly coupled
- No clear extension points
- 添加功能前需要重构
- 测试脆弱或缺失
- 代码耦合度高
- 无明确的扩展点
Resolution
解决方法
Strategy 1: Refactor-First
If refactoring is bounded and low-risk:
1. Create refactoring tasks separate from feature
2. Get approval for additional work
3. Complete refactoring with tests
4. Proceed with featureStrategy 2: Parallel Track
If refactoring is extensive:
1. Implement feature with workarounds
2. Create separate refactoring initiative
3. Document technical debt created
4. Plan future cleanupStrategy 3: Incremental Improvement
If refactoring can be done in pieces:
1. Refactor only what you touch
2. Leave code better than you found it
3. Add tests for refactored areas
4. Continue feature implementation策略1:先重构
If refactoring is bounded and low-risk:
1. Create refactoring tasks separate from feature
2. Get approval for additional work
3. Complete refactoring with tests
4. Proceed with feature策略2:并行推进
If refactoring is extensive:
1. Implement feature with workarounds
2. Create separate refactoring initiative
3. Document technical debt created
4. Plan future cleanup策略3:增量改进
If refactoring can be done in pieces:
1. Refactor only what you touch
2. Leave code better than you found it
3. Add tests for refactored areas
4. Continue feature implementationPrevention
预防措施
- Assess existing code quality during design
- Include refactoring tasks when needed
- Set realistic timelines accounting for debt
- 在设计阶段评估现有代码质量
- 必要时加入重构任务
- 设定考虑技术债务的合理时间线
Issue 5: Tests Failing or Hard to Write
问题5:测试失败或难以编写
Symptoms
症状
- Tests fail randomly (flaky)
- Setup code is complex
- Mocking is complicated
- Tests take too long
- 测试随机失败(不稳定)
- 代码设置复杂
- 模拟操作繁琐
- 测试耗时过长
Resolution
解决方法
For Tightly Coupled Code:
- Extract interfaces for dependencies
- Use dependency injection
- Create test fixtures/factories
- Implement test doubles
For Complex Setup:
- Create reusable test utilities
- Use test builders/factories
- Implement setup helpers
- Share fixtures across tests
For Flaky Tests:
- Remove timing dependencies
- Eliminate global state
- Mock external dependencies
- Use deterministic test data
For Slow Tests:
- Use test doubles for expensive operations
- Parallelize test execution
- Optimize database setup/teardown
- Cache expensive setups
针对高耦合代码:
- 为依赖项提取接口
- 使用依赖注入
- 创建测试夹具/工厂
- 实现测试替身
针对复杂设置:
- 创建可复用的测试工具
- 使用测试构建器/工厂
- 实现设置助手
- 在测试间共享夹具
针对不稳定测试:
- 移除时间依赖
- 消除全局状态
- 模拟外部依赖
- 使用确定性测试数据
针对慢速测试:
- 对昂贵操作使用测试替身
- 并行执行测试
- 优化数据库设置/清理
- 缓存昂贵的设置
Prevention
预防措施
- Design for testability during design phase
- Include test strategy in design document
- Write tests alongside implementation
- 在设计阶段考虑可测试性
- 在设计文档中包含测试策略
- 边实施边编写测试
Issue 6: Performance Problems
问题6:性能问题
Symptoms
症状
- Slow response times
- High memory usage
- Database query issues
- Excessive network calls
- 响应时间慢
- 内存使用率高
- 数据库查询问题
- 网络调用过多
Resolution
解决方法
Step 1: Measure
- Profile the code
- Identify bottlenecks
- Quantify the gap
- Establish baseline
Step 2: Analyze
- Algorithmic complexity?
- Database inefficiency?
- Network latency?
- Resource contention?
Step 3: Optimize
- Target biggest bottleneck first
- Make one change at a time
- Measure after each change
- Document optimizations
Step 4: Validate
- Verify requirements met
- Check no regressions
- Add performance tests
- Document characteristics
Common Fixes:
- Database: Add indexes, optimize queries, implement caching
- Algorithm: Better data structures, reduce complexity, lazy loading
- Network: Batch requests, compression, reduce payload size
步骤1:测量
- 对代码进行性能分析
- 识别瓶颈
- 量化差距
- 建立基准
步骤2:分析
- 算法复杂度问题?
- 数据库效率问题?
- 网络延迟问题?
- 资源竞争问题?
步骤3:优化
- 首先针对最大的瓶颈
- 每次只做一处修改
- 每次修改后进行测量
- 记录优化内容
步骤4:验证
- 验证是否满足需求
- 检查是否有回归
- 添加性能测试
- 记录性能特征
常见修复方法:
- 数据库:添加索引、优化查询、实现缓存
- 算法:使用更好的数据结构、降低复杂度、懒加载
- 网络:批量请求、压缩、减少 payload 大小
Prevention
预防措施
- Include performance requirements in spec
- Design with performance in mind
- Profile early and often
- 在规范中包含性能需求
- 设计时考虑性能
- 尽早并经常进行性能分析
Issue 7: Integration Problems
问题7:集成问题
Symptoms
症状
- Works locally, fails in integration
- Timing issues in production
- Data format mismatches
- Auth failures
- 本地运行正常,集成环境失败
- 生产环境出现时序问题
- 数据格式不匹配
- 认证失败
Resolution
解决方法
Step 1: Isolate Problem
- Does it work in isolation?
- Which integration point fails?
- Consistent or intermittent?
- What's different in integration environment?
Step 2: Verify Contracts
- Check API specifications
- Validate data formats
- Verify authentication flow
- Review error responses
Step 3: Test Integration Points
- Test each integration separately
- Use integration test environment
- Verify error handling
- Check timeout behavior
Step 4: Fix and Validate
- Implement fix
- Add integration tests
- Verify in integration environment
- Update spec if assumptions wrong
Common Issues:
- Configuration differences (URLs, credentials)
- Data format issues (dates, encoding, nulls)
- Timing issues (race conditions, timeouts)
步骤1:隔离问题
- 单独运行是否正常?
- 哪个集成点失败?
- 是持续还是间歇性的?
- 集成环境与本地有何不同?
步骤2:验证契约
- 检查API规范
- 验证数据格式
- 验证认证流程
- 查看错误响应
步骤3:测试集成点
- 单独测试每个集成
- 使用集成测试环境
- 验证错误处理
- 检查超时行为
步骤4:修复并验证
- 实施修复
- 添加集成测试
- 在集成环境中验证
- 若假设错误则更新规范
常见问题:
- 配置差异(URLs、credentials)
- 数据格式问题(dates、encoding、nulls)
- 时序问题(race conditions、timeouts)
Prevention
预防措施
- Test in integration environment early
- Document integration requirements clearly
- Include integration tests in task breakdown
- 尽早在集成环境中测试
- 清晰记录集成需求
- 在任务分解中包含集成测试
Issue 8: Scope Creep During Implementation
问题8:实施期间范围蔓延
Symptoms
症状
- "While I'm here, I should also..."
- "It would be easy to add..."
- Tasks taking longer than estimated
- Feature complexity growing
- "既然我在这里,我还应该……"
- "添加这个很容易……"
- 任务耗时超过预估
- 功能复杂度不断增加
Resolution
解决方法
Step 1: Recognize It
- Notice when going beyond spec
- Identify additions vs requirements
- Assess if it's scope creep
Step 2: Evaluate
- Is it required for current requirements?
- Is it a bug fix or enhancement?
- Cost of doing now vs later?
Step 3: Decide
Option A: Required for Current Feature
- Update spec with new requirement
- Add to current work
- Adjust timeline
Option B: Nice to Have
- Document as future enhancement
- Complete current spec first
- Create separate spec later
Option C: Out of Scope
- Note as explicitly excluded
- Create future spec if valuable
- Stay focused on current work
步骤1:识别范围蔓延
- 注意何时超出规范范围
- 区分新增内容与需求内容
- 评估是否属于范围蔓延
步骤2:评估
- 这是当前需求所必需的吗?
- 这是 bug 修复还是功能增强?
- 现在做与以后做的成本对比?
步骤3:决策
选项A:当前功能必需
- 更新规范以包含新需求
- 添加到当前工作中
- 调整时间线
选项B:锦上添花的功能
- 记录为未来增强功能
- 先完成当前规范内容
- 之后再创建单独的规范
选项C:超出范围
- 明确标注为排除内容
- 若有价值则创建未来规范
- 专注于当前工作
Red Flags
危险信号
- "Just one more feature"
- "While we're changing this..."
- Refactoring beyond what's needed
- Gold-plating solutions
- "再添加一个功能就好"
- "既然我们在改这个……"
- 超出需求的重构
- 过度优化解决方案
Prevention
预防措施
- Clear requirements and acceptance criteria
- Regular review against spec
- Time-box implementation tasks
- 明确的需求与验收标准
- 定期对照规范进行评审
- 为实施任务设定时间盒
Debugging Strategies
调试策略
Rubber Duck Debugging
橡皮鸭调试
Explain the problem out loud. Often the explanation reveals the solution.
大声解释问题。通常在解释的过程中就能找到解决方案。
Binary Search
二分查找
Isolate by dividing code in half repeatedly until you find the issue.
通过反复将代码分成两半来隔离问题,直到找到问题所在。
Strategic Logging
策略性日志
Add logging to understand code flow and data transformations.
添加日志以了解代码流程和数据转换。
Minimal Reproduction
最小复现
Create smallest test case that reproduces the issue.
创建能复现问题的最小测试用例。
Compare Working vs Broken
对比正常与异常版本
Find similar working code and compare differences.
找到类似的正常工作代码并对比差异。
When to Update the Spec
何时更新规范
Always Update When:
- Design assumptions were wrong
- Requirements need clarification
- Tasks need reordering
- New edge cases discovered
- Technical approach changes
Document:
- Why changes were made
- When they were made
- Impact on timeline
- Alternatives considered
以下情况必须更新:
- 设计假设错误
- 需求需要澄清
- 任务需要重新排序
- 发现新的边缘情况
- 技术方案变更
需记录:
- 变更原因
- 变更时间
- 对时间线的影响
- 考虑过的替代方案
Getting Unstuck
如何摆脱困境
When truly blocked:
- Take a break - Solution often comes when you step away
- Review the spec - Re-read requirements and design
- Ask for help - Get a second pair of eyes
- Simplify - Solve a simpler version first
- Prototype - Try multiple approaches quickly
- Go back a phase - Maybe the spec needs work
当真正陷入阻塞时:
- 休息一下 - 往往在你离开后解决方案就会浮现
- 回顾规范 - 重新阅读需求与设计
- 寻求帮助 - 获得他人的视角
- 简化问题 - 先解决更简单的版本
- 制作原型 - 快速尝试多种方案
- 回到上一阶段 - 可能规范需要调整