---
name: azure-pbi-authoring
description: Escribe Product Backlog Items de Azure Boards que se puedan estimar y cerrar sin discusión - criterios de aceptación verificables, alcance acotado y campos completos. Úsala al crear un PBI, un bug o una feature, o al reescribir uno que llega vacío al refinamiento.
version: 1.0.0
license: CC-BY-4.0
updated: 2026-08-16
---

# Azure Boards: escribir un PBI que se pueda hacer

El coste de un PBI mal escrito no se paga al escribirlo. Se paga en el
refinamiento, en la estimación que falla y en la discusión de si está
terminado.

## Estructura

**Título** — resultado observable, no tarea técnica. En imperativo y sin
prefijos de módulo.

```
✗ Modificar OrderService y añadir columna
✓ Exportar el listado de pedidos a CSV desde la ficha de cliente
```

**Descripción** — tres bloques, nunca más:

```markdown
**Contexto.** Quién lo necesita y qué hace hoy en su lugar.
**Cambio.** Qué hará el sistema después. Un párrafo.
**Fuera de alcance.** Lo que alguien va a asumir que entra y no entra.
```

El bloque de fuera de alcance es el que más discusiones evita y el que casi
nadie escribe.

**Criterios de aceptación** — en `Microsoft.VSTS.Common.AcceptanceCriteria`,
comprobables por alguien que no ha escrito el código:

```
- [ ] Con al menos un pedido, el botón "Exportar" descarga un CSV con
      cabecera y una fila por pedido visible según el filtro activo.
- [ ] Sin pedidos, el botón queda deshabilitado con el texto "Nada que exportar".
- [ ] Con más de 10.000 pedidos, la descarga empieza en menos de 3 s.
- [ ] Un usuario sin permiso de lectura de pedidos recibe 403 y no ve el botón.
```

Regla: **si dos personas pueden discrepar sobre si un criterio se cumple, el
criterio está mal escrito.** "Rápido", "usable", "bien formateado" no son
criterios.

Cubre siempre los cuatro: **caso feliz, caso vacío, caso límite y permisos.**

## Campos que no son opcionales

| Campo | Por qué |
|---|---|
| `Effort` / `StoryPoints` | Sin él no entra en sprint |
| `AcceptanceCriteria` | Sin él no se puede cerrar |
| `AreaPath` / `IterationPath` | Sin ellos no aparece en ningún informe |
| `Priority` o `BacklogPriority` | Sin ella el orden lo decide el azar |
| Enlace `Parent` a Feature/Épica | Sin él el avance de la épica miente |

## Bugs: otra plantilla

Un bug no lleva criterios de aceptación, lleva reproducción:

```markdown
**Pasos.** 1. … 2. … 3. …
**Esperado.** …
**Obtenido.** … (mensaje literal, captura o ID de correlación)
**Entorno.** Versión, navegador o cliente, usuario y hora aproximada.
**Alcance.** ¿Le pasa a un usuario o a todos? ¿Hay workaround?
```

Severidad la marca el **impacto en el usuario**, no la dificultad del arreglo.
`Repro Steps` va en `Microsoft.VSTS.TCM.ReproSteps`, que es campo HTML: el
Markdown plano se ve literal.

## Tamaño

Si al escribir los criterios de aceptación te salen más de seis, o aparece la
palabra "y" separando dos resultados distintos, es más de un PBI. Trocea por
**valor entregable**, no por capa técnica:

```
✗ #1  Backend del export      ✓ #1  Export a CSV del listado filtrado
  #2  Frontend del export       #2  Programar el export como envío diario
```

Un PBI que solo toca el backend no se puede demostrar en la review, y lo que
no se demuestra no se cierra.

## Crearlo

```bash
az boards work-item create \
  --title "Exportar el listado de pedidos a CSV" \
  --type "Product Backlog Item" \
  --area "Proyecto\\Pedidos" --iteration "Proyecto\\Sprint 43" \
  --fields "Microsoft.VSTS.Scheduling.Effort=5" \
           "Microsoft.VSTS.Common.AcceptanceCriteria=<ul><li>…</li></ul>"
```

Los campos de texto enriquecido (descripción, criterios, repro steps) son HTML.
Enlazar con el padre después:

```bash
az boards work-item relation add --id <hijo> --relation-type parent --target-id <padre>
```

Revisa el borrador con la persona antes de crearlo. Un PBI mal creado se queda
en el backlog para siempre.