Empieza un proyecto con el método, o súmale uno que ya tienes.

# AGENTS.md — cómo se trabaja en este proyecto

Este proyecto se desarrolla con especificaciones (SDD) y tests primero (TDD). Estas reglas valen para cualquier agente de código y para cualquier persona. El método completo, con ejemplos, está en `METODO.md`.

1. **La spec es el contrato.** `specs/` dice qué hace el sistema. Léela antes de tocar código. Nada se implementa si no está especificado.
2. **Algo nuevo empieza por preguntas, no por código.** Ante un proyecto nuevo, una funcionalidad nueva o un encargo ambiguo, no escribas código ni spec todavía. Haz como mucho cinco preguntas: solo las que cambien qué se construye, cada una con opciones y con tu recomendación razonada.
3. **Lo que decidas tú, enuméralo.** Todo lo que resuelvas sin preguntar va a una lista en `bitacora/`: la pregunta que nadie hizo, lo que has decidido y dónde está en la spec. Es lo que se revisa.
4. **Criterios comprobables.** Cada comportamiento es un criterio numerado (`ABC-01`) con la forma Dado / Cuando / Entonces, con valores y mensajes de error exactos. La spec dice también lo que queda fuera.
5. **Sin visto bueno no se implementa.** Escrita la spec y la lista de decisiones, párate y pide revisión.
6. **Tests primero.** Al menos un test por criterio, con el identificador escrito tal cual (`ABC-01`) en el nombre del test; si el lenguaje no admite guiones en un nombre, en un comentario justo encima. Ejecútalos y enseña que fallan antes de implementar. Después, lo mínimo para que pasen. El refactor, al final y con todo en verde.
7. **No modifiques un test para que pase.** Si crees que un test o un criterio están mal, párate y dilo.
8. **Si el código contradice la spec, la spec cambia en el mismo cambio**, y se dice en el informe. Una spec desactualizada es un fallo.
9. **Terminado** es toda la suite en verde y el formateador y el linter sin avisos, en todo el repositorio y no solo en lo tocado. Las órdenes exactas están en `specs/001-plan-tecnico.md`.
10. **Dependencias**: solo las del plan técnico. Añadir otra exige cambiar antes esa spec.
11. **Informe al acabar**: ficheros tocados, decisiones y su porqué, desviaciones de cualquier spec y el resultado de la suite.

# El método, en una página

Este proyecto usa la plantilla de [iadev.xavi.net](https://iadev.xavi.net): primero la especificación, después los tests y solo entonces el código. Aquí está lo justo para empezar; el porqué de cada paso está en el tutorial.

## Qué hay en la plantilla

| Fichero | Para qué |
|---|---|
| `AGENTS.md` | Las reglas. Lo leen solos Codex, Claude Code, pi, opencode y casi cualquier agente |
| `CLAUDE.md` | Para Claude Code: apunta a `AGENTS.md` y a la skill |
| `.claude/skills/sdd-tdd/SKILL.md` | La skill de Claude Code con los tres procedimientos de abajo, paso a paso |
| `specs/000-especificacion.md` | Esqueleto: qué es, para quién, qué queda fuera |
| `specs/001-plan-tecnico.md` | Esqueleto: stack, estructura y la definición de «terminado» |
| `bitacora/` | Las decisiones tomadas por defecto y lo que se le encarga a cada agente |

## Cómo se empieza

Abre tu agente en la carpeta del proyecto. Con Claude Code, escribe `/sdd-tdd` y di qué quieres. Con cualquier otro, pega uno de estos tres encargos.

**Un proyecto nuevo**

```text
Quiero <la idea, en una frase, y para quién es>.

Sigue AGENTS.md. No escribas código todavía.
1. Hazme como mucho cinco preguntas, solo las que cambien qué se construye,
   con opciones y tu recomendación.
2. Con mis respuestas, rellena specs/000 y specs/001 y escribe una spec por
   área, con criterios numerados Dado / Cuando / Entonces.
3. Guarda en bitacora/ la lista de lo que hayas decidido sin preguntarme.
4. Párate ahí y espera mi revisión.
```

**Un proyecto que ya existe**

```text
Este proyecto ya tiene código y no tiene specs. Quiero pasarlo a este método
sin cambiar lo que hace.

Sigue AGENTS.md. No cambies comportamiento.
1. Elige conmigo un área pequeña para empezar; no intentes cubrirlo todo.
2. Lee el código de esa área y escribe la spec de lo que hace HOY, con
   criterios numerados. Lo que no esté claro, márcalo «por confirmar» y
   pregúntamelo (como mucho cinco preguntas).
3. Escribe un test por criterio. Deben pasar con el código actual. Para
   comprobar que prueban algo, rompe a mano la línea que cubren y enséñame
   que entonces fallan; después deja el código como estaba.
4. Dime qué has tenido que tocar del código para poder probarlo, si algo.
```

**Una funcionalidad nueva en un proyecto que ya sigue el método**

```text
Quiero añadir <la funcionalidad>.

Sigue AGENTS.md. Empieza por la spec: preguntas si hacen falta, criterios
nuevos, qué specs existentes cambian y la lista de lo decidido por defecto.
No implementes hasta que te dé el visto bueno. Después, tests en rojo y,
solo entonces, el código.
```

## El ciclo, una vez arrancado

1. La spec dice qué debe pasar (un criterio).
2. Un test lo comprueba y falla: todavía no hay código.
3. El código mínimo lo hace pasar.
4. Se limpia con todo en verde.
5. Se revisa el cambio contra la spec, no contra la intuición.

---
name: sdd-tdd
description: Arranca un proyecto nuevo, adopta el método en un proyecto que ya tiene código o añade una funcionalidad siguiendo SDD + TDD (primero la spec, después los tests, al final el código). Úsala cuando el usuario quiera empezar un proyecto, «pasar esto a specs y tests», o pida una funcionalidad que todavía no está en specs/.
---

# SDD + TDD: punto de partida

Las reglas están en `AGENTS.md`; léelo antes de nada. Esta skill dice **por dónde empezar** según el estado del proyecto.

## 1. Mira en qué caso estás

- No hay código, o casi: **Arranque**.
- Hay código y no hay `specs/` con criterios: **Adopción**.
- Hay specs con criterios y el usuario pide algo que no está en ellas: **Funcionalidad nueva**.

Dile al usuario en una línea qué caso has visto antes de seguir.

## 2. Arranque (proyecto nuevo)

1. **No escribas código.**
2. **Pregunta.** Como mucho cinco preguntas, solo las que cambien qué se construye (qué entra en la primera versión, quién lo usa, dónde se guardan los datos, quién puede hacer qué). Cada una con dos a cuatro opciones y tu recomendación primero, con su porqué. Si tienes una herramienta para hacer preguntas, úsala. Lo que puedas decidir tú con un criterio razonable, no lo preguntes.
3. **Escribe la spec.** Rellena `specs/000-especificacion.md` y `specs/001-plan-tecnico.md`. Añade una spec por área (`002-…`, `003-…`) con criterios numerados (`ABC-01`) de la forma Dado / Cuando / Entonces, con valores y mensajes de error exactos. Incluye qué queda fuera.
4. **Enumera lo que has decidido tú.** En `bitacora/001-decisiones.md`, una tabla: la pregunta que nadie hizo, lo que dice la spec, dónde.
5. **Párate.** Resume en pocas líneas qué has escrito y pide revisión. No implementes.
6. **Tras el visto bueno**, divide el trabajo en piezas pequeñas. Para cada una: tests de todos sus criterios, ejecutarlos y enseñar que fallan; después, lo mínimo para que pasen, sin tocar los tests; al final, limpiar con todo en verde.

## 3. Adopción (ya hay código)

El objetivo es poner el contrato debajo del código que existe, **sin cambiar lo que hace**.

1. **Acota.** Propón un área pequeña y con valor (la que más se toca o la que más duele) y acuerda con el usuario empezar por ahí. No intentes especificarlo todo.
2. **Describe lo que hay.** Lee el código de esa área y escribe su spec con criterios numerados que digan lo que el sistema hace **hoy**, no lo que debería hacer. Si algo parece un fallo, especifícalo tal como es y anótalo aparte como «posible fallo»: arreglarlo es un cambio posterior, con su propio criterio.
3. **Pregunta lo que el código no dice.** Marca «por confirmar» lo que no se pueda deducir y pregúntalo, como mucho cinco preguntas, con opciones.
4. **Tests de lo que hay.** Un test por criterio. Aquí el primer paso no es rojo: deben pasar con el código actual. Para comprobar que prueban algo, rompe a mano la línea que cubren, enseña que el test falla y deja el código como estaba.
5. **Toca lo mínimo.** Si para poder probar hay que abrir una rendija en el código (inyectar una dependencia, hacer accesible un método), que sea la mínima, y dila en el informe.
6. **Rellena `specs/001-plan-tecnico.md`** con el stack y las órdenes reales del proyecto.
7. A partir de ahí, cualquier cambio en esa área sigue el ciclo normal. Las demás áreas se adoptan cuando toque trabajar en ellas.

## 4. Funcionalidad nueva (el proyecto ya sigue el método)

1. Lee las specs del área afectada.
2. Si hay algo que solo el usuario puede decidir, pregúntalo: como mucho cinco preguntas, con opciones y recomendación.
3. Escribe o amplía la spec: criterios nuevos, y los cambios que hagan falta en las specs existentes para que sigan siendo coherentes.
4. Enumera en `bitacora/` lo que has decidido por defecto. Párate y pide revisión.
5. Tras el visto bueno: tests de los criterios nuevos en rojo, y solo entonces el código.

## Siempre

- No modifiques un test para que pase. Si crees que está mal, párate y dilo.
- Si el código acaba contradiciendo una spec, la spec cambia en el mismo cambio.
- Al terminar: ficheros tocados, decisiones y su porqué, desviaciones de cualquier spec y resultado de la suite completa.

# Notas para Claude Code

Las reglas del proyecto están en @AGENTS.md y el contrato en `specs/`.

Para arrancar el proyecto, adoptar el método en código que ya existe o añadir una funcionalidad, usa la skill `sdd-tdd`.

# 000 — Especificación de producto

<!-- Rellena este fichero con las respuestas de la entrevista. Borra los comentarios al terminar. -->

## Qué es

<!-- Dos o tres frases: qué hace y para quién. Sin tecnología. -->

## Objetivos

<!-- Dos o tres. Lo que tiene que ser verdad para dar el proyecto por bueno. -->

## Fuera de esta versión

<!-- Lo que NO se va a hacer, aunque parezca razonable. Evita que alguien lo añada por su cuenta. -->

## Historias de usuario

| # | Como… | quiero… | para… | Spec |
|---|---|---|---|---|
| H1 | | | | |

## Glosario

<!-- Las palabras que en este proyecto significan algo concreto. -->

| Término | Significado |
|---|---|
| | |

## Índice de specs

| Spec | Contenido |
|---|---|
| `000-especificacion.md` | Este documento |
| `001-plan-tecnico.md` | Stack, estructura, convenciones y definición de terminado |
<!-- Añade una spec por área (002, 003…), con sus criterios numerados. -->

# 001 — Plan técnico

<!-- Decisiones técnicas cerradas. Si el código se aparta de aquí, este fichero cambia en el mismo cambio. -->

## Stack

| Pieza | Elección |
|---|---|
| Lenguaje | |
| Tests | |
| Formateador y linter | |

**Dependencias permitidas**: <!-- la lista cerrada. Añadir otra exige cambiar antes este fichero. -->

## Estructura

<!-- Qué carpeta o paquete hace qué, y qué depende de qué. -->

## Convenciones

- **Idioma** de los identificadores, de los comentarios y de los textos que ve el usuario:
- **Tests**: cada test nombra el criterio que comprueba, escrito tal cual (`ABC-01`), en su nombre o en un comentario justo encima. Así se puede buscar qué criterio se ha quedado sin test.
<!-- Añade las que hagan falta: errores, fechas, nombres… -->

## Órdenes

```sh
# ejecutar los tests
# formatear y pasar el linter
# construir
```

## Definición de terminado

Un cambio está terminado cuando, sobre **todo** el repositorio y no solo lo tocado:

1. La suite completa pasa y el formateador y el linter no avisan.
2. Cada criterio nuevo o cambiado tiene al menos un test que lo nombra.
3. Si el cambio contradice una spec, la spec se ha actualizado en el mismo cambio.

# Bitácora

Lo que no cabe en la spec pero conviene poder releer:

- **Las decisiones por defecto.** Cada vez que se especifica algo, la lista de lo que el agente decidió sin preguntar: la pregunta que nadie hizo, lo que se decidió y dónde está en la spec. Un fichero por tanda (`001-decisiones.md`, `002-…`).
- **Los encargos.** Si se delega una tarea en un agente, lo que se le pidió y lo que contestó.

No es documentación del producto: eso es `specs/`. Es la memoria de cómo se llegó hasta ahí.