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.
3.7 KiB
3.7 KiB
Reglas del proyecto
Guias operativas para LLMs que trabajan en este codebase. Cada regla describe como ejecutar una tarea especifica respetando la arquitectura y convenciones del proyecto.
Reglas disponibles
| Regla | Archivo | Cuando aplicarla |
|---|---|---|
| Crear agente | create_agent.md | Al crear un nuevo bot/agente Matrix completo |
| Crear herramienta | create_tool.md | Al añadir una nueva tool para LLM function calling |
| Crear comando | create_command.md | Al añadir un comando directo (!xxx) a un agente |
| Crear issue | create_issue.md | Al crear un nuevo issue/feature request en dev/issues/ |
| Arreglar issue | fix_issue.md | Al implementar/arreglar un issue existente de dev/issues/ |
Cuando consultar las reglas
- Crear agente: cuando el usuario pida crear un nuevo bot, agente, o asistente. Incluye la estructura de archivos, reglas puras, config YAML, system prompt y registro en el launcher.
- 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 — Trunk-based development (TBD)
El proyecto usa TBD estricto. master es el unico branch estable y siempre deployable. Nunca trabajar directamente en master.
master (trunk) ← siempre deployable
↑
└── issue/<NNNN>-<slug> ← rama efimera (horas, no dias)
├── commit: feat: ...
├── commit: test: ...
└── commit: docs: ...
merge --no-ff → master → push → delete branch
/git-branch— crea ramaissue/<NNNN>-<slug>desde master actualizado- Implementar con commits atomicos por bloque logico (no WIP, no mezclar tipos)
/git-push— tests → merge--no-ffa master → push → eliminar rama
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-ffpreserva commits;git log --first-parentda 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
Todas las reglas respetan el patron pure core / impure shell:
pkg/es puro — nunca añadir side effectsshell/es impuro — todo I/O va aquiagents/compone ambos — reglas puras + ensamblado con shelltools/sigue el mismo patron:Def(datos puros) +Exec(funcion impura)