estimate-jira

JIRA 工单估算技能

此技能可对 JIRA 工单、功能或项目进行结构化的复杂度和工作量估算，并生成一致、专业的估算报告，其中包括复杂度级别、时间估算、依赖关系分析、风险评估以及未知事项识别。

何时使用此技能

当用户提出以下请求时，启用此技能：

• “估算此 JIRA 工单”
• “分析 [工单/功能] 的复杂度”
• “这个项目需要多少工作量？”
• “评估此功能的规模”
• “这需要多长时间？”
• “这项工作的风险有哪些？”

前提条件

• 用户提供 JIRA 工单内容（首选 Markdown 格式）
• 可以访问代码库，以便分析依赖关系
• 了解项目架构（如有需要，请查阅 tools/prompts/technology-stack.md）

工作流

步骤 0：加载所需文档

在开始任何分析之前，先阅读以下文件：

1. tools/prompts/guides/jira.md - JIRA 快速参考
2. tools/prompts/technology-stack.md - 架构约束和模式
3. CLAUDE.md - 代码库约定和构建要求

阅读后，确认你已了解：

• 代码库结构和关键包
• 构建和测试命令
• 架构约束（例如，零运行时依赖）

步骤 1：收集并分析工单信息

继续之前，完成以下所有事项：

• 从用户处获取 JIRA 工单内容（Markdown 格式）
• 提取关键需求、验收标准和约束
• 确定主要受影响的区域（包/文件）
• 记录工单中已有和缺失的信息

初步分析问题：

• 这是什么类型的工作？（错误修复、新功能、重构、文档等）
• 会影响哪些包？（community、enterprise、types、website 等）
• 是否提到了相关工单或依赖项？
• 范围定义明确还是比较模糊？

第 2 步：识别歧义和实现选择

重要：未完成此步骤前，请勿继续估算。

请分析以下方面的歧义：

1. 技术方案

   • 是否存在多种有效的实现策略？
   • 是否指定了预期的架构／模式？
   • 是否定义了性能要求？

2. 范围边界

   • 功能范围是否明确？
   • 是否说明了边缘情况和错误处理？
   • 是否需要向后兼容？

3. 集成点

   • 应如何与现有系统集成？
   • 是否会影响框架包装器（React/Angular/Vue）？
   • 是否会变更公共 API？

4. 测试与质量

   • 预期的测试覆盖率是多少？
   • 是否需要视觉回归测试？
   • 是否应新增或更新基准测试？

5. 文档

   • 是否需要编写文档？
   • 是否需要示例？
   • 是否应编写迁移指南？

对于识别出的每项重要歧义：

• 清楚记录歧义
• 列出可能的实现选择
• 说明每种选择对时间、复杂度和风险的影响
• 使用 AskUserQuestion 工具，在继续前获取澄清

使用 AskUserQuestion 工具呈现歧义：

每次使用 AskUserQuestion 工具呈现 1 至 4 项歧义，格式如下：

• question：关于歧义的清晰问题（例如：“‘xy’ 模式在视觉上应如何呈现？”）
• header：简短标签（最多 12 个字符）（例如：“双轴 UI”）
• options：2 至 4 个实现选项，包含：
  • label：简洁的选项名称（例如：“两个导航器”）
  • description：影响说明（例如：“同时显示 X 轴（底部）和 Y 轴（右侧）导航器——复杂度增加 20%，界面更清晰”）
• multiSelect：false（用户应选择一种方案）

使用示例：

AskUserQuestion({
    questions: [
        {
            question: "How should the 'xy' mode work visually?",
            header: 'Dual-axis UI',
            multiSelect: false,
            options: [
                {
                    label: 'Two Separate Navigators',
                    description:
                        'Show both X-axis (bottom) and Y-axis (right) navigators simultaneously - +20% complexity, clearer UI',
                },
                {
                    label: 'Integrated Navigator',
                    description: 'Single unified UI component - High complexity, unclear UX, needs design work',
                },
                {
                    label: 'Not Supported',
                    description: "Only allow 'x' or 'y', defer 'xy' to future ticket - -30% complexity, simpler scope",
                },
            ],
        },
        {
            question: 'Should Y-axis navigator position be configurable?',
            header: 'Position',
            multiSelect: false,
            options: [
                {
                    label: 'Configurable (left/right)',
                    description:
                        'Add navigator.position option - +10% complexity, flexible but may overlap Y-axis labels',
                },
                {
                    label: 'Right Side Only',
                    description: 'Always on right to avoid conflicts - Baseline complexity, simpler but less flexible',
                },
            ],
        },
    ],
});

收到答复后：

• 在摘要中记录选定的方案
• 根据所选选项调整估算
• 将决策纳入报告的“实施决策”部分

第 3 步：调查代码库依赖关系和复杂度

使用 Explore Agent 全面分析代码库：

• 识别所有受影响的文件和包
• 分析现有类似实现的模式
• 检查对其他系统／模块的依赖
• 查找需要更新的相关测试
• 搜索需要修改的文档

重点调查领域：

1. 核心实现

   • 主要逻辑位于何处？
   • 该区域的现有代码有多复杂？
   • 是否有可供参考的类似功能？

2. 类型系统

   • 是否需要更新 ag-charts-types？
   • 是否涉及复杂的类型定义？
   • 是否会影响公共 API 接口？

3. 测试范围

   • 有多少测试文件会受到影响？
   • 是否需要图像快照？
   • 是否需要端到端测试？

4. 文档与示例

   • 有多少文档页面需要更新？
   • 是否需要新增示例？
   • 是否会生成框架变体？

5. 构建依赖

   • 哪些包需要重新构建？
   • 是否存在循环依赖风险？
   • 是否会影响构建性能？

第 4 步：生成结构化估算报告

请使用以下确切模板以保持一致：

---

估算报告：[工单 ID／功能名称]

日期：[当前日期] **估算者：**Claude Code 工单摘要：[用 1 至 2 句话简要概述]

---

执行摘要

指标	值
总投入	[X-Y 天]（[X-Y 小时]）
复杂度	[低 | 中 | 高 | 极高]
风险等级	[低 | 中 | 高]
置信度	[低 | 中 | 高]

重点摘要：

• [用 1-2 句话概述主要实施工作]
• [主要范围决策或限制]
• [适用时列出首要风险或顾虑]

---

1. 复杂度估算

总体复杂度：[低 | 中 | 高 | 极高]

理由：

• [说明复杂度的主要影响因素]
• [说明选择此复杂度级别的原因]

复杂度细分：

• 实施：[低/中/高]
• 测试：[低/中/高]
• 文档：[低/中/高]
• 集成：[低/中/高]

---

2. 时间投入估算

总估算：单个开发者需要 [X-Y 天]

置信度：[低 | 中 | 高]

细分：

• 调研与设计：[X 小时/天]

  • 理解需求
  • 设计决策
  • 按需进行探索性工作

• 核心实施：[X 小时/天]

  • 主要代码变更
  • 类型定义
  • 公共 API 更新

• 测试：[X 小时/天]

  • 单元测试
  • E2E 测试（如适用）
  • 视觉回归测试（如适用）
  • 基准测试更新（如适用）

• 文档：[X 小时/天]

  • 更新/创建文档页面
  • 创建示例
  • 迁移指南（如适用）

• 评审与迭代：[X 小时/天]

  • 代码评审反馈
  • 测试失败
  • Bug 修复

假设：

• [列出影响估算的关键假设]
• [例如：“假设开发者熟悉画布渲染”]
• [例如：“假设不需要重大架构变更”]

---

3. 依赖项、缺口与缺失信息

外部依赖项：

• [列出对其他团队/工单的依赖]
• [任何受阻或会阻塞其他事项的项目]

信息缺口：

• [工单中未说明的内容]
• [尚未解答的问题]
• [需要利益相关方澄清的领域]

隐含范围（未明确提及）：

• [可能需要但未说明的任务]
• [例如：“框架封装层更新”]
• [例如：“添加本地化字符串”]

范围之外（请与利益相关方确认）：

• [可能被认为应该包含、但应单独处理的事项]
• [例如：“超出基本实施范围的性能优化”]

---

4. 最高风险的 3 个方面

风险 #1：[描述]

类别：[已知未知 | 技术复杂度 | 集成风险 | 等]

详情：

• [风险来源]
• [潜在影响]

缓解措施：

• [如何降低此风险]

---

风险 #2：[描述]

类别：[已知未知 | 技术复杂度 | 集成风险 | 等]

详情：

• [风险来源]
• [潜在影响]

缓解措施：

• [如何降低此风险]

---

风险 #3：[描述]

类别：[已知未知 | 技术复杂度 | 集成风险 | 等]

详情：

• [风险来源]
• [潜在影响]

缓解措施：

• [如何降低此风险]

---

5. 总体风险等级

风险评估：[低 | 中 | 高]

理由：

• [总体风险分析]
• [导致该风险等级的因素]
• [已知未知因素汇总]

风险因素：

• 技术风险：[低/中/高] - [原因]
• 进度风险：[低/中/高] - [原因]
• 集成风险：[低/中/高] - [原因]
• 需求风险：[低/中/高] - [原因]

估算置信度：

• [置信度为高/中/低及其原因]
• [哪些信息可以提高置信度]

---

建议的后续步骤

1. [立即行动项]
2. [实施前需要进行的调研]
3. [需要利益相关方澄清的事项]

---

实施决策（已确认）

根据利益相关方于 [date] 的澄清：

1. [决策领域 1]：[选定方案]（[选项字母]）
2. [决策领域 2]：[选定方案]（[选项字母]）
3. [决策领域 3]：[选定方案]（[选项字母]）

注意：仅当估算过程中澄清了重要的实施选择时，才包含本节。

---

报告结束

---

完成检查清单

只有在全部勾选后，才能将估算标记为完成：

• 用户已提供 JIRA 工单内容
• 已识别所有重要歧义，并与用户确认
• 已使用 Explore Agent 完成代码库调查
• 已填写估算报告的所有部分
• 已说明复杂度等级及其依据
• 时间估算包含明细和假设
• 已识别最重要的 3 项风险，并制定缓解策略
• 已评估总体风险等级
• 已检查报告的完整性和准确性

关键规则

1. 绝不能跳过歧义澄清——如果实施选择会显著影响估算，继续之前必须使用 AskUserQuestion 工具询问用户。与其给出误导性估算，不如暂停以澄清。清楚说明各选项及其对复杂度和时间的影响。

2. 始终使用 AskUserQuestion 工具澄清歧义——不要通过临时文字对话来澄清实施选择。使用结构化的 AskUserQuestion 工具，一次呈现 1-4 项歧义，并清楚说明选项及其影响。

3. 始终使用 Explore Agent 分析代码库——不要尝试手动进行复杂的代码库导航。Explore Agent 专为此任务优化。

4. 如实说明不确定性——如果把握不高，请明确说明。指出哪些信息有助于提高把握。

5. 考虑完整工作范围——别忘了测试、文档、评审迭代和框架封装。这些通常占总工作量的 40-50%。

6. 将未知因素纳入考虑——已知的未知因素应按比例增加时间估算和风险等级。

7. 使用范围，而非单点估算——给出范围（例如“3-5 天”）以反映不确定性，尤其是复杂工作。

8. 明确记录假设——每项估算都基于假设。请清楚说明，以便验证。

失败处理

问题：工单信息不足

解决方案：

• 向用户请求更多详情
• 列出所需的具体信息
• 如果用户无法提供更多详情，则给出不确定性较大的估算范围

问题：找不到相关代码区域

解决方案：

• 使用 Explore Agent 并扩大搜索范围
• 询问用户是否能提供代码可能所在位置的线索
• 在报告中将此记录为“已知未知因素”

问题：存在多种有效的实施方案，且复杂度差异很大

解决方案：

• 使用 AskUserQuestion 工具将每种方案列为一个选项
• 在各选项的说明中包含复杂度和时间影响
• 如适用，在其中一个选项的说明中给出建议
• 通过结构化界面让用户选择偏好的方案
• 在“实施决策”部分记录选定方案

问题：估算超出合理时间（例如，单人工作超过 2 周）

解决方案：

• 考虑是否应将工作拆分为多个工单
• 在风险评估中重点说明这一点
• 建议创建子任务或分阶段实施
• 与用户讨论缩小范围的方案

估算校准数据点

对常见的 AG Charts 工作项，使用以下基准估算：

系列实现

• 新系列类型（扩展 AbstractBarSeries、CartesianSeries 等）：10 天 / 2 周
  • 包括：核心实现、类型定义、渲染逻辑、主题集成
  • 包括：单元测试、视觉回归测试、文档页面、框架示例
  • 示例：重叠条形图/柱形图系列、时间线系列、象限图
  • 不包括：高度复杂的渲染算法、超出标准范围的高级交互

注释实现

• 新注释类型：15-20 天（3-4 周）
  • 包括：核心注释类、渲染、拖动/调整大小交互、类型定义
  • 包括：全面测试（单元测试、E2E、视觉回归测试）、文档、示例
  • 示例：文本注释、形状注释、测量工具
  • 复杂度因素：拖放交互、调整大小控制柄、连接点、样式系统

其他常见工作项

• 简单 Bug 修复（问题孤立，根本原因明确）：0.5-1 天
• 复杂 Bug 修复（需要调查，涉及多个区域）：2-3 天
• 新增图表选项（简单属性，逻辑极少）：1-2 天
• 新增事件/回调：2-4 天（取决于复杂度）
• 性能优化：3-5 天（调查 + 实现）
• 破坏性 API 变更：增加 20-30%，用于迁移指南和向后兼容性测试

调整指南：

• 如果实现需要与多个系统深度集成，增加 20-30%
• 如果功能存在重大未知因素或需求不明确，增加 30-50%
• 对于需要许可检查、高级主题功能的企业级功能，增加 40-60%
• 仅当借助大量现有基础设施且只需进行少量更改时，减少 20-30%

相关文档

• JIRA 指南 - JIRA 快速参考
• JIRA 创建技能 - 创建 JIRA 工单
• 技术栈 - 架构约束
• 测试指南 - 测试要求和模式
• 文档指南 - 文档要求
• 代码质量指南 - 质量标准

示例用法

当用户说：

• “估算 AG-12345”
• “这个功能有多复杂？”
• “帮我评估这个工单的工作量”
• “实现 [feature] 需要多少工作量？”
• “分析这项工作的风险”

此技能将会：

1. 请求 JIRA 工单内容（如果尚未提供）
2. 分析需求并找出不明确之处
3. 与你确认实现方案
4. 全面调查代码库
5. 生成包含所有要求部分的综合估算报告
6. 突出说明风险、未知因素和复杂之处

输出始终遵循结构化报告格式，以确保所有估算的一致性。