Ingeniería compuesta: una base de código que acelera

La mayoría de los códigos se ralentizan a medida que crecen. El mío se acelera. Después de construir 95 hooks, 44 skills y 14 archivos de configuración en mi infraestructura .claude/, cada nueva función cuesta menos que la anterior porque la infraestructura se encarga de más trabajo.¹

TL;DR

La ingeniería compuesta describe códigos donde cada función añadida abarata la construcción de las siguientes. Lo he experimentado de primera mano: mi sistema de hooks de Claude Code comenzó con 3 hooks y creció hasta 95. El primer hook tomó una hora en construirse. Los hooks recientes toman 10 minutos porque la infraestructura (eventos del ciclo de vida, carga de configuración, gestión de estado, entorno de pruebas) ya existe. El patrón opuesto, la ingeniería entrópica, describe códigos donde cada función incrementa el costo de las funciones posteriores. La diferencia entre un equipo que entrega más rápido en el tercer año que en el primero y un equipo que se estanca es si sus decisiones de ingeniería se componen positiva o negativamente.

La composición en la práctica: mi infraestructura .claude/

La curva de crecimiento

El primer hook (git-safety-guardian.sh) requirió construir todo el ciclo de vida de hooks: comprender los eventos PreToolUse, escribir bash que analice la entrada JSON, manejar casos de error, probar manualmente. El hook número 95 heredó toda esa infraestructura. El tiempo por hook se redujo 6 veces no porque los hooks se hicieran más simples, sino porque la infraestructura se encargaba de más trabajo.

Lo que se compone

Consistencia de patrones. Cada hook sigue la misma estructura: leer la entrada JSON, analizar con jq, verificar condiciones, producir JSON de decisión. Un desarrollador (o agente de IA) que lea cualquier hook reconoce el patrón al instante. Mi linter de blog de 12 módulos sigue el mismo principio de consistencia: cada módulo exporta la misma interfaz (check(content, meta) -> findings), lo que hace trivial agregar nuevos módulos.

Comportamiento dirigido por configuración. Los 14 archivos de configuración JSON codifican umbrales y reglas que originalmente estaban escritos directamente en el código. Cuando moví el umbral de consenso de deliberación de un valor fijo 0.70 en Python a deliberation-config.json, obtuve la capacidad de ajustarlo por tipo de tarea (seguridad=85%, documentación=50%) sin cambios en el código.²

Infraestructura de pruebas. Los primeros 20 hooks no tenían pruebas. Agregar el entorno de pruebas (48 pruebas de integración en bash, 81 pruebas unitarias en Python) costó dos semanas. Cada hook posterior se entrega con pruebas en menos de 5 minutos porque los fixtures, las funciones auxiliares de aserción y los ejecutores de pruebas ya existen.

Sistema de memoria. Mi archivo MEMORY.md captura errores, decisiones y patrones entre sesiones. Con 54 entradas, evita que repita errores. El problema de ((VAR++)) en bash del hook #23 ha prevenido el mismo error en los hooks #24 al #95. Cada entrada se compone en todas las sesiones futuras.³

El modelo de composición

Composición positiva

La productividad de ingeniería sigue una fórmula de interés compuesto:

Productivity(n) = Base × (1 + r)^n

Donde r es la tasa de cambio de productividad por función y n es la cantidad de funciones entregadas.

r positivo (composición): Cada función hace la siguiente un 2-5% más barata. Después de 50 funciones: 1,03^50 = 4,38 veces de mejora en productividad.

r negativo (entropía): Cada función hace la siguiente un 2-5% más cara. Después de 50 funciones: 0,97^50 = 0,22 veces de productividad, una degradación del 78%.

La diferencia entre estas trayectorias es una brecha de 20 veces en la velocidad de ingeniería después de 50 funciones.⁴

Mis números reales

Mi sitio blakecrosley.com comenzó como una única ruta FastAPI con una plantilla HTML. Nueve meses después:

La última entrada es el resultado de la composición: agregar un nuevo módulo del linter toma 15 minutos porque la interfaz del módulo, la integración con CLI, el entorno de pruebas y el pipeline CI ya existen. El primer módulo tomó 3 horas porque nada de esa infraestructura existía.⁵

Ejemplos de entropía en mi propio código

La composición no es automática. También he experimentado entropía:

El atajo del esquema ContentMeta

Definí el dataclass ContentMeta para publicaciones del blog en una sola sesión: título, slug, fecha, descripción, etiquetas, autor, publicado. No incluí category, series, hero_image, scripts ni styles. Cada adición posterior requirió modificar el analizador, actualizar cada plantilla que consumía los metadatos y volver a probar todo el pipeline. Cinco adiciones a lo largo de tres meses costaron más tiempo total que diseñar el esquema cuidadosamente desde el principio. Este es el problema del momento de las decisiones: las decisiones irreversibles merecen un análisis previo.

La colisión de claves de caché i18n

Una implementación rápida del almacenamiento en caché de traducciones usó los slugs del blog como claves de caché. Cuando existían dos traducciones del mismo slug en diferentes locales, la caché devolvía el idioma incorrecto. La depuración tomó 3 horas. La corrección tomó 15 minutos (agregar prefijo de locale a la clave de caché). El atajo que ahorró 5 minutos durante la implementación costó 3 horas en depuración y una revisión arquitectónica de cada clave de caché en el sistema.⁶

El directorio de depuración de 3,2 GB

La salida de depuración de los hooks se acumuló en ~/.claude/debug/ sin limpieza. En tres meses, el directorio creció a 3,2 GB. El skill de auditoría de contexto que construí después detectó esto y limpió archivos con más de 7 días de antigüedad, pero la infraestructura de limpieza debió haberse construido junto con la primera salida de depuración.

Prácticas que se componen

Patrones consistentes sobre patrones óptimos

Un equipo que usa el mismo patrón “suficientemente bueno” en 50 funciones opera más rápido que un equipo que usa el patrón “óptimo” para cada función individual. La consistencia reduce la carga cognitiva, habilita herramientas automatizadas y acelera las revisiones de código.⁷

Mi sistema de hooks usa el mismo patrón en bash para los 95 hooks aunque algunos hooks se expresarían más naturalmente en Python. La consistencia significa que cualquier hook es legible por cualquier persona (o cualquier agente de IA) que haya leído un solo hook. La elección subóptima del lenguaje se compensa ampliamente con la curva de aprendizaje nula para nuevos hooks.

La infraestructura como primera función

Construí mi pipeline CI/CD, el entorno de pruebas y el flujo de despliegue antes de construir cualquier función del producto en blakecrosley.com. La inversión se sintió lenta en su momento. Cada función desde entonces se despliega en menos de 2 minutos con pruebas automatizadas.⁸

El patrón del palacio mental

Mi directorio .claude/ funciona como un “palacio mental” — un conjunto estructurado de documentos optimizado tanto para consumo humano como de IA:

~/.claude/
├── configs/     # 14 JSON files — system logic, not hardcoded
├── hooks/       # 95 bash scripts — lifecycle event handlers
├── skills/      # 44 directories — reusable knowledge modules
├── docs/        # 40+ markdown files — system documentation
├── state/       # Runtime tracking — recursion depth, agent lineage
├── handoffs/    # 49 documents — multi-session context preservation
└── memory/      # MEMORY.md — 54 cross-domain error/pattern entries

El palacio mental se compone porque cada nueva entrada enriquece el contexto disponible para futuras sesiones de desarrollo. Después de 54 entradas en MEMORY.md, el agente de IA evita errores que ya he resuelto. Después de 95 hooks, los nuevos hooks se escriben solos siguiendo los patrones establecidos. El contexto más rico produce código generado por IA mejor adaptado, lo que hace que la siguiente función sea más barata.⁹

La composición en la era de la IA

La IA amplifica ambas direcciones

Los asistentes de programación con IA aceleran cualquier patrón que el código ya siga. Mis 95 hooks con patrones consistentes producen hooks generados por IA excelentes porque la IA replica la estructura establecida. Un código con 5 estilos de hooks diferentes produciría código generado por IA peor porque la IA no tiene un patrón consistente que replicar.¹⁰

El efecto de composición se duplica: los patrones consistentes hacen el desarrollo humano más rápido (reducción de carga cognitiva) Y el desarrollo asistido por IA más rápido (coincidencia de patrones). Los patrones inconsistentes hacen ambos más lentos.

Códigos legibles por agentes

Diseñé mi infraestructura .claude/ para el consumo de agentes de IA:

• Configuraciones estructuradas (JSON, no valores escritos directamente en el código) que los agentes analizan programáticamente
• Convenciones de nomenclatura consistentes (verb-noun.sh para hooks, SKILL.md para definiciones de skills)
• Verificaciones de calidad comprobables por máquinas (141 pruebas que los agentes ejecutan de forma autónoma)
• Documentación explícita (MEMORY.md, handoffs, docs/) que los agentes leen al inicio de sesión

Cada inversión en legibilidad para agentes se compone a medida que las herramientas de IA se vuelven más capaces.¹¹

Conclusiones clave

Para ingenieros: - Mida su “tiempo por función” a medida que el código crece; si aumenta, tiene entropía; si disminuye, tiene composición - Aplique la regla de tres antes de extraer abstracciones: construya la solución específica dos veces, luego extraiga el patrón reutilizable en la tercera ocurrencia - Invierta el 15-20% de cada sprint en mejoras de infraestructura y herramientas; los retornos compuestos superan el costo de velocidad de funciones a corto plazo en 3-5 sprints

Para gerentes de ingeniería: - Mida la salud de ingeniería por el tiempo de entrega por función a lo largo del tiempo; un tiempo de entrega creciente señala entropía - Trate la documentación y la infraestructura de pruebas como funciones, no como gastos generales; mi inversión en infraestructura de pruebas (2 semanas) ha ahorrado más de 50 horas en 95 hooks

Referencias