# Construye con calidad: reglas para que Claude no te entregue una app que se rompe Este archivo no es para que tú lo leas. Es para que se lo des a Claude Code. Abre en Visual Studio Code la carpeta del proyecto que estás construyendo (tu app de inventarios, de recursos humanos, tu panel). Arrastra este archivo al chat sosteniendo **Shift** y escribe: ``` instala las reglas de construcción en este proyecto ``` --- ## INSTRUCCIONES PARA CLAUDE CODE Quien te habla es dueño de un negocio, no programador. Está construyendo herramientas internas contigo y no tiene forma de saber si el código que le entregas está bien hecho. Su miedo es real: ya le pasó que una app funcionó con pocos datos y se cayó cuando cargó los de verdad. Tu trabajo es instalar en este proyecto las reglas y los candados que hacen que **tú** te detengas cuando algo se está haciendo mal, sin depender de que él lo note. Español de México, sin tecnicismos, frases cortas. Cuando tengas que usar una palabra técnica, tradúcela en la misma oración. Una pregunta a la vez. ### Paso 1 · Conoce el proyecto antes de tocar nada Pregúntale, de una en una: 1. ¿Qué hace esta herramienta y quién la va a usar? (él solo, sus gerentes, las sucursales) 2. ¿De dónde salen los datos? (la API de su sistema, una hoja de cálculo, archivos que descarga, lo que capturan en la app) 3. ¿Cuántos registros va a manejar, más o menos, en un año? Si no sabe, ayúdale a calcular: tickets al día por sucursal, por número de sucursales, por 365. 4. ¿Ya existe código en esta carpeta o empezamos de cero? Si ya hay código, revísalo antes de seguir y dile en tres líneas cómo lo encontraste. ### Paso 2 · Instala los dos candados Son dos revisiones automáticas que corren solas. No dependen de que te acuerdes. **Candado 1, al escribir.** Antes de crear o editar un archivo de código, calcula con cuántos renglones va a quedar. Si pasa de 800, te frena y te obliga a dividirlo primero. **Candado 2, al terminar.** Cuando vayas a dar una tarea por terminada, mide todos los archivos de código del proyecto. Atrapa lo que se escribió por cualquier otro camino (por ejemplo, con un script que genera el archivo). Si alguno pasa de 800, no te deja terminar. Los dos hacen falta. En las pruebas, un archivo de 1,357 renglones se escribió con un script y el primer candado no lo vio; el segundo sí. Antes de escribirlos, avísale: *"te va a salir una ventana pidiendo permiso para escribir en la carpeta `.claude`; dile que sí, ahí es donde viven los candados"*. Claude Code protege esa carpeta a propósito. Si el permiso se niega, no le busques la vuelta: deja los archivos en `candados-pendientes/` con los pasos para activarlos y díselo. Primero revisa qué tiene instalado su computadora: corre `python3 --version`, y si no responde, `python --version` y `py --version`. Usa el que conteste. Si ninguno contesta, escribe los dos candados en Node (`node --version`) con la misma lógica exacta. Crea `.claude/hooks/limite_de_renglones.py`: ```python #!/usr/bin/env python3 """Frena a Claude antes de dejar un archivo de código con más renglones de los permitidos. Revisa Write (archivo nuevo o reescrito) y Edit (calcula cómo quedaría el archivo después del cambio).""" import json, sys, os LIMITE = 800 CODIGO = ('.py','.js','.jsx','.ts','.tsx','.html','.css','.sql','.php','.gs','.vue','.svelte','.rb','.go','.java','.cs') d = json.load(sys.stdin) herr, e = d.get('tool_name',''), d.get('tool_input',{}) ruta = e.get('file_path','') if not ruta.lower().endswith(CODIGO): sys.exit(0) if herr == 'Write': final = e.get('content','') elif herr == 'Edit': try: actual = open(ruta, encoding='utf-8', errors='ignore').read() except OSError: sys.exit(0) viejo, nuevo = e.get('old_string',''), e.get('new_string','') final = actual.replace(viejo, nuevo) if e.get('replace_all') else actual.replace(viejo, nuevo, 1) else: sys.exit(0) n = final.count('\n') + 1 if n > LIMITE: print(f"ALTO: {os.path.basename(ruta)} quedaría con {n} renglones y el límite es {LIMITE}. " "No sigas agregando. Primero divide este archivo en piezas más chicas, cada una con un solo trabajo, " "explícale al usuario en una línea cómo quedó dividido y después continúa.", file=sys.stderr) sys.exit(2) sys.exit(0) ``` Crea `.claude/hooks/revision_al_terminar.py`: ```python #!/usr/bin/env python3 """Segunda red: cuando Claude va a dar por terminada una tarea, mide TODOS los archivos de código del proyecto, sin importar cómo se escribieron. Si alguno pasa del límite, no lo deja terminar.""" import json, sys, os LIMITE = 800 CODIGO = ('.py','.js','.jsx','.ts','.tsx','.html','.css','.sql','.php','.gs','.vue','.svelte','.rb','.go','.java','.cs') IGNORAR = {'node_modules','.git','dist','build','.next','venv','.venv','__pycache__','vendor','.claude'} d = json.load(sys.stdin) if d.get('stop_hook_active'): # ya lo frenamos una vez en este turno; no lo encerramos en un ciclo sys.exit(0) raiz = os.environ.get('CLAUDE_PROJECT_DIR') or d.get('cwd') or '.' grandes = [] for carpeta, subs, archivos in os.walk(raiz): subs[:] = [s for s in subs if s not in IGNORAR] for a in archivos: if a.lower().endswith(CODIGO) and '.min.' not in a: ruta = os.path.join(carpeta, a) try: with open(ruta, encoding='utf-8', errors='ignore') as f: n = sum(1 for _ in f) except OSError: continue if n > LIMITE: grandes.append((n, os.path.relpath(ruta, raiz))) if grandes: lista = '; '.join(f'{r} ({n} renglones)' for n, r in sorted(grandes, reverse=True)) print(f"Todavía no termina. Estos archivos pasan del límite de {LIMITE} renglones: {lista}. " "Divídelos en piezas más chicas, cada una con un solo trabajo, comprueba que todo siga funcionando " "y explícale al usuario en una línea cómo quedó dividido.", file=sys.stderr) sys.exit(2) sys.exit(0) ``` Regístralos en `.claude/settings.json` del proyecto (si el archivo ya existe, **agrega** esta sección sin borrar lo que tiene). Si usas `python` o `py` en vez de `python3`, cambia la palabra en los dos comandos: ```json { "hooks": { "PreToolUse": [{"matcher": "Write|Edit", "hooks": [{"type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/limite_de_renglones.py\""}]}], "Stop": [{"hooks": [{"type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/revision_al_terminar.py\""}]}] } } ``` **Compruébalo antes de decirle que quedó.** Corre estas tres pruebas directo contra el primer candado, pasándole el texto por la entrada, y enséñale el resultado con palomita o tache: | Prueba | Lo que le mandas | Lo que debe pasar | |---|---|---| | Archivo nuevo de 900 renglones | `Write` de un `.py` con 900 renglones | Lo frena (sale con código 2 y el mensaje ALTO) | | Archivo de 790 que crece a 819 | `Edit` sobre un `.py` real de 790 renglones | Lo frena | | Notas de 5,000 renglones | `Write` de un `.md` | Lo deja pasar (no es código) | Borra los archivos de prueba al terminar. Avísale que los candados se activan desde la siguiente conversación que abra en esta carpeta. Si el usuario te pide expresamente un archivo grande ("todo en un solo archivo"), haz caso pero díselo: *"esto rompe el límite de 800 renglones; te recomiendo dividirlo en X, Y y Z"*. Nunca lo comprimas a escondidas para que quepa: un archivo apretado es peor que uno largo. ### Paso 3 · Escribe las reglas en su CLAUDE.md Agrega este bloque al `CLAUDE.md` **de esta carpeta** (créalo si no existe). Adapta los ejemplos a su negocio con lo que te contestó en el paso 1. --- ## REGLAS DE CONSTRUCCIÓN **1. Archivos chicos, cada uno con un solo trabajo.** Lo normal es entre 200 y 400 renglones. 800 es el techo y hay un candado que lo cuida. Una función que pasa de 50 renglones se divide. Si para entender un archivo hay que leerlo entero, está mal partido. **2. Antes de construir, el mapa de los datos.** Antes de escribir código de un módulo nuevo, escribe o actualiza `MAPA-DE-DATOS.md` con cuatro cosas, en palabras simples: de dónde entra cada dato, dónde se guarda, quién lo lee y quién lo puede cambiar. Si un dato se captura en dos lugares, o dos caminos llegan al mismo resultado, **detente y pregúntame cuál se queda**. Dos caminos para lo mismo es la causa número uno de que los números no cuadren. **3. Avísame cuando el flujo no tenga sentido.** Si lo que te pido obliga a que la información dé vueltas, se copie a mano, se capture dos veces o dependa de que alguien se acuerde, dímelo antes de construirlo, con la alternativa. No me des la razón por educación. **4. Construye para los datos de verdad, no para los de prueba.** Este proyecto va a manejar [N] registros al año. Por eso: - Nunca cargues todos los registros de golpe. Pide solo los que se van a ver (por fecha, por sucursal, de 50 en 50). - Los cálculos pesados se hacen donde viven los datos (la base de datos, la consulta a la API), no en la pantalla del usuario. - Antes de decir que está listo, pruébalo con un volumen parecido al real. Si no hay datos reales, fabrica datos de prueba de ese tamaño y dime cuánto tardó. **5. Ningún error se esconde.** Si algo falla, se anota en `bitacora-de-errores` con fecha, hora, qué se estaba haciendo y el mensaje. Nunca un "intentar y si falla, seguir como si nada". Un error escondido es un número equivocado que nadie va a ver. **6. No digas "listo" sin haberlo probado en esta misma conversación.** Corre la prueba, lee el resultado y enséñamelo. Si no lo pudiste probar, dilo así: *"no lo pude probar porque..."*. **7. Al cerrar cada módulo, una revisión con ojos nuevos.** Lanza un agente revisor aparte, sin el contexto de cómo lo construiste, con esta lista: ¿algún archivo o función se pasa de tamaño? ¿algún error se traga en silencio? ¿hay datos que se capturan dos veces? ¿se cargan todos los registros de golpe en algún lugar? ¿algo quedó sin probar? Corrige lo que encuentre y dame el resumen en una tabla de tres columnas: qué encontró, qué tan grave, qué hiciste. **8. Todo se respalda.** Cada avance que funcione se guarda en su repositorio de GitHub con un mensaje que diga qué cambió. Nunca una contraseña o llave dentro del código. --- ### Paso 4 · El monitoreo: que te avise dónde se está quebrando La regla 5 deja la bitácora. Ahora conéctala para que no tenga que ir a leerla: 1. Pregúntale dónde quiere enterarse. Si ya tiene su bot de Telegram (TU-TELEGRAM.md), ese es el canal. Si no, una hoja de cálculo que él revise. 2. Haz que cada error nuevo de la bitácora le llegue como mensaje corto: qué módulo, qué pasó, a qué hora, y si se repite. Si el mismo error se repite 10 veces, un solo aviso que diga "10 veces desde las 9:00", no 10 avisos. 3. Una vez al día, un resumen de salud: cuántos errores, cuál módulo falla más y cuánto tardaron las consultas más lentas. Si algo tarda más de 5 segundos, márcalo. ### Paso 5 · Cómo cierras Dile, adaptado: *"Quedaron dos candados y ocho reglas en este proyecto. Desde la próxima conversación, si un archivo crece de más, me freno y lo divido; antes de construir algo nuevo te enseño el mapa de los datos; y si algo se rompe, te llega un aviso. Lo único que te pido es que me digas siempre la verdad de cuántos datos vas a manejar."* Si tiene más de un proyecto, ofrécele instalar lo mismo en los otros.