feat: añadir flujo de desarrollo con ramas y feature flags
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/<NNNN>-<slug> - 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 <noreply@anthropic.com>
This commit is contained in:
@@ -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`.
|
||||
|
||||
|
||||
@@ -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/<issue_number>-<slug>
|
||||
```
|
||||
|
||||
Ejemplo: `git checkout -b issue/0013-hot-reload`
|
||||
|
||||
4. Confirmar al usuario:
|
||||
|
||||
```
|
||||
Rama `issue/<issue_number>-<slug>` creada desde master actualizado.
|
||||
Puedes empezar a trabajar. Cuando termines, usa `/git-push` para integrar a master.
|
||||
```
|
||||
|
||||
## Convenciones
|
||||
|
||||
- **Formato de rama**: `issue/<NNNN>-<slug>` (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)
|
||||
@@ -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/<NNNN>-<slug>
|
||||
```
|
||||
|
||||
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 <archivos_del_bloque_1>
|
||||
git commit -m "<tipo>: <resumen breve>" -m "Descripción larga en español explicando qué cambia, por qué se hizo, impacto esperado y alcance del bloque."
|
||||
git commit -m "<tipo>: <resumen breve>" -m "Descripcion larga en espanol explicando que cambia, por que se hizo, impacto esperado y alcance del bloque."
|
||||
|
||||
git add <archivos_del_bloque_2>
|
||||
git commit -m "<tipo>: <resumen breve>" -m "Descripción larga en español explicando qué cambia, por qué se hizo, impacto esperado y alcance del bloque."
|
||||
git commit -m "<tipo>: <resumen breve>" -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/<NNNN>-<slug> -m "merge: issue/<NNNN>-<slug> — <titulo breve>"
|
||||
```
|
||||
|
||||
El merge commit debe tener formato:
|
||||
- Titulo: `merge: issue/<NNNN>-<slug> — <descripcion corta>`
|
||||
- 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/<NNNN>-<slug>
|
||||
```
|
||||
|
||||
### 8. Confirmar al usuario
|
||||
|
||||
```
|
||||
Rama `issue/<NNNN>-<slug>` 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.
|
||||
|
||||
@@ -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/<NNN>-<slug>.md`.
|
||||
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: `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
|
||||
| <N> | <Titulo> | [<NNN>-<slug>.md](<NNN>-<slug>.md) | pendiente |
|
||||
| <N> | <Titulo> | [<NNNN>-<slug>.md](<NNNN>-<slug>.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/<NNN>-<slug>.md`
|
||||
- [ ] 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)
|
||||
|
||||
@@ -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/<NNNN>-<slug>.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/<NNNN>-<slug>` 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/<NNNN>-<slug>.md dev/issues/completed/
|
||||
```
|
||||
|
||||
#### 8.2. Actualizar el README
|
||||
|
||||
En `dev/issues/README.md`, cambiar la fila del issue:
|
||||
- **Link**: de `[<NNNN>-<slug>.md](<NNNN>-<slug>.md)` a `[<NNNN>-<slug>.md](completed/<NNNN>-<slug>.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/<NNNN>-<slug> — <titulo>`
|
||||
|
||||
## 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.
|
||||
@@ -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/<NNNN>-<slug>` 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
|
||||
|
||||
|
||||
@@ -0,0 +1,3 @@
|
||||
{
|
||||
"flags": {}
|
||||
}
|
||||
Reference in New Issue
Block a user