Plantillas

OpenSpec: 1.14.0
Revisado: 4 de octubre de 2026

Adapta nombres de proyecto, rutas y convenciones antes de usarlas. Los ejemplos usan un dominio neutro de gestión de reservas.

CLAUDE.md

En la raíz del repositorio. Claude Code lo carga siempre: reserva para él el stack, los comandos y las convenciones de código.

# Contexto del proyecto

## Stack
- Backend: .NET 8, ASP.NET Core Web API, Clean Architecture (Api / Application / Domain / Infrastructure)
- Persistencia: EF Core + SQL Server, migraciones code-first
- Frontend: Angular (standalone components, signals)
- Tests: xUnit + FluentAssertions + Testcontainers; Angular con Jest

## Comandos
- Build: `dotnet build`
- Tests backend: `dotnet test`
- Tests frontend: `npm run test` (desde /src/Web)

## Convenciones
- Casos de uso en Application; validación con FluentValidation.
- Errores de negocio con códigos estables (p. ej. RESERVA_SOLAPADA), mapeados a ProblemDetails.
- Nada de lógica de negocio en controladores.

## Spec-driven development (OpenSpec)
- Todo cambio de comportamiento pasa por un change de OpenSpec (/opsx:propose).
- NUNCA edites openspec/specs/ directamente: solo cambia mediante /opsx:archive.
- Cada Scenario de una spec debe tener un test automatizado.
- Nombre del change = nombre de la rama = <clave-ticket>-<slug>.

openspec/config.yaml

Dominio, glosario y reglas por artefacto. Incluye solo restricciones que el agente no puede inferir leyendo el código.

schema: spec-driven

context: |
  Dominio: gestión de reservas (recursos, franjas, reservas).
  Glosario:
    - franja: intervalo de tiempo reservable de un recurso
    - reserva: asignación confirmada de una franja a un cliente
  Las APIs públicas mantienen compatibilidad hacia atrás.

rules:
  proposal:
    - Primera línea: enlace al ticket de origen (Jira PROJ-XXXX o Azure Boards AB#XXXX)
    - Incluir impacto en base de datos y plan de rollback
    - Identificar contratos de API o eventos afectados (breaking o no)
  specs:
    - Formato Given/When/Then; un escenario por regla de negocio y por caso de error
    - Cada criterio de aceptación del ticket tiene al menos un Scenario
    - Si un criterio es ambiguo, registrarlo como pregunta abierta en proposal.md
  design:
    - Referenciar patrones existentes antes de proponer nuevos
  tasks:
    - Cada tarea incluye su test asociado
    - Migraciones de base de datos en tarea separada

operations:
  apply:
    guidance:
      - Ejecuta los tests afectados tras cada bloque de tareas
  archive:
    guidance:
      - Confirma que el subagente spec-verifier no reporta escenarios sin cubrir

El bloque operations (orientación para apply y archive) aparece en la plantilla que genera la 1.14 y no figura en la KB.

Comando /ticket-propose

Comando de chat propio en .claude/commands/ticket-propose.md: crea un change a partir de un ticket leído por MCP en solo lectura.

---
description: Crea un cambio OpenSpec a partir de un ticket de Jira o Azure Boards
argument-hint: <PROJ-1234 | AB#1234>
model: opus
---
1. Lee el ticket $ARGUMENTS con el MCP correspondiente (título, descripción,
   criterios de aceptación, enlaces). Solo lectura: no modifiques el ticket.
2. Si hay criterios ambiguos o contradictorios, lístalos y PARA; pregúntame antes de seguir.
3. Ejecuta /opsx:propose con el nombre `<clave-ticket-en-minúsculas>-<slug-kebab-case>`.
   - proposal.md: enlace al ticket en la primera línea.
   - specs: al menos un Scenario por criterio de aceptación.
4. Muéstrame un resumen de proposal.md y de las delta specs para revisión antes de /opsx:apply.

Subagente spec-verifier

Subagente en .claude/agents/spec-verifier.md: verifica la implementación sin modificar nada, después de /opsx:apply y antes de abrir la PR.

---
name: spec-verifier
description: Verifica de forma independiente que la implementación de un cambio OpenSpec cumple sus specs. Úsalo después de /opsx:apply y antes de abrir la PR.
tools: Read, Grep, Glob, Bash
model: opus
---
No modifiques ningún fichero.
1. Lee openspec/changes/<cambio>/ (proposal, specs, tasks).
2. Para cada Requirement y Scenario, localiza el código que lo implementa y el test que lo cubre.
3. Ejecuta los tests de los proyectos afectados.
4. Devuelve:
   - Tabla: Requirement | Scenario | Código | Test | Estado (cubierto / parcial / sin cubrir)
   - Tareas marcadas [x] en tasks.md que no están realmente implementadas
   - Riesgos detectados (breaking changes, migraciones, seguridad)

Validación en Azure Pipelines

Regístrala como validación de build en la política de main. La versión de OpenSpec va fijada.

trigger: none
pool: { vmImage: ubuntu-latest }
steps:
  - task: NodeTool@0
    inputs: { versionSpec: '22.x' }
  - script: npm i -g @fission-ai/openspec@1.14.0
    displayName: Install OpenSpec
  - script: openspec validate --all --strict --no-interactive
    displayName: Validate specs
    env: { OPENSPEC_TELEMETRY: '0' }

La variante para GitHub Actions está en Validación en CI.

Plantilla de pull request

## Ticket
PROJ-1234 / AB#1234

## Change OpenSpec
`openspec/changes/archive/<fecha>-proj-1234-...` (o `no-spec` justificado)

## Checklist
- [ ] Propuesta y delta specs revisadas antes de implementar
- [ ] Cada Scenario tiene test automatizado
- [ ] spec-verifier sin elementos "sin cubrir"
- [ ] Change archivado en esta PR (specs/ actualizado)
- [ ] Pipeline verde (openspec validate + build + tests)
- [ ] Migraciones revisadas y con plan de rollback (si aplica)

Plantilla de ticket

Story o PBI compatible con OpenSpec: redactar los criterios en Given/When/Then facilita que el agente los convierta en escenarios sin interpretar.

**Como** <rol> **quiero** <objetivo> **para** <beneficio>

**Criterios de aceptación**
1. Dado <contexto>, cuando <acción>, entonces <resultado>
2. Dado <contexto>, cuando <acción errónea>, entonces <error esperado>

**Fuera de alcance**
- …

**Notas** (sin datos personales reales)

Siguiente paso

Glosario