Files

T

egutierrez abfd04420f docs: documentar TBD, feature flags y convenciones de commits en reglas

Añade documentación completa del flujo trunk-based development a todos
los archivos de reglas y comandos del proyecto:

- CLAUDE.md: sección completa de TBD con flujo, commits, ramas y feature flags
- git-branch.md: sección de features multi-issue y reglas de commits
- git-push.md: reglas críticas de commits (no WIP, no squash, no rebase -i)
- create_issue.md: guía de desglose en sub-issues con feature flags
- fix_issue.md: cuándo usar/no usar feature flags, flujo multi-issue
- index.md: resumen expandido del flujo TBD con commits y flags

Impacto: todas las reglas ahora documentan consistentemente el flujo
de desarrollo, convenciones de commits y uso de feature flags.

2026-03-07 18:55:09 +00:00

3.4 KiB

Raw Blame History

Regla: Crear un nuevo issue

Guia para crear issues de features, mejoras o bugs en dev/issues/.

Inputs — preguntar al usuario si no los da

Input	Requerido	Ejemplo
Titulo	si	"Hot reload de configuracion"
Descripcion/objetivo	si	"Recargar config sin reiniciar el agente"
Dependencias	no	"Requiere issue 0010"

Pasos

1. Determinar el numero del issue

Buscar el numero mas alto en dev/issues/ (incluyendo completed/) y usar el siguiente. Formato: 4 digitos con ceros a la izquierda (0019, 0020, etc.).

2. Crear el archivo desde el template

Copiar .claude/templates/issue.md a dev/issues/<NNNN>-<slug>.md.

El slug debe ser:

Lowercase
Palabras separadas por guiones
Conciso (2-4 palabras)
Ejemplo: 0019-hot-reload.md

3. Rellenar el template

Completar todas las secciones del template:

Objetivo: 1-3 frases claras de que se quiere lograr
Contexto: que existe, que falta, dependencias
Arquitectura: archivos afectados, marcar NEW los nuevos. Incluir como se respeta pure core / impure shell
Tareas: desglosar en fases con tareas numeradas (1.1, 1.2, etc.). Cada tarea debe ser concreta y verificable. Incluir siempre una fase de tests y una de cleanup/docs
Ejemplo de uso: flujo concreto mostrando la feature funcionando
Decisiones de diseno: justificar las decisiones clave
Prerequisitos: que debe estar implementado antes
Riesgos: problemas potenciales y mitigacion

4. Actualizar el indice

Agregar una fila al final de la tabla en dev/issues/README.md:

| <N> | <Titulo> | [<NNNN>-<slug>.md](<NNNN>-<slug>.md) | pendiente |

Features multi-issue (feature flags)

Si la feature es demasiado grande para completarse en una sola rama corta (horas), desglosar en sub-issues que se implementan y mergean por separado. Cada sub-issue debe:

Ser autocontenido: compilar, pasar tests, no romper master
Proteger el codigo parcial con un feature flag en dev/feature_flags.json (desactivado hasta que todo este listo)
Usar numeracion con sufijo letra: 0015a, 0015b, etc.

Ejemplo:

0015a-telegram-types       → tipos puros en pkg/
0015b-telegram-client      → cliente en shell/
0015c-telegram-listener    → integracion en agents/
0015d-telegram-enable      → activar flag, cleanup

Indicar en el issue principal que es multi-issue y listar los sub-issues planificados.

Feature flag ≠ WIP. Un flag protege codigo terminado y testeado; un WIP es codigo a medias. Nunca commitear codigo incompleto a master.

Reglas

Patron pure core / impure shell: toda feature debe explicar que va en pkg/ (puro) vs shell/ (impuro).
Tareas atomicas: cada tarea debe ser implementable de forma independiente.
Numeracion continua: nunca reusar numeros de issues eliminados.
Estado: los issues nuevos siempre empiezan como pendiente.
Completados: cuando se termine un issue, moverlo a dev/issues/completed/ y actualizar el README.
Issues grandes: si no cabe en una rama corta, desglosar en sub-issues con feature flags.

Verificacion

Archivo creado en dev/issues/<NNNN>-<slug>.md
Todas las secciones del template rellenadas
Fila agregada en dev/issues/README.md
Numero de issue es consecutivo (no hay saltos ni duplicados)
Si es multi-issue: sub-issues planificados y feature flag definido

3.4 KiB Raw Blame History