XeroBis/website

Planificar y Documentar

Por qué

Solicitudes como "porta las tarjetas" o "añade etiquetas al portafolio" parecen decisiones finales, pero normalmente ocultan opciones sin resolver: cuánto construir ahora, qué cambiar o descartar del repositorio antiguo, qué esquema posee los datos, qué va en @shared. Construir de inmediato corre el riesgo de hacer lo incorrecto, tener que rehacerlo, o desviarse de una decisión ya registrada en documentation/decisions.md. Preguntar primero mantiene los documentos — y luego el código — como un registro preciso de lo que el usuario realmente quiere.

Cuándo aplica

Cualquier solicitud que cambiaría algo que documentation/ rastrea: una característica o comportamiento visible para el usuario, un esquema/tabla/columna/regla de negocio, una elección técnica o de librería, la estructura de carpetas/arquitectura, o un paso de migration-plan.md. Las ediciones pequeñas y completamente especificadas (corrige esta errata, renombra esta etiqueta exactamente a X) no necesitan la entrevista — usa tu criterio sobre cuánto es realmente ambiguo.

Pasos

1. Lee antes de preguntar. Revisa las secciones de documentation/*.md relacionadas con la solicitud (y el código relevante). Al portar, también lee la documentación del repositorio antiguo (../<repo>/documentation/, ../<repo>/CLAUDE.md) y el código que se está portando. No preguntes algo que ya esté respondido. Úsalos como base para tus preguntas.

2. Haz preguntas aclaratorias con AskUserQuestion. Prefiere varias preguntas pequeñas y concretas a una amplia. Buenos objetivos para este repositorio:

   • cuánto construir ahora vs. después;
   • al portar: qué mantener tal cual, cambiar o descartar de la aplicación antigua (el comportamiento antiguo no se quiere automáticamente);
   • qué esquema posee las nuevas tablas (el de la propia aplicación, o core si cada aplicación lo necesita);
   • si una pieza pertenece a una aplicación o a @shared / un módulo backend compartido;
   • detalles de UX que features.md necesitaría registrar, y la forma de los nuevos datos.

   Dale a cada pregunta un valor por defecto recomendado para que el usuario pueda avanzar rápido.

3. Respeta exactamente el alcance que el usuario devuelva. Si lo reduce a "solo documentación" o "solo X, no Y", no hagas más en silencio — confirma de nuevo antes de expandir el alcance más adelante.

4. Actualiza los documentos en el mismo paso que la decisión, enrutando según la tabla de CLAUDE.md:

   • Estructura de carpetas, entornos, puertos, flujo de solicitudes → architecture.md
   • Esquemas, tablas, columnas, relaciones, reglas de negocio → data-model.md, en la sección de ese esquema
   • Elección técnica/librería/arquitectura → decisions.md: una entrada con fecha que indique qué se eligió, sobre qué y por qué, siguiendo el estilo de ese archivo
   • Comportamiento visible para el usuario, reglas de validación → features.md, en la sección de esa aplicación
   • Cualquier cosa aplazada, descartada o que aún sea solo una posibilidad → ideas.md
   • Progreso del porte → columna de estado de migration-plan.md
   • Cambios en el runbook de producción → deployment.md

5. Mueve las ideas resueltas fuera de ideas.md. Si un cambio convierte una entrada de ideas.md en una decisión real, elimina o reescribe esa entrada en lugar de dejar un duplicado desactualizado.