From abfd04420fc268dba0d863609fb39019df1b33c9 Mon Sep 17 00:00:00 2001 From: Enmanuel Date: Sat, 7 Mar 2026 18:55:09 +0000 Subject: [PATCH] docs: documentar TBD, feature flags y convenciones de commits en reglas MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- .claude/CLAUDE.md | 94 ++++++++++++++++++++++++++++++++++ .claude/commands/git-branch.md | 18 ++++++- .claude/commands/git-push.md | 12 ++++- .claude/rules/create_issue.md | 23 +++++++++ .claude/rules/fix_issue.md | 30 ++++++++++- .claude/rules/index.md | 43 ++++++++++++---- 6 files changed, 207 insertions(+), 13 deletions(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 33aaf37..ce5ccc6 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -167,6 +167,100 @@ ANTHROPIC_API_KEY # Anthropic/Claude Nunca commitear `.env`. Plantilla en `.env.example`. +## Trunk-based development (TBD) + +El proyecto usa trunk-based development estricto. **master** es el único branch estable y siempre deployable. + +### Flujo de trabajo + +``` +master (trunk) ← siempre deployable, único branch permanente + ↑ + └── issue/- ← rama efímera (horas, no días) + ├── commit: feat: ... + ├── commit: test: ... + └── commit: docs: ... + merge --no-ff → master → push → delete branch +``` + +1. **`/git-branch`** — crea rama `issue/-` desde master actualizado +2. Implementar en la rama con commits granulares por bloque lógico +3. **`/git-push`** — tests → merge `--no-ff` a master → push → eliminar rama + +### Convención de commits + +Dentro de la rama, cada commit es **atómico por bloque lógico** (no mezclar feat + test en uno): + +| Prefijo | Uso | +|---------|-----| +| `feat:` | nueva funcionalidad | +| `fix:` | corrección de error | +| `refactor:` | cambio estructural sin cambio funcional | +| `docs:` | documentación | +| `chore:` | mantenimiento | +| `test:` | tests nuevos o modificados | +| `merge:` | commit de merge (generado por `--no-ff`) | + +- **Título** (`-m` corto): resumen del bloque +- **Cuerpo** (`-m` largo): en español, explica qué, por qué, impacto y alcance +- **No hacer commits WIP**: nada de "wip", "tmp", "fix fix" — cada commit debe tener mensaje real +- **No squash**: `--no-ff` preserva los commits individuales; `git log --first-parent master` da la vista limpia (un merge = un issue) + +### Reglas de ramas + +- **Nunca trabajar directamente en master** — siempre crear rama con `/git-branch` +- **Una rama por issue** — no mezclar issues en la misma rama +- **Ramas cortas** — idealmente horas, no días +- **Nunca pushear la rama** — solo se pushea master después del merge +- **No rebase interactivo** — si los commits ya son limpios, no hay nada que reescribir + +### Feature flags — features grandes en TBD + +En TBD no existen ramas largas. Para features que no caben en una sola rama, se usan **feature flags**: código completo y testeado que se mergea a master pero desactivado hasta que todas las piezas estén listas. + +**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:** +- Feature multi-issue que requiere varias ramas para completarse +- Cambio con riesgo que necesita poder desactivarse en producción +- 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 +- Bug fix, refactor, docs → no necesitan flag + +**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. + +**Archivo:** `dev/feature_flags.json` + +```json +{ + "flags": { + "telegram-support": { + "enabled": false, + "issue": "0015", + "description": "Soporte multi-plataforma Telegram", + "added": "2026-03-07" + } + } +} +``` + +### Comandos disponibles + +- `/git-branch` — crear rama de trabajo (`.claude/commands/git-branch.md`) +- `/git-push` — integrar rama a master y publicar (`.claude/commands/git-push.md`) + ## Preferencias del usuario - **Idioma**: español en configs/comentarios de dominio, inglés en código Go diff --git a/.claude/commands/git-branch.md b/.claude/commands/git-branch.md index e755cff..c45a733 100644 --- a/.claude/commands/git-branch.md +++ b/.claude/commands/git-branch.md @@ -52,4 +52,20 @@ Puedes empezar a trabajar. Cuando termines, usa `/git-push` para integrar a mast - **Formato de rama**: `issue/-` (siempre 4 digitos) - **Ramas cortas**: idealmente horas, no dias - **Una rama por issue**: no mezclar issues en la misma rama -- **Nunca pushear la rama al remoto**: el push se hace desde master despues del merge (a menos que se necesite un PR de un agente) +- **Nunca pushear la rama al remoto**: el push se hace desde master despues del merge +- **No rebase interactivo**: si los commits son limpios desde el inicio, no reescribir historia +- **No commits WIP**: cada commit en la rama debe ser atomico y con mensaje real (ver convencion en `/git-push`) + +## Features multi-issue + +Para features que no caben en una sola rama, usar sub-issues con sufijo letra: + +``` +issue/0015a-telegram-types +issue/0015b-telegram-client +issue/0015c-telegram-listener +issue/0015d-telegram-enable +``` + +Cada sub-rama sigue el mismo flujo: crear → implementar → merge --no-ff → delete. +El codigo parcial se protege con **feature flags** en `dev/feature_flags.json` (no con commits WIP). diff --git a/.claude/commands/git-push.md b/.claude/commands/git-push.md index 2fde46e..f022851 100644 --- a/.claude/commands/git-push.md +++ b/.claude/commands/git-push.md @@ -41,7 +41,7 @@ git diff --stat git diff ``` -Si hay cambios de distinta naturaleza, crear varios commits separados por bloque logico: +Crear commits **atomicos por bloque logico**. Cada commit agrupa cambios de la misma naturaleza: ```bash git add @@ -51,6 +51,12 @@ git add git commit -m ": " -m "Descripcion larga en espanol." ``` +**Reglas criticas de commits:** +- **No WIP**: nunca commitear "wip", "tmp", "fix fix" ni codigo a medias. Cada commit debe ser atomico y completo. +- **No mezclar tipos**: no combinar `feat:` + `test:` en un mismo commit. Separar por bloque logico. +- **No squash**: los commits individuales se preservan en master via `--no-ff`. Usar `git log --first-parent master` para ver solo merge commits. +- **No rebase interactivo**: si los commits ya son limpios, no reescribir historia. + ### 3. Ejecutar tests **Obligatorio antes de mergear.** Si el proyecto tiene tests, ejecutarlos: @@ -65,13 +71,15 @@ go test -tags goolm ./... ### 4. Evaluar feature flags +Feature flags se usan cuando el issue es **parte de una feature multi-issue** o el cambio tiene riesgo y necesita poder desactivarse. **Feature flag ≠ WIP** — un flag protege codigo terminado y testeado, no codigo a medias. + Si se modifico `dev/feature_flags.json` o si los cambios son parte de una feature que se despliega en fases: 1. Verificar que `dev/feature_flags.json` existe y esta actualizado. 2. Confirmar que el flag correspondiente tiene el estado correcto (`enabled: true/false`). 3. Incluir el archivo en el commit correspondiente (no crear commit separado solo para flags). -Si no aplican feature flags, saltar este paso. +Si el issue es autocontenido (se completa en esta rama), no necesita flag. Saltar este paso. ### 5. Actualizar master y hacer merge --no-ff diff --git a/.claude/rules/create_issue.md b/.claude/rules/create_issue.md index 9f24079..f76a585 100644 --- a/.claude/rules/create_issue.md +++ b/.claude/rules/create_issue.md @@ -47,6 +47,27 @@ Agregar una fila al final de la tabla en `dev/issues/README.md`: | | | [-.md](-.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). @@ -54,6 +75,7 @@ Agregar una fila al final de la tabla en `dev/issues/README.md`: - **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 @@ -61,3 +83,4 @@ Agregar una fila al final de la tabla en `dev/issues/README.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 diff --git a/.claude/rules/fix_issue.md b/.claude/rules/fix_issue.md index 1a4fbb7..9e27e7f 100644 --- a/.claude/rules/fix_issue.md +++ b/.claude/rules/fix_issue.md @@ -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 diff --git a/.claude/rules/index.md b/.claude/rules/index.md index ca89d03..3fdfc41 100644 --- a/.claude/rules/index.md +++ b/.claude/rules/index.md @@ -20,19 +20,44 @@ Guias operativas para LLMs que trabajan en este codebase. Cada regla describe co - **Crear issue**: cuando el usuario pida crear un nuevo issue, feature request o task. Usa el template en `.claude/templates/issue.md`. - **Arreglar issue**: cuando el usuario pida implementar, arreglar o trabajar en un issue existente. Incluye crear rama (`/git-branch`), implementar las tareas con tests, cerrar el issue, e integrar a master (`/git-push`). -## Flujo de desarrollo (TBD) +## Flujo de desarrollo — Trunk-based development (TBD) -El proyecto usa trunk-based development. **Nunca trabajar directamente en master.** +El proyecto usa TBD estricto. **master** es el unico branch estable y siempre deployable. **Nunca trabajar directamente en master.** -1. `/git-branch` — crea rama `issue/-` desde master -2. Implementar cambios + tests en la rama -3. `/git-push` — merge --no-ff a master, push, cleanup rama +``` +master (trunk) ← siempre deployable + ↑ + └── issue/- ← rama efimera (horas, no dias) + ├── commit: feat: ... + ├── commit: test: ... + └── commit: docs: ... + merge --no-ff → master → push → delete branch +``` -Comandos disponibles en `.claude/commands/`: -- `git-branch.md` — crear rama de trabajo -- `git-push.md` — integrar rama a master y publicar +1. `/git-branch` — crea rama `issue/-` desde master actualizado +2. Implementar con commits atomicos por bloque logico (no WIP, no mezclar tipos) +3. `/git-push` — tests → merge `--no-ff` a master → push → eliminar rama -Feature flags opcionales en `dev/feature_flags.json` (solo para features que se despliegan en fases). +### Commits + +- Cada commit es **atomico por bloque logico** con prefijo: `feat:`, `fix:`, `test:`, `docs:`, `refactor:`, `chore:` +- Titulo corto + cuerpo largo en español +- **No WIP**: nunca commitear "wip", "tmp", codigo a medias +- **No squash**: `--no-ff` preserva commits; `git log --first-parent` da vista limpia +- **No rebase -i**: commits limpios desde el inicio + +### Feature flags (para features multi-issue) + +Cuando una feature no cabe en una sola rama corta, desglosar en sub-issues. Cada sub-issue mergea codigo **completo y testeado** protegido por un feature flag (desactivado). **Feature flag ≠ WIP** — un flag protege codigo terminado, no codigo a medias. + +Archivo: `dev/feature_flags.json` + +### Comandos + +- `/git-branch` — crear rama de trabajo (`.claude/commands/git-branch.md`) +- `/git-push` — integrar rama a master y publicar (`.claude/commands/git-push.md`) + +Filosofia completa documentada en `CLAUDE.md` seccion "Trunk-based development". ## Principio general