diff --git a/.claude/rules/INDEX.md b/.claude/rules/INDEX.md index d5f982e9..2591307b 100644 --- a/.claude/rules/INDEX.md +++ b/.claude/rules/INDEX.md @@ -19,3 +19,4 @@ Reglas operativas del proyecto. Cada archivo es una regla independiente. | 13 | [frontend_theming.md](frontend_theming.md) | Componentes propios y sistema de temas en frontends | | 14 | [deploy.md](deploy.md) | Deploy de apps a VPS remotos via SSH + systemd + rsync | | 15 | [projects.md](projects.md) | Projects: agrupar apps, analysis y vaults bajo un tema | +| 16 | [kiss.md](kiss.md) | KISS en proyectos y apps: cuestionar herramientas externas, sin abstracciones especulativas | diff --git a/.claude/rules/kiss.md b/.claude/rules/kiss.md new file mode 100644 index 00000000..0321ee32 --- /dev/null +++ b/.claude/rules/kiss.md @@ -0,0 +1,30 @@ +## KISS en proyectos y apps + +**Mantener proyectos (`projects/`) y apps (`apps/`, `projects/*/apps/`) simples**. La complejidad no solicitada es deuda — cada línea, cada dependencia y cada herramienta externa se justifican o no entran. + +### Reglas + +1. **Preferir herramientas ya presentes en el sistema o en el registry** antes que paquetes/CLI externos. + - ¿Lo hace `git` / `bash` / una función del registry? Úsalo. + - Antes de añadir una dependencia nueva, buscar en `registry.db` (FTS5) si ya existe algo similar. + +2. **Cuestionar cada nueva herramienta externa**. Antes de instalarla preguntar: + - ¿Qué problema concreto resuelve que NO podemos resolver con lo que ya tenemos? + - ¿El coste (instalar, mantener, aprender, conflictos con nuestro flujo) compensa el beneficio real? + - ¿Qué pasa si el proyecto upstream se abandona / rompe compatibilidad? + +3. **Sin abstracciones ni features especulativas**. No generalizar "por si acaso". Tres líneas similares son mejores que una abstracción prematura. + +4. **Ser consciente del flujo de trabajo actual**. Si algo funciona bien con `git` / submódulos / `fn` CLI, no lo sustituyas por una herramienta que prometa "mejorarlo" sin evidencia de mejora concreta en tu contexto. + +5. **Escritura de apps**: una responsabilidad clara, layout mínimo (`main.*`, `app.md`, y lo estrictamente necesario), sin config ni estructuras que no se usen hoy. + +### Caso aprendido (GitButler) + +Se probó GitButler (virtual branches) pensando en paralelizar trabajo. Resultado: +- Bugs con submódulos (git submodule add + gitlinks) — commits vacíos o contenido cruzado. +- Auto-commits con el texto del chat como commit message. +- Pre-commit hook que bloquea `git commit` directo y exige otro CLI (`but`). +- Un binario externo de 37 MB + un plugin en Claude Code + skill propio + hooks en `settings.json`. + +Al volver a `git` + ramas normales + `fn` CLI: cero fricción, commits limpios, submódulos funcionan. **Lección**: antes de adoptar una capa nueva, medir la fricción real actual. Si no la hay, no vale la pena añadir complejidad.