Back to Details

ado-create-work-items

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ado-create-work-items

创建Azure DevOps工作项

Take a 
backlog_input.json
and create the work items in Azure DevOps by driving the bundled 
create-backlog.cs
. The script creates an optional parent (Feature/Epic), then every item linked under it, and writes a 
backlog_result.json
mapping each 
key
to its new 
id
/
url
.
Creating items in a live org is outward-facing and effectively un-undoable (delete is manual, links and notifications already fired). So this skill is built around a hard gate: dry-run always, real run only on an explicit "yes".
For the exact JSON shapes (
backlog_input.json
, 
backlog_result.json
, the 
key
field that threads source row → ticket, and the process→types table) see 
${CLAUDE_PLUGIN_ROOT}/references/data-contracts.md
. Don't duplicate schemas here.
接收
backlog_input.json
文件，通过运行捆绑的
create-backlog.cs
脚本在Azure DevOps中创建工作项。该脚本可创建可选的父项（Feature/Epic），然后将所有子项链接到其下，并生成
backlog_result.json
文件，将每个
key
映射到新创建项的
id
/
url
。
在生产环境中创建工作项是对外操作，且无法撤销（删除需手动操作，链接和通知已发送）。因此本技能设置了严格的限制：始终先执行试运行，仅在用户明确回复“yes”后才执行真实创建。
关于确切的JSON格式（
backlog_input.json
、
backlog_result.json
、关联源行与工单的
key
字段，以及流程→类型表），请参阅
${CLAUDE_PLUGIN_ROOT}/references/data-contracts.md
，请勿在此处重复定义 schema。

Prerequisites

前提条件

  • Auth — sign in once: 
    az login
    (the script fetches an Entra token for the Azure DevOps resource). Alternatively set 
    $env:AZDO_PAT
    (PAT with Work Items Read & Write). See the 
    ado-auth
    skill for token/PAT details and tenant.
  • Org/project — set 
    $env:AZDO_ORG
    / 
    $env:AZDO_PROJECT
    , or include 
    org
    / 
    project
    in the JSON. Env vars override the JSON.
  • .NET 10 SDK — 
    create-backlog.cs
    is a .NET 10 file-based program.
  • Unsure if prereqs are met? Run the checker: 
    powershell -ExecutionPolicy Bypass -File "${CLAUDE_PLUGIN_ROOT}/scripts/setup_check.ps1"
Confirm the 
type
of each item is valid for the target project's process (Agile vs Scrum vs Basic vs CMMI) — see the table in data-contracts.md. A type that doesn't exist on the board is the most common dry-run failure.
  • 身份验证 — 登录一次：
    az login
    （脚本会获取Azure DevOps资源的Entra令牌）。或者设置
    $env:AZDO_PAT
    （具有工作项读写权限的PAT）。有关令牌/PAT和租户的详细信息，请参阅
    ado-auth
    技能。
  • 组织/项目 — 设置
    $env:AZDO_ORG
    / 
    $env:AZDO_PROJECT
    ，或在JSON中包含
    org
    / 
    project
    字段。环境变量优先级高于JSON配置。
  • .NET 10 SDK — 
    create-backlog.cs
    是基于文件的.NET 10程序。
  • 不确定是否满足前提条件？运行检查脚本： 
    powershell -ExecutionPolicy Bypass -File "${CLAUDE_PLUGIN_ROOT}/scripts/setup_check.ps1"
确认每个项的
type
对于目标项目的流程（Agile、Scrum、Basic或CMMI）有效——请参阅data-contracts.md中的表格。项类型在看板中不存在是试运行最常见的失败原因。

Step 1 — DRY RUN (default; creates nothing)

步骤1 — 试运行（默认模式；不创建任何项）

AZDO_DRY_RUN
defaults to dry-run unless it is the literal string 
false
, so we set it explicitly to be safe. In this mode the script PATCHes each item with 
validateOnly=true
— ADO checks types, required fields, and field values without persisting anything.
powershell
$env:AZDO_ORG     = "Cartagena365"   # or rely on the JSON / already-set env
$env:AZDO_PROJECT = "GlassHull"
$env:AZDO_DRY_RUN = "true"
dotnet run "${CLAUDE_PLUGIN_ROOT}/scripts/create-backlog.cs" -- "<path>/backlog_input.json"
The script prints a 
PASS
/ 
FAIL
line per item (and per parent), then a summary like 
DRY RUN done. valid=N invalid=M. No work items were created.
Relay that list to the user. If anything is FAIL, stop and fix the input (usually a bad 
type
for the process, a missing 
System.Title
, or unescaped 
& < >
in an HTML field like 
Microsoft.VSTS.TCM.ReproSteps
/ 
System.Description
) before going on.
AZDO_DRY_RUN
默认设置为试运行模式，除非将其显式设置为字符串
false
，因此我们建议显式设置以确保安全。在此模式下，脚本会使用
validateOnly=true
对每个项进行PATCH操作——ADO会检查类型、必填字段和字段值，但不会持久化任何数据。
powershell
$env:AZDO_ORG     = "Cartagena365"   # 或依赖JSON配置/已设置的环境变量
$env:AZDO_PROJECT = "GlassHull"
$env:AZDO_DRY_RUN = "true"
dotnet run "${CLAUDE_PLUGIN_ROOT}/scripts/create-backlog.cs" -- "<path>/backlog_input.json"
脚本会为每个项（包括父项）打印
PASS
/
FAIL
行，然后输出摘要信息，例如
DRY RUN done. valid=N invalid=M. No work items were created.
。请将此结果列表告知用户。如果有任何项显示FAIL，请停止操作并修复输入（通常是流程对应的
type
错误、缺少
System.Title
，或者HTML字段如
Microsoft.VSTS.TCM.ReproSteps
/
System.Description
中存在未转义的
& < >
），然后再继续。

Step 2 — REAL RUN (only after explicit approval)

步骤2 — 真实创建（仅在明确批准后执行）

Do not proceed until the user has clearly said yes (e.g. "create them", "go ahead"). A clean dry-run is necessary but not sufficient — the human owns the decision to write to their org.
Point 
BACKLOG_RESULT
at your working directory so the writeback step can find it, then flip the gate to 
false
:
powershell
$env:AZDO_DRY_RUN  = "false"
$env:BACKLOG_RESULT = "<your-working-dir>/backlog_result.json"
dotnet run "${CLAUDE_PLUGIN_ROOT}/scripts/create-backlog.cs" -- "<path>/backlog_input.json"
What happens: if the input has a 
parent
, it is created first; every item is then created and linked to it via 
System.LinkTypes.Hierarchy-Reverse
(child → parent). If an item has an 
estimate
, a child Task carrying the hours (Original/Remaining Work + the breakdown in its description) is created under that item — so the hierarchy is Feature → Bug/Story → Task. 
AZDO_AREA_PATH
and 
AZDO_ASSIGNED_TO
, if set, are stamped on every item (
AZDO_ASSIGNED_TO
only on items that didn't already set their own 
System.AssignedTo
). The script prints 
key … -> <type> #<id>
per item and writes 
backlog_result.json
(
key
→ 
id
/ 
url
/ 
type
/ 
title
). Failures are recorded per-item with an 
error
field instead of an 
id
, so a partial run is visible rather than silent.
请勿继续操作，直到用户明确表示同意（例如“创建它们”“继续执行”）。顺利完成试运行是必要条件，但并非充分条件——是否写入组织的决定权在用户手中。
将
BACKLOG_RESULT
指向你的工作目录，以便回写步骤可以找到它，然后将试运行开关设置为
false
：
powershell
$env:AZDO_DRY_RUN  = "false"
$env:BACKLOG_RESULT = "<your-working-dir>/backlog_result.json"
dotnet run "${CLAUDE_PLUGIN_ROOT}/scripts/create-backlog.cs" -- "<path>/backlog_input.json"
执行过程：如果输入中包含
parent
，则先创建父项；然后创建所有子项，并通过
System.LinkTypes.Hierarchy-Reverse
（子项→父项）将其链接到父项。如果项包含
estimate
，则会在该项下创建一个子Task，携带工时信息（Original/Remaining Work及其描述中的细分）——因此层级结构为Feature → Bug/Story → Task。如果设置了
AZDO_AREA_PATH
和
AZDO_ASSIGNED_TO
，则会将其标记到所有项上（
AZDO_ASSIGNED_TO
仅应用于未自行设置
System.AssignedTo
的项）。脚本会为每个项打印
key … -> <type> #<id>
，并生成
backlog_result.json
文件（
key
→ 
id
/
url
/
type
/
title
）。失败项会记录
error
字段而非
id
，因此可以看到部分运行结果，而非静默失败。

After creating — verify

创建后 — 验证

Confirm the items landed as intended. Query the new ids in one batch and check 
System.WorkItemType
, 
System.State
, and the parent link. Pull the ids from 
backlog_result.json
and use the ADO MCP 
wit_get_work_items_batch_by_ids
(or the workitemsbatch REST endpoint). Spot-check that children show the expected parent.
确认工作项已按预期创建。批量查询新创建项的ID，检查
System.WorkItemType
、
System.State
和父项链接。从
backlog_result.json
中提取ID，使用ADO MCP的
wit_get_work_items_batch_by_ids
（或workitemsbatch REST端点）。抽样检查子项是否显示预期的父项。

Idempotency — don't double-create

幂等性 — 避免重复创建

create-backlog.cs
is not idempotent: re-running the REAL run on the same 
backlog_input.json
creates a second set of items (duplicates). After a successful real run, hand off to ado-writeback-tracking to stamp 
Ticket ID
/ 
Ticket URL
back onto the source rows (matched by 
key
). Once a row carries a Ticket ID, treat it as done. If you must re-file a subset, prune the input to only the un-filed 
key
s first.
create-backlog.cs
不具备幂等性：对同一个
backlog_input.json
重复执行真实创建会生成第二组重复项。成功完成真实创建后，移交至ado-writeback-tracking，将
Ticket ID
/
Ticket URL
回写到源行（通过
key
匹配）。一旦源行带有Ticket ID，则视为已完成。如果必须重新提交子集，请先将输入修剪为仅包含未提交的
key
。

Windows notes

Windows注意事项

  • The install path can contain spaces — always wrap 
    "${CLAUDE_PLUGIN_ROOT}/..."
    and the JSON path in double quotes.
  • Console is cp1252; the .cs program emits ASCII status lines, so output is safe. (The bundled Python scripts force UTF-8 for source dumps / writeback.)
  • 安装路径可能包含空格——请始终用双引号包裹
    "${CLAUDE_PLUGIN_ROOT}/..."
    和JSON路径。
  • 控制台编码为cp1252；.cs程序输出ASCII状态行，因此输出是安全的。（捆绑的Python脚本强制使用UTF-8进行源数据导出/回写。）