From a92213853d6df6f73cd73b0d05f40ae1a6eba0cc Mon Sep 17 00:00:00 2001 From: egutierrez Date: Fri, 24 Apr 2026 14:13:29 +0200 Subject: [PATCH] =?UTF-8?q?docs(rules):=20a=C3=B1adir=20regla=20KISS=20par?= =?UTF-8?q?a=20proyectos=20y=20apps?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Formaliza la filosofía de mantener projects/ y apps/ simples: - preferir herramientas del sistema o del registry antes que paquetes externos, - cuestionar cada nueva dependencia (coste/beneficio, riesgo upstream), - evitar abstracciones especulativas, - ser consciente del flujo de trabajo actual. Incluye el aprendizaje del experimento con GitButler (retirado en commit correspondiente de repo_Claude) como caso concreto de una herramienta externa que añadió complejidad sin beneficio en nuestro contexto. Co-Authored-By: Claude Opus 4.7 (1M context) --- .claude/rules/INDEX.md | 1 + .claude/rules/kiss.md | 30 ++++++++++++++++++++++++++++++ 2 files changed, 31 insertions(+) create mode 100644 .claude/rules/kiss.md 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.