🔀 Separa auditar de aplicar
La skill audit-ablacao es diagnóstico: lee, clasifica y propone, y nunca edita, mueve, borra ni hace commit. Esto no es una limitación, es una decisión de diseño. Aplicar es un solicitud aparte, en otra sesión — por dos motivos. Primero: hacer el diagnóstico al mismo tiempo que se trabaja en el teclado lo contamina la prisa por cambiar; empiezas a justificar el recorte que ya quieres hacer. Segundo: el informe debe seguir existiendo intacto después, para que verifiques si lo aplicado es realmente lo recomendado. Una auditoría que ya empieza haciendo cambios es una auditoría en la que no confías.
🆕 Dos palabras antes de continuar
- Skill: una carpeta con un archivo
SKILL.mdque enseña a Claude Code un procedimiento específico. Solo se carga cuando la tarea es esa, a diferencia deCLAUDE.md, que siempre se lee. - Contexto: la ventana de texto que el modelo está «viendo» en esa ejecución. Todo lo que ocupa contexto —incluso una regla que no tiene nada que ver con la tarea— es espacio que se le quita al trabajo de verdad.
- Snapshot: una copia congelada del estado actual de tu configuración, a la que puedes volver con un comando. Un commit de git es el snapshot más barato que existe.
⚠️ Nunca recortes sin una instantánea
La ablación solo es un método porque es reversible. Si no puedes volver atrás con un comando al estado anterior, no estás haciendo un experimento: estás cruzando los dedos. Y la primera vez que un recorte rompa algo sin posibilidad de volver atrás, abandonarás todo el proceso y nunca más tocarás la configuración.
Regla estricta: no sale ninguna línea antes de que exista el commit "antes". Sin git, como mínimo un cp -r ~/.claude ~/.claude.bak-AAAA-MM-DD.
Poner la configuración bajo git lleva treinta segundos y te sirve durante todo el módulo 4, cuando compares las versiones A, B y C. Hazlo en la carpeta de la configuración global (~/.claude) o en la raíz del proyecto, según el alcance que hayas auditado.
📦 Copiar y ejecutar: configuración bajo git
Objetivo: tener un punto de retorno con nombre antes de cualquier recorte.
# escopo global — a pasta de config do Claude Code cd ~/.claude git init -b main # so na primeira vez git add -A git commit -m "antes da ablacao" # escopo projeto — a config que anda com o repo # cd ~/projetos/<seu-projeto> # git add CLAUDE.md .claude/ # git commit -m "antes da ablacao"
Cómo verificar: ejecuta git status. Si la salida dice nothing to commit, working tree clean, tienes un punto de retorno. Prueba la vuelta antes de necesitarla: git diff después de un recorte muestra exactamente qué se quitó, y git checkout -- CLAUDE.md deshace.
✓ Sesión de aplicación saludable
- ✓Sesión nueva, con el informe en
.mdabierto al lado - ✓Commit «antes» ya hecho y
git statuslimpio - ✓Un cambio a la vez, con el fragmento del informe pegado en la solicitud
- ✓El informe permanece intacto: es la prueba de lo que se decidió
✗ Señales de que saldrá mal
- ✗"Ya que estás aquí, aplica todo" en la misma sesión de la auditoría
- ✗Configuración fuera de git, «después la versiono»
- ✗Diez cambios en un solo commit: si algo se rompe, no sabes cuál fue
- ✗Informe sobrescrito por la propia sesión que aplicó los recortes
🎯 Ataca en el orden correcto
La sección 10 del informe presenta el Top 10 según impacto ÷ riesgo — los cambios que devuelven más contexto con el menor riesgo de romper el comportamiento. Pero no es una lista para que la recorras de arriba abajo en un solo día. El orden práctico depende de categoría de riesgo, en cuatro oleadas, y existe para generar confianza en el proceso antes de que te acerques a lo que da miedo.
Ola 1 — Redundancias y conflictos
Riesgo casi nulo. Beneficio inmediato.
La misma regla escrita en tres lugares se convierte en una sola; dos reglas que se contradicen se convierten en una decisión. No estás eliminando comportamiento: estás eliminando copias. Nadie pierde nada y la configuración se reduce visiblemente desde el primer día. Además, se acaba eso de que una copia cambie y las demás no.
Ola 2 — Legado / obsoleta
Riesgo bajo, pero requiere una comprobación.
Instrucciones con fecha: reparación de una debilidad de un modelo que ya dejó de usarse, excepción de 2024, solución provisional para un error ya corregido. La comprobación es sencilla: ¿el motivo original sigue existiendo? Si no puedes nombrar el motivo, es un indicio claro de que ya desapareció.
Ola 3 — Microgestión → criterio
Riesgo medio: cambias la forma, no eliminas la intención.
El rígido paso a paso de doce etapas se convierte en «tarea + guardrails + criterio de salida». La intención se conserva por completo; lo que devuelves es la libertad de que el modelo encuentre un camino mejor que el tuyo. Aquí ya conviene observar el comportamiento durante algunos días antes de darlo por bueno.
Ola 4 — Lo que quedó en TEST
Riesgo desconocido; por eso es la última.
TEST es la decisión que toma la skill cuando tiene dudas: puede ser peso muerto o puede estar sosteniendo algo. No se aplican por convicción, sino mediante experimentos; y el experimento es el plan A/B/C de la Trilha 4. Posponer esta ronda no es cobardía, es seguir la secuencia.
💡 Por qué empezar por el riesgo casi nulo
La tentación es empezar por el recorte más grande: ese bloque de 80 líneas que siempre te pareció inútil. Es el recorte heroico, y es la trampa clásica: algo se rompe, no sabes cuál de las 80 líneas era necesaria, reviertes todo y concluyes que «la configuración estaba bien como estaba».
- •Las olas 1 y 2 te dan días de evidencia de que recortar no rompe nada — eso es lo que te da la confianza para las olas 3 y 4
- •Los cambios pequeños y separados por commit dejan claro quién es el culpable cuando algo cambia de comportamiento
- •No buscamos maximizar la reducción; el objetivo es calidad + autonomía + verificabilidad ÷ complejidad
| Ola | Categoría | Riesgo | Cómo confirmar que funcionó | Cuándo aplicar |
|---|---|---|---|---|
| 1 | Redundancia / conflicto | casi cero | la regla sigue existiendo, en un solo lugar | primera sesión |
| 2 | Legado / obsoleta | bajo | no puedes nombrar el motivo original | primera sesión |
| 3 | Microgestión → criterio | medio | el resultado sigue cumpliendo el nuevo criterio | después de días de uso real |
| 4 | TEST | desconocido | solo mediante un experimento A/B/C | ruta 4 |
📦 Mueve el procedimiento a una skill
Este es el argumento central del módulo. Una regla que vive en el CLAUDE.md se lee en cada ejecución — incluso en el ~90% de las tareas que no tienen nada que ver con ella. La misma una regla dentro de una skill solo consume contexto cuando la tarea es esa. Esto es load-on-demand: cargar bajo demanda, en vez de siempre. Mover el procedimiento de CLAUDE.md para una skill es la forma más barata de aligerar la config sin perder nada — es exactamente lo que el informe llama MOVE y de LOAD-ON-DEMAND.
Qué observar: el bloque morado no desapareció: se encogió y el resto se convirtió en el bloque cian, que aparece una vez en vez de diez. No se perdió ninguna instrucción; lo que cambió fue cuántas veces pagas por ella. Por eso MOVE suele rendir más que REMOVE en las primeras oleadas: aligeras sin tener que decidir si algo es prescindible.
🧪 Copiar y ejecutar: crear la skill y recortar el bloque
Objetivo: retirar un procedimiento de CLAUDE.md y ponerlo en una skill que solo se carga cuando se invoca.
# 1. criar a pasta da skill (global; use .claude/skills/ para so o projeto) mkdir -p ~/.claude/skills/<nome-da-skill> # 2. escrever o SKILL.md — o frontmatter e o bloco YAML entre --- no topo, # que da nome e descricao a skill (e o que o Claude Code le pra saber que ela existe) cat > ~/.claude/skills/<nome-da-skill>/SKILL.md <<'EOF' --- name: <nome-da-skill> description: <quando usar, em uma frase, com as palavras que voce realmente usa> --- # <Nome da skill> <cole aqui o bloco procedimental que estava no CLAUDE.md, sem mudar nada> EOF # 3. remover o bloco do CLAUDE.md (agora ele vive na skill) # edite o arquivo e apague as linhas movidas — deixe UM ponteiro curto se precisar: # "Procedimento de <assunto>: /<nome-da-skill>" # 4. registrar o antes/depois wc -l ~/.claude/CLAUDE.md git -C ~/.claude add -A && git -C ~/.claude commit -m "move: <assunto> do CLAUDE.md para skill"
Cómo verificar: reinicia la sesión, llama a /<nome-da-skill> y confirma que el procedimiento responde igual que antes. Después ejecuta una tarea que no es esa y confirma que el comportamiento tampoco cambió: eso es lo que demuestra que lo moviste y no lo perdiste.
Cuidado con el puntero: si el "puntero corto" en el CLAUDE.md empezar a crecer y volver a explicar el procedimiento, habrás recreado el problema. Una línea, como máximo — o ninguna, si piensas invocarlo directamente (tema 4).
✓ Se queda en CLAUDE.md — verdad SIEMPRE
- ✓Identidad — qué es este proyecto, quién es el público, cuál es el dominio
- ✓Guardrails — qué nunca hacer, límites que aplican a cualquier tarea
- ✓Fuentes de verdad — dónde están las claves, los datos, el archivo canónico
- ✓Seguridad y cumplimiento — qué no puede filtrarse, qué no puede publicarse
- ✓Convenciones internas que el modelo no puede inferir por sí solo
✗ Sale de CLAUDE.md — se convierte en skill
- ✗Procedimiento — "para hacer X, sigue estos pasos"
- ✗Formato — modelo de salida, estructura de documento, plantilla
- ✗Receta — secuencia de comandos de deploy, publicación, build
- ✗Integración — cómo hablar con una API/herramienta específica
- ✗Enrutamiento — "cuando pida X, usa la skill Y" (consulta el tema 4)
⌨️ Llama a la skill directamente
Una skill normalmente se activa por disparador — el modelo compara tu frase con el campo description del frontmatter y decide si esa skill aplica. Funciona, pero es una lotería: si escribiste "guía" y la descripción dice "landing page", la skill no se activa. Invocación explícita (/nome-da-skill) elimina por completo la lotería: dejas de depender de que la descripción coincida con tu frase.
💡 La invocación explícita anula la regla de enrutamiento
Cuando varias skills compiten por el mismo tema, el impulso es escribir en el CLAUDE.md: "cuando te pida una guía, usa la skill X, no la Y". Esa línea es otra línea zombi: se lee en cada ejecución y solo existe para desempatar un caso raro. La invocación explícita resuelve el empate y es gratis: escribes /x y se acabó la discusión.
- •Cada regla de enrutamiento que eliminas es contexto que recuperas en todas las ejecuciones
- •Si tú sabe lo que quieres; decir el nombre siempre es más barato y preciso que describir
- •El activador sigue siendo útil para cuando tú no sabe que la skill existe — pero no hace falta reforzarlo con una regla global
Dónde vive la skill también importa. Skill en ~/.claude/skills/ se aplica a todo lo que haces; skill en .claude/skills/ dentro del proyecto se versiona junto con el código. Esto cambia el régimen de mantenimiento: el procedimiento acompaña al repo, entra en el pull request, otra persona puede revisarlo y, algo crucial, no se filtra a los demás proyectos. Una receta de deploy específica del proyecto A no tiene por qué ocupar contexto cuando trabajas en el proyecto B.
| Dónde vive la instrucción | Costo de contexto | Alcance | Revisable en PR |
|---|---|---|---|
~/.claude/CLAUDE.md | cada ejecución, en todos los proyectos | todo | no |
CLAUDE.md del proyecto | cada ejecución en ese proyecto | el proyecto | sí |
~/.claude/skills/ | solo cuando se invoca/activa | todo | no |
.claude/skills/ del proyecto | solo cuando se invoca/activa | el proyecto | sí |
Conceptos clave
La descripción coincide con tu frase, o no
/nome — sin lotería
El enrutamiento en CLAUDE.md es una de ellas
Versiona en el repo, no lo filtres
💊 Elige el remedio adecuado
Cuando el modelo tropieza, el impulso es añadir una regla más al CLAUDE.md. En el ciclo de Boris hay tres soluciones, y elegir la correcta es lo que impide que la configuración vuelva a engordar: prompt mejor (la instrucción era confusa) · skill (falta un procedimiento repetible) · MCP (falta contexto o acceso al que no puede llegar). MCP es el protocolo mediante el cual Claude Code se comunica con una fuente externa — una base de datos, una API, un sistema de archivos remoto — que no podría ver por su cuenta.
Qué observar: ninguno de los cuatro caminos termina en "escribe una línea más en el CLAUDE.md". Y fíjate en la rama cian de la izquierda: un fallo que ocurrió una vez no es ningún remedio: la regla de reintroducción exige esperar a que la misma falla se repita antes de devolver cualquier instrucción. La mitad de las líneas zombi de una configuración surgieron de un tropiezo aislado.
Tropiezo → mejor prompt
Pediste "mejora este texto" y recibiste una reescritura completa que perdió tu tono. El modelo no se equivocó: "mejorar" no significa nada específico. La solución está en la solicitud — "corrige la gramática y elimina redundancias, conservando las elecciones de palabras" — no en la config. Una instrucción poco clara que se corrige con una regla global se convierte en una regla global poco clara.
Tropiezo → skill
Cada vez que publicas un proyecto, tienes que recordarle al modelo la misma secuencia: guía en guia/, nunca en la raíz; el nombre del repo = el nombre de la carpeta; Pages mediante Actions. Es la tercera vez que lo explicas. Es un procedimiento repetible con un alcance claro: se convierte en una skill, y la invocas /publicar cuando hace falta.
Tropiezo → MCP
Pides un análisis de las solicitudes del último trimestre y el modelo inventa números plausibles. Ninguna regla resuelve esto, porque el problema no es el comportamiento — es que los datos están en una base de datos a la que no puede acceder. La solución es darle acceso (un servidor MCP para la base de datos), no escribir "no inventes datos" en el CLAUDE.md.
🧹 La Skill es fácil de auditar y de retirar
Una skill tiene límite, nombre y alcance. Eso significa que es una unidad que puedes sostener con las manos: puedes cambiarle el nombre a la carpeta, pasar una semana sin ella y medir si algo empeoró. Es una ablación a escala de una unidad completa.
Desactivar «ese párrafo del medio de CLAUDE.md" es mucho más difícil: no tiene nombre, no tiene límites claros, no sabes qué tareas dependían de él y nada te avisa cuando desaparece. Por eso, la misma instrucción, dentro de una skill, es más barata de mantener — no solo más barata de ejecutar.
Revisión rápida (no bloquea nada): por tercera semana consecutiva, vuelves a explicarle al modelo la misma secuencia de 8 pasos para publicar un proyecto. ¿Cuál es el remedio adecuado?
🛠️ Aplica tus 3 primeros cambios
El ejercicio de este módulo es breve y concreto: aplicar las 3 primeros cambios del Top 10 de tu informe, en una sesión nueva, con la configuración bajo git, y al menos una de ellas siendo un MOVE del bloque procedimental de CLAUDE.md para una skill. Un cambio por commit. Registra el antes y el después con dos métricas: número de líneas y número de reglas.
📏 Copiar y ejecutar: medir antes y después
Objetivo: tener un número, no una impresión. «Quedó más conciso» no es un registro.
# ANTES de aplicar qualquer coisa wc -l ~/.claude/CLAUDE.md grep -c '^[-*] ' ~/.claude/CLAUDE.md # aproximacao do numero de regras (bullets) git -C ~/.claude log --oneline -1 # confirma o commit "antes da ablacao" # ... aplique UMA mudanca, commite, repita ... # DEPOIS das 3 mudancas wc -l ~/.claude/CLAUDE.md grep -c '^[-*] ' ~/.claude/CLAUDE.md git -C ~/.claude diff --stat "antes da ablacao"..HEAD ls ~/.claude/skills/ # a skill nova esta la?
Cómo verificar: git diff --stat te da el número exacto de líneas eliminadas y agregadas, y en un MOVE bien hecho, ves líneas saliendo del CLAUDE.md e entrando en el SKILL.md, casi en la misma cantidad. Esa es la señal de que moviste contenido, en vez de borrarlo por error.
📋 Copiar y pegar: la solicitud de aplicación
Objetivo: pedir una cambio específico, con el fragmento del informe pegado; nunca «aplica el informe».
Sessao de APLICACAO (a auditoria ja foi feita e esta salva em relatorio-ablacao.md — nao rode auditoria de novo, nao releia tudo). Aplique EXATAMENTE UMA mudanca, esta: <cole aqui o trecho do relatorio> Regras desta sessao: - Nao aplique nada alem do que esta no trecho acima. - Nao "aproveite pra melhorar" outras partes do arquivo. - Se for um MOVE: crie ~/.claude/skills/<nome>/SKILL.md com frontmatter (name, description) e mova o bloco INTEGRAL, sem reescrever o conteudo. - Remova do CLAUDE.md exatamente as linhas movidas. - No fim, mostre: (a) o diff, (b) wc -l do CLAUDE.md antes e depois, (c) uma frase dizendo o que EU devo testar pra confirmar que nada mudou. - Nao commite: eu commito depois de ler o diff.
Por qué «no hagas commit»: el commit es tu punto de decisión. Leer el diff antes de hacer el commit es el único momento en que comparas lo que pidió con qué ocurrió — y es exactamente ahí donde aparece la reescritura silenciosa de un bloque que pediste mover sin cambiar.
✓ Criterio de salida de este módulo
- ✓Commit (o snapshot) "antes" e "después" existen y son localizables
- ✓
CLAUDE.mdmenor — con el número, no con la impresión - ✓La nueva skill responde a la invocación directa
/<nome> - ✓El comportamiento de la tarea correspondiente no cambió
✗ No cuenta como completado si
- ✗Los 3 cambios quedaron en un solo commit
- ✗El bloque movido se "mejoró" en el proceso; así cambiaste dos cosas a la vez
- ✗La skill existe, pero nunca la invocaste para comprobar que responde
- ✗Mediste "parece más ligero" en vez de
wc -l
📌 Resumen del Módulo
TEST. Empezar por el riesgo casi nulo evita el recorte heroico que hace que te rindas.MOVE es la herramienta principal — regla en el CLAUDE.md se lee en cada ejecución; la misma regla dentro de una skill solo consume contexto cuando la tarea corresponde./nome-da-skill desempata sin costar una línea global. Una skill de proyecto se versiona en el repo y no se filtra.CLAUDE.md"; y un fallo que ocurrió una vez todavía no es ningún remedio.CLAUDE.md — solo lo que siempre es verdad: identidad, guardrails, fuentes de verdad, seguridad. Todo lo demás es una skill.Próximo módulo:
4.1 — El plan de ablación A/B/C: demostrar mediante pruebas, en tareas reales, que la versión mínima no perdió calidad.