egutierrez
abfd04420f
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.
87 lines
3.4 KiB
Markdown
87 lines
3.4 KiB
Markdown
# 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`:
|
|
|
|
```markdown
|
|
| <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:
|
|
|
|
1. Ser autocontenido: compilar, pasar tests, no romper master
|
|
2. Proteger el codigo parcial con un **feature flag** en `dev/feature_flags.json` (desactivado hasta que todo este listo)
|
|
3. 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
|