🔍 Reconoce la especificación excesiva
Boris Cherny describe la especificación excesiva — escribir la secuencia exacta de movimientos que debe hacer el modelo — como uno de los errores más comunes que ve. Y el detalle incómodo: es más frecuente en quienes tienen años o décadas de ingeniería, no menos. Cuanto más experiencia tiene el autor de la config, más guionizada tiende a ser.
El motivo es histórico. El software se construía diseñando todo el sistema de antemano, escribiendo una enorme suite
de pruebas unitarias y tratando una re-arquitectura como un proyecto de meses o años. Ese reflejo —decidirlo todo antes,
sobre el papel— se convirtió en la forma de escribir CLAUDE.md. Con los modelos antiguos funcionaba:
necesitaban que alguien los guiara en cada paso. Hoy, el guion hace lo contrario de lo que quieres: le impide al
modelo encontrar un camino mejor que el que imaginaste.
🆕 Cuatro palabras que aparecerán durante todo el módulo
- Guardrail: un límite que no se puede cruzar: “nunca hagas commit sin ejecutar las pruebas”, “no toques en
node_modules/”. Dice qué está prohibido, no cómo hacerlo. - Criterio de salida: la frase que permite al modelo saber que terminó. «Listo cuando el build pasa y el archivo existe» es un criterio; «listo cuando quede bien» no lo es.
- Verificación: la forma concreta en que el modelo comprobar por tu cuenta si se cumplió el criterio de salida — un comando, una prueba, una comparación de archivos, una captura de pantalla.
- Autonomía: el permiso explícito para que el modelo elija la estrategia de ejecución, siempre que respete los guardrails y cumpla el criterio.
Qué observar: a la izquierda hay una sola ruta, y es la ruta que tú imaginó. Si hay un camino mejor, el carril lo prohíbe — y el modelo obedece. A la derecha no se guionizó nada: las barreras son los guardrails (lo que no se puede hacer), el portón es el criterio de salida (cuándo terminó) y el núcleo es libre. Las tres flechas muestran la ganancia concreta: el modelo puede elegir la ruta más corta para el problema real de hoy, que no necesariamente es la que escribiste hace meses.
✗ Señales de especificación excesiva
- ✗“Primero ejecuta
git status, despuésgit diff, después lee el archivo, después…” - ✗Numeración de 8 a 12 pasos para una tarea que cabe en dos frases
- ✗“Usa la herramienta X, nunca la Y” sin decir por qué (el porqué es lo que envejece)
- ✗Excepciones apiladas: «excepto si…, pero si…, a menos que…»
- ✗Instrucción que enseña al modelo a pensar (“analiza con cuidado antes de responder”)
✓ Lo que sobrevive a la auditoría
- ✓“El deploy se realiza mediante un push en git; el webhook se encarga del resto.” — contexto que el modelo no infiere
- ✓“Nunca imprimas el valor de una API key.” — guardrail de seguridad
- ✓“Las keys están en
~/projetos/wifi/.env.” — fuente de verdad, ruta concreta - ✓“Está listo cuando
npm run buildtermina con el código 0.” — criterio verificable - ✓“Elige la estrategia de ejecución.” — autonomía declarada
Conceptos clave
La secuencia exacta de movimientos
Diseñar todo de antemano, en papel
Bloquea el mejor camino
Más común en veteranos
🔄 Convierte la receta en criterio
Hay una conversión canónica, y cabe en una línea. Toda instrucción en la forma “haz A, luego B, luego C” se convierte en: “Produce X. Respeta Y. El resultado debe alcanzar Z. Verifica usando W. Elige la estrategia.” Cinco espacios. X es el objetivo, Y son las reglas de protección, Z es el criterio de salida, W es la verificación, y la última frase es la autonomía.
🎯 La frase modelo
Produce X. Respeta Y. El resultado debe alcanzar Z. Verifica usando W. Elige la estrategia.
Si no puedes completar W, detente: todavía no tienes una instrucción, tienes un deseo. La ausencia de W es el defecto más común en las configuraciones que encuentra la auditoría.
Un caso real: regla de publicación con pasos definidos
A continuación, una regla de publicación escrita como casi todo CLAUDE.md real
escribe: ocho pasos, orden fijo, un comando por línea. Funciona, pero ata al modelo a una secuencia que ya
no es la mejor (y que falla en el primer proyecto que tiene un paso más).
✗ ANTES: 8 pasos, 14 líneas
## Publicação 1. Rode `git status` e verifique se há mudanças. 2. Rode `git diff` e leia tudo o que mudou. 3. Rode `git log -5` para ver o estilo das mensagens anteriores. 4. Rode `git config user.email` e confira se é o autor certo. 5. Se estiver errado, rode `git config user.email`. 6. Faça `git add` só dos arquivos que você editou (nunca `git add .`). 7. Escreva a mensagem de commit no padrão `tipo: descrição`. 8. Rode `git push` e depois confira no dashboard se o deploy subiu.
✓ DESPUÉS: 4 líneas de criterio
## Publicação Objetivo: publicar = commit + push no `origin`. O deploy é automático; não é sua responsabilidade. Guardrails: nunca `git add .`; o autor do commit acompanha a conta de destino do repo (default `inematds`). Critério de saída: o commit está em `origin` e a mensagem segue `tipo: descrição`. Verificação: `git log origin/main -1` mostra o seu commit com o autor esperado.
Lo que realmente cambió: los pasos 1–3 desaparecieron porque el modelo ya sabe inspeccionar un repositorio — eran puro micromanagement. Los pasos 4–5 se convirtieron en un guardrail (la regla, no el procedimiento). Los pasos 6–7 se convirtieron en guardrail y criterio. Y el paso 8 — “revisa el dashboard” — se convirtió en una verificación ejecutable: un comando que da la respuesta sin depender de que alguien abra un sitio web.
💡 La prueba del bisturí
Para cada paso numerado de la instrucción, pregunta: “¿esto es una regla que siempre se aplica o es un movimiento que el modelo elegiría por sí solo?” La regla se convierte en guardrail. El movimiento se convierte en nada: se borra. Lo que queda suele ser el 20–30 % del original, y es exactamente la parte que el modelo no podía adivinar.
🧱 Usa la plantilla de 6 campos
La frase modelo del tema anterior, extendida, se convierte en una plantilla de seis campos:
Objetivo · Contexto · Guardrails · Criterios de calidad · Verificación · Autonomía.
No es burocracia: cada campo existe porque su ausencia produce un tipo específico de fallo. Esto aplica a prompts
puntuales y a bloques de CLAUDE.md y para el cuerpo de una skill.
Objetivo: el resultado, no el camino
Una frase que diga qué debe existir al final.
Error típico: describir la actividad («revisar el código») en lugar del resultado («un informe con los errores de corrección encontrados en el diff»).
Contexto — solo lo que no puede descubrir por sí solo
Rutas, nombres de sistemas, fuentes de verdad, convenciones internas.
Error típico: volcar el historial del proyecto. El contexto es una dirección, no una biografía. Si el modelo puede leer el archivo, indica dónde está en vez de resumirlo.
Guardrails — lo prohibido, en forma negativa
Seguridad, cumplimiento, contratos de interfaz, lo que nunca se puede tocar.
Error típico: disfrazar un procedimiento de guardrail. «Ejecuta siempre el lint antes del build» no es un límite: es un paso. El límite es «no hagas commit si el lint falla».
Criterios de calidad — qué significa «quedó bien»
Preferiblemente cuantificables: número máximo de líneas, formato de salida, cobertura, tono.
Error típico: adjetivos por sí solos — “claro”, “profesional”, “bien escrito”. Un adjetivo sin un punto de referencia no decide nada y el modelo lo completa con su propia suposición.
Verificación — cómo revisa por sí mismo
Un comando, una prueba, una comparación, una comprobación de archivo. Con una condición para detenerse.
Error típico: el campo simplemente no existe. Es el campo más ausente y el de mayor impacto: el tema 4 trata íntegramente sobre él.
Autonomía — el permiso explícito
“Elige la estrategia de ejecución.” Una línea, y cambia el comportamiento.
Error típico: creer que es redundante. Sin esta línea, una configuración llena de reglas antiguas todavía empuja al modelo al modo «sigue el guion».
📋 Plantilla lista para copiar y pegar
Copia y cambia lo que está entre < > y elimina los campos que no aplican, excepto el de Verificación, que nunca se quita.
## <nome da tarefa> **Objetivo:** <o resultado que deve existir no final, em uma frase> **Contexto:** <caminhos, sistemas e convenções que o modelo não descobre sozinho> **Guardrails:** - <o que nunca pode acontecer> - <limite de segurança / compliance / interface> **Critérios de qualidade:** - <algo contável: tamanho, formato, cobertura> - <algo observável: tom, estrutura, nomes> **Verificação:** <comando, teste ou comparação que prova o critério>. Repita produzir → verificar até <condição de parada explícita>. **Autonomia:** escolha a estratégia de execução; não peça confirmação para decisões cobertas pelos guardrails acima.
💡 Consejo: la plantilla es una guía, no un formulario
No necesitas los seis títulos literales en la config. Necesitas que los seis existan en algún lugar. Usa la
plantilla para auditar una instrucción: léela y marca cuáles de los seis campos cubre. Una instrucción
que solo cubre “el camino” y ninguno de los seis es candidata directa a REMOVE o
SIMPLIFY en la taxonomía del módulo 2.1.
🔬 Instala la verificación (la palanca)
Le preguntaron a Boris qué habilidad importa ahora que “prompt engineering” perdió fuerza como puesto. La respuesta: darle al modelo una tarea que parezca un poco demasiado difícil, y hacer posible que verifique su propio trabajo a lo largo del proceso. Llamó a la verificación «lo más importante que la gente no logra hacer bien». En términos de este curso: un prompt corto con una forma real de comprobarlo es mejor que uno enorme sin ninguna.
El ejemplo de Electron → Swift
Boris quiso saber cómo sería la app de escritorio de Claude —hecha en Electron— si se convirtiera en una app nativa. Conectó un runner de macOS (una máquina virtual Mac), creó un repositorio vacío y le dio una única instrucción: reescribe la app Electron en Swift, ejecuta la original en la VM, toma capturas de pantalla, compáralas píxel por píxel con la versión Swift y no pares hasta terminar. En la fecha de la charla, la tarea llevaba más de dos semanas en marcha y había creado desde miles hasta decenas de miles de agentes. El prompt no tenía ninguna técnica. Tenía un ciclo de verificación completo.
Qué observar: la flecha cian de retorno. Casi todo el mundo escribe los tres primeros cuadros; lo que falta es el retorno y el cuadro resaltado. Sin una condición de parada explícita, el ciclo no es un ciclo: es una línea recta que termina con la primera entrega. Y fíjate en que observar es la caja que exige un recurso del mundo real (la VM, el comando, el archivo). Verificar sin observación externa es solo el modelo releyéndose a sí mismo.
Cuatro verificaciones objetivas, en contextos diferentes
1. Prueba que se ejecuta
“Está listo cuando pytest tests/test_parser.py pasa completo. Si falla, corrige y vuelve a ejecutarlo”. Observación externa: el resultado de la prueba. Se detiene: cero fallas.
2. Comando cuyo código de salida lo demuestra
“Ejecuta npm run build; considéralo terminado solo con el código de salida 0». Observación externa: el código de salida. Parada: 0. No hay margen para interpretaciones.
3. Comparación de archivos
“Genera el CSV y ejecuta diff saida.csv esperado.csv; repite hasta que el diff quede vacío». Observación externa: el archivo de referencia. Parada: diff vacío.
4. Captura de pantalla / comparación visual
“Abre la página, toma una captura de pantalla, compara con referencia.png; corrige hasta que la diferencia sea inferior al 2%.» Observación externa: la imagen renderizada. Parada: el umbral.
⚠️ Por qué «revisa antes de entregar» NO es verificación
Es la línea más común en configuraciones reales y no verifica nada. Faltan las dos piezas que hacen funcionar el mecanismo:
- ✗No hay observación externa. El modelo vuelve a leer su propio texto en el mismo contexto que lo produjo: el razonamiento que generó el error sigue ahí, empujando hacia el «está bien».
- ✗No hay condición de parada. “Revisa” ocurre una vez y se acabó. No hay ningún criterio que indique si la revisión fue suficiente, así que nunca hay una segunda vuelta.
Corrección: cámbialo por «ejecuta <comando>; mientras lo repruebe, corrígelo y vuelve a ejecutarlo». La
frase tiene el mismo tamaño, pero el mecanismo es completamente distinto.
Los cuatro momentos, en orden
Producir
Generar la salida. Es el único momento que todas las configs ya tienen.
Observar
Mirar algo fuera del propio texto: ejecutar un comando, abrir un archivo, tomar una captura de pantalla.
Comparar
Contrastar el resultado con la referencia y emitir un veredicto: pasó o no pasó.
Condición de parada
La frase que cierra el ciclo. «No pares hasta terminar», «hasta que el diff quede vacío», «hasta que el exit code sea 0».
🚀 Apunta por encima del límite
La recomendación de Boris es apuntar más alto de lo que parece cómodo: dale al modelo una tarea un poco más difícil de lo que crees que puede manejar. El motivo es simple: el límite cambia con cada lanzamiento. Tu estimación de «lo que puede hacer» se calibró con una generación anterior y no te diste cuenta de que quedó desactualizada, porque nadie te avisa cuando sube el límite.
La consecuencia directa para la auditoría: vuelve a probar tus fallos antiguos con cada versión nueva. Esa regla que escribiste porque «siempre se equivoca en eso» puede estar protegiendo contra una falla que ya no existe. Sigue costando contexto en cada ejecución, y el motivo desapareció sin aviso. Es exactamente el mecanismo del módulo 1.1: una instrucción es la solución a la debilidad de un modelo específico.
🧬 Ciencia empírica, no teórica
Trabajar con un modelo se parece más a conocer a una criatura viva que a configurar un sistema.
Cada generación se comporta de una manera y tiene una personalidad ligeramente distinta. Pasas un tiempo aprendiendo cómo funciona y luego ajustas el harness — el conjunto de prompts, herramientas y reglas alrededor del modelo — a partir de lo que observaste. Fíjate en el orden: observar primero, escribir la regla después. Lo contrario de esto es teoría, y la teoría sobre modelos envejece en semanas.
💡 El criterio del compañero de trabajo
El nivel adecuado de instrucciones es el mismo que usarías para orientar a un colega competente: contexto, objetivo, los límites que no puede adivinar y cómo saber que terminó. No le escribirías a un colega: «abre el editor, haz clic en archivo, escribe el nombre». Si tu instrucción no pasaría la prueba de leerse en voz alta ante una persona sin sonar ofensiva, es microgestión.
✓ Enfoque empírico
- ✓Pídele una tarea que supere lo que espera y observa dónde se atasca
- ✓Guarda los fracasos anteriores y vuelve a ejecutar con cada modelo nuevo
- ✓Corrige la dificultad específica observada: nada más que eso
- ✓Elige el remedio correcto: mejor prompt, skill o MCP
✗ Postura teórica
- ✗Asume el límite de la generación anterior y nunca vuelve a probar
- ✗Escribe reglas preventivas para fallas que nunca viste ocurrir
- ✗Corrige «en el área»: tres párrafos nuevos por un error puntual
- ✗Busca el truco secreto en un influencer de redes sociales
🔁 No hay ningún truco secreto: hay un ciclo
Le preguntaron a Boris qué separa al 1% de los mejores usuarios de Claude Code. La respuesta fue: deja de buscar un truco. Este es el método, y es público:
1. tarefa difícil demais
2. meios de verificar o trabalho
3. observar onde ele trava
4. corrigir AQUILO → prompt melhor (instrução obscura)
→ skill (falta procedimento repetível)
→ MCP (falta contexto que ele não alcança)
5. repetir
El paso 4 es donde la mayoría se equivoca: ante un tropiezo, el reflejo siempre es «una regla más en el
CLAUDE.md”. Tres causas, tres remedios diferentes, y solo uno de ellos consiste en escribir texto.
✍️ Reescribe tu peor instrucción
Es hora de aplicar. Abre tu configuración — ~/.claude/CLAUDE.md, o
CLAUDE.md de un proyecto o el cuerpo de una skill tuya, y encuentra allí la instrucción más
«receta de cocina» que exista: la más numerada, la más larga, la que describe pasos. Vas a escribir
dos versiones de ella, y la segunda obligatoriamente con verificación objetiva.
Versión 50% más pequeña
La misma estructura, la mitad del texto. Elimina lo que el modelo ya hace por su cuenta y combina los pasos que siempre van juntos. Ninguna regla real puede desaparecer en esta versión: es un recorte de grasa, no de músculo.
Versión mínima, con la plantilla de 6 campos
Reescritura desde cero con la estructura Objetivo · Contexto · Guardrails · Criterios · Verificación · Autonomía. La verificación debe ser un comando, una prueba, una comparación o una comprobación de archivo: algo que produzca un resultado observable.
🧪 Prompt listo para pegar en Claude Code
Objetivo: hacer que el propio Claude Code produzca las dos versiones una al lado de la otra, sin dejar que aplique nada al archivo.
Lee <ruta de tu CLAUDE.md o de tu skill> y localiza el bloque "<título o primera línea del bloque más detallado>". NO edites ningún archivo. Solo produce texto en la respuesta. Devuelve tres bloques en markdown: 1. ORIGINAL — el fragmento exactamente como está hoy, con el recuento de líneas. 2. VERSIÓN 50% MÁS CORTA — el mismo fragmento con la mitad de líneas. Recorta solo lo que harías por tu cuenta sin la instrucción. Enumera debajo, una línea por elemento, qué recortaste y por qué. 3. VERSIÓN MÍNIMA — reescribe usando los campos Objetivo, Contexto, Guardrails, Criterios de calidad, Verificación y Autonomía. La Verificación debe ser un comando, una prueba, una comparación de archivos o una comprobación de existencia — nada de «revísalo antes de entregar» — y debe incluir una condición para detenerse. Al final, responde en una frase: ¿un colega que no conoce este proyecto podría ejecutar la Verificación de la versión mínima sin preguntarme nada? Si la respuesta es no, reescribe la Verificación.
Criterio de salida de este ejercicio: las dos versiones están escritas una al lado de la original, y la verificación de la versión mínima es ejecutable por un tercero sin preguntarte nada. Si depende de un contexto que solo está en tu cabeza, aún no es una verificación.
Cómo comprobarlo en la práctica: envía la versión mínima a alguien (o pégala en una sesión nueva, sin historial) y pídele solo que ejecute la línea de Verificación. Si te hace una pregunta de vuelta, reescríbela. Guarda las tres versiones: se convierten en la entrada directa del plan A/B/C de la Trilha 4.
Revisión rápida (no bloquea nada): tu instrucción mínima termina con “antes de finalizar, revisa el resultado con atención y corrige lo que esté mal”. ¿Eso cuenta como verificación?
Conceptos clave
50% más pequeño y mínimo
La original queda visible
Ejecutable sin preguntarte
Las tres versiones se convierten en una prueba
📌 Resumen del Módulo
Próximo módulo:
3.1 — Ejecutar la skill audit-ablacao: instalar, elegir el alcance y leer el informe de 10 secciones sabiendo qué te exige cada una.