From 9a77ef59e87396eb72e4f4ee4735166308e60f21 Mon Sep 17 00:00:00 2001 From: Enmanuel Date: Sat, 7 Mar 2026 18:39:43 +0000 Subject: [PATCH] =?UTF-8?q?feat:=20a=C3=B1adir=20flujo=20de=20desarrollo?= =?UTF-8?q?=20con=20ramas=20y=20feature=20flags?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Se añaden las reglas y commands para el flujo trunk-based completo: - fix_issue.md: guía para implementar issues (rama → tests → merge) - git-branch.md: command para crear ramas issue/- - git-push.md: actualizado con flujo de ramas, tests obligatorios y feature flags - create_issue.md: ajustado formato de numeración a 4 dígitos - index.md: añadida sección de flujo de desarrollo y regla fix_issue - CLAUDE.md: referencia a la nueva regla fix_issue - feature_flags.json: archivo base para flags de despliegue por fases Co-Authored-By: Claude Opus 4.6 --- .claude/CLAUDE.md | 1 + .claude/commands/git-branch.md | 55 +++++++++++++++ .claude/commands/git-push.md | 125 +++++++++++++++++++++++++-------- .claude/rules/create_issue.md | 12 ++-- .claude/rules/fix_issue.md | 122 ++++++++++++++++++++++++++++++++ .claude/rules/index.md | 16 +++++ dev/feature_flags.json | 3 + 7 files changed, 298 insertions(+), 36 deletions(-) create mode 100644 .claude/commands/git-branch.md create mode 100644 .claude/rules/fix_issue.md create mode 100644 dev/feature_flags.json diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index c13e0c0..33aaf37 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -70,6 +70,7 @@ Ver índice completo en `.claude/rules/index.md`. | `.claude/rules/create_tool.md` | Al añadir una nueva tool para function calling | | `.claude/rules/create_command.md` | Al añadir un comando directo (!xxx) a un agente | | `.claude/rules/create_issue.md` | Al crear un nuevo issue en `dev/issues/` | +| `.claude/rules/fix_issue.md` | Al implementar/arreglar un issue existente | Documentación detallada para humanos en `docs/creating-agents.md`. diff --git a/.claude/commands/git-branch.md b/.claude/commands/git-branch.md new file mode 100644 index 0000000..e755cff --- /dev/null +++ b/.claude/commands/git-branch.md @@ -0,0 +1,55 @@ +# Command: git branch (TBD) + +Crea una rama de trabajo para un issue. **Nunca trabajar directamente en master.** + +## Inputs + +Se necesita el numero del issue y el slug. Si no se proporcionan, preguntar. + +- `issue_number`: numero de 4 digitos (e.g. `0020`) +- `slug`: nombre corto separado por guiones (e.g. `hot-reload`) + +## Flujo obligatorio + +1. Verificar que estamos en master y limpio: + +```bash +git branch --show-current +git status --short +``` + +Si no estamos en master, cambiar primero: + +```bash +git checkout master +``` + +Si hay cambios sin commitear, **avisar al usuario** y no continuar hasta resolver. + +2. Actualizar master desde remoto: + +```bash +git pull --rebase +``` + +3. Crear la rama y cambiar a ella: + +```bash +git checkout -b issue/- +``` + +Ejemplo: `git checkout -b issue/0013-hot-reload` + +4. Confirmar al usuario: + +``` +Rama `issue/-` creada desde master actualizado. +Puedes empezar a trabajar. Cuando termines, usa `/git-push` para integrar a master. +``` + +## Convenciones + +- **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) diff --git a/.claude/commands/git-push.md b/.claude/commands/git-push.md index b4f6a7c..2fde46e 100644 --- a/.claude/commands/git-push.md +++ b/.claude/commands/git-push.md @@ -1,75 +1,140 @@ # Command: git push -Usa este comando para cerrar una tarea completa con sincronización, commits por bloques de cambio y publicación al remoto. +Integra cambios a master y publica. Soporta dos flujos segun la rama actual. ## Flujo obligatorio -1. Verificar rama y estado: +### 1. Verificar rama actual y estado ```bash git branch --show-current git status --short ``` -2. Sincronizar antes de preparar commits (stash para proteger cambios locales): +#### Si estamos en una rama `issue/*` + +Continuar directamente al paso 2. + +#### Si estamos en `master` con cambios pendientes + +Crear una rama automaticamente antes de continuar: + +1. Preguntar al usuario un nombre descriptivo si no es obvio por los cambios. +2. Determinar el siguiente numero de issue disponible (buscar en `dev/issues/` y `dev/issues/completed/`). +3. Crear la rama: ```bash -git stash -git pull --rebase -git stash pop +git checkout -b issue/- ``` -Si `git stash` reporta "No local changes to save", continuar directo con `git pull --rebase` (sin stash pop). +4. Continuar al paso 2 con los cambios ya en la rama nueva. -3. Revisar cambios y separarlos por tema: +#### Si estamos en `master` sin cambios + +**STOP**: no hay nada que publicar. + +### 2. Revisar cambios y crear commits por bloque ```bash +git status --short git diff --stat git diff ``` -4. Si hay cambios de distinta naturaleza, crear varios commits: - -- Commit 1: refactor/código -- Commit 2: documentación -- Commit 3: reglas/configuración - -Comandos sugeridos: +Si hay cambios de distinta naturaleza, crear varios commits separados por bloque logico: ```bash git add -git commit -m ": " -m "Descripción larga en español explicando qué cambia, por qué se hizo, impacto esperado y alcance del bloque." +git commit -m ": " -m "Descripcion larga en espanol explicando que cambia, por que se hizo, impacto esperado y alcance del bloque." git add -git commit -m ": " -m "Descripción larga en español explicando qué cambia, por qué se hizo, impacto esperado y alcance del bloque." +git commit -m ": " -m "Descripcion larga en espanol." ``` -5. Publicar commits: +### 3. Ejecutar tests + +**Obligatorio antes de mergear.** Si el proyecto tiene tests, ejecutarlos: + +```bash +go test -tags goolm ./... +``` + +- Si los tests **fallan** → **STOP**: corregir antes de continuar. No mergear codigo roto. +- Si los tests **pasan** → continuar al paso 4. +- Si no hay tests aplicables (e.g. solo cambios de docs/config) → indicar al usuario y continuar. + +### 4. Evaluar feature flags + +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. + +### 5. Actualizar master y hacer merge --no-ff + +```bash +git checkout master +git pull --rebase +git merge --no-ff issue/- -m "merge: issue/- — " +``` + +El merge commit debe tener formato: +- Titulo: `merge: issue/- — ` +- Cuerpo (opcional): resumen de lo que entra + +Si hay conflictos durante el merge: +1. Resolver los conflictos +2. `git add` los archivos resueltos +3. `git commit` (sin -m, para mantener el mensaje de merge) + +### 6. Push a remoto ```bash git push ``` -## Convención de commits +### 7. Limpiar rama local + +```bash +git branch -d issue/- +``` + +### 8. Confirmar al usuario + +``` +Rama `issue/-` integrada a master y publicada. +Rama local eliminada. +``` + +## Convencion de commits - `feat:` nueva funcionalidad -- `fix:` corrección de error +- `fix:` correccion de error - `refactor:` cambio estructural sin cambio funcional -- `docs:` documentación +- `docs:` documentacion - `chore:` mantenimiento +- `test:` tests nuevos o modificados +- `merge:` commit de merge (generado por --no-ff) ## Regla de mensajes -- El título (`-m` corto) debe resumir el bloque. -- El cuerpo (`-m` largo) debe estar en español y explicar: - - qué se cambió, - - por qué se cambió, - - qué impacto tiene, - - qué no se tocó. +- El titulo (`-m` corto) debe resumir el bloque. +- El cuerpo (`-m` largo) debe estar en espanol y explicar: + - que se cambio, + - por que se cambio, + - que impacto tiene, + - que no se toco. -## Checklist rápido +## Checklist rapido -- [ ] `git stash` + `git pull --rebase` + `git stash pop` ejecutado sin conflictos. +- [ ] Todos los cambios estan commiteados en una rama `issue/*`. - [ ] Se separaron cambios distintos en commits diferentes. -- [ ] Cada commit tiene descripción larga en español. +- [ ] Cada commit tiene descripcion larga en espanol. +- [ ] Tests ejecutados y pasando (o no aplican). +- [ ] Feature flags evaluados (o no aplican). +- [ ] `git merge --no-ff` ejecutado desde master. - [ ] `git push` ejecutado correctamente. +- [ ] Rama local eliminada. diff --git a/.claude/rules/create_issue.md b/.claude/rules/create_issue.md index 8a7ed6d..9f24079 100644 --- a/.claude/rules/create_issue.md +++ b/.claude/rules/create_issue.md @@ -8,23 +8,23 @@ Guia para crear issues de features, mejoras o bugs en `dev/issues/`. |-------|-----------|---------| | Titulo | si | "Hot reload de configuracion" | | Descripcion/objetivo | si | "Recargar config sin reiniciar el agente" | -| Dependencias | no | "Requiere issue 010" | +| Dependencias | no | "Requiere issue 0010" | ## Pasos ### 1. Determinar el numero del issue -Buscar el numero mas alto en `dev/issues/` y usar el siguiente. Formato: 3 digitos con ceros a la izquierda (`019`, `020`, etc.). +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/-.md`. +Copiar `.claude/templates/issue.md` a `dev/issues/-.md`. El slug debe ser: - Lowercase - Palabras separadas por guiones - Conciso (2-4 palabras) -- Ejemplo: `019-hot-reload.md` +- Ejemplo: `0019-hot-reload.md` ### 3. Rellenar el template @@ -44,7 +44,7 @@ Completar todas las secciones del template: Agregar una fila al final de la tabla en `dev/issues/README.md`: ```markdown -| | | [-.md](-.md) | pendiente | +| | | [-.md](-.md) | pendiente | ``` ## Reglas @@ -57,7 +57,7 @@ Agregar una fila al final de la tabla en `dev/issues/README.md`: ## Verificacion -- [ ] Archivo creado en `dev/issues/-.md` +- [ ] Archivo creado en `dev/issues/-.md` - [ ] Todas las secciones del template rellenadas - [ ] Fila agregada en `dev/issues/README.md` - [ ] Numero de issue es consecutivo (no hay saltos ni duplicados) diff --git a/.claude/rules/fix_issue.md b/.claude/rules/fix_issue.md new file mode 100644 index 0000000..1a4fbb7 --- /dev/null +++ b/.claude/rules/fix_issue.md @@ -0,0 +1,122 @@ +# Regla: Arreglar/implementar un issue existente + +Guia para trabajar en un issue de `dev/issues/` y cerrarlo al terminar. +Usa trunk-based development: siempre trabajar en una rama, nunca en master. + +## Inputs — preguntar al usuario si no los da + +| Input | Requerido | Ejemplo | +|-------|-----------|---------| +| Numero o nombre del issue | si | `0010`, `0010-access-control` | + +## Pasos + +### 1. Leer el issue + +Abrir `dev/issues/-.md` y entender: +- **Objetivo**: que se quiere lograr +- **Tareas**: lista de tareas a completar +- **Arquitectura**: archivos afectados, que es puro vs impuro + +### 2. Crear rama de trabajo + +Ejecutar `/git-branch` con el numero y slug del issue: + +``` +/git-branch +``` + +Esto crea la rama `issue/-` desde master actualizado. +**Nunca trabajar directamente en master.** + +### 3. Planificar el trabajo + +Crear un plan con `TodoWrite` basado en las tareas del issue. Respetar el orden de fases si el issue las define. **Incluir siempre una tarea de tests.** + +### 4. Implementar + +- Seguir las tareas del issue en 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 ./...` + +### 5. Tests — OBLIGATORIO + +Toda implementacion debe incluir tests. Antes de cerrar el issue: + +- Escribir tests para el codigo nuevo o modificado +- Tests de `pkg/` (puro): tests unitarios directos, sin mocks de I/O +- Tests de `shell/` (impuro): pueden usar mocks/stubs para dependencias externas +- Tests de integracion si el issue lo requiere + +Ejecutar: + +```bash +go test -tags goolm ./... +``` + +**No cerrar el issue si los tests no pasan.** + +### 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`: + +```json +{ + "flags": { + "nombre-del-flag": { + "enabled": false, + "issue": "0020", + "description": "Descripcion breve de la feature", + "added": "2026-03-07" + } + } +} +``` + +Incluir el cambio en el commit correspondiente (no crear commit separado solo para flags). + +### 7. Verificar + +- [ ] `go build -tags goolm ./...` compila sin errores +- [ ] `go test -tags goolm ./...` pasa sin errores +- [ ] Todas las tareas del issue estan implementadas +- [ ] El codigo respeta pure core / impure shell +- [ ] Se escribieron tests para el codigo nuevo/modificado + +### 8. Cerrar el issue — OBLIGATORIO al terminar + +Al completar todas las tareas del issue, ejecutar estos pasos: + +#### 8.1. Mover el archivo a completed + +```bash +mv dev/issues/-.md dev/issues/completed/ +``` + +#### 8.2. Actualizar el README + +En `dev/issues/README.md`, cambiar la fila del issue: +- **Link**: de `[-.md](-.md)` a `[-.md](completed/-.md)` +- **Estado**: de `pendiente` a `completado` + +### 9. Integrar y publicar + +Ejecutar `/git-push` para: +1. Commitear los cambios restantes (cierre de issue, README) +2. Hacer merge --no-ff de la rama a master +3. Push a remoto +4. Eliminar la rama local + +El commit de merge tendra formato: `merge: issue/- — ` + +## Reglas + +- **Leer antes de actuar**: siempre leer el issue completo antes de empezar a implementar. +- **Siempre en rama**: nunca trabajar en master. Usar `/git-branch` al inicio. +- **Siempre tests**: toda implementacion debe tener tests. No cerrar sin tests. +- **No saltear tareas**: implementar todas las tareas del issue, no solo las faciles. +- **Cerrar siempre**: nunca dejar un issue implementado sin moverlo a `completed/`. +- **Pure core / impure shell**: toda implementacion debe respetar el patron. +- **Compilar con goolm**: siempre usar `-tags goolm` en build y test. +- **Feature flags**: solo cuando el issue es parte de algo mayor. No es obligatorio en cada fix. diff --git a/.claude/rules/index.md b/.claude/rules/index.md index ba02dac..ca89d03 100644 --- a/.claude/rules/index.md +++ b/.claude/rules/index.md @@ -10,6 +10,7 @@ Guias operativas para LLMs que trabajan en este codebase. Cada regla describe co | **Crear herramienta** | [create_tool.md](create_tool.md) | Al añadir una nueva tool para LLM function calling | | **Crear comando** | [create_command.md](create_command.md) | Al añadir un comando directo (!xxx) a un agente | | **Crear issue** | [create_issue.md](create_issue.md) | Al crear un nuevo issue/feature request en `dev/issues/` | +| **Arreglar issue** | [fix_issue.md](fix_issue.md) | Al implementar/arreglar un issue existente de `dev/issues/` | ## Cuando consultar las reglas @@ -17,6 +18,21 @@ Guias operativas para LLMs que trabajan en este codebase. Cada regla describe co - **Crear herramienta**: cuando el usuario pida añadir una nueva herramienta/tool al sistema. Incluye el patron Def (puro) + Exec (impuro), registro en runtime.go y habilitacion en config. - **Crear comando**: cuando el usuario pida añadir un comando directo (!xxx) a un agente. Los comandos se resuelven sin pasar por reglas ni LLM. - **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) + +El proyecto usa trunk-based development. **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 + +Comandos disponibles en `.claude/commands/`: +- `git-branch.md` — crear rama de trabajo +- `git-push.md` — integrar rama a master y publicar + +Feature flags opcionales en `dev/feature_flags.json` (solo para features que se despliegan en fases). ## Principio general diff --git a/dev/feature_flags.json b/dev/feature_flags.json new file mode 100644 index 0000000..b04d153 --- /dev/null +++ b/dev/feature_flags.json @@ -0,0 +1,3 @@ +{ + "flags": {} +}