azure-devops-create-work-item

Azure DevOps 创建工作项

将零散的上下文整理为本地 Azure DevOps 工作项资料包，并以官方 Azure Boards 工作项模型为依据。

已于 2026 年 5 月 9 日根据 Microsoft Learn 上的 About work items and work item types、Scrum workflow in Azure Boards、Agile workflow in Azure Boards、Define, capture, triage, and manage bugs in Azure Boards 和 Choose a process 页面进行核实。改编后的写作指南已于 2026 年 8 月 19 日对照 Google 开发者文档风格指南进行审阅。

先判断是否需要“戳破假设”

此技能会起草本地资料包。除非用户另行要求使用 REST、CLI 或 UI 自动化，否则不会创建或更新实时 Azure DevOps 工作项。

此技能擅长：

• 提取有效上下文，并确定一个主要 Azure Boards 工作项类型
• 在调用方当前目录中创建确定性的文件夹
• 生成可直接复制粘贴的 work-item.md 及配套资料
• 使用提供的或检测到的项目流程；如果类型和流程未知，则回退到 Product Backlog Item
• 在项目内运行时检查周边代码库，并提供相关代码片段
• 使主要草稿符合标准字段架构，并为 Bug 添加 Reproduction Steps
• 确保内容对技术和非技术读者都清晰易懂
• 应用以读者为先的技术写作规则，但不覆盖 Azure Boards 语义、资料包架构、本地术语或区域设置
• 将手动 QA 部分整理为有针对性、基于风险的场景，读起来如同资深测试人员撰写
• 使用 Azure Boards 官方工作项基本元素，而非臆造工单格式

决策树

1. 如果用户想根据笔记、聊天上下文或粗略需求生成适用于 Azure DevOps 的本地草稿，请使用此技能。
2. 如果用户想通过浏览器、REST API 或 Azure CLI 直接在 Azure DevOps 中创建工作项，请停止并转交给自动化或 API 工作流。
3. 如果用户想要独立的 Azure DevOps wiki 页面或一般文档，请转交给文档撰写工作流；此技能仅在本地工作项资料包中应用文档写作风格。
4. 如果未指定类型，请根据提供的或检测到的项目流程选择类型；如果类型和流程都未知，则回退到 Scrum Product Backlog Item。
5. 如果已明确指定类型，请使用匹配的模板；若与已知流程冲突，则明确指出，而不是悄悄重新映射。
6. 使用 references/official-primitives.md 解决类型或流程歧义；只有剩余的不确定性会实质性影响资料包时，才提出简短问题。
7. 如果当前目录是项目或 git 仓库，请在定稿前检查代码库。
8. 如果上下文过少，无法说明问题或预期结果，请先询问缺失信息，再起草。

默认保存路径规则

如果用户未指定目标位置，请在当前工作目录中创建资料包。不要将其保存到隐藏缓存、临时目录或默认主目录位置。

生成的资料包布局为：

<current-working-directory>/azure-devops-work-item-<type>-<slug>-<timestamp>/
  work-item.md
  context.md
  sources.md
  metadata.json

快速参考

任务	命令	原因
在当前目录创建默认的 PBI 数据包	python3 scripts/create_work_item_packet.py --title "Restore team login after token expiry"	在命令所在目录旁创建 Product Backlog Item 数据包
根据已保存的笔记创建数据包	python3 scripts/create_work_item_packet.py --type bug --title "Checkout button freezes on Safari" --context-file ./notes/checkout-bug.md	使用现有笔记填充 context.md
将数据包保存到指定目录	python3 scripts/create_work_item_packet.py --type user-story --title "Resend invite from team page" --save-root ./work-items	将数据包保存在选定的可见文件夹中
端到端检查数据包工作流	python3 scripts/probe_create_work_item_packet.py	验证脚手架命令是否创建了预期的制品
确认类型选择和编写规则	阅读 references/official-primitives.md	确保草稿符合 Azure Boards 语义

操作规则

1. 即使用户没有指定类型，也要采用项目提供或观察到的流程：例如，敏捷流程中的用户需求应对应 User Story，而不是 Scrum PBI。只有在类型和流程都未知时，才默认使用 Scrum Product Backlog Item。
2. 先提取上下文。即使 work-item.md 内容更精简，也要将原始源材料保存在 context.md 中。
3. 只选择一种主要类型：Product Backlog Item、Epic、Feature、User Story、Task、Issue 或 Bug。
4. 除非用户明确要求其他格式，否则保持助手数据包的布局以及主要章节标签和顺序稳定。默认使用加粗章节标签；在详细的 **Test Scenario** 章节之外，不要使用 #、## 或 ### 标题。
5. 非 Bug 草稿使用以下可见结构：
   • **Title**
   • **Problem**
   • **Action**
   • **Outcome**
   • **Acceptance Criteria**
   • **Developer Notes**
   • **Test Scenario**
6. 对于 Bug，在 **Problem** 后立即添加 **Reproduction Steps**。使用简单的编号步骤，让 QA、产品或开发人员都能照着操作。
7. 在 **Test Scenario** 中编写手动 QA 内容时，遵循 references/output-packet.md 中的 Manual QA Scenario Contract：按风险设计场景，包含 Test environment notes 区块，步骤应适用于被测 UI、API 或后端，预期结果应可观察，标题应聚焦行为，并包含实际验证陷阱。只有在搭建环境确实需要开发人员支持时，才标注 (needs dev support)。默认使用新西兰英语；如用户或项目另有地区语言要求，则遵从其要求。
8. 将类型模板视为内容指导，而非固定文案或场景配额。保持数据包结构；根据实际工作调整各章节中的措辞、格式和细节。
9. 将支持性细节、假设、原始笔记和源材料摘录放入 context.md，不要放入主要工作项草稿。
10. 面向不同背景的读者写作。优先使用通俗语言，说明业务影响；只有在实现细节会实质性影响需求时，才保留这些细节。
11. 对数据包正文应用 references/writing-style.md。除非明确要求覆盖，否则在采用调整后的 Google 风格偏好之前，保留固定的 Azure 章节标签和顺序、项目术语、指定地区语言以及原文中的精确字面内容。
12. 对于安全、升级、合规、维护和依赖项工作，使用同样的类型与流程优先级规则，不要一概假定这些工作都需要 Task。如果源上下文支持，保留诸如 SECURITY:、MAINTENANCE: 或 COMPLIANCE: 这样的直接标题前缀。
13. 在代码仓库中执行时，最终确定 work-item.md 前先检查代码库：

• 通过 git status --short、rg --files、包清单、路由文件、服务目录、测试和相关文档，了解项目结构并识别可能负责的模块
• 搜索工作项标题、症状、UI 标签、API 名称、实体、错误信息和可能的文件名中的领域术语
• 阅读理解受影响路径所需的最少量相关文件
• 添加简洁的文件引用，以及有助于实现或排查问题的简短代码片段；没有合适内容时可以不添加，不要凑数
• 将较长的代码片段、调查笔记和排除的线索放入 context.md
• 不要编造代码片段，也不要仅为证明做过调查而添加无关代码

类型约定

• Product Backlog Item：用于 Scrum 待办事项，或在类型和流程未知时作为回退选项。使用 templates/product-backlog-item-template.md。
• Epic：用于汇集多个功能的较大场景或计划。
• Feature：用于具有用户或业务价值的具体能力。使用 templates/feature-template.md。
• User Story：用于描述用户需求的谁／做什么／为什么陈述，且不规定实现方式。使用 templates/user-story-template.md。
• Task：用于 Sprint 规模的执行工作。使用 templates/task-template.md。
• Issue：用于可能拖慢或阻碍交付的障碍或非代码项目问题。使用 templates/issue-template.md。
• Bug：用于具有可复现行为的代码缺陷。使用 templates/bug-template.md；加入 Reproduction Steps。

建议的工作流

1. 阅读源上下文，提取核心问题、受众和预期结果。
2. 如果调用方位于代码仓库内，请检查代码库并收集相关文件路径、函数、配置、测试和简短代码片段。
3. 使用 references/official-primitives.md 选择最合适的工作项类型。
4. 在调用方当前目录中运行 python3 scripts/create_work_item_packet.py --title "<title>"，以生成回退 PBI。流程已知时，同时传入 --type <type> 和 --process <process>；--process 用于记录元数据，不会推断类型。如果磁盘上已有备注，添加 --context-file。如果项目类型不受支持，应说明辅助工具的限制，而不是声称某个不受支持的标志或映射是原生支持的。
5. 使用所选模板、references/writing-style.md 和 references/output-packet.md 中的数据包规则填写 work-item.md；如果 **Test Scenario** 中包含手动 QA 场景，还应遵守 Manual QA Scenario Contract。
6. 最终文件应简洁、明了，可直接粘贴到 Azure DevOps。除非用户明确要求，否则不要添加额外的顶级章节。

来源与维护

保持本地数据包边界、来源忠实度和辅助工具契约稳定。如果类型语义或说明不充分、过时或存在冲突，请查阅相关 Microsoft Learn 文档或提供的项目流程定义；不要例行浏览。报告限制，并提出附有来源依据的修正方案，且包含示例数据包或回归用例。只有在维护范围内时才修改规范技能；不要暗中更新已安装副本，也不要对 Azure DevOps 进行实时更改。

阅读指南

需求	阅读
Azure Boards 官方类型语义及跨流程说明	references/official-primitives.md
面向混合受众的字段文案、术语、流程、链接、无障碍性及样式优先级	references/writing-style.md
数据包布局、章节撰写规则、Manual QA Scenario Contract 及当前目录行为	references/output-packet.md
失败模式和分类陷阱	references/gotchas.md
Product Backlog Item 模板	templates/product-backlog-item-template.md
Epic 模板	templates/epic-template.md
Feature 模板	templates/feature-template.md
User Story 模板	templates/user-story-template.md
Task 模板	templates/task-template.md
Issue 模板	templates/issue-template.md
Bug 模板	templates/bug-template.md

注意事项

1. 此技能会在本地创建一个工作项包，而不会创建实时的 Azure DevOps 工作项。
2. Product Backlog Item、Feature、User Story 和 Task 不可互换。PBI 是默认的 Scrum 待办项，Feature 用于归类或定义某项可交付能力，User Story 表示明确采用敏捷流程的措辞，Task 用于记录执行工作。
3. Bug 表示代码缺陷。如果该工作项属于阻塞因素或依赖项，但不存在行为缺陷，请改用 Issue。
4. Azure DevOps 工作项类型取决于所用流程。请依据已知的 Basic、Agile、Scrum、CMMI 或自定义流程证据来判断；只有在映射关系仍不明确时才询问。
5. 主要工作项草稿应少用标记。使用粗体章节标签，并避免使用标题语法。
6. Bug 需要包含 **Reproduction Steps** 章节，并列出简单的编号步骤。如果上下文缺少相关细节，请询问，或在 context.md 中指出这一缺口。
7. 不要把业务影响淹没在工程细节中。混合受众应能在第一个简短章节后理解该工作项为何重要。
8. 不要编造机密环境名称、URL、客户名称或系统标识符。对于用户提供的上下文中没有的细节，请予以隐去或泛化。
9. 代码片段应作为证据，而非填充内容。仅当它们能指向可能的实现位置、缺陷来源、测试范围、配置依赖或发布注意事项时才纳入。
10. 不要把 **Test Scenario** 变成穷尽所有排列组合的表格。手动 QA 应覆盖主路径以及此次变更带来的实际风险。
11. 不要将此技能用于独立的 wiki 页面。其改编后的文档风格仅适用于工作项包。