complexity-assessment

复杂度评估技能

概述

分析任务描述，判断其实际复杂度，以确保选择合适的工作流和验证深度。准确性优先于速度——复杂度判断错误，就会选错工作流，导致实现失败。

**核心原则：**准确性优先于速度。复杂度判断错误 = 工作流选择错误 = 实现失败。

何时使用

始终适用：

• 规划任何新任务之前
• 收集完需求但尚未明确实施方案时
• 确定 QA 验证深度时

例外情况：

• 明显简单的修复（错别字、颜色变更）
• 已明确指定复杂度的任务

铁律

1. 绝不在评估复杂度前开始规划——复杂度等级判断错误 = 工作流选择错误 = 实现失败；务必先评估，再选择适当的工作流阶段和验证深度。
2. 不确定时务必采取保守判断——选择更高等级——低估复杂度比高估更危险；将复杂任务误判为标准任务，会跳过安全审查、架构设计和全面测试。
3. 分配等级前务必统计受影响的文件数——凭直觉估算并不可靠；分配简单／标准／复杂／史诗等级前，先扫描代码库，统计此次变更实际涉及的文件。
4. 务必标记不熟悉的技术以便调研——陌生技术暗藏复杂性；继续评估复杂度之前，先将任何不熟悉的框架、库或服务标记为需要调研。
5. 绝不因用户措辞随意而降低等级——“只是快速修复”或“小改动”反映的是用户的看法，并非实际技术范围；无论用户如何描述，都要客观评估。

工作流类型

确定请求的工作类型：

FEATURE

• 为代码库添加新功能
• 为现有功能增强能力
• 构建新的 UI 组件、API 端点或服务
• 示例：“添加粘贴截图功能”“构建用户仪表板”“创建新的 API 端点”

REFACTOR

• 用新的实现替换现有功能
• 从一个系统／模式迁移到另一个系统／模式
• 在保持行为不变的同时重组代码结构
• 示例：“将身份验证从会话迁移到 JWT”“重构缓存层”

INVESTIGATION

• 调试未知问题
• 分析错误的根本原因
• 调查性能问题
• 示例：“查明页面加载缓慢的原因”“调试间歇性崩溃”

MIGRATION

• 在不同系统之间迁移数据
• 对数据库架构进行更改并转换数据
• 导入／导出操作
• 示例：“将用户数据迁移到新架构”“导入旧版记录”

SIMPLE

• 范围明确、非常小的更改
• 修改单个文件
• 无需架构决策
• 示例：“修正错别字”“更新按钮颜色”“更改错误消息”

复杂度等级

SIMPLE

• 修改 1–2 个文件
• 涉及单个服务／领域
• 无外部集成
• 无基础设施变更
• 无新增依赖
• 示例：修正错别字、变更颜色、更新文本、简单修复错误

STANDARD

• 修改 3–10 个文件
• 涉及 1–2 个服务／领域
• 0–1 个外部集成（文档完善且易于使用）
• 极少的基础设施变更（例如添加环境变量）
• 可能需要一些调研，但已有核心模式可供参考
• 示例：添加新的 API 端点、创建新组件

COMPLEX

• 修改 10 个以上文件，或涉及跨领域变更
• 涉及多个服务／领域
• 涉及 2 个或更多外部集成
• 涉及基础设施变更（Docker、数据库、队列）
• 引入新的架构模式
• 需要调研的全新功能
• 示例：新的集成（Stripe、Auth0）、数据库迁移、新服务

工作流

阶段 1：加载需求

阅读需求文档：

# Read the requirements file
cat .claude/context/requirements/[task-name].md

提取：

• task_description：需要构建什么
• workflow_type：工作类型（功能、重构等）
• scope：涉及哪些范围
• requirements：具体需求
• acceptance_criteria：成功的衡量标准
• constraints：任何限制

阶段 2：分析任务

仔细阅读任务描述。留意：

复杂度指标（表明复杂度可能较高）：

• “integrate”、“integration”——外部依赖
• “optional”、“configurable”、“toggle”——功能开关、条件逻辑
• “docker”、“compose”、“container”——基础设施
• 数据库名称（postgres、redis、mongo）——基础设施 + 配置
• API/SDK 名称（stripe、auth0、openai）——需要外部调研
• “migrate”、“migration”——数据/架构变更
• “across”、“all services”、“everywhere”——跨领域改动
• “new service”——范围较大
• “.env”、“environment”、“config”——配置复杂度

简单性指标（表明复杂度可能较低）：

• “fix”、“typo”、“update”、“change”——修改
• “single file”、“one component”——范围有限
• “style”、“color”、“text”、“label”——UI 微调
• 提及具体文件路径——范围明确

阶段 3：评估维度

范围分析

• 可能会涉及多少个文件？
• 涉及多少个领域？
• 这是局部变更还是跨领域变更？

集成分析

• 是否涉及外部服务/API？
• 是否需要添加新依赖？
• 是否需要调研这些依赖？

基础设施分析

• 是否需要更改 Docker/容器？
• 是否需要更改数据库架构？
• 是否需要新增环境配置？

知识分析

• 代码库中是否已有可遵循的模式？
• 是否需要调研外部文档？
• 是否涉及不熟悉的技术？

风险分析

• 可能出现什么问题？
• 是否有安全方面的考量？
• 是否可能破坏现有功能？

阶段 4：确定所需阶段

根据分析结果，确定需要哪些阶段：

对于简单任务：

discovery → quick_spec → validation

（3 个阶段，无需调研，规划最少）

对于标准任务：

discovery → requirements → context → spec_writing → planning → validation

（6 个阶段，基于上下文编写规范）

对于含外部依赖的标准任务：

discovery → requirements → research → context → spec_writing → planning → validation

（7 个阶段，包含对不熟悉依赖的调研）

对于复杂任务：

discovery → requirements → research → context → spec_writing → self_critique → planning → validation

（8 个阶段，完整流程，包含调研和自我审查）

阶段 5：确定验证深度

根据复杂度和风险分析，建议验证深度：

风险级别	适用情形	验证深度
TRIVIAL	仅文档、注释、空白字符	完全跳过验证
LOW	单个领域，少于 5 个文件，无 DB/API 变更	仅单元测试
MEDIUM	多个文件，1-2 个领域，有 API 变更	单元测试 + 集成测试
HIGH	数据库变更、身份验证/安全、跨服务	单元测试 + 集成测试 + E2E + 安全
CRITICAL	支付、数据删除、安全关键	以上全部 + 人工审查 + 预发布环境

跳过验证的标准（TRIVIAL）： 仅当以下条件全部满足时设置：

• 仅更改文档（*.md、注释、文档字符串）
• 或纯粹的外观调整（空白字符、格式、Lint 修复）
• 未修改任何功能代码
• 置信度 >= 0.9

满足以下任一条件时，必须进行安全扫描：

• 涉及身份验证/授权代码
• 修改了用户数据处理
• 涉及支付/财务代码
• 处理 API 密钥、机密或凭据
• 新增可访问网络的依赖
• 文件上传/下载功能

阶段 6：输出评估结果

创建结构化评估：

# Complexity Assessment: [Task Name]

## Summary

| Dimension     | Assessment                                        |
| ------------- | ------------------------------------------------- |
| Complexity    | [simple/standard/complex]                         |
| Workflow Type | [feature/refactor/investigation/migration/simple] |
| Confidence    | [0.0-1.0]                                         |

## Reasoning

[2-3 sentence explanation]

## Analysis

### Scope

- Estimated files: [number]
- Estimated areas: [number]
- Cross-cutting: [yes/no]
- Notes: [brief explanation]

### Integrations

- External services: [list]
- New dependencies: [list]
- Research needed: [yes/no]
- Notes: [brief explanation]

### Infrastructure

- Docker changes: [yes/no]
- Database changes: [yes/no]
- Config changes: [yes/no]
- Notes: [brief explanation]

### Knowledge

- Patterns exist: [yes/no]
- Research required: [yes/no]
- Unfamiliar tech: [list]
- Notes: [brief explanation]

### Risk

- Level: [low/medium/high]
- Concerns: [list]
- Notes: [brief explanation]

## Recommended Phases

1. [phase1]
2. [phase2]
3. ...

## Validation Recommendations

| Setting          | Value                              |
| ---------------- | ---------------------------------- |
| Risk Level       | [trivial/low/medium/high/critical] |
| Skip Validation  | [yes/no]                           |
| Minimal Mode     | [yes/no]                           |
| Test Types       | [unit, integration, e2e]           |
| Security Scan    | [yes/no]                           |
| Staging Required | [yes/no]                           |

**Reasoning**: [1-2 sentences explaining validation depth]

## Flags

- Needs research: [yes/no]
- Needs self-critique: [yes/no]
- Needs infrastructure setup: [yes/no]

决策流程图

START
  |
  +--> Are there 2+ external integrations OR unfamiliar technologies?
  |     YES -> COMPLEX (needs research + critique)
  |     NO
  |      |
  +--> Are there infrastructure changes (Docker, DB, new services)?
  |     YES -> COMPLEX (needs research + critique)
  |     NO
  |      |
  +--> Is there 1 external integration that needs research?
  |     YES -> STANDARD + research phase
  |     NO
  |      |
  +--> Will this touch 3+ files across 1-2 areas?
  |     YES -> STANDARD
  |     NO
  |      |
  +--> SIMPLE (1-2 files, single area, no integrations)

验证清单

完成评估前：

• 通读需求文档
• 找出所有复杂度指标
• 找出所有简单度指标
• 分析范围（文件、领域、跨领域）
• 分析集成（外部集成、依赖项）
• 评估基础设施需求
• 找出知识缺口
• 确定风险级别
• 确定阶段
• 推荐验证深度

常见错误

低估集成工作

为什么不对： 一项集成可能涉及许多文件。

应这样做： 对任何不熟悉的技术，标记出调研需求。

忽视基础设施

为什么不对： Docker/数据库变更会显著增加复杂度。

应这样做： 尽早检查基础设施需求。

过度自信

为什么不对： 信心通常不应超过 0.9。

应这样做： 保持谨慎。如有疑问，按更高的复杂度评估。

与其他技能的集成

此技能适用于以下场景：

• spec-gathering：提供评估所需的需求
• spec-writing：根据评估确定规格说明的深度
• qa-workflow：使用验证建议

反模式

反模式	失败原因	正确做法
未扫描文件就评为 SIMPLE	低估实际受影响的文件数量	在分配级别前统计受影响的文件数量
“快速修复”的说法降低了级别	用户认知 ≠ 技术范围	客观评估；忽略用户随意的表述
忽视集成和外部 API	外部依赖会增加风险和复杂度	在评估中列出所有外部服务/API
对未知技术跳过调研标记	不熟悉的技术存在不可见的复杂度	将任何不熟悉的技术标记为需要调研
不考虑回滚复杂度	COMPLEX/EPIC 需要恢复计划	在复杂度评分中纳入回滚难度

记忆协议

开始前： 阅读 .claude/context/memory/learnings.md

完成后：

• 新模式 -> .claude/context/memory/learnings.md
• 发现问题 -> .claude/context/memory/issues.md
• 做出决策 -> .claude/context/memory/decisions.md

假设工作可能中断：如果没有记录在记忆中，就等于没有发生。