ousterhout-quality-program

SKILL.md

---
name: ousterhout-quality-program
description: Usa siempre que el código que se está escribiendo o revisando crea o cambia un límite: un nuevo módulo, clase, componente, helper, hook, servicio o wrapper; cualquier extracción o centralización de código compartido; cualquier momento de "hagamos esto reutilizable"; y cuando se revisa, refactoriza o diseña explícitamente un módulo. Juzga si una abstracción justifica su existencia: profundidad del módulo, si se debe ocultar una decisión de diseño, si el código duplicado protege un invariante compartido o simplemente rima, si una interfaz es estable. Protege contra un SOLID/Clean Code mecánico que produce muchas clases superficiales. También define la prueba del costo para el lector (código que es barato para que humanos y agentes lo lean y modifiquen) y el procedimiento para refactorizar una base de código existente a este estándar.
---

# Programa de Calidad Ousterhout

## Resumen

El trabajo de un módulo es ocultar la complejidad detrás de una interfaz pequeña. La medida central es la **profundidad**: un módulo profundo ofrece una interfaz simple sobre una funcionalidad sustancial; la interfaz de un módulo superficial es casi tan compleja como su implementación, por lo que no se justifica. La complejidad es lo que sientes cuando un cambio te obliga a entender o tocar código que no esperabas — Ousterhout nombra dos fuentes: **dependencias** (no puedes cambiar A sin cambiar B) y **oscuridad** (la información importante no es obvia).

Ousterhout por sí solo te dice cómo *se siente* un buen módulo. Es más fuerte combinado con algunas otras perspectivas que te indican dónde deben estar los límites y cómo avanzar hacia ellos de forma segura. Esta habilidad es esa perspectiva combinada.

## Dónde Realmente Fallan las Revisiones

Los dos fallos que esta habilidad existe para corregir — observados repetidamente en código escrito por agentes — están en el **remedio**, no en el veredicto de dividir/no dividir en sí:

1. **La solución superficial.** Dado seis casteos `as unknown as`, el revisor sin ayuda los centraliza en un único helper genérico `castRows<T>()` — más ordenado, pero la oscuridad persiste. La solución profunda es mapeadores tipados fila→dominio con pruebas fijadas primero (aplicando Parnas: un casteo es el olor de un límite faltante; Beck: prueba el mapeo antes de moverlo). Ordenar un olor no es eliminarlo.
2. **La extracción refleja.** Dada la misma lógica de actualización repetida en tres componentes hermanos, todos los revisores sin ayuda dijeron "extrae un helper compartido" — el reflejo DRY. La regla de este programa, extendiendo Metz: espera al invariante, no al tercer parecido — centraliza cuando el código protege una regla compartida, no cuando rima.

Cuando te encuentres recomendando una solución, pásala por ambos filtros: ¿elimina la oscuridad o solo la reubica?, y ¿la extracción protege un invariante o solo deduplica una forma?

## Puerta de Proporcionalidad

Omite la perspectiva cuando un cambio no añade ningún nombre exportado/importable nuevo, no crea un nuevo módulo/clase/componente/helper/hook/servicio/wrapper, y no centraliza nada. Cambios puros de nombre, codemods mecánicos, ediciones de configuración/datos y correcciones de una línea están exentos. En caso de duda, ejecuta solo las dos pruebas centrales (profundidad, invariante) y detente ahí.

## La Regla Completa

Cada pieza de código generado o revisado pasa por la perspectiva Ousterhout antes de que la tarea se considere terminada — no solo revisiones de diseño explícitas — excepto cambios por debajo de la puerta de proporcionalidad (sin nuevo límite, sin centralización: renombrados, codemods, ediciones de configuración). Dos pruebas: (1) **Profundidad** — una nueva interfaz debe ocultar sustancialmente más de lo que expone; una interfaz tan compleja como lo que envuelve no paga nada. (2) **Invariante** — extrae código compartido solo cuando protege una regla compartida, nunca porque tres sitios rimen; y una solución debe eliminar la oscuridad, no reubicarla (centralizar seis casteos en un helper sigue siendo seis casteos). Cuando un cambio crea o remodela un límite, primero encuentra cómo un producto establecido resuelve un problema de esta forma y escala y adopta sus convenciones a menos que haya una razón declarada para no hacerlo (un patrón recordado del entrenamiento es una afirmación, no una fuente), luego ejecuta las comprobaciones abajo.

## Cuándo Usar

- Decidir si una nueva clase/función/hook vale su interfaz, o es solo un paso superficial.
- Un archivo cruza un umbral de tamaño y estás decidiendo *cómo* dividirlo, no solo que deberías.
- Código repetido te tienta a extraer un helper compartido.
- Diseñar o revisar un límite alrededor de una regla de negocio (una comprobación de alcance de autorización, una regla de dinero/redondeo, una guardia de transición de máquina de estados, una regla de retención de datos).
- Una interfaz está a punto de crecer un parámetro o un caso especial.
- Llevar una base de código existente a este estándar — ver "Refactorización de una Base de Código Existente a Este Estándar" abajo.

**No para:** ediciones mecánicas triviales, o cuando una convención del proyecto ya dicta la estructura — ver la Puerta de Proporcionalidad arriba. Deferir a `karpathy-guidelines` para disciplina de cambios quirúrgicos y una habilidad de desarrollo guiado por pruebas para la red de seguridad de refactorización, cuando estén disponibles.

## Las Perspectivas

Cada perspectiva añade exactamente una pregunta. Ousterhout es la columna vertebral; las otras corrigen sus puntos ciegos.

| Lente | La única pregunta que añade | Cuándo prevalece |
|---|---|---|
| **Ousterhout** — módulos profundos | ¿Esta interfaz oculta más de lo que expone? | Espina dorsal por defecto. |
| **Parnas** — ocultación de información | ¿Qué decisión de diseño (probablemente cambiante) oculta este módulo? | La *razón* por la que un módulo debe ser profundo. Si no oculta nada que cambie, la profundidad es cosmética. |
| **Brooks** — esencial vs accidental | ¿Esto elimina complejidad accidental o solo reubica la complejidad esencial del dominio? | Elimina "refactorizaciones" que solo mueven el desorden sin reducirlo. |
| **Evans** — Domain-Driven Design | ¿Este límite está nombrado en lenguaje del dominio, no en lenguaje genérico de utilidad? | Renombrar `utils`/`helpers` — nombrar el límite según el invariante que este repositorio realmente tiene. |
| **Fowler** — refactorización / olores | ¿Cuál es el movimiento más pequeño y seguro hacia un diseño más profundo? | Convierte "debería ser más profundo" en pasos concretos detrás de pruebas que pasan. |
| **Beck** — diseño simple, test-first | ¿He probado el comportamiento actual antes de profundizar la costura? | Un freno a la arquitectura prematura. Haz que funcione y esté probado primero, luego profundiza la costura correcta. |
| **Hickey** — simple vs fácil | ¿Esto entrelaza conceptos no relacionados o es genuinamente un solo concepto? | Un ayudante superficial suele ser *fácil* (cercano, rápido), no *simple* (pocos conceptos entrelazados). Prefiere simple. |
| **Metz** — duplicación sobre abstracción incorrecta | ¿Este código repetido protege un invariante compartido o solo se parece (regla de este programa, extendiendo a Metz)? | Metz: la duplicación es más barata que la abstracción incorrecta — inserta una abstracción incorrecta de nuevo en línea en lugar de forzarla. Este programa la extiende: no centralices porque se repite; centraliza solo cuando protege un invariante real. Tolera la duplicación hasta que el invariante se revele. |
| **Ley de Hyrum** — comportamiento observable | ¿Los llamadores dependerán de un comportamiento más allá del contrato de esta interfaz? | Aboga por interfaces pequeñas y estables: todo comportamiento observable eventualmente se vuelve fundamental. |

## La Receta Combinada

Aplica en este orden — las lentes posteriores solo importan una vez que las anteriores pasan:

1. **Metz — la puerta de admisión.** ¿Este límite/abstracción merece existir? Regla de este programa, extendiendo a Metz: extrae solo cuando el código protege una regla compartida — tres similares no son un invariante revelado. Si no, detente aquí.
2. **Parnas / Ousterhout** — Oculta la decisión volátil (alcance de autorización, regla de redondeo, guardia de transición, regla de retención) detrás de un módulo profundo.
3. **Evans** — Nombra ese módulo en lenguaje del dominio, no `utils`.
4. **Beck / Fowler** — Para código existente, fija el comportamiento actual con pruebas, luego refactoriza hacia él en pequeños movimientos seguros. Para código recién generado no hay comportamiento actual que fijar — escribe la prueba que define el comportamiento deseado.
5. **Hickey** — Rechaza interfaces que mezclan conceptos no relacionados solo porque los flujos de trabajo se vean similares.

## El Anti-Patrón Estructural

**SOLID mecánico / Clean Code produce módulos superficiales.** Una lectura dogmática — una clase por responsabilidad, extraer cada función, mantener todo pequeño — genera un enjambre de clases cuyas interfaces son tan complejas como sus cuerpos. Cuando una regla dice "divide esto", pregunta qué *decisión* oculta la división (Parnas) y si oculta más de lo que expone (Ousterhout). Si no oculta nada que cambie, no dividas. Esta protección es más importante bajo presión de refactorización ("limpia esto", "este archivo es muy grande") — en análisis calmado, los revisores ya la resisten; a mitad de refactorización, con mandato de producir cambio visible, es cuando se escriben enjambres de archivos superficiales.

## Errores Comunes

- **Dividir solo por tamaño.** Un módulo de consulta de 400 líneas que oculta una decisión coherente puede ser más profundo que cuatro módulos de 100 líneas que cada uno filtran las mismas uniones.
- **Nombrar la división `helpers`/`utils`.** Si no puedes nombrarlo en lenguaje del dominio (Evans), probablemente el límite está mal.
- **Extraer en la segunda ocurrencia.** Regla de este programa, extendiendo a Metz: espera al invariante, no al tercer parecido.
- **Profundizar antes de fijar el comportamiento.** Beck: sin una prueba que demuestre el comportamiento actual, un refactor "de profundización" es una reescritura.
- **Contar un paso directo como módulo.** Un envoltorio que reenvía sus argumentos añade una interfaz y no oculta nada — superficial por definición.
- **Confundir una rima con un invariante.** La mejor evidencia de un invariante compartido es el cambio conjunto: las copias han sido corregidas o cambiadas juntas en la historia (el mismo error corregido en dos lugares). Los parecidos que cambian independientemente son rimas; déjalos duplicados.
- **Ordenar un olor en lugar de eliminarlo.** Centralizar seis conversiones en un ayudante genérico de conversión es la versión ordenada de la misma oscuridad. La solución profunda nombra el límite que la conversión estaba encubriendo.

## Costo para el Lector: la Tercera Prueba

La profundidad y el invariante deciden si un límite debe existir. El costo para el lector decide si el código alrededor es barato de cambiar. El siguiente lector, humano o agente, paga por cada línea que debe cargar para cambiar algo de forma segura. Los agentes pagan en tokens y navegan por búsqueda de texto, lecturas parciales y ciclos de verificación/prueba, por lo que los mismos defectos les cuestan más. Pregunta:

- **¿Encontrable?** Un nombre por concepto, escrito igual en todas partes, accesible mediante búsqueda de texto plano. Defectos: nombres ensamblados a partir de cadenas, conexiones por efecto secundario de importación, cadenas de reexportación que ocultan la definición, dos nombres para un mismo concepto.
- **¿Puede el lector detenerse temprano?** El contrato está al principio del archivo o encima de la exportación: lo que promete, lo que oculta, lo que nunca hace. Defecto: el contrato solo puede derivarse leyendo el cuerpo.
- **¿Comprobable por máquina?** Tipos precisos de entrada y salida en cada límite, de modo que una comprobación de tipos reemplaza la lectura de los llamadores. Defectos: `any`, diccionarios sin tipo, banderas booleanas cuyo significado vive en el cuerpo.
- **¿Es visible el acoplamiento?** Los lugares que deben cambiar juntos están forzados (un tipo compartido, una prueba, una fuente única) o, en su defecto, marcados en ambos sitios. La evidencia de acoplamiento oculto es el cambio conjunto en la historia que nada en el código menciona.
- **¿Libre de ruido?** Sin comentarios que repitan el código, sin código comentado, sin ramas muertas, sin comentarios de historial de cambios, sin rutas obsoletas mantenidas junto a su reemplazo.
- **¿Predecible?** La disposición sigue el patrón existente del repositorio; la prueba está donde un lector la buscará y se ejecuta por sí sola.

El tamaño del archivo está deliberadamente ausente. Un archivo muy grande es una razón para buscar una segunda decisión oculta, nunca una razón para cortar: los lectores pueden buscar y leer un rango, y una división que no oculta nada añade interfaces sin eliminar carga.

Para marcadores en el código y un mapa del repositorio, use `context-audit` donde esté disponible: su ancla `AIDEV-NOTE:` (un hecho no recuperable más una referencia de procedencia, como máximo dos líneas, en el sitio) es la convención para el acoplamiento que no puede ser forzado.

## Refactorización de una base de código existente a este estándar

Una adaptación se juzga igual que el código nuevo; lo que difiere es el orden y la moderación. La mayor parte de una base de código debe dejarse intacta.

1. **Censo, solo lectura.** Liste los límites (módulos, servicios, ayudantes compartidos). Para cada registro: la decisión que oculta, o "ninguna"; tamaño de la interfaz contra el cuerpo; socios de cambio conjunto según la historia; defectos que aumentan el costo para el lector. No cambie nada aún.
2. **Ordene por rotación, no por fealdad.** La prioridad es la frecuencia con que cambia el código multiplicada por el costo de leerlo. El código frío que funciona se mantiene tal cual, por superficial que sea. La complejidad esencial del dominio permanece donde está (Brooks).
3. **Asigne un remedio por hallazgo:**
   - capa de paso o envoltorio que no oculta nada: elimínelo, los llamadores usan lo que envolvía;
   - abstracción incorrecta doblada por banderas y casos especiales: insértela de nuevo (Metz), luego busque la verdadera invariante;
   - hermanos superficiales que comparten una decisión: únalos detrás de una interfaz;
   - decisión filtrada (los llamadores conocen el formato, la regla, el esquema): baje esa decisión al módulo que la posee;
   - nombre genérico (`utils`, `helpers`, `manager`): renómbrelo según la decisión que oculta, o disuélvalo en sus llamadores;
   - límite sin tipar: tipéelo y reemplace los casts con el mapeador que estaban encubriendo;
   - acoplamiento oculto: hágalo cumplir o marque ambos sitios;
   - ruido: elimínelo.

   Las rimas que cambian independientemente no reciben remedio.
4. **Fije el comportamiento primero.** Ningún remedio comienza hasta que una prueba demuestre el comportamiento actual del código que toca (Beck). Las refactorizaciones preservan el comportamiento; un cambio de comportamiento es un commit separado.
5. **Divida el trabajo en unidades que un agente pueda terminar solo.** Un límite por unidad. Cada unidad nombra los archivos que posee, el contrato que debe preservar y el comando que lo prueba por sí solo. Ninguna dos unidades concurrentes escriben el mismo archivo; los archivos compartidos (barriles, registros, tablas de rutas) tienen un único propietario o esperan integración. Los cambios de interfaz de los que dependen varias unidades se implementan primero, como su propia unidad.
6. **Mida el resultado.** Elija un cambio representativo antes de comenzar y cuente los archivos y líneas que un lector debe cargar para hacerlo; cuente de nuevo después. Los nombres exportados y las líneas totales deben bajar o mantenerse. Una refactorización que añade interfaces debe justificarlo.
7. **Deténgase** cuando lo que queda sea frío, esencial o una rima.

Habilidades relacionadas, donde estén disponibles: `repo-review` (tipo de diseño) produce el censo como artefacto solo de consejo; `design-cleanup` ejecuta el ciclo de arreglar y volver a escanear para complejidad accidental; `context-audit` añade anclas y el mapa del código; `ousterhout-build-deep` es la lista de verificación en tiempo de autor para los agentes que hacen las unidades.

## Dónde se sitúa esto

Esta habilidad es la capa de revisión y juicio: úsela para decidir si una abstracción es profunda, nombrada por la decisión correcta y vale la pena extraer. `find-shared-code` la usa como prueba de admisión al barrer la historia reciente en busca de código que valga la pena compartir. El Apéndice a continuación da el razonamiento de cada autor.

---

## Apéndice: Las lentes en profundidad

El modo de fallo que cada autor detecta y el único movimiento que cada uno te da. La tabla anterior es la referencia rápida; esto es el razonamiento detrás.

### Ousterhout — Módulos profundos (la columna vertebral)

*Una filosofía del diseño de software.*

- **Profundidad** = beneficio (funcionalidad oculta) ÷ costo (complejidad de la interfaz). Un módulo profundo oculta mucho tras poco. La interfaz de un módulo superficial es casi tan compleja como su cuerpo, por lo que no aporta nada.
- **Complejidad** es cualquier cosa del sistema que dificulta entenderlo o modificarlo. Dos fuentes:
  - **Dependencias** — no puedes cambiar una pieza sin tocar otra.
  - **Oscuridad** — la información importante no es obvia desde el código.
- **Síntomas:** amplificación de cambios (una decisión, muchas ediciones), carga cognitiva (cuánto debes mantener en la cabeza), desconocidos desconocidos (no puedes saber qué código afectará un cambio).
- **Movimiento clave:** bajar la complejidad — el módulo absorbe el caso difícil para que los llamadores no tengan que hacerlo. Los parámetros de configuración y las capas de paso empujan la complejidad hacia arriba al llamador; eso es superficialidad.

Detecta: interfaces que filtran su implementación; ayudantes que no ayudan.

### Parnas — Ocultamiento de información (por qué importa la profundidad)

*Sobre los criterios para descomponer sistemas en módulos (1972).*

- Descomponer alrededor de **decisiones de diseño que probablemente cambien**, no alrededor de los pasos de
  un cálculo. Cada módulo oculta una de esas decisiones.
- Este es el ancestro directo del módulo profundo. Un módulo es profundo *porque*
  oculta una decisión que de otro modo se propagaría a través de los llamadores.

Trampas: un "módulo" que no oculta nada volátil — su profundidad es cosmética. Pregúntate:
¿Qué cambia detrás de esta interfaz que los llamadores nunca ven? Si la respuesta es
"nada", el límite es decoración.

### Brooks — Complejidad Esencial vs Accidental

*No hay bala de plata.*

- La complejidad **esencial** es inherente al dominio (la tasación realmente es tan
  intrincada). La complejidad **accidental** es lo que imponen nuestras herramientas y estructura.
- Solo la complejidad accidental es removible. Un refactor que "limpia" moviendo
  la complejidad esencial del dominio de un archivo a otro no ha hecho nada.

Trampas: reordenamientos disfrazados de simplificación. Pregúntate: ¿la complejidad total disminuyó,
o solo se movió?

### Evans — Domain-Driven Design

*Domain-Driven Design.*

- Los límites deben nombrarse en el **lenguaje ubicuo** del dominio, no en
  términos genéricos de utilidad. Un módulo llamado `helpers` no nombra nada; un módulo llamado
  `AccessScope` o `PricingPolicy` nombra un invariante.
- Los contextos acotados evitan que los invariantes de negocio se filtren a través de las uniones.

Trampas: descomposición correcta con nombres sin sentido. Si no puedes nombrar el
módulo en el lenguaje del dominio, probablemente cortaste el límite en el lugar equivocado.

### Fowler — Refactorización y Olores de Código

*Refactorización.*

- Proporciona movimientos concretos, seguros y nombrados (Extraer Función, Mover Campo, Reemplazar
  Condicional con Polimorfismo) para pasar del diseño actual al más profundo.
- Cada movimiento preserva el comportamiento y es pequeño, para que sea reversible.

Trampas: la brecha entre "esto debería ser más profundo" y saber cuál es el próximo commit.
Ousterhout establece el objetivo; Fowler es el camino.

### Beck — Diseño Simple, Test-First

*Desarrollo guiado por pruebas; XP.*

- Cuatro reglas de diseño simple, en el orden publicado por Beck: pasa pruebas, no
  duplicación, revela intención, menos elementos. Este programa sigue el
  reordenamiento posterior de Fowler/Haines — intención antes que duplicación — porque
  sirve a la regla invariante que extiende Metz (ver Metz, abajo):
  no actúes sobre la duplicación hasta que puedas nombrar la intención que protege.
- Test-first es un freno contra la arquitectura prematura. Haz que funcione y prueba
  el comportamiento *primero*, luego profundiza la unión que ahora protegen las pruebas.

Trampas: arquitectura construida antes de fijar el comportamiento. Sin una prueba que demuestre el
comportamiento actual, un refactor de "profundización" es una reescritura no verificada.

### Hickey — Simple vs Fácil

*Simple Made Easy.*

- **Simple** = sin entrelazar: un concepto, no entremezclado con otros (objetivo).
- **Fácil** = al alcance, familiar, rápido de alcanzar (relativo a ti).
- Los dos son independientes. Un helper superficial suele ser *fácil* — rápido de escribir,
  cercano — pero no *simple* si entrelaza preocupaciones no relacionadas.

Trampas: conveniencia disfrazada de diseño. Prefiere construcciones que mantengan los conceptos
sin entrelazar incluso cuando una entrelazada sea más rápida de escribir.

### Metz — Prefiere la Duplicación a la Abstracción Incorrecta

*"The Wrong Abstraction" (2016).* 

- La duplicación es mucho más barata que la abstracción incorrecta. Una abstracción extraída
  demasiado pronto obliga a cada llamador futuro a adaptarse a suposiciones que nunca
  fueron verdaderas para todos ellos.
- Cuando una abstracción resulta incorrecta, el remedio de Metz es insertarla de nuevo y dejar
  que la duplicación regrese, en lugar de forzarla a encajar en un caso para el que nunca fue construida.
- **La regla de este programa, que extiende a Metz: no centralices porque el código se repite.
  Centraliza cuando protege un invariante real y compartido.** Hasta que el invariante
  se revele, tolera la duplicación.

Trampas: sobrecentralización — el helper compartido superficial que ahora todos deben
trabajar alrededor. Esto es el contrapeso a un "DRY a toda costa" mecánico.

### Ley de Hyrum — El Comportamiento Observable se Convierte en Contrato

*"Con un número suficiente de usuarios, cada comportamiento observable de tu sistema
será dependido por alguien."*

- Lo que sea que una interfaz *suceda* hacer — orden, tiempo, texto de error — alguien
  eventualmente dependerá de ello. Así que la superficie que expones es mayor que la superficie
  que documentaste.
- Esto apoya la preferencia de Ousterhout por **interfaces pequeñas y estables**: cuanto menos
  expongas, menos puede volverse fundamental por accidente.

Trampas: interfaces amplias que se osificarán. Cada observable extra se convierte en
una restricción futura.

### Cómo Encajan

- **Parnas → Ousterhout:** oculta una decisión volátil → el módulo es profundo.
- **Brooks:** confirma que la profundidad eliminó complejidad en lugar de reubicarla.
- **Evans:** nombra el límite en el lenguaje del dominio.
- **Beck → Fowler:** fija el comportamiento, luego refactoriza con movimientos pequeños y seguros.
- **Metz:** resiste centralizar hasta que el invariante sea real.
- **Hickey:** mantén la interfaz a un solo concepto.
- **Hyrum:** mantén esa interfaz pequeña para que pueda mantenerse estable.

El peligro es mezclar a Ousterhout con una lectura mecánica de SOLID o Clean Code:
eso produce muchas clases y funciones diminutas con interfaces superficiales — el exacto
opuesto a módulos profundos. Ousterhout, con Metz como contrapeso, es el antídoto.

Tags