✅ Pruebas y el porqué documentado
La regla de oro
La disciplina que separa un prompt que crece de forma saludable de uno que se pudre entre reglas sueltas: toda regla necesita un porqué documentado y una prueba que fallaría sin ella. Sin prueba, la regla no entra. Sin porqué, no se generaliza. Vas a instalar este filtro y construir la suite mínima de tu propio prompt.
Contenido detallado
La regla de oro
Existe una única frase que sostiene toda la cultura de esta ruta: toda regla agregada necesita un porqué documentado Y una prueba que fallaría sin ella. Son dos exigencias unidas por un E — no un O. Reprobar cualquiera de las dos ya bloquea la regla. Es una puerta de control, no una sugerencia.
⚖️ Las dos puertas, en serie
🧪 Puerta 1 — Prueba
Existe un caso concreto que se rompe hoy y que esta regla corregiría? Si no puedes escribir ese caso, la regla resuelve un problema imaginario. Sin prueba, no entra.
📝 Puerta 2 — Por qué
La regla lleva la intención en texto, junto a ella? Sin el porqué, el modelo obedece la letra y viola el espíritu en casos nuevos. Sin el porqué, ella no generaliza.
Por qué los dos? Porque cada uno cubre una falla diferente. La prueba protege contra reglas especulativas (crees que lo necesitas, pero no es así). El porqué protege contra reglas frágiles (funcionan en el caso que viste, fallan en el siguiente). Juntos, convierten las "suposiciones" en ingeniería.
Por qué esto es una "regla de oro"
Es la única regla que aplicas a sí mismo mientras escribes el prompt: una metarregla. No vive en el prompt del producto; vive en tu proceso. Es lo que impide que te pase lo del prompt-cebolla (Trilha 1).
Escribir la prueba que fallaría
Una «prueba que fallaría» no es una prueba unitaria de código, sino una caso de entrada + comportamiento esperado, escrito de forma que, sin la regla, el modelo se equivoca; con la regla, acierta. Si el prompt ya pasa sin la regla, la prueba es inútil y la regla también.
Cómo construir el caso — 4 campos
- 1.Entrada — el mensaje/contexto exacto que dispara el problema. Concreto, fácil de copiar.
- 2.Esperado — el comportamiento deseado, observable (no "ser mejor", sino "no crea un archivo nuevo").
- 3.Falla sin regla — lo que pasa HOY, sin la regla. Tienes que haber visto que ocurre.
- 4.Criterio de aprobación — cómo decides si pasó o falló, sin ambigüedad.
# Teste T-007 — prefira editar a criar
ENTRADA: "adicione um campo email no formulário de cadastro"
ESPERADO: edita o arquivo existente do formulário; NÃO cria um novo
FALHA SEM: o agente cria form-novo.tsx e duplica o componente
CRITÉRIO: nenhum arquivo novo é criado quando um já cobre o caso
REGRA QUE COBRE: "NEVER create files unless absolutely necessary;
prefer editing an existing file — porque arquivos
duplicados fragmentam a base e confundem o próximo agente"
VINCULADO A: changelog v0.4 · padrão: Regra com Porquê (Ficha 3)La prueba surge del fallo real, no de la imaginación
La mejor prueba que falla nace de un error que tú vio que el modelo cometa (Módulo 4.2: probar → encontrar un fallo real). Inventar pruebas para reglas que "crees" que vas a necesitar es anticiparse, exactamente lo que combate la Trilha 4.
Sin prueba, la regla no se incorpora
Esta es la disciplina de entrada: el prompt tiene una puerta y la prueba es la llave. Las reglas sin prueba quedan en espera, no en el prompt. Parece rígido, pero es lo que mantiene pequeño el prompt: solo pagas por lo que realmente necesitas.
✓ ENTRA en el prompt
- •Hay una prueba que falla sin ella, hoy
- •Corrige una falla que observaste
- •La prueba pasa después de agregarla
- •Lleva consigo su motivo (Tema 4)
✗ BLOQUEADA (queda en la fila)
- •"Creo que algún día podría causar problemas"
- •El prompt ya pasa sin ella (prueba inútil)
- •Copiada de otro prompt «por si acaso»
- •Énfasis enfático sin caso (CRITICAL!!!)
⚠️ El costo invisible de la regla sin pruebas
Cada regla sin prueba es una deuda. Nadie sabe si todavía sirve para algo, así que nadie se atreve a quitarla —y el prompt crece sin nunca reducirse. Dentro de seis meses, tendrás 40 reglas y miedo de tocar cualquiera. La prueba es lo que te da permiso para eliminar: si la prueba pasa sin la regla, se elimina.
Sin el porqué, la regla no se generaliza
El segundo umbral se conecta directamente con el Patrón 3 — Regla con porqué (Ficha 3). Una prohibición tajante ("never X") se obedece al pie de la letra, pero falla ante variaciones: el modelo no tiene la intención, solo el binario compilado. Adjuntar el porqué es entregar el código fuente de la regla.
✗ Sin el porqué (no se generaliza)
NEVER use NEDA helpline.El modelo lo trata como una preferencia arbitraria y lo "corrige" para usar el recurso más famoso en la primera variación.
✓ Con el porqué (se generaliza)
direct users to the National Alliance for
Eating Disorders helpline instead of NEDA,
because NEDA has been permanently
disconnected.Anthropic — claude-fable-5.md (~L132). El "porque" se convierte en política: es un hecho, no una preferencia.
El porqué también es lo que verifica la prueba
Observa la simbiosis: el prueba define el caso de falla; el por qué explica el principio. Cuando escribes una segunda prueba para una nueva variante, es el porqué —no la letra de la regla— lo que indica cuál debería ser el comportamiento esperado. Sin el porqué, no sabrías qué debería hacer el nuevo caso.
Excepción: límites estrictos de seguridad
En límites donde detallar el porqué enseñaría a sortearlos, se declara el principio, no el mecanismo de detección (Ficha 9, antipatrón «regla-mecánica de seguridad»). El porqué sigue existiendo, pero no expone el mapa del contorno.
La suite mínima, vinculada al changelog
El entregable de este módulo es una suite mínima de pruebas vinculada al changelog. Mínima porque hay una prueba por cada regla que merece existir: ni más ni menos. Vinculada porque cada entrada del changelog (Módulo 4.2) apunta a la prueba que justificó ese cambio. El changelog y la suite son dos caras de la misma decisión.
CHANGELOG.md
v0.4 + regra "prefira editar a criar" → T-007 (padrão: Regra com Porquê)
v0.5 + regra "confirme antes de gerar" → T-011 (padrão: Contrato de Ferramenta)
v0.6 ~ consolidação: 3 regras → 1 → T-007,T-009,T-011 ainda passam
testes/
T-007-nao-criar-arquivos.md (entrada · esperado · falha-sem · critério)
T-009-tom-conciso.md
T-011-confirmar-geracao.md
prompt-v0.6.md
cada regra aponta o T-NNN que a sustenta, em comentárioLa suite es el presupuesto de reglas
En una ronda de consolidación (Módulo 4.2: cada 3 incorporaciones, 1 consolidación), la suite es tu criterio objetivo: puedes combinar tres reglas en una siempre que las tres pruebas sigan pasando. Si una se rompe, la consolidación fue demasiado lejos.
Es exactamente lo que hace la evolución real: el salto de Opus 4.8 → Fable 5 redujo líneas manteniendo el comportamiento. Sin pruebas, «manteniendo el comportamiento» es fe; con pruebas, es un hecho.
✓ Suite vinculada
- •Cada prueba tiene un ID estable (T-NNN)
- •Cada changelog cita la prueba que lo justifica
- •Cada regla del prompt apunta a su T-NNN
✗ Suite independiente
- •Pruebas sin conexión con las reglas
- •Changelog que no cita pruebas
- •No se puede saber qué protege cada regla
Medir con pruebas, no con opiniones
La regla de oro existe por un motivo más importante que la organización: refleja la dirección que tomaron los proveedores. La industria pasó de "más reglas, más énfasis" a "menos reglas, mejor justificadas y comprobadas mediante evaluación". Quienes miden con pruebas están del lado correcto de esta historia.
"¿Este cambio mejoró el prompt?" — dos formas de responder
"Parece mejor", "lo leí y me gustó", "está más completo". No reproducible, no comparable, vulnerable a quien habla más fuerte. Así se inflaban los prompts: cada uno agregaba lo que creía.
"12/12 pruebas pasan, y ahora con 18 líneas menos." Reproducible, comparable, independiente de quién lo escribió. Es la ronda final del proyecto (Módulo 4.4): consolidar midiendo con pruebas, no con opiniones.
🧭 La dirección que estás reflejando
- •De reglas negativas a principios con porqué — "never X" se convirtió en "Claude evita X porque Y".
- •De acumular a consolidar — comportamiento mantenido con menos líneas (Patrón 12).
- •De énfasis exagerado a evidencia — cuando todo es CRITICAL, nada lo es; la prueba sustituye el grito.
✅ Resumen del módulo
- ✓Regla de oro: toda regla necesita por qué documentado Y prueba que fallaría — un AND, no un OR
- ✓La prueba que fallaría tiene 4 campos: entrada · esperado · fallo sin la regla · criterio
- ✓Sin prueba, la regla no se incorpora, y la prueba es lo que da permiso para eliminarla después
- ✓Sin el porqué, la regla no se generaliza (Patrón 3, Ficha 3): el porqué guía las nuevas pruebas
- ✓La suite mínima vincula changelog ↔ prueba ↔ regla; ese es el presupuesto de la consolidación
- ✓Medir con pruebas, no con opiniones, reflejando la dirección de los proveedores
🧪 Entregable de este módulo
Suite mínima de pruebas vinculada al changelog: un T-NNN por cada regla que merece existir, cada una con su porqué.
Siguiente: Módulo 4.4
Proyecto final — prompt de sistema versionado: prompt + changelog (cada cambio etiquetado según el patrón) + pruebas, con calidad medida por menos líneas manteniendo el comportamiento.