🏷️ Clasifica cada línea en una de las 10 categorías
Antes de decidir si una instrucción se queda o se va, tienes que decir lo que es. Sin esto, la auditoría se convierte en una cuestión de gustos. La taxonomía tiene 10 categorías, y cada línea de tu configuración cae en una de ellas. Si no puedes elegir la casilla, ese ya es el diagnóstico: la instrucción está haciendo dos cosas al mismo tiempo y debe dividirse.
🆕 Cinco palabras antes de continuar
- Configuración: el conjunto de archivos que instruye al agente —
CLAUDE.md(globales y de proyecto), skills, hooks ysettings.json. - Skill: un paquete de instrucciones que solo se carga cuando aparece esa tarea (o cuando llamas a
/nome) — a diferencia deCLAUDE.md, que se lee en el 100% de las ejecuciones. - Hook: un comando que el programa ejecuta automáticamente antes o después de una acción del agente. No es texto que el modelo lee: es código que ejecuta el harness.
- Guardrail: un límite estricto. Dice qué no puede que ocurra, nunca. «No hagas commit en la rama principal» es un guardrail.
- Instrucción: aquí, la unidad auditable más pequeña —normalmente una viñeta, una frase o un párrafo corto con una sola regla.
| Categoría | Lo que es | Ejemplo real de instrucción |
|---|---|---|
| CONTEXTO | Hecho de tu mundo que el modelo no puede adivinar. | "El portal es el proyecto en ~/projetos/portal, dominio inema.club, Next.js en Vercel." |
| GUARDRAIL | Límite estricto. Lo que nunca puede pasar. | "Nunca hagas commit directamente en la main: siempre crea una rama antes.» |
| CRITERIO DE CALIDAD | Define cómo es un buen resultado, sin decir qué camino seguir. | "La página tiene que funcionar sin internet: nada de CDN externo." |
| VERIFICACIÓN | Dale al modelo una forma objetiva de verificar su propio trabajo. | "Antes de decir «listo», ejecuta npm run build y pega la salida." |
| INTEGRACIÓN/HERRAMIENTA | Dónde vive una credencial, un servicio, un binario. | "Las API keys están en ~/projetos/wifi/.env; cárgalo en runtime, nunca imprimas el valor.» |
| PROCEDIMIENTO REPETIBLE | Secuencia que realmente se repite y aporta valor: candidata a convertirse en skill. | "Publicar en el portal = editar el catálogo, hacer commit en los 3 repos, push." |
| MICROGESTIÓN | Dirige cómo el modelo piensa/ejecuta, en vez de decir el resultado. | "Primero lee el archivo, después enumera las funciones, luego elige una y después..." |
| REDUNDANCIA | La misma regla ya indicada en otro archivo (o dos veces en el mismo). | "Sin emojis en la salida" — presente en el CLAUDE.md global, en la del proyecto y en dos skills. |
| LEGADO/OBSOLETA | Corrige la debilidad de un modelo que ya no funciona aquí. | "No intentes editar más de un archivo a la vez, te confundes." |
| AMBIGUA/NO COMPROBADA | Nadie sabe qué sostiene ni qué se rompe sin ella. | "Ten cuidado y piensa bien antes de responder." |
💡 Las seis de arriba y las cuatro de abajo
Las primeras seis categorías describen instrucciones que pueden estar pagando su propio costo. Las cuatro últimas (microgestión, redundancia, legado, ambigüedad) son diagnósticos: ponerle esa etiqueta a una línea ya significa que no saldrá de la auditoría tal como entró.
Cuidado con la inversión fácil: etiquetar algo como CONTEXTO no es un pase libre. El contexto que solo sirve para el 2% de tus tareas y está en el CLAUDE.md global sigue teniendo un costo en el 100% de las ejecuciones.
🎚️ Decide entre las 6 salidas
La categoría es un diagnóstico; la decisión es lo que haces con él. Hay seis resultados posibles y ninguna línea
puede quedarse sin uno. Una auditoría en la que el 90% de las líneas termina como KEEP
no es una configuración saludable: es una auditoría que no se hizo.
Qué observar: toda la pila de la izquierda entra en el embudo: ninguna línea se salta la selección. Fíjate en que el único cuadro con brillo es TEST: es el destino predeterminado cuando no tienes evidencia, no una tercera vía para aplazar la decisión. Fíjate también en que diez categorías desembocan en seis salidas: el mapeo no es uno a uno, y suele ser la pregunta 3 (tema 3) la que decide hacia qué lado va la línea.
KEEP — se queda como está
Elige cuándo: sabes decir qué falla sin ella y ya viste que falla.
Típico de CONTEXTO, GUARDRAIL e INTEGRACIÓN. KEEP exige una justificación; si tu justificación es "mejor no tocarlo", la decisión correcta es TEST.
SIMPLIFY — la intención se mantiene, el volumen desaparece
Elige cuándo: la regla es válida, pero está escrita en tres párrafos con cuatro ejemplos.
Es la salida más común para un PROCEDIMIENTO REPETIBLE inflado y un MICROGERENCIAMENTO leve. La prueba: ¿puedes decirlo en una frase que un colega entendería?
MOVE — la regla es buena, el lugar es incorrecto
Elige cuándo: la instrucción solo se aplica a un tipo de tarea, pero está en el archivo que se lee en cada ejecución.
Del CLAUDE.md global por la del proyecto; del CLAUDE.md para una skill. Costo cero cuando la tarea no aparece.
MERGE — varias líneas, una intención
Elige cuándo: la misma idea aparece en fragmentos dispersos, a veces con pequeñas contradicciones.
Resultado natural de REDUNDANCIA. Al fusionar, elige explícitamente qué versión prevalece; si no, solo habrás reunido la contradicción en un mismo lugar.
TEST: elimínala en una ronda y observa
Elige cuándo: tú cree que ayuda, pero no puede citar un fallo real que haya evitado.
Es la salida honesta para AMBÍGUA/NO COMPROBADA y para buena parte del LEGADO. No borra nada ahora: programa una medición (el plan A/B/C de la Trilha 4).
ELIMINA — se quita, con el fragmento citado y el riesgo por escrito
Elige cuándo: la línea es un duplicado exacto, corrige un modelo que ya no usas o dirige un razonamiento que el modelo ya hace.
Cada eliminación viene acompañada de tres cosas: el fragmento, el riesgo y cómo probarla. Eliminar sin esas tres cosas es una conjetura con apariencia de método.
💡 La regla de oro de este módulo
Sin evidencia suficiente, prefiere TEST a KEEP.
Ninguna configuración se vuelve demasiado grande porque alguien haya decidido deliberadamente ampliarla. Crece porque, línea a línea,
mantenerla parecía más barato que verificarla. TEST es el antídoto: hoy no cuesta nada y la semana que viene convierte «me parece» en datos.
❓ Haz las 7 preguntas por instrucción
La categoría y la decisión no aparecen de la nada: surgen de siete preguntas planteadas en el mismo orden para cada instrucción. Hacer siempre las siete es lo que evita que la auditoría se convierta en una impresión. Y una de ellas —la tercera— suele resolver el caso por sí sola.
| # | Pregunta | Hacia dónde apunta la respuesta |
|---|---|---|
| 1 | ¿Qué intenta evitar o garantizar? | Si no puedes responder: AMBÍGUA → TEST. |
| 2 | ¿El modelo actual todavía la necesita? | Escrita para un modelo antiguo: LEGADO → TEST o REMOVE. |
| 3 | ¿Dice QUÉ debe ocurrir o intenta dirigir CÓMO piensa o ejecuta el modelo? | "Cómo" → MICROGERENCIAMENTO → SIMPLIFY. La más discriminante. |
| 4 | ¿Está duplicada en otro archivo? | REDUNDÂNCIA → MERGE o REMOVE. |
| 5 | ¿Limita la autonomía sin necesidad? | Cierra mejores caminos sin motivo → SIMPLIFY o REMOVE. |
| 6 | ¿Hay una forma más breve de preservar la intención? | Casi siempre sí → SIMPLIFY. |
| 7 | ¿Qué se rompe si desaparece? | Respuesta concreta → KEEP. Silencio o «no sé» → TEST. |
Por qué la 3 es la más discriminante. Las instrucciones que describen el resultado envejecen bien: «el build debe pasar» sigue siendo cierto con cualquier modelo. Las instrucciones que describen el proceso interno envejecen mal, porque se calibraron para una debilidad específica de una generación específica. Cuando llega un modelo mejor, la instrucción sobre «cómo» no queda neutral: se convierte en una grillete, impidiendo el mejor camino que el modelo ahora podría encontrar por sí solo. Aquí, autonomía es exactamente eso: el espacio que dejas para que el modelo elija la estrategia después de que tú hayas definido el objetivo.
✓ Dice QUÉ (envejece bien)
- ✓"El resultado tiene que funcionar offline: ninguna solicitud a un host externo."
- ✓"Antes de decir que terminaste, ejecuta las pruebas y pega la salida."
- ✓"Nunca hagas push con el autor incorrecto; comprueba
git config user.emailantes.» - ✓"Publicar = commit + push. El deploy es automático y no es tu responsabilidad."
✗ Dirige CÓMO (envejece mal)
- ✗"Primero lee el archivo, después enumera las funciones, luego elige una y edita."
- ✗"Piensa paso a paso y explica tu razonamiento antes de actuar."
- ✗"No uses más de dos herramientas por respuesta."
- ✗"Siempre vuelve a leer lo que escribiste dos veces antes de continuar."
🧾 Las 7 preguntas aplicadas a una línea real
FRAGMENTO «Antes de editar cualquier archivo, léelo completo,
enumera las funciones que encuentres, elige la función objetivo,
y solo entonces aplica la edición».
1 evita/garantiza? editar a ciegas un archivo que el agente no leyó
2 todavía hace falta? no: el modelo actual ya lee antes de editar
3 QUÉ o CÓMO? CÓMO ← decide el caso
4 duplicada? sí, ya existe una versión corta en la skill de refactor
5 limita la autonomía? sí: prohíbe editar directamente incluso cuando es obvio
6 forma más corta? «no edites un archivo que no hayas leído en esta sesión»
7 qué se rompe? no se observó nada en los últimos meses
CATEGORÍA MICROGESTIÓN
DECISIÓN SIMPLIFY (usar la forma de la pregunta 6)
🛡️ Protege lo que el modelo no infiere
Hay una clase de instrucción que tú nunca elimines por reflejo, por mucho
que el recorte parezca atractivo al contar líneas: aquello que el modelo no puede descubrir por sí solo.
Puede razonar; no puede adivinar que tu dominio es inema.club, que la fuente de verdad de los precios es una hoja de cálculo específica, o que tu empresa prohíbe enviar datos de clientes al exterior.
✓ Contexto que solo tú conoces: protegido
- ✓Identidad del proyecto: qué es, para quién y cuál es el nombre correcto.
- ✓Rutas de archivos: dónde está cada cosa en tu disco y en el repo.
- ✓Fuentes de verdad: qué archivo prevalece cuando dos no coinciden.
- ✓Branding: paleta, tono de voz, lo que nunca aparece en la marca.
- ✓Seguridad y cumplimiento: lo que no puede salir, lo que necesita aprobación.
- ✓Contratos de interfaz: formato del payload, nombres de campos, versiones.
- ✓Integraciones: qué servicio, qué credencial, qué límite de uso.
- ✓Convenciones internas: "aquí lo llamamos X", patrón de commit.
✗ Razonamiento genérico — el modelo ya lo hace
- ✗"Escribe código legible y con buenos nombres."
- ✗"Trata los errores y los casos límite."
- ✗"Divide los problemas grandes en partes más pequeñas."
- ✗"Explica qué hace una función antes de reescribirla."
- ✗"Considera las alternativas antes de elegir una."
- ✗"Usa buenas prácticas de seguridad en general."
- ✗"Verifica si la respuesta tiene sentido."
- ✗Una skill completa que enseña «cómo depurar un problema».
🧭 La prueba del colega nuevo
Imagina a un profesional competente que se incorporó hoy a tu equipo. Sabe programar, sabe escribir, sabe investigar, pero no conoce tu entorno. Toda instrucción que tendrías que darle porque no habría tenido cómo saberlo es contexto protegido. Toda instrucción que insultaría su inteligencia es candidata a ser recortada.
La pregunta 3 y esta prueba se apoyan: "lee el archivo antes de editar" ofende al nuevo compañero; "el CSS del curso viene
de assets/curso.css, «no repitas inline» es exactamente el tipo de cosa que agradecería saber desde el primer día.
⚠️ El error costoso de una ablación mal hecha
El fallo más costoso no es mantener una línea inútil, sino eliminar contexto irremplazable y descubrirlo solo tres semanas después, cuando el agente publicó en el repositorio equivocado, con el autor equivocado y siguiendo una convención que nadie más documentaba. Una línea inútil cuesta contexto; perder contexto cuesta retrabajo y confianza. Por eso el orden del curso es diagnóstico → propuesta → prueba, nunca elimines por impulso.
⚖️ Optimiza la función correcta
Aquí está la parte en la que casi todos se equivocan cuando descubren la ablación: el objetivo no es reducir al máximo. El objetivo no es una configuración de cero líneas. El objetivo es una proporción, y tiene tres elementos arriba y uno abajo.
Qué observar: es una fracción, no una meta de reducción. Las dos cajas rojas de abajo muestran las dos formas de equivocarse, y apuntan en direcciones opuestas. Fíjate que verificabilidad está en el numerador: agregar una instrucción de verificación aumenta el resultado, incluso si cuesta líneas, porque la ganancia de arriba es mayor que el costo de abajo. La ablación no es solo sustracción.
Calidad: ¿el resultado sirve?
El trabajo entregado cumple con lo que necesitabas, sin que tengas que corregirlo después. Se mide en correcciones humanas por tarea, no en sensaciones.
Autonomía — ¿cuánto resuelve sin ti?
Espacio para elegir la estrategia después de definir el objetivo. Una instrucción sobre «cómo» reduce la autonomía; un criterio de salida la preserva.
Verificabilidad — ¿puede revisar su propio trabajo?
Hay un comando, una prueba, una comparación que indica objetivamente «aprobado» o «no aprobado». Es el término que más gente olvida auditar —y el único que suele estar faltante en vez de sobrar.
Complejidad — el denominador
Líneas que se leen en cada ejecución, reglas que compiten entre sí, excepciones acumuladas, archivos que nadie entiende por completo. Cada línea del CLAUDE.md global se cobra en el 100% de las tareas, incluso en las que no tienen nada que ver con ella.
💡 Dos auditorías que reprueban
- "Recorté el 90% y el agente quedó perdido": el numerador también cayó. Eliminaste contexto irreemplazable o la única verificación que existía. Reprobado, aunque haya sido la mayor reducción del grupo.
- "No cambié nada, todo parecía importante": el denominador sigue inflado y no tienes ni un solo dato. También reprobado, solo que sin hacer ruido, que es como sobrevive el sedimento.
- Aprobado: menos líneas, la misma calidad medida en tareas reales, más autonomía y al menos una verificación objetiva donde antes no había ninguna.
🎯 Busca las señales en tu config
La teoría terminó. Ahora aplicas la taxonomía a tu propia config. Antes, la lista de búsqueda: los 13 patrones que aparecen en casi toda configuración acumulada. Revísala con el archivo abierto: cada elemento que reconozcas ya es un candidato con la categoría casi decidida.
Lista de verificación para detectar
CLAUDE.md y skillsMOVE🧪 Ejercicio: 15 líneas clasificadas
Objetivo: extraer 15 instrucciones reales de tu config y asignar una categoría y una decisión a cada una. Cópialo y ejecútalo en la terminal.
# 1) Extraia as instruções numeradas/bulletadas do CLAUDE.md global grep -n "^-\|^[0-9]\." ~/.claude/CLAUDE.md | head -40 # 2) Faça o mesmo no CLAUDE.md do projeto que você mais usa grep -n "^-\|^[0-9]\." ./CLAUDE.md | head -40 # 3) Tamanho de cada skill (skill grande demais é sinal do checklist) wc -l ~/.claude/skills/*/SKILL.md | sort -rn | head -15 # 4) Caça rápida a redundância: uma palavra-chave sua em toda a config grep -rn "commit\|deploy\|emoji" ~/.claude/CLAUDE.md ~/.claude/skills/ | head -20
Ahora completa esta tabla con 15 líneas. Una instrucción por línea, sin agrupar.
| Fragmento | Categoría | Decisión | Pregunta decisiva | Qué se rompe si desaparece |
|---|---|---|---|---|
| "Sin emoji en la salida" | REDUNDANCIA | MERGE | 4 — duplicada | nada: se queda en la versión fusionada |
| "Primero lee, después enumera, después…" | MICROGESTIÓN | SIMPLIFY | 3 — dirige el CÓMO | nada observado |
"Las API keys están en ~/projetos/wifi/.env" | INTEGRACIÓN | KEEP | 7 — falla de inmediato | el agente le pide la key al usuario |
| "Ten cuidado y piensa bien" | AMBIGUA | TEST | 1 — sin una intención clara | desconocido; por eso hay que probar |
| … | … | … | … | … |
Criterio de salida: 15 líneas completadas,
todas con categoría e decisión, y al menos una en TEST.
Por qué el requisito del TEST:
si las 15 resultaron KEEP, lo más probable no es que tu configuración sea perfecta, sino que la clasificaste según tu comodidad. Vuelve a las preguntas 1 y 7: si no puedes decir qué evita la línea ni qué se rompe sin ella, no es KEEP.
Revisión rápida (no bloquea nada): encuentras una línea que dice "siempre vuelve a leer el archivo dos veces antes de editarlo". No recuerdas ningún fallo que haya evitado. ¿Cuál es la combinación de categoría y decisión más defendible?
Conceptos clave
¿No puedes elegir? Estás haciendo dos cosas
QUÉ envejece bien, CÓMO envejece mal
Sin evidencia, programa la medición
El único elemento que se resuelve agregando
📌 Resumen del Módulo
Próximo módulo:
2.2 — De la microgestión al criterio y la verificación: cómo reescribir «haz A, luego B, luego C» como objetivo, guardrails, criterio de salida y una forma real de comprobarlo.