---
title: "Specs vivas y cambios"
description: "SDD anclado a specs — las specs vivas son la fuente de verdad y los cambios traen deltas que se fusionan en ellas."
canonical_url: "https://razcue-agent-kit.vercel.app/es/concepts/living-specs"
---
# Specs vivas y cambios

> SDD anclado a specs — las specs vivas son la fuente de verdad y los cambios traen deltas que se fusionan en ellas.

El SDD de agent-kit está **anclado a specs**: las specs no son documentos de planificación desechables; siguen siendo ciertas mientras viva el código.

## Specs vivas

`work/specs/<capacidad>/spec.md` dice cómo se comporta **hoy** un área del sistema. Una capacidad es un área que los usuarios reconocen —`auth`, `invoices`, `user-roles`—, no una página ni una tabla.

```markdown [work/specs/auth/spec.md]
---
capability: auth
retired: [auth.R1]
---

# Auth

## Purpose
Who can sign in and how.

## Requirements

### auth.R2 — Session restore
While a session is stored, the app shall restore it on reload.

#### auth.R2.S1 — Reload keeps the user signed in @simple
- Given a signed-in user
- When the page reloads
- Then the user is still signed in
```

El contexto de sesión lista las capacidades (una línea); el agente lee la spec de una capacidad antes de cambiar su comportamiento. La notación se describe en [Notación](https://razcue-agent-kit.vercel.app/es/concepts/notation).

## Cambios

El trabajo complejo es un **cambio** en `work/changes/NNN-slug/`, creado con `agent-kit work new change <slug>`:

<table>
<thead>
  <tr>
    <th>
      Archivo
    </th>
    
    <th>
      Qué es
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        proposal.md
      </code>
    </td>
    
    <td>
      Por qué, qué cambia (dentro / fuera), capacidades afectadas, preguntas abiertas. El primer artefacto que apruebas.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        specs/<capacidad>.md
      </code>
    </td>
    
    <td>
      Spec delta: <code>
        ## ADDED
      </code>
      
      , <code>
        ## MODIFIED
      </code>
      
       (el bloque completo como debe quedar) y <code>
        ## REMOVED Requirements
      </code>
      
       (con un motivo).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        plan.md
      </code>
    </td>
    
    <td>
      Archivos, cambios de esquema / RPC, decisiones, riesgos.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tasks.md
      </code>
    </td>
    
    <td>
      Tareas ordenadas con los ids de escenario que cubren, la evidencia bajo cada una y una tabla de verificación.
    </td>
  </tr>
</tbody>
</table>

## Fusión

Cuando el cambio está verificado, `agent-kit specs merge NNN`:

- aplica todos los deltas del cambio **o ninguno**: se niega y nombra el conflicto cuando falta un requisito MODIFIED o REMOVED, o cuando un id ADDED está tomado o retirado;
- retira los ids de requisitos eliminados y los escenarios que faltan en un bloque MODIFIED (nunca se reutilizan, así los tests, las pasadas de QA y los fixtures antiguos no apuntan al comportamiento equivocado);
- marca la propuesta con `merged: <fecha>` y renueva el checklist de QA.

La carpeta del cambio se queda como registro de por qué cambió el comportamiento.

## Ids

`agent-kit specs next <capacidad>` da el siguiente id de requisito; `agent-kit specs next <capacidad>.R<n>`, el siguiente id de escenario. Ambos cuentan los ids vivos, retirados y de deltas pendientes, para que dos cambios abiertos no choquen.

## Herramientas

<table>
<thead>
  <tr>
    <th>
      Comando
    </th>
    
    <th>
      Hace
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        agent-kit specs lint [cap|NNN]
      </code>
    </td>
    
    <td>
      Revisa la notación y los ids (sale con 1 si hay errores).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        agent-kit specs list
      </code>
    </td>
    
    <td>
      Capacidades con su número de requisitos y escenarios.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        agent-kit specs trace [NNN|cap]
      </code>
    </td>
    
    <td>
      Escenario → tests o comprobaciones ✅.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        agent-kit work status
      </code>
      
       / <code>
        board
      </code>
    </td>
    
    <td>
      Trabajo activo y su próxima tarea.
    </td>
  </tr>
</tbody>
</table>


## Sitemap

See the full [sitemap](https://razcue-agent-kit.vercel.app/sitemap.md) for all pages.