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.
This commit is contained in:
2026-03-07 18:55:09 +00:00
parent 982c210fca
commit abfd04420f
6 changed files with 207 additions and 13 deletions
+29 -1
View File
@@ -39,6 +39,9 @@ Crear un plan con `TodoWrite` basado en las tareas del issue. Respetar el orden
- Respetar **pure core / impure shell**: `pkg/` puro, `shell/` impuro
- Marcar cada tarea como completada en el TodoWrite conforme se avanza
- Compilar frecuentemente: `go build -tags goolm ./...`
- **Commits atómicos por bloque lógico** — no mezclar `feat:` + `test:` en un commit
- **No hacer commits WIP** — nada de "wip", "tmp", "fix fix". Si no hay un bloque lógico completo, no commitear todavía
- Cada commit lleva título corto con prefijo (`feat:`, `fix:`, `test:`, `docs:`, `refactor:`, `chore:`) y cuerpo largo en español explicando qué, por qué e impacto
### 5. Tests — OBLIGATORIO
@@ -59,7 +62,20 @@ go test -tags goolm ./...
### 6. Feature flags (solo si aplica)
Si el issue es parte de una feature mayor que se despliega en fases, actualizar `dev/feature_flags.json`:
En TBD no existen ramas largas. Para features que no caben en un solo issue/rama, se usan **feature flags**: código completo y testeado que se mergea a master pero desactivado.
**Feature flag ≠ WIP.** Un flag protege código terminado; un WIP es código a medias. Nunca commitear código incompleto.
**Cuándo usar feature flags:**
- Este issue es **parte de una feature multi-issue** (ej: issue 0015a, 0015b, 0015c)
- El cambio tiene **riesgo** y necesita poder desactivarse en producción
- Se quiere **despliegue gradual** (activar para un agente primero, después para todos)
**Cuándo NO usarlos:**
- Issue autocontenido que se completa en una rama → mergear directo, sin flag
- Bug fix, refactor, docs → no necesitan flag
Si aplica, actualizar `dev/feature_flags.json`:
```json
{
@@ -76,6 +92,18 @@ Si el issue es parte de una feature mayor que se despliega en fases, actualizar
Incluir el cambio en el commit correspondiente (no crear commit separado solo para flags).
**Flujo para features multi-issue:**
```
Feature grande (ej: 0015 Telegram)
├── issue/0015a-telegram-types → pkg/ types, flag OFF → merge
├── issue/0015b-telegram-client → shell/ client, flag OFF → merge
├── issue/0015c-telegram-listener → integration, flag OFF → merge
└── issue/0015d-telegram-enable → flag ON, cleanup → merge
```
Cada rama es corta, cada merge es seguro, master nunca se rompe.
### 7. Verificar
- [ ] `go build -tags goolm ./...` compila sin errores