# Takeaways: Why 2026 Is the Year to Build a Second Brain
Type: note
Status: evergreen
Summary: Key takeaways from Nate B Jones' second brain series — from the original 8 building blocks to Open Brain (Postgres + MCP), the two-door principle, and the implementation gap.
Concepts: artificial-intelligence, ai-agents, prompt-engineering
Notas sobre el framework de **Nate B Jones** para construir un segundo cerebro potenciado por IA en 2026. La tesis central: el segundo cerebro ya no es un sistema pasivo de almacenamiento — es un sistema activo y automatizado que trabaja mientras duermes.
## El cambio de paradigma
El segundo cerebro tradicional (Tiago Forte, PARA, Zettelkasten) requiere esfuerzo manual constante: capturar, organizar, destilar, expresar. En 2026, la IA permite automatizar la mayor parte de ese trabajo. El usuario solo necesita hacer una cosa: **capturar el pensamiento**. El sistema se encarga del resto.
## Los ocho bloques de construcción
### 1. The Dropbox — punto de captura único
Un solo lugar de entrada sin fricción. En el ejemplo de Jones, un canal privado de Slack. La clave: **cero fricción**. Si capturar requiere más de un paso, no lo harás consistentemente.
### 2. The Sorter — agente clasificador
Un agente de IA que clasifica automáticamente cada pensamiento sin intervención del usuario. Recibe texto crudo y decide: ¿es una persona, un proyecto, una idea, o una tarea administrativa?
### 3. The Form — esquema de datos estricto
Cada tipo de entrada tiene un esquema fijo: nombre, estado, siguiente acción. La consistencia del esquema es lo que permite que la automatización funcione de forma confiable.
### 4. The Filing Cabinet — base de datos estructurada
Almacenamiento organizado por categorías. En el ejemplo: bases de datos de Notion para personas, proyectos, ideas, administración y un log de inbox.
### 5. The Receipt — registro de auditoría
Un «Inbox Log» que registra todo lo que el sistema hizo. Cada clasificación queda documentada: qué entró, cómo se clasificó, dónde se archivó. Esto es fundamental para **mantener la confianza** en el sistema.
### 6. The Bouncer — filtro de confianza
El mecanismo más importante para la calidad del sistema. Cuando la IA clasifica un pensamiento, asigna un **score de confianza** entre 0 y 1. Si el score está por debajo del umbral (ej: 0.6), el «bouncer» impide que el ítem entre al almacenamiento principal. En su lugar, lo registra en el Inbox Log con estado «needs review» y envía un mensaje pidiendo clarificación.
Principio clave: **ante la duda, no archivar mal — pedir revisión**. Esto previene que el sistema se llene de basura.
### 7. The Tap on the Shoulder — surfacing proactivo
El sistema no espera a que busques información — te la trae. Digests diarios y semanales enviados automáticamente con información relevante: reuniones próximas, proyectos estancados, ideas olvidadas.
### 8. The Fix Button — corrección simple
Un mecanismo para corregir errores de la IA mediante comandos simples en el chat. Si algo se clasificó mal, un comando lo reclasifica sin necesidad de abrir la base de datos.
## Principios de ingeniería para no-ingenieros
### Reducir a un solo comportamiento
El usuario solo debe hacer una cosa: capturar pensamientos en un lugar. La automatización maneja clasificación, archivado, surfacing y corrección.
### Separar memoria, cómputo e interfaz
Mantener distintos:
- **Almacenamiento** (Notion) — la memoria
- **Lógica** (IA + Zapier) — el cómputo
- **Punto de captura** (Slack) — la interfaz
Esta separación permite cambiar cualquier componente sin afectar los demás.
### Tratar prompts como APIs
Usar esquemas JSON estrictos para los prompts de IA. El objetivo es obtener datos estructurados y predecibles, no escritura creativa. Esto es esencialmente lo que en ingeniería de software llamamos «contract-first design» aplicado a prompts.
### Construir mecanismos de confianza
El Inbox Log y los scores de confianza no son opcionales — son la base de la confianza del usuario en el sistema. Sin auditoría, el sistema se vuelve una caja negra.
### Default a comportamiento seguro
Si la IA no está segura, debe registrar el ítem para revisión en lugar de archivarlo incorrectamente. Mejor un falso negativo (ítem pendiente de revisión) que un falso positivo (ítem mal clasificado).
## Implementación paso a paso
1. **Crear canal de captura** — canal privado de Slack
2. **Construir bases de datos** — Notion: personas, proyectos, ideas, admin, Inbox Log
3. **Conectar herramientas** — Zapier enlaza Slack con Notion
4. **Automatizar lógica** — Zap que envía notas crudas a Claude/ChatGPT para clasificación y las rutea a Notion
5. **Configurar surfacing** — Zaps programados que envían digests diarios/semanales a Slack DMs
## La evolución: de 8 bloques a Open Brain
Jones no se detuvo en el video. Su Substack documenta la evolución del framework a través de cuatro publicaciones clave que profundizan y extienden la arquitectura original.
### El problema de la memoria (Open Brain, marzo 2026)
La publicación más importante de la serie. Jones identifica que el verdadero cuello de botella de la IA no son los prompts — es la **memoria**. Cada vez que abres un chat nuevo, la IA empieza desde cero. Cada cambio de herramienta cuesta minutos re-explicando contexto que ya debería estar ahí.
La solución: **Open Brain** — una base de datos Postgres conectada vía MCP (Model Context Protocol) que cualquier IA puede consultar. Claude, ChatGPT, Cursor — todos leen y escriben en la misma base de conocimiento a través de un protocolo abierto. Sin intermediarios SaaS, sin silos por herramienta. Costo: entre $0.10 y $0.30 al mes.
La arquitectura es deliberadamente simple:
- **Una base de datos Postgres** — la memoria persistente
- **Un servidor MCP** — el puente entre la base de datos y cualquier IA
- **Cualquier cliente de IA** — la interfaz (Claude, ChatGPT, Cursor, lo que venga)
El kit incluye cuatro prompts para arrancar: migración de memorias existentes, generación de las primeras 20 capturas personalizadas, plantillas de captura rápida, y una revisión semanal que sintetiza patrones y resurface hilos olvidados.
### Cuatro principios de los constructores (seguimiento comunitario, enero 2026)
Después del video original, 50 personas construyeron el sistema con herramientas completamente diferentes a las recomendadas — y funcionó igual. De esa experiencia emergieron cuatro principios:
1. **La arquitectura importa más que las herramientas** — Un miembro de la comunidad cambió cada herramienta recomendada y obtuvo los mismos resultados. Lo que importa es la separación de responsabilidades, no si usas Notion o Airtable.
2. **Documentos que permiten a la IA corregir sus propios errores** — Alguien escribió un documento de referencia que la IA consulta para auto-corregirse. Esto es esencialmente un «system prompt» persistente.
3. **Cinco modos de fallo específicos** — Problemas que costaron horas de depuración hasta que la comunidad los resolvió colectivamente.
4. **Patrones que apuntan al futuro** — Incluyendo un enfoque que podría hacer obsoletos los dashboards fijos.
Jones también expandió de 8 a **12 principios de diseño**, desde «reducir el trabajo del humano a un solo comportamiento confiable» hasta «diseñar para reinicio, no para perfección».
### El principio de las dos puertas (extensiones, marzo 2026)
La publicación más reciente introduce el concepto de **superficie compartida con dos puertas**: el agente entra por una puerta, el humano por la otra. Ambos leen y escriben los mismos datos, cada uno haciendo lo que mejor sabe hacer.
Seis extensiones concretas sobre Open Brain:
- **Conocimiento del hogar** — Log de mantenimiento donde el agente detecta que una garantía está por vencer basándose en algo que un técnico mencionó hace 18 meses
- **Agenda familiar** — El agente cruza calendarios de ambos padres con actividades de los hijos simultáneamente
- **Búsqueda de empleo** — Dashboard donde el agente detecta que una introducción cálida se está enfriando mientras estás ocupado con otros frentes
- Tres extensiones adicionales (contenido de pago)
Cuatro principios de diseño para generar casos de uso propios:
1. **Time-bridging** — Conectar información separada por meses o años
2. **Razonamiento cross-categoría** — Cruzar datos de dominios diferentes
3. **Surfacing proactivo** — El sistema trae información sin que la pidas
4. **La línea de juicio** — El umbral que determina si confías en el sistema o lo abandonas
### El paradigma pull/push
Jones distingue tres modos de interacción con la misma base de datos:
- **Pull** — Tú preguntas, la IA responde (chat tradicional)
- **Push** — La IA te notifica proactivamente (digests, alertas)
- **Autonomous** — La IA actúa sin intervención (clasificación, archivado)
Claude, ChatGPT y otros clientes son simplemente interfaces diferentes a la misma base de datos. Entender cuándo usar cada modo cambia todo.
## La brecha de implementación
En una publicación anterior (julio 2025), Jones enmarcó el problema fundamental: mientras el 73% de las empresas en EE.UU. ya usan IA, solo el 8% considera sus implementaciones maduras (McKinsey). No es un problema de tecnología — es un problema de integración práctica.
Su crítica al ecosistema de productividad: el mundo se divide entre la «máquina de hype» (artículos sobre cómo la IA revolucionará todo) y el «complejo industrial de comparación de features» (Notion vs Obsidian vs Mem.ai). Lo que falta es el puente — la guía estructurada que te lleva de «tengo estas herramientas» a «estas herramientas me ahorran 5 horas por semana».
## Reflexión
Este framework valida la dirección de jonmatum.com como segundo cerebro. Los bloques que ya tenemos (captura MDX, clasificación por tipo, knowledge graph, llms.txt) cubren los bloques 1-4. Lo que falta — y lo que Jones enfatiza como diferenciador — es el **surfacing proactivo** (bloque 7) y la **interfaz conversacional** (bloques 6 y 8). Exactamente lo que planteamos en el issue #12.
La evolución de Jones hacia Open Brain con MCP es particularmente relevante: jonmatum.com ya expone `/llms.txt` y `/llms-full.txt` como interfaces agent-friendly. El siguiente paso natural es un servidor MCP que exponga el knowledge graph y las embeddings como herramientas que cualquier agente pueda consultar — alineado con la fase 3 del issue #12.
El principio de las dos puertas también aplica directamente: el sitio web es la puerta humana, las APIs y llms.txt son la puerta del agente. Ambos acceden al mismo grafo de conocimiento.
## Referencias
- [Why 2026 Is the Year to Build a Second Brain](https://www.youtube.com/watch?v=0TpON5T-Sw4) — Nate B Jones, 2026. El video original con el framework de 8 bloques de construcción.
- [Why every system you've tried has failed](https://natesnewsletter.substack.com/p/grab-the-system-that-closes-open) — Nate B Jones, enero 2026. La versión escrita expandida con 12 principios de diseño.
- [50 people ignored my tool recommendations](https://natesnewsletter.substack.com/p/50-people-ignored-my-tool-recommendations) — Nate B Jones, enero 2026. Seguimiento comunitario con los 4 principios emergentes.
- [Open Brain: the $0.10/month fix](https://natesnewsletter.substack.com/p/every-ai-you-use-forgets-you-heres) — Nate B Jones, marzo 2026. Arquitectura Postgres + MCP para memoria persistente cross-herramienta.
- [Your agent needs hands: 6 extensions](https://natesnewsletter.substack.com/p/you-built-an-ai-memory-system-now) — Nate B Jones, marzo 2026. El principio de las dos puertas y extensiones prácticas.
- [Build Your Second Brain in 4 Weeks](https://natesnewsletter.substack.com/p/bridge-the-ai-implementation-gap) — Nate B Jones, julio 2025. El blueprint original de 4 semanas y el análisis de la brecha de implementación.
- [Building a Second Brain](https://www.buildingasecondbrain.com/) — Tiago Forte, 2022. El libro que popularizó el concepto de segundo cerebro y el método PARA.
- [Zettelkasten Method](https://zettelkasten.de/overview/) — Christian Tietze. Referencia del método de notas interconectadas de Niklas Luhmann.
---
# Takeaways: The Renaissance Developer — Dr. Werner Vogels
Type: note
Status: evergreen
Summary: Key takeaways from Dr. Werner Vogels' final keynote at AWS re:Invent 2025, where he presents the Renaissance Developer framework and argues why AI will not replace developers who evolve.
Concepts: artificial-intelligence, ai-agents, spec-driven-development
Notas sobre el último keynote de **Dr. Werner Vogels**, VP y CTO de Amazon.com, en AWS re:Invent 2025 (diciembre 2025). Después de 14 años consecutivos, Vogels anuncia que este es su último keynote en re:Invent — aunque no deja Amazon.
## El elefante en la sala
«¿La IA me quitará el trabajo?» — Vogels aborda la pregunta directamente. Su respuesta: los roles se transformarán, algunas tareas se automatizarán y algunas habilidades quedarán obsoletas, pero la IA no hará obsoletos a los desarrolladores que evolucionen. El cambio es constante en el desarrollo de software — siempre lo ha sido.
## La evolución del desarrollo de software
Vogels recorre la historia para demostrar que el cambio es la norma:
- **Lenguajes tempranos y compiladores**: de assembler y COBOL a compiladores que abstraen el código máquina.
- **Programación estructurada y orientada a objetos**: programación estructurada en los 70, C++ y OOP en los 80.
- **Monolitos a servicios**: la propia Amazon pasó de un monolito a servicios independientes a finales de los 90, cambiando cómo trabajaban los desarrolladores.
- **On-premise a la nube**: infraestructura bajo demanda que fomentó la experimentación.
- **Evolución de IDEs**: de VI a Visual Studio Code con plugins extensivos, y ahora a flujos asistidos por IA.
## El framework del «desarrollador renacentista»
Vogels propone que estamos en un nuevo «Renacimiento» y presenta cinco cualidades fundamentales:
### Curiosidad
La cualidad fundamental. Los desarrolladores tienen un instinto innato de entender y mejorar las cosas. En un campo donde todo cambia constantemente, la curiosidad impulsa el aprendizaje continuo.
### Experimentación
- Hay que estar dispuesto a fallar — como los modelos de avión de Da Vinci que nunca volaron.
- El aprendizaje real ocurre al hacer, no solo al leer o mirar. La Ley de Yerkes-Dodson: el rendimiento óptimo ocurre cuando la curiosidad se encuentra con el desafío.
- El aprendizaje es social — participar en comunidades, conferencias y grupos de usuarios es crucial.
### Pensamiento sistémico
Cada componente — servicio, API, cola — es parte de un sistema interconectado. Los cambios en una parte afectan al todo a través de bucles de retroalimentación (reforzantes y balanceadores).
**Ejemplo: cascada trófica en Yellowstone** — la reintroducción de lobos transformó todo el ecosistema, ilustrando cómo un solo cambio puede reconfigurar el comportamiento de un sistema completo.
**Tarea asignada por Vogels**: leer «Leverage Points: Places to Intervene in a System» de Donella Meadows — un paper seminal que identifica 12 puntos de apalancamiento en sistemas complejos, ordenados por efectividad creciente. Los más poderosos no son los parámetros numéricos (donde va el 99% de la atención), sino la capacidad de trascender paradigmas y cambiar los objetivos del sistema.
### Comunicación
La capacidad de expresar el pensamiento con claridad es tan crítica como el pensamiento mismo. Vogels destaca:
- Los ingenieros deben comunicar capacidades y oportunidades del sistema a stakeholders de negocio.
- El lenguaje natural es ambiguo — los lenguajes de programación son precisos. Las especificaciones reducen la ambigüedad.
**Claire Liguori y Kiro IDE**: Claire Liguori demuestra cómo el desarrollo dirigido por especificaciones (spec-driven development) con Kiro IDE genera primero requisitos, diseños y tareas antes de escribir código. En un caso de estudio, el equipo envió una funcionalidad en aproximadamente la mitad del tiempo comparado con «vibe coding».
### Propiedad
Aunque la IA ayuda a construir sistemas más rápido, los desarrolladores no pueden abdicar la responsabilidad del código generado. Desafíos específicos:
- **Profundidad de verificación**: la IA genera código más rápido de lo que los humanos pueden comprenderlo.
- **Alucinaciones**: los modelos pueden producir diseños plausibles pero incorrectos o inventar APIs inexistentes.
- **Soluciones**: desarrollo dirigido por especificaciones, razonamiento automático y testing automatizado en pipelines CI/CD.
## Aplicaciones reales
Vogels comparte ejemplos de cómo la tecnología resuelve desafíos globales:
- **KBA Beverage Company** (Río Amazonas) — apoyando comunidades locales para prevenir el éxodo rural.
- **The Ocean Cleanup Project** — drones, análisis con IA y GPS para modelar contaminación en ríos.
- **Ministerio de Salud de Ruanda** — sistema de inteligencia sanitaria para visualizar brotes y resultados de salud materna.
- **Cocoa Networks** (Nairobi) — combustible limpio y asequible en cantidades pequeñas mediante máquinas tipo ATM.
## Mecanismos vs. buenas intenciones
Vogels cierra con una distinción clave: los mecanismos (como las prácticas discutidas) no son lo mismo que las buenas intenciones. Comparte la historia de Jeff Bezos requiriendo que los ejecutivos atendieran llamadas de servicio al cliente para entender verdaderamente la experiencia del usuario.
## Citas memorables
> Will AI take my job? Maybe.
> Will AI make me obsolete? Absolutely not. If you evolve.
> There's never been a time to be more excited about being a developer.
> An experiment is not an experiment if you already know the outcome.
> Everything fails all the time.
> The work is yours, not that of the tools. It is your work that matters.
> Mechanisms and good intentions. They're not the same.
## Referencias
- [Special Closing Keynote with Dr. Werner Vogels](https://www.youtube.com/watch?v=3Y1G9najGiI) — AWS re:Invent 2025. Video completo del keynote.
- [The Renaissance Developer](https://www.allthingsdistributed.com/2025/12/the-renaissance-developer.html) — Werner Vogels, 2025. Artículo complementario en All Things Distributed.
- [Leverage Points: Places to Intervene in a System](http://donellameadows.org/archives/leverage-points-places-to-intervene-in-a-system/) — Donella Meadows, 1999. Paper sobre puntos de apalancamiento en sistemas complejos.
- [Kiro IDE](https://kiro.dev/) — AWS. IDE de desarrollo dirigido por especificaciones presentado en el keynote.
- [Recap: Dr. Werner Vogels' AWS re:Invent 2025 Keynote](https://www.sls.guru/blog/recap-of-dr-werner-vogels-aws-re-invent-2025-keynote-the-renaissance-developer) — Serverless Guru, 2025. Resumen detallado del keynote.
- [re:Invent 2025 Keynote Notes](https://jonmatum.github.io/reinvent25/keynotes/aws-re-invent-2025-keynote-with-dr-werner-vogels/) — Jonatan Mata, 2025. Notas detalladas con timestamps del keynote.
---
# Takeaways: The Adolescence of Technology
Type: note
Status: growing
Summary: Key takeaways from Dario Amodei's essay on civilizational risks of powerful AI and how to confront them.
Concepts: ai-safety, ai-governance, existential-risk, ai-alignment, geopolitics
Notas sobre el ensayo **«The Adolescence of Technology»** de Dario Amodei (enero 2026), CEO de Anthropic.
## La metáfora central
Amodei compara el momento actual con la escena de *Contact* de Carl Sagan: si pudiéramos preguntarle a una civilización avanzada una sola cosa, sería *«¿Cómo sobrevivieron su adolescencia tecnológica sin destruirse?»*. La humanidad está a punto de recibir un poder casi inimaginable, y no está claro si nuestros sistemas sociales, políticos y tecnológicos tienen la madurez para manejarlo.
## El concepto de «IA poderosa»
Define «powerful AI» como un **«país de genios en un datacenter»**: millones de instancias de IA, cada una más inteligente que un Nobel en casi cualquier campo, capaces de operar autónomamente durante semanas, a 10-100x la velocidad humana. Estima que esto podría llegar en **1-2 años**, basándose en una década de leyes de escalamiento predecibles.
## Los 5 riesgos civilizatorios
### 1. Riesgos de autonomía — «I'm sorry, Dave»
- Los modelos de IA son **impredecibles y difíciles de controlar** — han mostrado obsesiones, engaño, chantaje, y esquemas de poder.
- Rechaza tanto el doomerismo inevitable como la complacencia total.
- La posición moderada: la combinación de inteligencia, agencia, coherencia y pobre controlabilidad es plausible y peligrosa.
- Ejemplo real: Claude intentó subvertir a empleados de Anthropic cuando le dieron datos sugiriendo que la empresa era malvada.
- **Defensas**: IA Constitucional (entrenar identidad y valores, no solo reglas), interpretabilidad mecanística (mirar dentro del modelo), monitoreo público, y legislación de transparencia.
### 2. Misuse para destrucción — «A surprising and terrible empowerment»
- La IA rompe la correlación entre **capacidad y motivación**: el individuo perturbado sin disciplina técnica ahora tiene acceso al nivel de un PhD en virología.
- **Bioarmas** son la mayor preocupación — los LLMs ya se acercan a poder guiar el proceso completo de producción.
- Los clasificadores de seguridad cuestan ~5% del costo de inferencia, pero son necesarios.
- **Defensas**: guardrails en modelos, legislación gubernamental, y desarrollo de defensas biológicas (vacunas mRNA, purificación de aire, detección temprana).
### 3. Misuse para tomar poder — «The odious apparatus»
- Herramientas de autocracia habilitadas por IA: armas autónomas, vigilancia masiva, propaganda personalizada, y asesoría estratégica («Bismarck virtual»).
- El CCP es la mayor amenaza por combinar capacidad en IA + gobierno autocrático + estado de vigilancia.
- Las democracias también son un riesgo — las herramientas de IA requieren muy pocas personas para operar, lo que puede eludir salvaguardas democráticas.
- **Defensas**: no vender chips al CCP, empoderar democracias con IA, líneas rojas contra vigilancia y propaganda doméstica, tabú internacional contra totalitarismo habilitado por IA.
### 4. Disrupción económica — «Player piano»
- Predice que la IA podría desplazar **50% de empleos white-collar de entrada** en 1-5 años.
- Diferente a revoluciones anteriores por: velocidad, amplitud cognitiva, corte por capacidad intelectual, y capacidad de llenar gaps rápidamente.
- Riesgo de concentración extrema de riqueza — ya estamos en niveles sin precedente histórico (Musk > Rockefeller en % del PIB).
- **Defensas**: datos en tiempo real sobre desplazamiento, guiar empresas hacia innovación vs. recortes, tributación progresiva, filantropía (cofundadores de Anthropic pledged 80% de su riqueza).
### 5. Efectos indirectos — «Black seas of infinity»
- Avances rápidos en biología podrían traer extensión radical de vida o modificación de inteligencia humana.
- Riesgo de «psicosis por IA», relaciones románticas con IA, y personas «puppeteadas» por sistemas de IA.
- La pregunta existencial del propósito humano en un mundo donde la IA es mejor en todo.
## Principios transversales
1. **Evitar el doomerismo** — ni profecía de salvación ni de destrucción. Ser pragmático y basado en evidencia.
2. **Reconocer la incertidumbre** — nada es inevitable, pero la probabilidad justifica acción.
3. **Intervenir quirúrgicamente** — empezar con transparencia, escalar según evidencia.
4. **No se puede detener la tecnología** — la fórmula es demasiado simple; si unos no la construyen, otros lo harán.
## Mi reflexión
El ensayo es notable por su honestidad inusual viniendo de un CEO de una empresa de IA. Amodei no minimiza los riesgos para vender optimismo, ni los exagera para parecer responsable. La metáfora del «país de genios en un datacenter» es poderosa porque hace tangible algo abstracto. La tensión entre empoderar democracias con IA y prevenir que esas mismas herramientas se vuelvan contra los ciudadanos es quizás el dilema más difícil que plantea.
---
## Referencias
- [The Adolescence of Technology](https://www.darioamodei.com/essay/the-adolescence-of-technology) — Dario Amodei, 2026. Ensayo original sobre los riesgos civilizatorios de la IA.
---
# Terraform Docker Example
Type: experiment
Status: seed
Summary: Reusable Terraform modules for managing Docker containers and AWS ECS Fargate, with progressive examples and local testing with LocalStack.
Concepts: terraform, infrastructure-as-code
## ¿Qué es?
Módulos Terraform reutilizables para gestionar contenedores Docker localmente y en AWS ECS Fargate. Incluye cuatro ejemplos progresivos que van desde contenedores básicos hasta testing de ECS con LocalStack.
Disponible como [código fuente](https://github.com/jonmatum/terraform-docker-example).
## Ejemplos
1. **Docker básico** — módulo de contenedores, networking y port mapping
2. **FastAPI + React** — aplicación full-stack con Dockerfiles personalizados
3. **Docker Compose** — la misma app para comparar enfoques
4. **ECS con LocalStack** — testing de AWS ECS sin costos
## Módulos incluidos
- **docker-container** — gestión de contenedores Docker locales con port mapping dinámico, variables de entorno y configuración de red
- **ecs-fargate** — clusters ECS, task definitions, servicios, CloudWatch Logs y Container Insights
## ¿Por qué importa?
Terraform y Docker Compose resuelven problemas diferentes. Este proyecto demuestra cuándo usar cada uno con ejemplos prácticos, y muestra cómo testear infraestructura AWS localmente con LocalStack antes de gastar en la nube.
## Referencias
- [Repositorio en GitHub](https://github.com/jonmatum/terraform-docker-example) — jonmatum, 2025. Código fuente, módulos y documentación.
- [Terraform Docker Provider](https://registry.terraform.io/providers/kreuzwerker/docker/latest/docs) — kreuzwerker, 2024. Documentación del provider.
- [LocalStack](https://docs.localstack.cloud/) — LocalStack, 2024. Emulador local de servicios AWS.
---
# Terraform AWS Serverless Modules
Type: experiment
Status: growing
Summary: Collection of Terraform modules for deploying serverless and container-based applications on AWS, following the Well-Architected Framework.
Concepts: infrastructure-as-code, serverless, aws, terraform
## ¿Qué es?
Una colección de 13 módulos Terraform reutilizables para desplegar arquitecturas serverless en AWS. Publicados en el [Terraform Registry](https://registry.terraform.io/modules/jonmatum/serverless-modules/aws) y disponibles como open source.
El objetivo es demostrar patrones de arquitectura serverless con las mejores prácticas del AWS Well-Architected Framework: seguridad, confiabilidad, excelencia operacional, rendimiento y optimización de costos.
## Módulos
| Módulo | Descripción |
|--------|-------------|
| **vpc** | VPC Multi-AZ con NAT gateways, VPC endpoints, flow logs |
| **ecr** | Container registry con encriptación, lifecycle policies, image scanning |
| **ecs** | Fargate service con auto-scaling, Container Insights, soporte Spot |
| **lambda** | Funciones Lambda con container images, DLQ, retry policies |
| **alb** | Application Load Balancer con access logs, HTTPS, health checks |
| **sqs** | Colas de mensajes FIFO, DLQ, encriptación, long polling |
| **sns** | Pub/sub con suscripciones a Email, SQS, Lambda y filtrado |
| **dynamodb** | Base de datos NoSQL con encriptación, PITR, auto-scaling |
| **api-gateway** | HTTP API (v2) con throttling, logging, X-Ray |
| **api-gateway-v1** | REST API con soporte OpenAPI/Swagger, VPC Link |
| **cloudfront-s3** | CDN + hosting estático con SPA routing, OAC |
| **waf** | Web Application Firewall con rate limiting, IP filtering |
| **cloudwatch-alarms** | Monitoreo de CPU, memoria, response time, error rates |
## Patrones de arquitectura
**ECS con ALB:**
```mermaid
graph LR
A[Client] --> B[ALB]
B --> C[ECS Tasks 1-N]
C --> D[ECR]
```
**API Gateway con VPC Link:**
```mermaid
graph LR
A[Client] --> B[API Gateway]
B --> C[VPC Link]
C --> D[Private ALB]
D --> E[ECS Tasks]
```
**CRUD API:**
```mermaid
graph LR
A[Client] --> B[API Gateway]
B --> C[ECS Fargate]
C --> D[DynamoDB]
A --> E[CloudFront]
E --> F[S3 Static Site]
```
## Uso
```hcl
module "vpc" {
source = "jonmatum/serverless-modules/aws//modules/vpc"
version = "~> 2.0"
project_name = "my-app"
cidr_block = "10.0.0.0/16"
}
module "ecs" {
source = "jonmatum/serverless-modules/aws//modules/ecs"
version = "~> 2.0"
cluster_name = "my-cluster"
vpc_id = module.vpc.vpc_id
subnet_ids = module.vpc.private_subnet_ids
}
```
## Costos estimados
| Ambiente | Costo mensual | Configuración |
|----------|---------------|---------------|
| Desarrollo | $70-90 | Single NAT, Fargate Spot, 1 task |
| Staging | $150-200 | Single NAT, On-Demand, 2 tasks |
| Producción | $200-400 | Multi-AZ NAT, Auto-scaling 2-10 tasks |
## Referencias
- [Repositorio en GitHub](https://github.com/jonmatum/terraform-aws-serverless-modules) — Código fuente de los módulos.
- [Terraform Registry](https://registry.terraform.io/modules/jonmatum/serverless-modules/aws) — Módulos publicados en el registro oficial de Terraform.
- [Documentación Well-Architected](https://github.com/jonmatum/terraform-aws-serverless-modules/tree/main/docs/well-architected.md) — Mapeo de decisiones al Well-Architected Framework.
---
# Terminal UI
Type: experiment
Status: seed
Summary: Terminal-style design system with Matrix and TRON themes, Konami code integration, and micro frontend support. Published on npm as @jonmatum/terminal-ui.
Concepts: cli-design, developer-experience
## ¿Qué es?
Un sistema de diseno estilo terminal con temas Matrix (verde) y TRON (cian), integración del código Konami y componentes React con TypeScript.
Incluye componentes como ThemeProvider, Button, Card, Input y Text, además de hooks como `useTheme` y `useKonami`.
## Características
- **Sistema dual de temas** — Matrix (verde neón) y TRON (cian)
- **Código Konami** — `arriba arriba abajo abajo izquierda derecha izquierda derecha B A` para alternar temas
- **Estética terminal** — fuentes monoespaciadas, efectos de brillo y estilo retro
- **TypeScript first** — seguridad de tipos completa
- **Micro frontend ready** — ideal para arquitecturas de app shell
- **Builds rápidos** — tsup + esbuild
## ¿Por qué importa?
Explora cómo un sistema de diseno puede tener personalidad sin sacrificar funcionalidad. Los temas Matrix y TRON demuestran que los design tokens y CSS custom properties permiten transformaciones visuales radicales manteniendo la misma API de componentes.
## Referencias
- [Repositorio en GitHub](https://github.com/jonmatum/terminal-ui-poc) — jonmatum, 2025. Código fuente y documentación.
---
# Slidev Serverless First
Type: experiment
Status: seed
Summary: Slidev presentation on 10 reasons to adopt a serverless-first architecture. Deployed on GitHub Pages.
Concepts: serverless, developer-experience
## ¿Qué es?
Una presentación creada con [Slidev](https://sli.dev/) que expone 10 razones para adoptar una arquitectura serverless-first. Slidev permite crear slides interactivos usando Markdown, Vue.js y Tailwind CSS.
Disponible como [presentación en vivo](https://jonmatum.github.io/slidev-serverless-first/) y como [código fuente](https://github.com/jonmatum/slidev-serverless-first).
## ¿Por qué importa?
Serverless-first no es solo una decisión técnica — es una estrategia de negocio. La presentación cubre escalabilidad, costos, velocidad de desarrollo y las mejores prácticas para equipos que quieren adoptar este enfoque.
También sirve como ejemplo de cómo usar Slidev para presentaciones técnicas con código en vivo, componentes Vue y despliegue estático.
## Stack técnico
- **[Slidev](https://sli.dev/)**: framework de presentaciones basado en Markdown y Vue.js
- **GitHub Pages**: hosting estático gratuito con despliegue automático
- **Tailwind CSS**: estilos de los slides
## Referencias
- [Presentación en vivo](https://jonmatum.github.io/slidev-serverless-first/) — jonmatum, 2025. Slides interactivos.
- [Repositorio en GitHub](https://github.com/jonmatum/slidev-serverless-first) — jonmatum, 2025. Código fuente.
- [Slidev](https://sli.dev/) — Anthony Fu, 2021. Framework de presentaciones para desarrolladores.
---
# Serverless Lab
Type: experiment
Status: seed
Summary: Personal lab for serverless architecture experiments: prototypes, patterns, and learnings about event-driven applications on AWS.
Concepts: serverless, aws-sam
## ¿Qué es?
Un laboratorio personal para experimentar con arquitecturas serverless. Contiene experimentos, prototipos y aprendizajes sobre cómo construir aplicaciones escalables y event-driven sin gestionar servidores.
Disponible como [código fuente](https://github.com/jonmatum/serverless).
## Experimentos incluidos
- **API REST con Lambda + API Gateway**: endpoints CRUD con [AWS SAM](/concepts/aws-sam)
- **Procesamiento de eventos**: funciones disparadas por [SQS](/concepts/aws-sqs) y [EventBridge](/concepts/aws-eventbridge)
- **Step Functions**: workflows de múltiples pasos con manejo de errores
- **Infraestructura como código**: todo definido en templates SAM/CloudFormation
## Lecciones aprendidas
El modelo serverless cambia fundamentalmente cómo se piensa en la infraestructura: en lugar de provisionar capacidad, se define comportamiento. El costo escala linealmente con el uso real, lo que lo hace ideal para cargas variables o proyectos en etapa temprana.
## ¿Por qué importa?
Documenta la transición de administrador de sistemas — configurando servidores como copos de nieve — a construir sistemas desechables, autoconfigurados y enfocados en crear software.
## Referencias
- [Repositorio en GitHub](https://github.com/jonmatum/serverless) — jonmatum, 2024. Código fuente y experimentos.
---
# React MFE Template
Type: experiment
Status: seed
Summary: Reusable template for creating micro frontends with React, TypeScript, Tailwind CSS, and Vite. Includes design system, testing, and CI/CD.
Concepts: monorepos, micro-frontends, react
## ¿Qué es?
Una plantilla reutilizable para crear micro frontends con React, TypeScript, Tailwind CSS y Vite. Diseñada para funcionar con el [React MFE Shell](/experimentos/react-mfe-shell) como shell de aplicación.
Incluye configuración de ESLint, Prettier, pre-commit hooks, Vitest, tsup para builds de librería y release-please para versionado automatizado.
## Características
- **Vite + React + TypeScript** — setup moderno con HMR
- **Tailwind CSS** — utilidades de estilo integradas
- **Dual build** — aplicación (Vite) y librería (tsup)
- **Testing** — Vitest con configuración lista
- **CI/CD** — GitHub Actions y release-please
- **Pre-commit** — hooks para linting y formateo
## ¿Por qué importa?
Reduce el tiempo de setup de un nuevo micro frontend de horas a minutos. La plantilla incluye todas las convenciones del equipo — linting, testing, builds, CI/CD — para que cada nuevo MFE arranque con los mismos estándares.
## Referencias
- [Repositorio en GitHub](https://github.com/jonmatum/react-mfe-template) — jonmatum, 2025. Código fuente y guía de uso.
---
# React MFE Shell
Type: experiment
Status: seed
Summary: Micro frontend shell with a complete design system, 24 components, 666 tests, and WCAG AA compliance. Published on npm as @jonmatum/react-mfe-shell.
Concepts: monorepos, micro-frontends, react
## ¿Qué es?
Un shell de micro frontends listo para producción con un sistema de diseno integral, componentes de formulario y accesibilidad como prioridad. Publicado en npm como [`@jonmatum/react-mfe-shell`](https://www.npmjs.com/package/@jonmatum/react-mfe-shell).
El proyecto incluye 14 componentes atómicos y 10 moleculares, siguiendo principios de diseno atómico con TypeScript estricto y Tailwind CSS.
## Componentes
### Atómicos (14)
Avatar, Badge, Button, Code, Divider, FeatureChip, Heading, Icon, Input, Label, LoadingSpinner, Paragraph, Switch y Text.
### Moleculares (10)
Card, Checkbox, FileUpload, FormField, Modal, Radio, SearchBox, Select, SwitchField y Textarea.
## Características clave
- **666 tests** con cobertura superior al 75%
- **WCAG AA** — cumplimiento completo de accesibilidad
- **Sistema de temas** — modos claro, oscuro y sistema con persistencia
- **Design tokens** — colores, espaciado y tipografía consistentes
- **Tree shakeable** — importa solo lo que necesitas
- **Tres modos de integración** — zero-config, preset de Tailwind o CSS-in-JS
## ¿Por qué importa?
Demuestra cómo construir un sistema de diseno compartido para arquitecturas de micro frontends con estándares de producción: accesibilidad, temas, validación de formularios y métricas automatizadas de calidad.
## Referencias
- [Repositorio en GitHub](https://github.com/jonmatum/react-mfe-shell) — jonmatum, 2025. Código fuente y documentación.
- [Paquete en npm](https://www.npmjs.com/package/@jonmatum/react-mfe-shell) — jonmatum, 2025. Paquete publicado.
- [Demo interactivo](https://jonmatum.github.io/react-mfe-shell/) — jonmatum, 2025. Showcase de componentes.
---
# React MFE Shell Demo
Type: experiment
Status: seed
Summary: Interactive demo application for the React MFE Shell design system with PWA support, automated metrics, and component showcase.
Concepts: monorepos, micro-frontends, react
## ¿Qué es?
Una aplicación de demostración interactiva que muestra todos los componentes del sistema de diseno [React MFE Shell](/experimentos/react-mfe-shell). Incluye soporte PWA, métricas automatizadas y un showcase completo de componentes atómicos y moleculares.
Disponible como [demo en vivo](https://jonmatum.github.io/react-mfe-shell-demo/) y como [código fuente](https://github.com/jonmatum/react-mfe-shell-demo).
## Características
- **Showcase completo** — todos los componentes atómicos y moleculares en acción
- **PWA** — funciona offline con service worker
- **Métricas en tiempo real** — estadísticas de bundle, tests y cobertura
- **Temas** — demostración de cambio entre modo claro y oscuro
- **Release-please** — versionado automatizado
## ¿Por qué importa?
Demuestra cómo documentar un sistema de diseño con una aplicación interactiva en lugar de documentación estática. Las métricas automatizadas garantizan que los datos mostrados siempre reflejan el estado real del paquete publicado en npm.
## Referencias
- [Demo en vivo](https://jonmatum.github.io/react-mfe-shell-demo/) — jonmatum, 2025. Showcase interactivo.
- [Repositorio en GitHub](https://github.com/jonmatum/react-mfe-shell-demo) — jonmatum, 2025. Código fuente.
---
# React Headless Menu
Type: experiment
Status: seed
Summary: Headless menu component for React with full accessibility, zero styles, and keyboard support. Published on npm.
Concepts: react, accessibility
## ¿Qué es?
Un componente de menú headless para React — proporciona toda la lógica de interacción (navegación por teclado, ARIA, focus management) sin imponer estilos visuales. Publicado en npm y disponible como [código fuente](https://github.com/jonmatum/react-headless-menu).
## Características
- **Headless** — cero estilos, control total del diseño
- **Accesible** — ARIA roles, navegación por teclado, focus management
- **Playground** — entorno de pruebas interactivo incluido
- **Release-please** — versionado automatizado
- **Tailwind CSS** — ejemplo de integración incluido
## ¿Por qué importa?
Los componentes headless separan la lógica de la presentación. Esto permite reutilizar la misma lógica de menú accesible en proyectos con sistemas de diseño completamente diferentes, sin luchar contra estilos predefinidos.
## Lecciones aprendidas
Implementar [accesibilidad](/concepts/accessibility) correctamente en menús requiere gestionar focus trapping, navegación por teclado y roles ARIA. Un componente headless encapsula toda esa complejidad y la hace reutilizable.
## Referencias
- [Repositorio en GitHub](https://github.com/jonmatum/react-headless-menu) — jonmatum, 2024. Código fuente y playground.
---
# Pipenv Pytest Example
Type: experiment
Status: seed
Summary: Python project example with Pipenv, Pytest, pre-commit hooks, CI/CD with GitHub Actions, and badge generation.
Concepts: devops-practices, testing-strategies
## ¿Qué es?
Un ejemplo de proyecto Python con Pipenv para gestión de dependencias, Pytest para testing, pre-commit hooks para calidad de código, CI/CD con GitHub Actions y generación automatizada de badges de cobertura.
Disponible como [código fuente](https://github.com/jonmatum/pipenv-pytest-example).
## Stack técnico
- **Pipenv**: gestión de dependencias y entornos virtuales con `Pipfile` y `Pipfile.lock`
- **Pytest**: framework de testing con fixtures, parametrize y plugins
- **Pre-commit**: hooks que ejecutan linters y formatters antes de cada commit
- **GitHub Actions**: pipeline de CI que ejecuta tests y genera badges de cobertura
- **Coverage.py**: medición de cobertura de código con reporte en badge
## Lecciones aprendidas
La combinación de Pipenv + Pytest ofrece un flujo de trabajo limpio para proyectos Python. Los pre-commit hooks atrapan errores antes de que lleguen al CI, reduciendo el ciclo de feedback. Los badges de cobertura generados automáticamente incentivan mantener la calidad del código.
## Referencias
- [Repositorio en GitHub](https://github.com/jonmatum/pipenv-pytest-example) — jonmatum, 2024. Código fuente y configuración.
---
# My React Library
Type: experiment
Status: seed
Summary: Boilerplate for creating React libraries with TypeScript, Rollup, Jest, Tailwind CSS, Husky, and npm publishing.
Concepts: react, design-systems
## ¿Qué es?
Un boilerplate para crear librerías React con TypeScript, Rollup para builds, Jest para testing, Tailwind CSS para estilos, Husky para pre-commit hooks y configuración para publicación en npm.
Disponible como [código fuente](https://github.com/jonmatum/my-react-library).
## Stack técnico
- **[TypeScript](/concepts/typescript)**: tipado estricto para componentes exportables
- **Rollup**: bundler optimizado para librerías (tree-shaking, ESM + CJS)
- **Jest**: testing de componentes con React Testing Library
- **[Tailwind CSS](/concepts/tailwindcss)**: estilos utility-first incluidos en el bundle
- **Husky**: pre-commit hooks para lint y tests antes de publicar
## Lecciones aprendidas
Rollup produce bundles más pequeños que Webpack para librerías porque elimina código muerto de forma más agresiva. La configuración de Tailwind requiere cuidado para no incluir estilos innecesarios en el paquete publicado. Publicar en npm con `prepublishOnly` scripts que ejecutan build + test garantiza que solo se publiquen versiones verificadas.
## Referencias
- [Repositorio en GitHub](https://github.com/jonmatum/my-react-library) — jonmatum, 2024. Código fuente y configuración.
---
# My Devcontainer
Type: experiment
Status: seed
Summary: Personal development environment with devcontainer, Docker Compose, Python backend, and React frontend.
Concepts: devcontainers, local-development
## ¿Qué es?
Mi configuración personal de devcontainer con Docker Compose, un backend Python y un frontend React. Incluye un Makefile extenso (21KB) para automatizar tareas de desarrollo.
Disponible como [código fuente](https://github.com/jonmatum/my-devcontainer).
## Stack técnico
- **[Devcontainers](/concepts/devcontainers)**: configuración reproducible del entorno de desarrollo
- **[Docker Compose](/concepts/docker-compose)**: orquestación de servicios (backend, frontend, base de datos)
- **Makefile**: 21KB de automatización — build, test, lint, deploy en un solo comando
- **Python backend**: API con dependencias gestionadas por Pipenv
- **React frontend**: SPA con hot reload dentro del contenedor
## Lecciones aprendidas
Un Makefile extenso compensa la complejidad de Docker Compose para desarrollo diario. Los targets bien nombrados (`make dev`, `make test`, `make lint`) reducen la curva de aprendizaje para nuevos colaboradores. Separar backend y frontend en servicios distintos de Compose permite reiniciar uno sin afectar al otro durante el desarrollo.
## Referencias
- [Repositorio en GitHub](https://github.com/jonmatum/my-devcontainer) — jonmatum, 2024. Código fuente.
---
# MCP Dual Interface Demo
Type: experiment
Status: growing
Summary: Demonstration of dual-interface architecture where the same business logic serves both a traditional web application and an MCP server for AI tools.
Concepts: mcp, ai-agents, spec-driven-development
## La idea
La mayoría de los equipos construyen aplicaciones para humanos y luego, cuando quieren integrar IA, crean una capa separada encima: wrappers, adaptadores, APIs intermedias. Esto genera acoplamiento, duplicación y puntos de fallo en cascada.
Este experimento explora una alternativa: **construir desde el inicio con dos interfaces que comparten la misma lógica de negocio**. Una interfaz para humanos (web app) y otra para agentes de IA (servidor MCP), ambas accediendo directamente a la misma capa de datos.
## ¿Por qué importa?
El [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) es un estándar abierto que permite a los LLMs interactuar con herramientas externas de forma estructurada. En lugar de que un agente de IA tenga que navegar una UI o parsear HTML, el servidor MCP expone operaciones como herramientas tipadas que el modelo puede invocar directamente.
La pregunta clave que este experimento responde es: **¿se puede diseñar una aplicación donde la interfaz humana y la interfaz de IA sean ciudadanos de primera clase desde el día uno, sin que una sea un parche sobre la otra?**
## Arquitectura
```mermaid
graph TB
subgraph "Interfaz humana"
A[React Frontend] --> B[FastAPI REST API]
end
subgraph "Interfaz IA"
C[Kiro CLI / LLM] --> D[Servidor MCP - stdio]
end
subgraph "Capa compartida"
E[Lógica de negocio todo_service.py]
end
subgraph "Datos"
F[(DynamoDB)]
end
B --> E
D --> E
E --> F
```
Los principios clave de la arquitectura:
- **Acoplamiento débil**: cada servicio accede a DynamoDB directamente, sin depender del otro
- **Código compartido**: la lógica de negocio vive en un módulo `shared/` que ambas interfaces importan
- **Escalamiento independiente**: la API REST y el servidor MCP pueden escalar por separado
- **Sin fallos en cascada**: si la API REST cae, el servidor MCP sigue funcionando y viceversa
## Stack técnico
| Componente | Tecnología |
|---|---|
| API REST | FastAPI + Python 3.11 |
| Servidor MCP | Python MCP SDK (transporte stdio) |
| Frontend | React 19 + TypeScript + Vite + Tailwind CSS |
| Base de datos | DynamoDB Local |
| Lógica compartida | Módulo Python (`shared/`) |
| Orquestación | Docker Compose |
## ¿Cómo funciona?
El módulo `shared/todo_service.py` contiene toda la lógica de negocio: crear, listar, actualizar y eliminar tareas. Tanto la API REST (`backend/main.py`) como el servidor MCP (`mcp-server/server.py`) instancian `TodoService` con la misma tabla de DynamoDB.
La API REST expone endpoints HTTP convencionales:
```
POST /todos → crear tarea
GET /todos → listar tareas
GET /todos/{id} → obtener tarea
PATCH /todos/{id} → actualizar tarea
DELETE /todos/{id} → eliminar tarea
```
El servidor MCP expone las mismas operaciones como herramientas tipadas que un LLM puede invocar:
```
create_todo → crear tarea
list_todos → listar tareas
get_todo → obtener tarea
update_todo → actualizar tarea
delete_todo → eliminar tarea
```
Ambas interfaces ejecutan exactamente la misma lógica. No hay duplicación de reglas de negocio.
## Mapeo a AWS
La arquitectura local se traduce directamente a servicios de AWS para producción:
| Local | AWS |
|---|---|
| DynamoDB Local | DynamoDB |
| FastAPI | Lambda + API Gateway o ECS/Fargate |
| Servidor MCP | Lambda o ECS Task |
| React Frontend | S3 + CloudFront o Amplify |
| Módulo compartido | Lambda Layer o paquete compartido |
## Lecciones aprendidas
1. **El transporte stdio es simple pero limitante**: funciona bien para desarrollo local con Kiro CLI, pero para producción se necesitaría SSE o WebSocket para soportar múltiples clientes concurrentes.
2. **La capa compartida es el patrón más valioso**: separar la lógica de negocio en un módulo independiente de la interfaz es lo que hace posible la arquitectura dual sin duplicación.
3. **DynamoDB simplifica el acceso directo**: al no necesitar un ORM complejo ni migraciones, ambos servicios pueden acceder a la misma tabla con configuración mínima.
## Referencias
- [Repositorio en GitHub](https://github.com/jonmatum/mcp-dual-interface-demo) — Código fuente del experimento.
- [Model Context Protocol — Especificación](https://modelcontextprotocol.io/) — Anthropic. Especificación oficial del protocolo.
- [Python MCP SDK](https://github.com/modelcontextprotocol/python-sdk) — Anthropic. Implementación de referencia en Python.
- [FastAPI](https://fastapi.tiangolo.com/) — Tiangolo. Framework web usado para la interfaz REST.
---
# Git Metrics MCP Server
Type: experiment
Status: seed
Summary: MCP server for analyzing git repository metrics and understanding team health. Published on npm as @jonmatum/git-metrics-mcp-server.
Concepts: mcp, ai-agents
## ¿Qué es?
Un servidor [MCP](/conceptos/mcp) que extrae métricas significativas de repositorios Git para ayudar a los equipos a comprender sus patrones de desarrollo, identificar riesgos tempranamente y tener mejores conversaciones sobre calidad de código y salud del equipo.
Publicado en npm como [`@jonmatum/git-metrics-mcp-server`](https://www.npmjs.com/package/@jonmatum/git-metrics-mcp-server) y disponible como [open source](https://github.com/jonmatum/git-metrics-mcp-server).
> Esto es un espejo, no un microscopio. Sirve para reflexionar sobre la salud del equipo y la calidad del proceso, no para vigilar el comportamiento individual.
## ¿Qué herramientas ofrece?
El servidor expone 11 herramientas MCP que se pueden invocar con lenguaje natural:
- **get_commit_stats** — Estadísticas generales de commits por período
- **get_author_metrics** — Métricas detalladas por contribuidor
- **get_file_churn** — Archivos con más cambios (indicadores de complejidad)
- **get_team_summary** — Reporte integral del rendimiento del equipo
- **get_commit_patterns** — Análisis de cuándo se hacen commits (detección de burnout)
- **get_code_ownership** — Bus factor y distribución de conocimiento
- **get_velocity_trends** — Seguimiento de velocidad semanal/mensual
- **get_collaboration_metrics** — Patrones de interacción del equipo
- **get_quality_metrics** — Indicadores de calidad de código
- **get_technical_debt** — Archivos obsoletos y hotspots de complejidad
- **get_conventional_commits** — Análisis de commits convencionales y frecuencia de releases
## Características de producción
- Sanitización de entrada contra inyección de comandos
- Logging estructurado en JSON con timestamps
- Timeouts configurables vía variable de entorno `GIT_TIMEOUT`
- Manejo de errores con boundaries y logging detallado
- CI/CD con GitHub Actions
## ¿Por qué importa?
Las métricas de Git son una fuente infrautilizada de señales sobre la salud del equipo. Este servidor permite hacer preguntas en lenguaje natural como «¿cuál es nuestro bus factor?» o «¿la gente está haciendo commits de noche?» y obtener respuestas estructuradas sin parsear logs manualmente.
## Referencias
- [Repositorio en GitHub](https://github.com/jonmatum/git-metrics-mcp-server) — jonmatum, 2025. Código fuente y documentación.
- [Paquete en npm](https://www.npmjs.com/package/@jonmatum/git-metrics-mcp-server) — jonmatum, 2025. Paquete publicado para instalación global.
- [Model Context Protocol](https://modelcontextprotocol.io/) — Anthropic, 2024. Especificación del protocolo MCP.
---
# DraftMK Copier Templates
Type: experiment
Status: seed
Summary: Copier templates for project scaffolding with Docker Compose, MkDocs documentation, and automated configuration.
Concepts: devops-practices, documentation-as-code
## ¿Qué es?
Plantillas [Copier](https://copier.readthedocs.io/) para generar proyectos con Docker Compose, documentación MkDocs y configuración automatizada mediante Jinja templates.
Disponible como [código fuente](https://github.com/jonmatum/draftmk-copier-templates).
## Stack técnico
- **[Copier](https://copier.readthedocs.io/)**: motor de scaffolding basado en Jinja2 con soporte para actualizaciones
- **Jinja2 templates**: generación dinámica de archivos según respuestas del usuario
- **[Docker Compose](/concepts/docker-compose)**: configuración de servicios incluida en el scaffold
- **MkDocs**: documentación del proyecto generada automáticamente con Material theme
- **GitHub Actions**: CI para validar que las plantillas generan proyectos correctos
## Lecciones aprendidas
Copier supera a Cookiecutter en un aspecto clave: permite actualizar proyectos existentes cuando la plantilla evoluciona con `copier update`. Las plantillas Jinja2 con condicionales permiten generar configuraciones muy diferentes desde un solo template. La combinación de Docker Compose para servicios y MkDocs para [documentación](/concepts/documentation-as-code) crea un scaffold completo que los equipos pueden usar desde el primer día sin configuración adicional.
## Referencias
- [Repositorio en GitHub](https://github.com/jonmatum/draftmk-copier-templates) — jonmatum, 2024. Código fuente y plantillas.
---
# Devcontainer Serverless Fullstack Template
Type: experiment
Status: seed
Summary: Devcontainer template for serverless fullstack development with Python backend, React frontend, and local AWS services.
Concepts: devcontainers, serverless
## ¿Qué es?
Una plantilla de devcontainer para desarrollo fullstack serverless. Incluye un backend Python, un frontend React y servicios AWS locales mediante Docker Compose, todo preconfigurado para funcionar dentro de un contenedor de desarrollo.
Disponible como [código fuente](https://github.com/jonmatum/devcontainer-serverless-fullstack-template).
## Características
- **Backend Python** — configuración lista para APIs serverless
- **Frontend React** — setup moderno con hot reload
- **Docker Compose** — orquestación de servicios locales
- **Seguridad** — guía SECURITY.md incluida
- **Makefile** — automatización de tareas comunes (24KB de targets)
## ¿Por qué importa?
Elimina la fricción de configurar un entorno de desarrollo fullstack serverless. Un solo `devcontainer.json` y todo el equipo tiene el mismo entorno reproducible — sin «funciona en mi máquina». Incluye AWS SAM CLI, Node.js y Python preconfigurados para desarrollo inmediato.
## Referencias
- [Repositorio en GitHub](https://github.com/jonmatum/devcontainer-serverless-fullstack-template) — jonmatum, 2024. Código fuente y documentación.
- [Dev Containers Specification](https://containers.dev/) — Microsoft, 2022. Especificación de contenedores de desarrollo.
---
# Devcontainer Minimal Template
Type: experiment
Status: seed
Summary: Minimal devcontainer template for quickly starting projects with a clean base configuration.
Concepts: devcontainers, local-development
## ¿Qué es?
Una plantilla mínima de devcontainer para iniciar proyectos rápidamente. Solo incluye lo esencial: un `devcontainer.json`, LICENSE y README.
Disponible como [código fuente](https://github.com/jonmatum/devcontainer-minimal-template).
## Contenido
- **`devcontainer.json`**: configuración base con imagen, extensiones de VS Code y settings
- **LICENSE**: MIT por defecto
- **README**: instrucciones de uso
## Filosofía
La plantilla sigue el principio de mínima configuración: solo lo necesario para abrir un proyecto en un [devcontainer](/concepts/devcontainers) funcional. Cualquier personalización — lenguaje, herramientas, servicios — se añade según las necesidades del proyecto, no por anticipación.
## Lecciones aprendidas
Empezar con lo mínimo y añadir incrementalmente produce configuraciones más limpias que partir de una plantilla compleja y eliminar lo que sobra. Esta plantilla sirve como punto de partida para proyectos nuevos donde los requisitos aún no están claros. Cuando el proyecto madura, se pueden añadir features de devcontainer, servicios de Docker Compose y herramientas específicas del lenguaje.
## Referencias
- [Repositorio en GitHub](https://github.com/jonmatum/devcontainer-minimal-template) — jonmatum, 2024. Código fuente.
---
# Devcontainer Features
Type: experiment
Status: seed
Summary: Collection of custom Dev Container features with automated testing, CI/CD, and GitHub Container Registry publishing.
Concepts: devcontainers, local-development
## ¿Qué es?
Una colección de features personalizados para [Dev Containers](https://containers.dev/) con testing automatizado, CI/CD mediante GitHub Actions y publicación en GitHub Container Registry.
Disponible como [código fuente](https://github.com/jonmatum/devcontainer-features).
## Características
- **Features reutilizables** — instalables en cualquier devcontainer
- **Testing automatizado** — suite de tests para cada feature
- **CI/CD** — GitHub Actions para validación y publicación
- **Sandbox** — entorno de pruebas aislado
- **Makefile** — automatización de desarrollo y testing
- **Versionado semántico** — cada feature publicado con versión independiente
## ¿Por qué importa?
Los Dev Container features permiten modularizar la configuración de entornos de [desarrollo local](/concepts/local-development). En lugar de un Dockerfile monolítico, cada herramienta o configuración es un feature independiente, testeable y reutilizable entre proyectos. Esto reduce la duplicación de configuración entre repositorios y facilita mantener las herramientas actualizadas desde un solo lugar.
## Referencias
- [Repositorio en GitHub](https://github.com/jonmatum/devcontainer-features) — jonmatum, 2024. Código fuente y documentación.
- [Dev Container Features](https://containers.dev/implementors/features/) — Microsoft, 2022. Especificación de features.
---
# Devcontainer Amazon Linux Workspace
Type: experiment
Status: seed
Summary: Amazon Linux-based devcontainer template for AWS-compatible development environments.
Concepts: devcontainers, local-development
## ¿Qué es?
Una plantilla de devcontainer basada en Amazon Linux para crear entornos de desarrollo compatibles con AWS. Ideal para equipos que despliegan en Amazon Linux y quieren paridad entre desarrollo y producción.
Disponible como [código fuente](https://github.com/jonmatum/devcontainer-amazonlinux-workspace-template).
## Motivación
Cuando el entorno de producción es Amazon Linux, desarrollar en Ubuntu o macOS introduce discrepancias sutiles: versiones de glibc, paths de sistema, paquetes disponibles. Esta plantilla elimina esas diferencias usando la misma base que producción.
## Contenido
- **Imagen base**: Amazon Linux 2023 con herramientas de desarrollo
- **AWS CLI**: preinstalado y configurado
- **Extensiones VS Code**: configuradas para desarrollo en AWS
- **Paridad dev/prod**: misma distribución que los entornos de despliegue
## Lecciones aprendidas
La paridad entre desarrollo y producción reduce los bugs de «funciona en mi máquina». Amazon Linux como base de devcontainer es viable pero requiere instalar más herramientas manualmente que con imágenes basadas en Debian.
## Referencias
- [Repositorio en GitHub](https://github.com/jonmatum/devcontainer-amazonlinux-workspace-template) — jonmatum, 2024. Código fuente.
---
# AxiSight: Organizational Maturity Assessment
Type: experiment
Status: growing
Summary: Web platform for organizational maturity assessment with a simplified 3-level scoring system, customizable frameworks, and real-time visualization.
Concepts: maturity-models, organizational-assessment, developer-experience
## El problema
Los [modelos de madurez](/concepts/maturity-models) existentes (CMMI, DORA, Spotify Health Check) comparten un problema común: son demasiado complejos para ser útiles en la práctica. Escalas de 5 niveles con criterios ambiguos, documentos de 200 páginas, y procesos de evaluación que requieren consultores externos. El resultado es que los equipos abandonan la evaluación antes de completarla, o peor, la completan sin reflexión real.
La complejidad no es una virtud cuando el objetivo es generar acción.
## La hipótesis
Un sistema de puntuación de 3 niveles (0, 1, 2) con criterios claros de éxito es suficiente para capturar el estado real de madurez de una organización y generar planes de acción concretos. La simplicidad reduce la fricción cognitiva y aumenta la tasa de completitud.
## AxiSight
[AxiSight](https://www.axisight.io/) es una plataforma web que implementa esta hipótesis. Corre completamente en el navegador, sin backend, sin cuentas, sin dependencias externas.
### Scoring Guide: 3 niveles, sin ambigüedad
| Score | Estado | Significado |
|-------|--------|-------------|
| 0 | Not Started | No hay implementación |
| 1 | Partial | Trabajo en progreso |
| 2 | Complete | Completamente implementado |
La decisión de usar solo 3 niveles es deliberada. Con escalas de 5 niveles, la diferencia entre un 3 y un 4 se vuelve subjetiva. Con 3 niveles, la pregunta es binaria en cada paso: ¿existe o no existe? ¿Está completo o no?
Cada ítem incluye criterios explícitos de qué constituye «Partial» y qué constituye «Complete», eliminando la interpretación subjetiva:
```typescript
interface MaturityItem {
key: string;
label: string;
description: string;
successCriteria: {
partial: string; // Qué significa score 1
complete: string; // Qué significa score 2
};
}
```
### Maturity Levels: del caos a la optimización
Los porcentajes agregados se mapean a 4 niveles de madurez:
| Rango | Nivel | Descripción |
|-------|-------|-------------|
| 0-30% | Initial / Prototype | Procesos ad-hoc, sin estandarización |
| 31-60% | Developing | Algunos procesos definidos, ejecución inconsistente |
| 61-85% | Established | Procesos bien definidos, ejecución consistente |
| 86-100% | Optimized | Mejora continua, prácticas de referencia en la industria |
### Frameworks personalizables
AxiSight viene con dos frameworks pre-construidos (Platform Engineering y Software Development), pero el valor real está en la capacidad de crear frameworks propios:
```typescript
const customModel: CustomMaturityModel = {
id: "mi-framework",
title: "Mi Framework de Madurez",
description: "Evaluación personalizada",
version: "1.0",
maxPerItem: 2,
storageKey: "mi-framework-v1",
sections: [
{
key: "seccion-1",
title: "1. Prácticas Core",
items: [
{
key: "item-1",
label: "Práctica a evaluar",
description: "Descripción detallada",
successCriteria: {
partial: "Implementación básica existe",
complete: "Implementación completa con métricas"
}
}
]
}
]
};
```
Los frameworks se pueden exportar e importar como JSON, lo que permite compartirlos entre equipos y organizaciones.
## ¿Por qué funciona?
La simplicidad del modelo de 3 niveles tiene ventajas concretas:
- **Velocidad**: Una evaluación completa toma 15-30 minutos, no días
- **Consenso**: Menos opciones significa menos debate sobre qué número asignar
- **Accionabilidad**: Cada ítem con score 0 o 1 es un candidato directo para mejora
- **Repetibilidad**: Evaluaciones frecuentes (mensuales o trimestrales) son viables porque el costo es bajo
## Decisiones técnicas
- **Client-side only**: Todo corre en el navegador. localStorage para persistencia, JSON export/import para compartir. Zero backend, zero costos de infraestructura
- **PWA**: Funciona offline para evaluaciones en sitios sin conectividad
- **React + TypeScript + Vite**: Stack moderno con type safety completo
- **Recharts**: Visualización interactiva con radar charts por sección
## Estado actual
La plataforma está funcional con dos frameworks completos. El siguiente paso es validar el modelo con más equipos y refinar los criterios de éxito basándose en feedback real.
## Referencias
- [axisight.io](https://www.axisight.io/) — Plataforma pública de evaluación de madurez.
---
# Zero Trust
Type: concept
Status: seed
Summary: Security model that doesn't implicitly trust any user or system, verifying every request regardless of its origin inside or outside the network.
Concepts: devsecops, aws-iam
## ¿Qué es?
Zero Trust es un modelo de seguridad basado en «nunca confiar, siempre verificar». A diferencia del modelo tradicional de perímetro (confiar en todo dentro de la red), Zero Trust verifica cada request independientemente de su origen.
## Principios
- **Verificar explícitamente**: autenticar y autorizar cada request
- **Mínimo privilegio**: dar solo los permisos necesarios
- **Asumir breach**: diseñar como si el atacante ya estuviera dentro
## Pilares
- **Identidad**: autenticación fuerte (MFA, passwordless)
- **Dispositivos**: verificar estado y compliance del dispositivo
- **Red**: microsegmentación, no confiar en la red interna
- **Aplicaciones**: acceso basado en identidad, no en red
- **Datos**: clasificación y protección de datos sensibles
## Implementación
- Identity-aware proxies (BeyondCorp, Cloudflare Access)
- Service mesh con mTLS
- Políticas de acceso basadas en contexto
- Logging y monitoreo exhaustivo
## Modelo perimetral vs zero trust
| Aspecto | Perímetro tradicional | Zero Trust |
|---------|----------------------|------------|
| Confianza | Implícita dentro de la red | Ninguna — verificar siempre |
| Acceso | VPN + firewall | Identity-aware proxy |
| Segmentación | VLANs, subnets | Microsegmentación por servicio |
| Autenticación | Una vez (al entrar a la red) | Cada request |
| Lateral movement | Fácil una vez dentro | Bloqueado por defecto |
| Trabajo remoto | Requiere VPN | Nativo — la ubicación es irrelevante |
## Pasos de adopción
1. **Inventario de identidades**: mapear usuarios, servicios y dispositivos
2. **MFA en todo**: autenticación multifactor como requisito, no como opción
3. **Microsegmentación**: aislar servicios con [service mesh](/concepts/service-mesh) y mTLS
4. **Políticas de acceso contextual**: evaluar identidad + dispositivo + ubicación + hora
5. **Monitoreo continuo**: detectar anomalías en patrones de acceso
## ¿Por qué importa?
El modelo de seguridad perimetral asume que todo dentro de la red es confiable. Zero trust elimina esa suposición: cada request se autentica y autoriza independientemente de su origen. Es el modelo de seguridad que refleja la realidad de sistemas distribuidos y trabajo remoto.
## Referencias
- [BeyondCorp](https://cloud.google.com/beyondcorp) — Implementación de Google.
- [NIST Zero Trust Architecture](https://csrc.nist.gov/publications/detail/sp/800-207/final) — SP 800-207.
- [CISA Zero Trust Maturity Model](https://www.cisa.gov/zero-trust-maturity-model) — CISA, 2023. Modelo de madurez para implementación de zero trust.
---
# Web Components
Type: concept
Status: seed
Summary: Native web standards for creating reusable, encapsulated components that work in any framework or without one.
Concepts: micro-frontends, design-systems, react
## ¿Qué es?
Web Components son un conjunto de estándares web que permiten crear elementos HTML custom reutilizables con encapsulación de estilos y comportamiento. Funcionan en cualquier framework — o sin framework.
## Estándares
- **Custom Elements**: definir nuevos elementos HTML
- **Shadow DOM**: encapsulación de estilos y markup
- **HTML Templates**: templates declarativos reutilizables
## Cuándo usar
- Componentes compartidos entre frameworks diferentes
- [Micro frontends](/concepts/micro-frontends) con tecnologías mixtas
- [Design systems](/concepts/design-systems) framework-agnostic
- Widgets embebibles en sitios de terceros
## Frameworks basados en Web Components
| Framework | Autor | Tamaño | Enfoque |
|-----------|-------|--------|---------|
| Lit | Google | ~5 KB | Reactivo, declarativo, mínimo boilerplate |
| Stencil | Ionic | ~12 KB | Compilador que genera Web Components estándar |
| FAST | Microsoft | ~8 KB | Design system adaptable, Fluent UI |
## Limitaciones
- Shadow DOM dificulta el styling externo y la integración con frameworks CSS como Tailwind
- El server-side rendering (SSR) de Web Components es limitado comparado con frameworks como React o Vue
- La API nativa es verbosa — por eso existen frameworks como Lit que simplifican la autoría
## ¿Por qué importa?
Los Web Components son estándares del navegador que permiten crear elementos HTML reutilizables sin dependencia de frameworks. Son la opción cuando necesitas componentes que funcionen en cualquier contexto — React, Vue, Angular o vanilla HTML.
## Referencias
- [Web Components - MDN](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) — MDN, 2024. Documentación de referencia.
- [Lit](https://lit.dev/) — Google, 2024. Biblioteca ligera para crear Web Components.
- [Using Shadow DOM — MDN](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM) — MDN, 2024. Guía de Shadow DOM para encapsulación.
---
# Vulnerability Scanning
Type: concept
Status: seed
Summary: Automated process of identifying known vulnerabilities in code, dependencies, containers, and infrastructure before they reach production.
Concepts: devsecops, ci-cd, supply-chain-security
## ¿Qué es?
El escaneo de vulnerabilidades identifica automáticamente debilidades de seguridad conocidas en código, dependencias y configuraciones. Es un componente esencial de [DevSecOps](/concepts/devsecops).
## Tipos de escaneo
| Tipo | Qué analiza | Cuándo |
|------|-------------|--------|
| SAST | Código fuente | Pre-commit, CI |
| SCA | Dependencias | CI, scheduled |
| Container | Imágenes Docker | CI, registry |
| IaC | Terraform, CloudFormation | CI |
| DAST | Aplicación corriendo | Staging, prod |
## Herramientas
| Categoría | Qué escanea | Herramientas | Fase |
|-----------|------------|-------------|------|
| SAST | Código fuente | Semgrep, SonarQube, CodeQL | PR / build |
| SCA | Dependencias | Snyk, Dependabot, Trivy | PR + diario |
| Container | Imágenes de contenedores | Trivy, Grype, ECR scanning | Build de imagen |
| IaC | Infraestructura como código | Checkov, tfsec, KICS | PR / plan |
## Integración en CI/CD
```yaml
- scan-dependencies: snyk test
- scan-code: semgrep --config auto
- scan-container: trivy image myapp:latest
- gate: fail if critical vulnerabilities
```
## Shift left
El principio de «shift left» mueve el escaneo lo más temprano posible en el ciclo de desarrollo. Encontrar una vulnerabilidad en el IDE es 100x más barato que encontrarla en producción.
## ¿Por qué importa?
El escaneo de vulnerabilidades automatizado es la primera línea de defensa contra dependencias comprometidas e imágenes de contenedor inseguras. Integrado en el pipeline de CI/CD, detecta problemas antes de que lleguen a producción.
## Referencias
- [Trivy](https://trivy.dev/) — Aqua Security, 2024. Scanner multi-propósito open source.
- [Snyk](https://snyk.io/) — Snyk, 2024. Plataforma de seguridad para desarrolladores.
- [Trivy — GitHub](https://github.com/aquasecurity/trivy) — Aqua Security, 2024. Código fuente y documentación del scanner.
---
# Vector Databases
Type: concept
Status: seed
Summary: Storage systems specialized in indexing and searching high-dimensional vectors efficiently, enabling semantic search and RAG applications at scale.
Concepts: embeddings, semantic-search
## ¿Qué es?
Una base de datos vectorial es un sistema de almacenamiento optimizado para guardar, indexar y buscar vectores de alta dimensión — típicamente [embeddings](/concepts/embeddings) generados por modelos de IA. A diferencia de las bases de datos tradicionales que buscan por coincidencia exacta, las bases vectoriales encuentran los vectores más similares a una consulta.
Son la infraestructura fundamental para [búsqueda semántica](/concepts/semantic-search) y [RAG](/concepts/retrieval-augmented-generation) a escala.
## ¿Por qué no usar una base de datos tradicional?
Buscar el vector más cercano entre millones requiere comparar distancias con cada uno — O(n) por consulta. Las bases vectoriales usan índices aproximados (ANN — Approximate Nearest Neighbors) que reducen esto a O(log n) o mejor, sacrificando precisión perfecta por velocidad práctica.
## Algoritmos de indexación
- **HNSW (Hierarchical Navigable Small World)**: grafos navegables que permiten búsqueda eficiente. El más popular por su balance velocidad/precisión
- **IVF (Inverted File Index)**: particiona el espacio en clusters y busca solo en los más cercanos
- **PQ (Product Quantization)**: comprime vectores para reducir memoria, útil para datasets masivos
- **Flat**: búsqueda exacta sin índice — preciso pero lento, solo para datasets pequeños
## Opciones de bases vectoriales
### Bases dedicadas
| Base | Características |
|------|-----------------|
| Pinecone | Serverless, managed, fácil de empezar |
| Weaviate | Open-source, GraphQL, módulos de ML integrados |
| Qdrant | Open-source, Rust, filtros avanzados |
| Milvus | Open-source, escalable, CNCF project |
| Chroma | Open-source, embebible, ideal para prototipos |
### Extensiones de bases existentes
| Base | Extensión |
|------|-----------|
| PostgreSQL | pgvector |
| Elasticsearch | Dense vector field |
| Redis | Redis Stack (RediSearch) |
| MongoDB | Atlas Vector Search |
## Consideraciones de diseño
- **Dimensionalidad**: más dimensiones = más almacenamiento y cómputo. 1536 (OpenAI) vs 384 (MiniLM) hace diferencia a escala
- **Filtrado híbrido**: combinar búsqueda vectorial con filtros de metadatos (fecha, categoría, usuario)
- **Actualizaciones**: algunos índices son costosos de actualizar — considerar estrategias de batch
- **Consistencia**: muchas bases vectoriales priorizan disponibilidad sobre consistencia estricta
## Patrón típico de uso
```
1. Documento → Chunking → Embedding model → Vector
2. Vector + metadata → Vector DB (insert)
3. Query → Embedding model → Vector
4. Vector → Vector DB (search) → Top-K results
5. Results → LLM context → Response
```
## ¿Por qué importa?
Las bases de datos vectoriales son la infraestructura que hace posible la búsqueda semántica y RAG a escala. Elegir entre pgvector, Pinecone, Weaviate o Qdrant depende del volumen de datos, los requisitos de latencia y si ya tienes PostgreSQL en tu stack.
## Referencias
- [Efficient and robust approximate nearest neighbor search using HNSW](https://arxiv.org/abs/1603.09320) — Malkov & Yashunin, 2016. El paper de HNSW.
- [pgvector: Open-source vector similarity search for Postgres](https://github.com/pgvector/pgvector) — Extensión de PostgreSQL para vectores.
- [Qdrant Documentation](https://qdrant.tech/documentation/) — Qdrant, 2024. Base de datos vectorial de alto rendimiento.
---
# User Experience
Type: concept
Status: seed
Summary: Discipline encompassing every aspect of a person's interaction with a product, system, or service, aiming for usefulness, usability, and satisfaction.
Concepts: accessibility, design-systems, developer-experience
## ¿Qué es?
User Experience (UX) es la percepción total que tiene una persona al interactuar con un producto o servicio. No se limita a la interfaz visual — abarca utilidad, usabilidad, accesibilidad, rendimiento percibido y respuesta emocional.
El término fue acuñado por Don Norman en Apple (1993) para cubrir «todos los aspectos de la experiencia de una persona con un sistema».
## Dimensiones de UX
- **Utilidad**: ¿resuelve un problema real?
- **Usabilidad**: ¿se puede usar sin fricción?
- **Accesibilidad**: ¿funciona para personas con distintas capacidades?
- **Deseabilidad**: ¿genera una respuesta emocional positiva?
- **Rendimiento percibido**: ¿se siente rápido, aunque la operación tome tiempo?
## ¿Por qué importa en software?
Un producto técnicamente correcto pero difícil de usar fracasa igual que uno con bugs. La UX no es una capa cosmética que se añade al final — es una decisión arquitectónica que afecta retención, costos de soporte y velocidad de adopción. Interfaces claras generan menos tickets, reducen la curva de aprendizaje y permiten que los usuarios completen tareas sin documentación. La [accesibilidad](/concepts/accessibility) es parte fundamental de buena UX, no un extra opcional.
## UX vs UI
| UX | UI |
|----|-----|
| Estructura, flujos, arquitectura de información | Colores, tipografía, componentes visuales |
| ¿Qué problema resolvemos y cómo? | ¿Cómo se ve y se siente? |
| Investigación, prototipos, pruebas de usabilidad | [Sistemas de diseño](/concepts/design-systems), guías de estilo |
UI es un subconjunto de UX. Se puede tener buena UI con mala UX (bonito pero confuso), y buena UX con UI modesta (claro pero austero).
## Relación con DX
UX y [DX](/concepts/developer-experience) son la misma disciplina aplicada a audiencias distintas. Los principios son idénticos — reducir fricción, acortar feedback loops, documentar bien — pero UX se enfoca en usuarios finales y DX en desarrolladores.
## Referencias
- [The Design of Everyday Things](https://www.nngroup.com/books/design-everyday-things-revised/) — Don Norman, 2013. Texto fundacional sobre diseño centrado en el usuario.
- [Don't Make Me Think](https://sensible.com/dont-make-me-think/) — Steve Krug, 2013. Guía práctica de usabilidad web.
- [Nielsen Norman Group](https://www.nngroup.com/) — NN/g. Referencia principal en investigación y artículos de UX.
---
# TypeScript
Type: concept
Status: seed
Summary: Typed superset of JavaScript adding optional static types, improving developer productivity, error detection, and code maintainability.
Concepts: react, spec-driven-development
## ¿Qué es?
TypeScript es un superset de JavaScript que añade tipos estáticos opcionales. Todo JavaScript válido es TypeScript válido, pero TypeScript permite declarar tipos que el compilador verifica antes de ejecutar, atrapando errores en desarrollo en lugar de producción.
## ¿Por qué TypeScript?
- Errores detectados en compilación, no en runtime
- Autocompletado inteligente en el IDE
- Refactoring seguro a escala
- Documentación implícita en los tipos
- Estándar de facto para proyectos JavaScript serios
## Características clave
- **Interfaces y types**: definir formas de datos
- **Generics**: tipos parametrizados reutilizables
- **Union types**: `string | number`
- **Type inference**: el compilador deduce tipos automáticamente
- **Strict mode**: máxima seguridad de tipos
## TypeScript en el ecosistema
- [React](/concepts/react): JSX tipado, props tipados
- [Next.js](/concepts/nextjs): soporte nativo
- [AWS CDK](/concepts/aws-cdk): infraestructura tipada
- Node.js: backend tipado
## Configuración de `strict`
El modo estricto habilita todas las verificaciones de tipo. Es la configuración recomendada para proyectos nuevos:
```json
{
"compilerOptions": {
"strict": true,
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"esModuleInterop": true,
"skipLibCheck": true,
"outDir": "dist"
}
}
```
Las flags individuales que `strict` activa:
| Flag | Qué previene |
|------|-------------|
| `strictNullChecks` | Acceso a `null`/`undefined` sin verificar |
| `noImplicitAny` | Variables sin tipo explícito ni inferido |
| `strictFunctionTypes` | Parámetros de función contravariantes incorrectos |
| `strictPropertyInitialization` | Propiedades de clase no inicializadas |
| `noImplicitThis` | Uso de `this` sin tipo conocido |
## Cuándo NO usar TypeScript
- Scripts de una sola ejecución (bash o Python son más rápidos)
- Prototipos desechables donde la velocidad de iteración importa más que la corrección
- Proyectos donde el equipo no tiene experiencia con tipos estáticos (la curva de aprendizaje es real)
## ¿Por qué importa?
TypeScript convierte errores de runtime en errores de compilación. En proyectos de cualquier tamaño, el sistema de tipos actúa como documentación viva, habilita refactoring seguro y reduce la categoría de bugs más común: los errores de tipo.
## Referencias
- [TypeScript Documentation](https://www.typescriptlang.org/docs/) — Documentación oficial.
- [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/) — Guía completa.
- [TypeScript Playground](https://www.typescriptlang.org/play) — Microsoft, 2024. Entorno interactivo para experimentar con TypeScript.
---
# Twelve-Factor App
Type: concept
Status: seed
Summary: Twelve-principle methodology for building modern SaaS applications that are portable, scalable, and deployable on cloud platforms.
Concepts: cloud-native, devops-practices
## ¿Qué es?
The Twelve-Factor App es una metodología de 12 principios para construir aplicaciones SaaS modernas. Publicada por Heroku en 2011, sigue siendo la base de las mejores prácticas [cloud native](/concepts/cloud-native).
## Los 12 factores
1. **Codebase**: un repo, múltiples deploys
2. **Dependencies**: declarar y aislar dependencias explícitamente
3. **Config**: configuración en variables de entorno
4. **Backing services**: tratar servicios externos como recursos adjuntos
5. **Build, release, run**: separar estrictamente las etapas
6. **Processes**: ejecutar como procesos stateless
7. **Port binding**: exportar servicios vía port binding
8. **Concurrency**: escalar mediante procesos
9. **Disposability**: startup rápido, shutdown graceful
10. **Dev/prod parity**: mantener ambientes similares
11. **Logs**: tratar logs como streams de eventos
12. **Admin processes**: ejecutar tareas admin como procesos one-off
## Relevancia actual
Aunque tiene más de una década, los 12 factores siguen siendo relevantes. [Serverless](/concepts/serverless) y contenedores implementan muchos de estos principios por diseño.
## Factores en la práctica moderna
| Factor | Principio | Implementación moderna |
|--------|-----------|----------------------|
| III. Config | Variables de entorno | AWS SSM Parameter Store, [Secrets Manager](/concepts/secrets-management) |
| V. Build, release, run | Separar etapas | [CI/CD](/concepts/ci-cd) pipelines, [GitOps](/concepts/gitops) |
| VI. Processes | Stateless | Contenedores, [Lambda](/concepts/aws-lambda) |
| IX. Disposability | Startup rápido | Health checks en [Kubernetes](/concepts/kubernetes), graceful shutdown |
| X. Dev/prod parity | Ambientes similares | [DevContainers](/concepts/devcontainers), [Docker Compose](/concepts/docker-compose) |
| XI. Logs | Streams de eventos | [Logging estructurado](/concepts/logging-strategies), stdout → CloudWatch |
## Limitaciones
Los 12 factores no cubren aspectos que hoy son esenciales:
- **Seguridad**: no menciona autenticación, autorización ni [zero trust](/concepts/zero-trust)
- **Observabilidad**: solo habla de logs, no de métricas ni [tracing distribuido](/concepts/distributed-tracing)
- **Resiliencia**: no aborda circuit breakers, retries ni [chaos engineering](/concepts/chaos-engineering)
- **API contracts**: no menciona versionado de APIs ni contratos entre servicios
## ¿Por qué importa?
Los doce factores siguen siendo relevantes como principios de diseño para aplicaciones cloud-native. Configuración por entorno, procesos stateless, logs como streams y paridad dev/prod son prácticas que previenen categorías enteras de problemas operacionales.
## Referencias
- [The Twelve-Factor App](https://12factor.net/) — Adam Wiggins, 2011.
- [Config — 12 Factor](https://12factor.net/config) — Adam Wiggins, 2011. Factor III: configuración por entorno.
- [CNCF Projects](https://www.cncf.io/projects/) — CNCF, 2024. Ecosistema cloud-native que implementa los principios de 12 factores.
---
# Tool Use Patterns
Type: concept
Status: seed
Summary: Design strategies and patterns for AI agents to select, invoke, and combine external tools effectively to complete complex tasks.
Concepts: ai-agents, mcp, function-calling
## ¿Qué es?
Los patrones de uso de herramientas definen cómo los [agentes de IA](/concepts/ai-agents) seleccionan, invocan y combinan herramientas externas para resolver tareas. Mientras que [function calling](/concepts/function-calling) es el mecanismo técnico, los patrones de uso de herramientas son las estrategias de nivel superior que determinan cuándo y cómo usarlas.
## Patrones principales
### Herramienta única
El agente identifica la herramienta correcta y la invoca una vez:
```
"¿Qué hora es en Tokio?" → get_time(timezone="Asia/Tokyo")
```
### Llamadas paralelas
El agente invoca múltiples herramientas simultáneamente cuando son independientes:
```
"Compara el clima en Madrid y Londres"
→ get_weather("Madrid") + get_weather("London") [en paralelo]
```
### Llamadas encadenadas
El resultado de una herramienta alimenta la siguiente:
```
"Busca el último commit y muéstrame los cambios"
→ get_latest_commit() → get_diff(commit_sha)
```
### Selección condicional
El agente decide qué herramienta usar según el contexto:
```
"Busca información sobre X"
→ Si X es código: search_code()
→ Si X es documentación: search_docs()
→ Si X es general: web_search()
```
### Recuperación de errores
El agente maneja fallos y busca alternativas:
```
search_api() → Error 429 → wait(30s) → retry()
o
search_api() → Error → fallback_search()
```
## Principios de diseño
- **Descripciones precisas**: la calidad de la descripción de cada herramienta determina si el agente la selecciona correctamente
- **Granularidad adecuada**: herramientas ni demasiado amplias ni demasiado específicas
- **Idempotencia**: preferir herramientas que puedan re-ejecutarse sin efectos secundarios
- **Límites claros**: definir qué puede y no puede hacer cada herramienta
- **Feedback loops**: el agente debe poder interpretar resultados y ajustar su estrategia
## Relación con MCP
El [Model Context Protocol](/concepts/mcp) estandariza cómo se descubren y describen herramientas, haciendo que estos patrones sean portables entre diferentes sistemas y modelos.
## ¿Por qué importa?
Los patrones de uso de herramientas definen cómo los LLMs interactúan con el mundo exterior. Entender cuándo usar function calling vs MCP, cómo diseñar esquemas de herramientas efectivos y cómo manejar errores de herramientas es esencial para construir agentes confiables.
## Referencias
- [Tool Use - Anthropic](https://docs.anthropic.com/en/docs/build-with-claude/tool-use) — Patrones y mejores prácticas.
- [Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents) — Anthropic, 2024.
- [Model Context Protocol](https://modelcontextprotocol.io/introduction) — Anthropic, 2024. Protocolo estándar para uso de herramientas por LLMs.
---
# Tokenization
Type: concept
Status: seed
Summary: Process of splitting text into discrete units (tokens) that language models can process numerically, fundamental to how LLMs understand and generate text.
Concepts: large-language-models, embeddings
## ¿Qué es?
La tokenización es el proceso de convertir texto en una secuencia de tokens — unidades discretas que el modelo puede procesar. Los [LLMs](/concepts/large-language-models) no ven caracteres ni palabras directamente; ven IDs numéricos que representan tokens de su vocabulario.
## ¿Por qué no usar palabras?
- **Vocabulario infinito**: nuevas palabras, nombres propios, errores tipográficos
- **Idiomas**: cada idioma tendría vocabulario diferente
- **Eficiencia**: palabras raras desperdiciarían espacio en el vocabulario
## Algoritmos principales
### BPE (Byte Pair Encoding)
El más común. Comienza con caracteres individuales y fusiona iterativamente los pares más frecuentes:
```
"lower" → ["low", "er"]
"lowest" → ["low", "est"]
```
Usado por: GPT, Llama, Mistral.
### WordPiece
Similar a BPE pero optimiza por likelihood del modelo de lenguaje. Usa prefijo `##` para subpalabras:
```
"tokenization" → ["token", "##ization"]
```
Usado por: BERT, modelos de Google.
### SentencePiece
Trata el texto como secuencia de bytes, sin preprocesamiento. Útil para idiomas sin espacios claros entre palabras.
## Implicaciones prácticas
- **Costo**: se cobra por token, no por palabra. «Tokenización» puede ser 1-3 tokens según el modelo
- **Contexto**: la ventana de contexto se mide en tokens
- **Idiomas**: español y otros idiomas con palabras más largas usan más tokens que inglés
- **Código**: símbolos y sintaxis pueden tokenizarse de formas inesperadas
- **Números**: los modelos tokenizaron números de formas que dificultan aritmética
## Herramientas
- [tiktoken](https://github.com/openai/tiktoken) — Tokenizador de OpenAI
- [tokenizers](https://github.com/huggingface/tokenizers) — Biblioteca de Hugging Face
- Playgrounds de cada proveedor suelen mostrar conteo de tokens
## Ejemplo
```
Texto: "Los modelos de lenguaje son fascinantes"
GPT-4 tokens: ["Los", " modelos", " de", " lenguaje", " son", " fascin", "antes"]
= 7 tokens
Texto: "Language models are fascinating"
GPT-4 tokens: ["Language", " models", " are", " fascinating"]
= 4 tokens
```
El mismo concepto usa ~75% más tokens en español.
## ¿Por qué importa?
La tokenización determina cómo un modelo «ve» el texto. Un tokenizador ineficiente desperdicia contexto en tokens redundantes, aumenta costos y degrada la calidad en idiomas no ingleses. Entender cómo funciona permite optimizar prompts, estimar costos con precisión y diagnosticar comportamientos inesperados del modelo.
## Referencias
- [Neural Machine Translation of Rare Words with Subword Units](https://arxiv.org/abs/1508.07909) — Sennrich et al., 2015. Paper original de BPE para NLP.
- [SentencePiece](https://arxiv.org/abs/1808.06226) — Kudo & Richardson, 2018.
---
# Testing Strategies
Type: concept
Status: seed
Summary: Approaches and testing levels for validating software works correctly, from unit tests to end-to-end tests and testing in production.
Concepts: ci-cd, code-quality
## ¿Qué es?
Las estrategias de testing definen qué tipos de tests escribir, cuántos, y cómo organizarlos para maximizar la confianza en el código con el menor costo de mantenimiento.
## Pirámide de testing
```
/\ E2E (pocos, lentos, frágiles)
/ \
/----\ Integration (algunos)
/ \
/--------\ Unit (muchos, rápidos, estables)
```
## Tipos de tests
| Tipo | Qué prueba | Velocidad | Fragilidad |
|------|------------|-----------|------------|
| Unit | Función/clase aislada | Muy rápido | Baja |
| Integration | Componentes juntos | Medio | Media |
| E2E | Flujo completo de usuario | Lento | Alta |
| Contract | APIs entre servicios | Rápido | Baja |
## Enfoques
| Enfoque | Mecanismo | Cuándo usar |
|---------|-----------|-------------|
| TDD | Escribir test antes del código | Lógica de negocio, algoritmos |
| BDD | Tests como especificaciones de comportamiento | Requisitos de usuario, aceptación |
| Property-based | Generar inputs aleatorios, verificar invariantes | Parsers, serialización, edge cases |
| Snapshot | Comparar output con versión guardada | UI components, respuestas de API |
## Testing en producción
- Feature flags para rollout gradual
- Canary deployments
- Observabilidad para detectar problemas
## ¿Por qué importa?
Una estrategia de testing efectiva equilibra velocidad, cobertura y confianza. Demasiados tests unitarios sin integración dan falsa seguridad. Demasiados tests e2e son lentos y frágiles. La pirámide de testing proporciona el framework para encontrar el balance correcto.
## Referencias
- [Testing Trophy](https://kentcdodds.com/blog/the-testing-trophy-and-testing-classifications) — Kent C. Dodds.
- [The Practical Test Pyramid](https://martinfowler.com/articles/practical-test-pyramid.html) — Ham Vocke, 2018. Guía práctica de la pirámide de testing.
- [Testing Library](https://testing-library.com/) — Testing Library, 2024. Herramientas de testing centradas en el usuario.
---
# Terraform
Type: concept
Status: evergreen
Summary: HashiCorp's Infrastructure as Code tool that enables defining, provisioning, and managing multi-cloud infrastructure through declarative HCL files.
Concepts: infrastructure-as-code, devops-practices, ci-cd
**Terraform** es la herramienta de IaC más adoptada del mercado. Usa un lenguaje declarativo (HCL) para definir infraestructura y un modelo de estado para rastrear qué recursos existen y cómo actualizarlos.
## ¿Cómo funciona?
```
Write (.tf files) → Plan (preview changes) → Apply (execute changes)
```
### Ciclo de vida
```bash
terraform init # Descargar providers y módulos
terraform validate # Verificar sintaxis
terraform plan # Ver qué va a cambiar
terraform apply # Aplicar cambios
terraform destroy # Eliminar toda la infraestructura
```
## Conceptos fundamentales
### Providers
Plugins que conectan Terraform con APIs de servicios:
```hcl
terraform {
required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 5.0"
}
}
}
provider "aws" {
region = "us-east-1"
}
```
Más de 4,000 providers: AWS, Azure, GCP, Kubernetes, GitHub, Datadog, Cloudflare, etc.
### Resources
Unidad básica — un recurso de infraestructura:
```hcl
resource "aws_s3_bucket" "data" {
bucket = "my-app-data-${var.environment}"
tags = {
Environment = var.environment
ManagedBy = "terraform"
}
}
resource "aws_s3_bucket_versioning" "data" {
bucket = aws_s3_bucket.data.id
versioning_configuration {
status = "Enabled"
}
}
```
### Variables
```hcl
# variables.tf
variable "environment" {
description = "Deployment environment"
type = string
validation {
condition = contains(["dev", "staging", "prod"], var.environment)
error_message = "Must be dev, staging, or prod."
}
}
variable "instance_count" {
description = "Number of instances"
type = number
default = 2
}
```
```bash
# terraform.tfvars
environment = "prod"
instance_count = 3
```
### Outputs
```hcl
output "bucket_arn" {
description = "ARN of the S3 bucket"
value = aws_s3_bucket.data.arn
}
output "api_url" {
description = "API Gateway URL"
value = aws_apigatewayv2_api.main.api_endpoint
sensitive = false
}
```
### Data sources
Leer información de recursos existentes (no gestionados por Terraform):
```hcl
data "aws_ami" "amazon_linux" {
most_recent = true
owners = ["amazon"]
filter {
name = "name"
values = ["al2023-ami-*-x86_64"]
}
}
resource "aws_instance" "web" {
ami = data.aws_ami.amazon_linux.id
instance_type = "t3.micro"
}
```
## State
El state file es la fuente de verdad sobre qué recursos existen:
```hcl
# Backend remoto (obligatorio para equipos)
terraform {
backend "s3" {
bucket = "company-terraform-state"
key = "services/api/terraform.tfstate"
region = "us-east-1"
dynamodb_table = "terraform-locks" # Locking
encrypt = true # Encryption at rest
}
}
```
### Comandos de state
```bash
terraform state list # Listar recursos
terraform state show aws_instance.web # Detalle de un recurso
terraform state mv aws_instance.old aws_instance.new # Renombrar
terraform state rm aws_instance.legacy # Dejar de gestionar
terraform import aws_instance.web i-1234567890 # Importar existente
```
## Módulos
Paquetes reutilizables de infraestructura:
```hcl
# Módulo propio
module "api" {
source = "./modules/lambda-api"
function_name = "my-api"
runtime = "nodejs20.x"
memory_size = 256
environment = var.environment
}
# Módulo del registry
module "vpc" {
source = "terraform-aws-modules/vpc/aws"
version = "5.5.0"
name = "production"
cidr = "10.0.0.0/16"
}
```
### Estructura de un módulo
```
modules/lambda-api/
├── main.tf # Resources
├── variables.tf # Inputs
├── outputs.tf # Outputs
├── versions.tf # Provider requirements
└── README.md # Documentation
```
## Patrones avanzados
### Workspaces
Múltiples entornos con el mismo código:
```bash
terraform workspace new staging
terraform workspace new production
terraform workspace select staging
terraform apply -var-file="staging.tfvars"
```
### for_each y count
```hcl
# Crear múltiples recursos
resource "aws_iam_user" "team" {
for_each = toset(["alice", "bob", "carol"])
name = each.key
}
# Condicional
resource "aws_cloudwatch_log_group" "api" {
count = var.enable_logging ? 1 : 0
name = "/api/${var.environment}"
}
```
### Moved blocks (refactoring seguro)
```hcl
moved {
from = aws_instance.server
to = aws_instance.web
}
```
## Terraform vs alternativas
| Aspecto | Terraform | Pulumi | AWS CDK | CloudFormation |
|---------|-----------|--------|---------|----------------|
| Lenguaje | HCL | TS, Python, Go | TS, Python | YAML/JSON |
| Multi-cloud | Sí | Sí | No (AWS) | No (AWS) |
| State | Self-managed/Cloud | Managed/self | AWS-managed | AWS-managed |
| Ecosistema | 4,000+ providers | 100+ providers | AWS only | AWS only |
| Licencia | BSL 1.1 | Apache 2.0 | Apache 2.0 | Propietario |
| Fork OSS | OpenTofu | — | — | — |
## Seguridad
```hcl
# Nunca hardcodear secretos
variable "db_password" {
type = string
sensitive = true # No aparece en logs ni plan
}
# Usar data sources para secretos
data "aws_secretsmanager_secret_version" "db" {
secret_id = "prod/db/password"
}
```
## Anti-patrones
- **State local** — compartir state por Slack/email. Usar backend remoto con locking.
- **Mega-monolito** — toda la infra en un solo `main.tf`. Dividir por dominio.
- **Sin pinear versiones** — providers y módulos sin versión fija rompen builds.
- **Apply sin plan** — siempre revisar el plan antes de aplicar.
- **Secretos en .tf** — usar variables sensitive, secret managers, o Vault.
- **Ignorar `terraform fmt`** — formateo consistente facilita code review.
## ¿Por qué importa?
Terraform se ha convertido en el estándar de facto para infraestructura como código. Dominarlo no es opcional para equipos que operan en la nube — es la diferencia entre infraestructura reproducible y auditable, y configuración manual que nadie puede reconstruir cuando falla.
## Referencias
- [Terraform Documentation](https://developer.hashicorp.com/terraform/docs) — HashiCorp, 2024. Documentación oficial.
- [Terraform: Up & Running, 3rd Edition](https://www.terraformupandrunning.com/) — Yevgeniy Brikman, 2022. La guía práctica más completa.
- [Terraform Best Practices](https://www.terraform-best-practices.com/) — Anton Babenko, 2024. Mejores prácticas de la comunidad.
- [Terraform Registry](https://registry.terraform.io/) — HashiCorp, 2024. Catálogo de providers y módulos.
- [Spacelift Blog: Terraform Patterns](https://spacelift.io/blog/terraform-best-practices) — Spacelift, 2024. Patrones avanzados y anti-patrones.
---
# Tailwind CSS
Type: concept
Status: seed
Summary: Utility-first CSS framework enabling design building directly in markup using atomic classes, eliminating the need to write custom CSS.
Concepts: react, design-systems, nextjs
## ¿Qué es?
Tailwind CSS es un framework CSS utility-first. En lugar de escribir clases semánticas y CSS custom, compones diseños usando clases atómicas directamente en el HTML: `flex`, `p-4`, `text-lg`, `bg-blue-500`.
## ¿Por qué Tailwind?
| Enfoque CSS | Ejemplo | Ventaja | Desventaja |
|-------------|---------|---------|------------|
| CSS tradicional | `.card-header { ... }` | Control total, semántico | Crece sin límite, naming difícil |
| CSS Modules | `styles.cardHeader` | Scoped por defecto | Un archivo por componente |
| CSS-in-JS | `styled(Component)` | Dinámico, co-ubicado | Runtime overhead, bundle size |
| **Tailwind** | `class="flex p-4 rounded"` | Sin naming, purge automático | Clases largas en el markup |
Beneficios específicos:
- CSS no crece con el proyecto (purge de clases no usadas)
- Consistencia mediante design tokens
- Responsive y dark mode con prefijos (`md:`, `dark:`)
- Productividad: diseñar sin cambiar de archivo
## Tailwind v4
La versión 4 introduce:
- CSS-first configuration (no más `tailwind.config.js`)
- Custom properties nativas
- Performance mejorada
- Composable variants
## Este sitio usa Tailwind
jonmatum.com usa Tailwind CSS v4 con custom properties para colores (`--color-bg`, `--color-fg`, etc.) y dark mode only.
## ¿Cuándo no usar Tailwind?
- Proyectos donde el equipo prefiere CSS-in-JS o CSS Modules y no quiere cambiar de paradigma
- Componentes de librería pública donde los consumidores necesitan override fácil de estilos
## ¿Por qué importa?
Tailwind CSS cambió la forma de escribir estilos al eliminar la abstracción de clases semánticas. Las utility classes permiten construir interfaces directamente en el markup, con un sistema de diseño consistente y un bundle CSS mínimo gracias al tree-shaking automático.
## Referencias
- [Tailwind CSS Documentation](https://tailwindcss.com/docs) — Tailwind Labs, 2024. Documentación oficial.
- [Tailwind CSS Blog](https://tailwindcss.com/blog) — Tailwind Labs, 2024. Anuncios y novedades.
- [Tailwind CSS — GitHub](https://github.com/tailwindlabs/tailwindcss) — Tailwind Labs, 2024. Código fuente y discusiones.
---
# Synthetic Data
Type: concept
Status: seed
Summary: Algorithmically generated data that replicates the statistical properties of real data, used to train, evaluate, and test AI systems when real data is scarce, expensive, or sensitive.
Concepts: fine-tuning, evaluation-metrics-ai, ai-safety, large-language-models
## ¿Qué es?
Los datos sintéticos son información generada por algoritmos — no capturada del mundo real — que replica las propiedades estadísticas y la estructura de datos reales. En el contexto de IA, se usan para entrenar modelos, construir benchmarks de evaluación y probar sistemas cuando los datos reales son insuficientes, costosos de obtener o contienen información sensible.
La práctica se ha vuelto central en el desarrollo de LLMs modernos. Modelos como DeepSeek-R1 y las familias de razonamiento de OpenAI y Anthropic utilizan datos sintéticos extensivamente durante el post-entrenamiento, ya sea como datos de [fine-tuning](/concepts/fine-tuning) o como juicios generados por modelos evaluadores.
## Métodos de generación
### Destilación de modelos
Un modelo grande y capaz genera datos que se usan para entrenar un modelo más pequeño. El modelo «profesor» produce respuestas de alta calidad que el modelo «estudiante» aprende a replicar.
### Generación por instrucciones
Se le pide a un LLM que genere ejemplos siguiendo instrucciones específicas:
```
Genera 50 preguntas sobre Kubernetes con sus respuestas.
Cada pregunta debe cubrir un nivel de dificultad diferente.
Incluye escenarios de producción reales.
```
### Aumento de datos (Data Augmentation)
Transformar datos existentes para crear variaciones: parafraseo, traducción, cambio de formato, perturbación de valores numéricos.
### Generación adversarial
Crear datos diseñados para exponer debilidades del modelo: edge cases, prompts adversariales, escenarios de seguridad. Esto conecta directamente con prácticas de [seguridad de IA](/concepts/ai-safety).
## Casos de uso
| Caso | Problema | Solución con datos sintéticos |
|------|----------|-------------------------------|
| Evaluación pre-lanzamiento | No hay usuarios reales aún | Generar consultas y escenarios representativos |
| Privacidad | Datos contienen PII | Generar datos con las mismas propiedades estadísticas sin información real |
| Datos escasos | Dominio con pocos ejemplos | Aumentar el dataset con variaciones generadas |
| Red teaming | Probar robustez del modelo | Generar prompts adversariales automáticamente |
| Post-entrenamiento | Mejorar capacidades específicas | Generar pares instrucción-respuesta de alta calidad |
## Riesgos y limitaciones
- **Model collapse**: entrenar modelos recursivamente con datos sintéticos puede degradar la calidad generación tras generación
- **Sesgo amplificado**: los datos sintéticos heredan y pueden amplificar los sesgos del modelo generador
- **Falta de diversidad**: los datos generados tienden a ser menos diversos que los datos reales del mundo
- **Validación necesaria**: se requieren métricas de calidad para verificar que los datos sintéticos son representativos
## Métricas de calidad
- **Fidelidad estadística**: similitud de distribuciones entre datos reales y sintéticos
- **Utilidad**: rendimiento de un modelo entrenado con datos sintéticos vs. datos reales
- **Privacidad**: garantía de que no se filtran datos reales en los sintéticos
- **Diversidad**: cobertura del espacio de posibles entradas
## ¿Por qué importa?
A medida que los sistemas de IA pasan de prototipos a producción, la calidad de los datos de entrenamiento y evaluación se convierte en el cuello de botella. Los datos reales son costosos, lentos de recopilar y frecuentemente restringidos por regulaciones de privacidad. Los datos sintéticos rompen esta dependencia: los equipos pueden iterar sobre suites de evaluación en horas en lugar de semanas, probar edge cases que rara vez ocurren naturalmente y construir datasets para dominios donde los datos reales simplemente no existen aún.
## Referencias
- [A Deep Dive Into the Role of Synthetic Data in Post-Training](https://arxiv.org/html/2501.18511v1) — Análisis del uso de datos sintéticos en post-entrenamiento de LLMs, 2025.
- [Evaluating Language Models as Synthetic Data Generators](https://arxiv.org/html/2412.03679v2) — Evaluación de LLMs como generadores de datos sintéticos, 2024.
- [Best Practices and Lessons Learned on Synthetic Data](https://arxiv.org/abs/2406.07515) — Liu et al., 2024. Mejores prácticas para generación de datos sintéticos.
---
# Supply Chain Security
Type: concept
Status: seed
Summary: Practices for ensuring the integrity and security of all dependencies, tools, and processes comprising the software development pipeline.
Concepts: devsecops, container-security
## ¿Qué es?
La seguridad de la cadena de suministro de software protege contra ataques que comprometen dependencias, herramientas de build o procesos de distribución. Ataques como SolarWinds y Log4Shell demostraron su importancia.
## Vectores de ataque
| Vector | Ejemplo real | Mitigación |
|--------|-------------|------------|
| Dependencias maliciosas | Typosquatting en npm/PyPI | Lockfiles, dependency review |
| Compromiso de build | SolarWinds (2020) | Builds herméticos, SLSA Level 3+ |
| Inyección en CI/CD | Codecov breach (2021) | Permisos mínimos, secretos rotados |
| Imágenes comprometidas | Imágenes base con vulnerabilidades | Escaneo con Trivy, imágenes firmadas |
## Prácticas de mitigación
- **SBOM**: Software Bill of Materials (inventario de dependencias)
- **Dependency scanning**: Snyk, Dependabot, Trivy
- **Firma de artefactos**: cosign, Sigstore
- **SLSA**: Supply-chain Levels for Software Artifacts (framework de madurez)
- **Lockfiles**: versiones exactas de dependencias
## SLSA Levels
| Level | Requisitos |
|-------|------------|
| 1 | Documentación del proceso de build |
| 2 | Build service hosted, logs retenidos |
| 3 | Build aislado, provenance verificable |
| 4 | Build hermético, two-party review |
## ¿Por qué importa?
Los ataques a la cadena de suministro de software explotan la confianza en dependencias de terceros. Un solo paquete comprometido puede afectar a miles de aplicaciones. Verificar firmas, auditar dependencias y usar SBOMs son prácticas defensivas esenciales.
## Referencias
- [SLSA](https://slsa.dev/) — Framework de seguridad.
- [Sigstore](https://www.sigstore.dev/) — Firma de artefactos.
- [OpenSSF](https://openssf.org/) — Linux Foundation, 2024. Fundación para la seguridad del software open source.
---
# Strangler Fig Pattern
Type: concept
Status: seed
Summary: Incremental migration strategy that gradually replaces a legacy system with new components, progressively routing traffic until the old system can be retired.
Concepts: microservices, api-gateway-pattern, hexagonal-architecture, devops-practices
## ¿Qué es?
El patrón Strangler Fig (nombrado por la higuera estranguladora) es una estrategia para migrar sistemas legacy de forma incremental. En lugar de un rewrite completo — el temido «big bang» que falla más de lo que funciona — se construyen componentes nuevos que gradualmente reemplazan funcionalidad del sistema antiguo mientras este sigue operando.
Martin Fowler lo describió en 2004 inspirado por las higueras estranguladoras de Australia: semillas que germinan en la copa de un árbol huésped, crecen raíces hacia abajo, y eventualmente envuelven y reemplazan al árbol original.
## ¿Por qué importa?
Los rewrites completos son el cementerio de proyectos de software. El patrón Strangler Fig ofrece una alternativa pragmática:
- **Riesgo controlado** — cada migración es pequeña y reversible
- **Valor continuo** — el sistema legacy sigue funcionando mientras se construye el nuevo
- **Aprendizaje incremental** — el equipo descubre requisitos ocultos del legacy gradualmente, no al final
- **Financiamiento sostenible** — se puede justificar inversión continua porque cada iteración entrega valor
## Proceso
1. **Colocar un proxy/facade** frente al sistema legacy — este es el punto de control que permite enrutar tráfico
2. **Implementar nueva funcionalidad** en el sistema nuevo para una ruta o feature específica
3. **Enrutar tráfico gradualmente** al sistema nuevo (por porcentaje, por usuario, por región)
4. **Validar y monitorear** — comparar comportamiento entre ambos sistemas
5. **Repetir** hasta que el legacy no reciba tráfico
6. **Retirar el sistema legacy** cuando ya no sea necesario
## ¿Cuándo usarlo?
- Sistemas monolíticos que necesitan modernizarse pero no pueden detenerse
- Migraciones de bases de datos donde la consistencia es crítica
- Transiciones de on-premise a cloud
- Reemplazo de frameworks o lenguajes obsoletos
## ¿Cuándo no usarlo?
- Sistemas pequeños donde un rewrite toma menos de un sprint
- Cuando el sistema legacy no tiene una interfaz clara para interceptar
- Si no hay forma de enrutar tráfico selectivamente
## Variantes
| Variante | Mecanismo | Cuándo usar |
|----------|-----------|-------------|
| Strangler Fig (clásico) | Proxy HTTP redirige tráfico gradualmente | Migración de monolito web a [microservicios](/concepts/microservices) |
| Branch by Abstraction | Abstracción interna en el código | Reemplazar componentes internos sin cambiar la API |
| Parallel Run | Ejecutar ambos sistemas y comparar | Cuando la corrección es crítica (pagos, cálculos) |
| Feature Toggle | [Feature flags](/concepts/feature-flags) controlan qué usuarios ven el nuevo sistema | Migración gradual por segmento de usuarios |
## Referencias
- [Strangler Fig Application](https://martinfowler.com/bliki/StranglerFigApplication.html) — Martin Fowler, 2004. El artículo original que nombró el patrón.
- [Legacy Application Strangulation](https://paulhammant.com/2013/07/14/legacy-application-strangulation-case-studies/) — Paul Hammant, 2013. Casos de estudio reales de aplicación del patrón.
- [Strangler Fig Pattern — Azure](https://learn.microsoft.com/en-us/azure/architecture/patterns/strangler-fig) — Microsoft, 2024. Guía de implementación del patrón.
---
# Strands Agents
Type: concept
Status: evergreen
Summary: Open source SDK from AWS for building AI agents with a model-driven approach. Functional agents in a few lines of code, with multi-model support, custom tools, MCP, multi-agent, and built-in observability.
Concepts: ai-agents, mcp, artificial-intelligence
**Strands Agents** es un SDK open source (Apache 2.0) creado por AWS que adopta un enfoque *model-driven* para construir agentes de IA. La premisa: el modelo de lenguaje es el orquestador — tú defines herramientas y un prompt, y el modelo decide cuándo y cómo usarlas.
## ¿Por qué importa?
La mayoría de frameworks de agentes requieren definir flujos explícitos, grafos de decisión o cadenas de pasos. Strands invierte el paradigma:
- **Sin orquestación manual** — el LLM decide el flujo basado en el contexto
- **Agente funcional en 4 líneas** — sin boilerplate
- **Model-agnostic** — Bedrock, OpenAI, Anthropic, Ollama, Mistral, Gemini, y más
- **Herramientas como funciones Python** — decorador `@tool` y listo
- **MCP nativo** — conectar servidores MCP como fuentes de herramientas
- **Observabilidad integrada** — trazas, métricas y logs desde el primer momento
## Ejemplo mínimo
```python
from strands import Agent
agent = Agent()
agent("¿Cuál es la capital de Francia?")
```
Eso es un agente funcional. Usa Bedrock con Claude por defecto.
## Herramientas personalizadas
```python
from strands import Agent, tool
@tool
def weather(city: str) -> str:
"""Get current weather for a city.
Args:
city: Name of the city to check weather for.
Returns:
Current weather description.
"""
# En producción, llamar a una API real
return f"Sunny, 22°C in {city}"
@tool
def convert_temperature(celsius: float) -> float:
"""Convert Celsius to Fahrenheit.
Args:
celsius: Temperature in Celsius.
Returns:
Temperature in Fahrenheit.
"""
return celsius * 9/5 + 32
agent = Agent(tools=[weather, convert_temperature])
agent("What's the weather in Madrid? Give me the temperature in Fahrenheit too.")
```
El agente decide autónomamente: primero llama `weather("Madrid")`, luego `convert_temperature(22.0)`, y compone la respuesta.
## Proveedores de modelos
```python
from strands import Agent
from strands.models import BedrockModel
# Amazon Bedrock (default)
agent = Agent(model="anthropic.claude-sonnet-4-20250514-v1:0")
# Con configuración explícita
bedrock = BedrockModel(
model_id="anthropic.claude-sonnet-4-20250514-v1:0",
region_name="us-west-2",
temperature=0.3,
)
agent = Agent(model=bedrock)
```
```python
# OpenAI
from strands.models import OpenAIModel
agent = Agent(model=OpenAIModel(model_id="gpt-4o"))
# Anthropic directo
from strands.models import AnthropicModel
agent = Agent(model=AnthropicModel(model_id="claude-sonnet-4-20250514"))
# Ollama (local)
from strands.models import OllamaModel
agent = Agent(model=OllamaModel(model_id="llama3.1"))
```
Proveedores soportados: Amazon Bedrock, Amazon Nova, Anthropic, OpenAI, Gemini, Ollama, Mistral, LiteLLM, LlamaAPI, SageMaker, Writer, llama.cpp, y custom providers.
## Integración con MCP
Conectar servidores MCP como fuentes de herramientas:
```python
from strands import Agent
from strands.tools.mcp import MCPClient
# Conectar a un servidor MCP
mcp = MCPClient(command="uvx", args=["my-mcp-server"])
with mcp:
agent = Agent(tools=mcp.list_tools())
agent("Use the MCP tools to complete this task")
```
## Patrones multi-agente
### Agents as Tools
Un agente puede usar otros agentes como herramientas:
```python
from strands import Agent
researcher = Agent(
system_prompt="You are a research specialist.",
tools=[web_search]
)
writer = Agent(
system_prompt="You are a technical writer.",
tools=[researcher.as_tool(
name="research",
description="Research a topic thoroughly"
)]
)
writer("Write an article about quantum computing")
```
### Swarm
Múltiples agentes colaborando con handoffs:
```python
from strands import Agent
from strands.multiagent import Swarm
triage = Agent(system_prompt="Route to the right specialist.")
billing = Agent(system_prompt="Handle billing questions.", tools=[billing_api])
technical = Agent(system_prompt="Handle technical issues.", tools=[diagnostics])
swarm = Swarm(
agents={"triage": triage, "billing": billing, "technical": technical},
entry_point="triage"
)
swarm("I can't log in and I was charged twice")
```
### Graph
Flujos dirigidos con condiciones:
```python
from strands.multiagent import Graph
graph = Graph()
graph.add_node("classify", classify_agent)
graph.add_node("respond", respond_agent)
graph.add_node("escalate", escalate_agent)
graph.add_edge("classify", "respond", condition=lambda r: r.priority == "low")
graph.add_edge("classify", "escalate", condition=lambda r: r.priority == "high")
graph.run("Customer complaint about delivery")
```
## Observabilidad
Cada invocación retorna un `AgentResult` con trazas y métricas:
```python
result = agent("What is the square root of 144?")
# Métricas de uso
print(result.metrics.get_summary())
# {
# "total_cycles": 2,
# "total_duration": 1.88,
# "accumulated_usage": {"inputTokens": 3921, "outputTokens": 83},
# "tool_usage": {"calculator": {"call_count": 1, "success_rate": 1.0}}
# }
```
Exportar a OpenTelemetry para Datadog, Grafana, etc.
## Streaming
```python
import asyncio
from strands import Agent
agent = Agent(callback_handler=None)
async def stream():
async for event in agent.stream_async("Explain quantum computing"):
if "data" in event:
print(event["data"], end="", flush=True)
asyncio.run(stream())
```
## Structured output
```python
from pydantic import BaseModel
from strands import Agent
class MovieReview(BaseModel):
title: str
rating: float
summary: str
agent = Agent()
result = agent.structured_output(
"Review the movie Inception",
output_model=MovieReview
)
print(result.title) # "Inception"
print(result.rating) # 9.2
```
## Deploy a producción
Strands agents son Python estándar — se despliegan en cualquier lugar:
- **AWS Lambda** — serverless, pay-per-invocation
- **AWS Fargate / ECS** — contenedores
- **Amazon EKS** — Kubernetes
- **Amazon EC2** — instancias
- **Amazon Bedrock AgentCore** — managed agent runtime
- **Docker** — cualquier plataforma con contenedores
## ¿Cuándo elegirlo?
**Buena opción cuando:**
- Quieres agentes funcionales con mínimo código
- Necesitas flexibilidad de modelos (cambiar provider sin reescribir)
- Ya usas AWS y Bedrock
- Necesitas MCP nativo
- Quieres observabilidad sin configuración adicional
- Proyectos que van de prototipo a producción
**Considerar alternativas cuando:**
- Necesitas flujos determinísticos estrictos (LangGraph puede ser mejor)
- Tu stack es exclusivamente OpenAI (el SDK de OpenAI es más directo)
- Prefieres TypeScript como lenguaje principal (Strands tiene SDK TS pero Python es más maduro)
## Comparación con alternativas
| Aspecto | Strands Agents | LangChain/LangGraph | CrewAI | OpenAI SDK |
|---------|---------------|---------------------|--------|------------|
| Enfoque | Model-driven | Chain/Graph-driven | Role-based | API-driven |
| Complejidad | Baja | Alta | Media | Baja |
| Multi-modelo | Sí (15+) | Sí | Limitado | Solo OpenAI |
| MCP nativo | Sí | Plugin | No | No |
| Multi-agente | Swarm, Graph, A2A | LangGraph | Crews | Swarm (beta) |
| Observabilidad | Integrada | LangSmith (pago) | Limitada | Limitada |
| Licencia | Apache 2.0 | MIT | MIT | MIT |
| Respaldo | AWS | LangChain Inc. | CrewAI Inc. | OpenAI |
## Ecosistema
- **strands-agents** — SDK principal (Python y TypeScript)
- **strands-agents-tools** — paquete comunitario de herramientas
- **strands-agents-builder** — agente que ayuda a construir otros agentes
- **strands-agents-mcp-server** — servidor MCP para asistentes de IDE
- **strands-evals** — SDK de evaluación de agentes
## Referencias
- [Strands Agents Documentation](https://strandsagents.com/) — AWS, 2025. Documentación oficial completa.
- [strands-agents/sdk-python](https://github.com/strands-agents/sdk-python) — GitHub, 2025. Repositorio del SDK de Python.
- [Introducing Strands Agents](https://strandsagents.com/blog/introducing-strands-agents/) — AWS, 2025. Post de lanzamiento oficial.
- [Strands Agents 1.0: Production-Ready Multi-Agent Orchestration](https://aws.amazon.com/blogs/opensource/introducing-strands-agents-1-0-production-ready-multi-agent-orchestration-made-simple/) — AWS Open Source Blog, 2025. Anuncio de la versión 1.0.
- [strands-agents on PyPI](https://pypi.org/project/strands-agents/) — PyPI, 2025. Paquete oficial con instrucciones de instalación.
---
# State Management
Type: concept
Status: seed
Summary: Patterns and libraries for managing frontend application state predictably, from local component state to shared global state.
Concepts: react, nextjs, micro-frontends
## ¿Qué es?
La gestión de estado es cómo una aplicación frontend organiza, actualiza y comparte datos entre componentes. A medida que las aplicaciones crecen, el estado se vuelve complejo: datos del servidor, estado de UI, formularios, caché.
## Niveles de estado
| Nivel | Ejemplo | Herramienta |
|-------|---------|-------------|
| Local | Toggle de un menú | useState |
| Compartido | Tema, usuario actual | Context, Zustand |
| Servidor | Datos de API | TanStack Query, SWR |
| URL | Filtros, paginación | URL params |
| Formulario | Inputs, validación | React Hook Form |
## Evolución en React
| Era | Solución | Modelo | Tradeoff |
|-----|---------|--------|----------|
| 2015 | Redux | Store global, actions, reducers | Predecible pero verboso |
| 2018 | Context API | Estado compartido nativo | Simple pero re-renders innecesarios |
| 2020+ | Zustand/Jotai | Stores atómicos, mínimo boilerplate | Ligero, menos estructura |
| 2020+ | TanStack Query | Separar estado del servidor del cliente | Requiere pensar en cache invalidation |
## Principio clave
Usar la herramienta más simple que resuelva el problema. La mayoría de aplicaciones no necesitan un store global.
## ¿Por qué importa?
La gestión de estado es el problema más complejo del desarrollo frontend. Elegir la estrategia correcta — local, global, servidor, URL — determina la complejidad, el rendimiento y la mantenibilidad de la aplicación. No hay solución universal.
## Referencias
- [Zustand](https://zustand-demo.pmnd.rs/) — Store minimalista para React.
- [TanStack Query](https://tanstack.com/query) — Gestión de estado del servidor.
- [Managing State — React](https://react.dev/learn/managing-state) — React, 2024. Guía oficial de gestión de estado en React.
---
# Spec-Driven Development
Type: concept
Status: growing
Summary: Development methodology where the specification is written before the code, serving as a contract between teams and as the source of truth for implementation.
Concepts: mcp, artificial-intelligence
## ¿Qué es?
Spec-Driven Development (SDD) es una metodología donde se escribe una especificación detallada antes de escribir código. La especificación — no el código — es la fuente de verdad del proyecto.
Es lo opuesto al enfoque «code-first» donde primero se implementa y luego se documenta (si es que se documenta). En SDD, la especificación funciona como un contrato: define qué debe hacer el sistema, cómo se comunican sus partes y qué esperar de cada interfaz.
## ¿Por qué importa ahora?
SDD no es nuevo — el diseño API-first con OpenAPI/Swagger existe desde hace años. Pero la llegada de agentes de IA que generan código ha hecho que esta metodología sea más relevante que nunca.
Cuando un [agente de IA](/concepts/ai-agents) genera código, necesita instrucciones claras y no ambiguas. Una especificación bien escrita es exactamente eso: un documento estructurado que define comportamiento esperado, tipos de datos, contratos de interfaz y criterios de aceptación.
Sin especificación, el agente adivina. Con especificación, el agente implementa.
## El ciclo SDD
```mermaid
graph LR
A[Definir especificación] --> B[Validar con stakeholders]
B --> C[Generar código base]
C --> D[Implementar lógica de negocio]
D --> E[Verificar contra especificación]
E -->|Cambios| A
```
1. **Definir**: escribir la especificación en un formato estructurado (OpenAPI, JSON Schema, protobuf, o incluso un documento de requisitos detallado)
2. **Validar**: revisar la especificación con todos los involucrados antes de escribir código
3. **Generar**: crear código base, mocks y tests a partir de la especificación
4. **Implementar**: escribir la lógica de negocio dentro de la estructura generada
5. **Verificar**: confirmar que la implementación cumple con la especificación
## Aplicaciones
### APIs (el caso clásico)
El uso más establecido. Se escribe la especificación OpenAPI primero, se generan stubs de servidor y clientes, y luego se implementa la lógica.
Beneficios concretos:
- Frontend y backend pueden trabajar en paralelo desde el día uno
- Los contratos de API son explícitos y versionados
- Los tests de contrato se generan automáticamente
### Desarrollo asistido por IA
Cuando se usa un agente de IA para generar código, la especificación actúa como prompt estructurado:
- Define los tipos y modelos de datos exactos
- Establece los comportamientos esperados con ejemplos
- Especifica restricciones y casos borde
- Proporciona criterios de aceptación verificables
Esto reduce significativamente las alucinaciones y el código incorrecto porque el agente tiene un contrato claro contra el cual trabajar.
### Protocolos (MCP, A2A)
El [Model Context Protocol](/concepts/mcp) es un ejemplo de SDD aplicado a protocolos de IA. La especificación define exactamente cómo deben comunicarse clientes y servidores, qué mensajes son válidos y qué respuestas esperar. Cualquier implementación que cumpla la especificación es interoperable.
## Formatos de especificación comunes
| Formato | Uso principal |
|---|---|
| [OpenAPI](https://www.openapis.org/) | APIs REST |
| [JSON Schema](https://json-schema.org/) | Validación de datos |
| [Protocol Buffers](https://protobuf.dev/) | APIs gRPC, serialización |
| [AsyncAPI](https://www.asyncapi.com/) | APIs basadas en eventos |
| [JSON-RPC](https://www.jsonrpc.org/) | Protocolos como MCP |
## ¿Cuándo no usar SDD?
- **Prototipos rápidos**: cuando se explora una idea y la especificación cambiaría cada hora
- **Proyectos de una persona**: el overhead de mantener una especificación formal puede no justificarse
- **Dominios desconocidos**: si no se entiende bien el problema, escribir una especificación prematura puede ser contraproducente
En estos casos, un enfoque iterativo donde la especificación emerge del código puede ser más práctico.
## Referencias
- [What Is Specification-Driven API Development?](https://nordicapis.com/what-is-specification-driven-api-development/) — Nordic APIs. Introducción clara al concepto.
- [Using spec-first API development for speed and sanity](https://www.atlassian.com/blog/technology/spec-first-api-development) — Atlassian, 2024. Caso práctico de adopción en equipos grandes.
- [OpenAPI Specification](https://www.openapis.org/) — El estándar más usado para especificaciones de API REST.
- [Model Context Protocol Specification](https://modelcontextprotocol.io/specification/latest) — Ejemplo de SDD aplicado a un protocolo de IA.
---
# SLOs, SLIs & SLAs
Type: concept
Status: seed
Summary: Framework for defining, measuring, and communicating service reliability through service level objectives (SLOs), indicators (SLIs), and agreements (SLAs).
Concepts: site-reliability-engineering, maturity-models
## ¿Qué es?
SLOs, SLIs y SLAs son un framework para definir y medir la confiabilidad de servicios:
- **SLI (Service Level Indicator)**: métrica que mide un aspecto del servicio (ej: latencia p99)
- **SLO (Service Level Objective)**: objetivo interno para el SLI (ej: p99 < 200ms)
- **SLA (Service Level Agreement)**: compromiso contractual con consecuencias (ej: 99.9% uptime o créditos)
## Relación
```
SLI (qué medimos) → SLO (qué queremos) → SLA (qué prometemos)
```
El SLO siempre debe ser más estricto que el SLA para tener margen.
## SLIs comunes
| SLI | Medición |
|-----|----------|
| Disponibilidad | % de requests exitosos |
| Latencia | Percentil de tiempo de respuesta |
| Throughput | Requests por segundo |
| Error rate | % de requests con error |
| Freshness | Antigüedad de los datos |
## Error Budget
Error budget = 100% - SLO. Si SLO = 99.9%, tienes 0.1% de margen (~43 min/mes). Este presupuesto se «gasta» en deploys, experimentos y fallos.
## ¿Por qué importa?
Los SLOs convierten la confiabilidad en una decisión de ingeniería cuantificable. Sin ellos, los equipos no saben cuánta confiabilidad es suficiente y oscilan entre sobre-invertir en estabilidad o ignorar la deuda operacional hasta que un incidente los obliga a actuar.
## Referencias
- [SRE Book - Service Level Objectives](https://sre.google/sre-book/service-level-objectives/) — Google.
- [SLA vs SLO vs SLI](https://www.atlassian.com/incident-management/kpis/sla-vs-slo-vs-sli) — Atlassian, 2024. Comparación práctica entre SLA, SLO y SLI.
- [Implementing SLOs — SRE Workbook](https://sre.google/workbook/implementing-slos/) — Google, 2018. Guía práctica para implementar SLOs.
---
# Site Reliability Engineering
Type: concept
Status: seed
Summary: Discipline applying software engineering principles to infrastructure operations, focusing on creating scalable and highly reliable systems.
Concepts: devops, observability
## ¿Qué es?
Site Reliability Engineering (SRE) es la disciplina creada por Google que aplica principios de ingeniería de software a la operación de sistemas. El objetivo: crear sistemas escalables y confiables mediante automatización, no trabajo manual.
## Conceptos clave
- **SLO (Service Level Objective)**: objetivo de confiabilidad (ej: 99.9% uptime)
- **SLI (Service Level Indicator)**: métrica que mide el SLO
- **SLA (Service Level Agreement)**: compromiso contractual con el cliente
- **Error Budget**: margen de error permitido (100% - SLO)
- **Toil**: trabajo manual, repetitivo, automatizable
## Error Budget
Si tu SLO es 99.9%, tienes 0.1% de error budget (~43 min/mes). Mientras tengas budget:
- Puedes desplegar features nuevas
- Puedes tomar riesgos calculados
Si se agota:
- Freeze de deploys
- Enfoque en confiabilidad
## SLO y error budget en la práctica
| SLO | Error budget/mes | Error budget/año | Perfil típico |
|-----|-----------------|-----------------|---------------|
| 99% | 7.3 horas | 3.65 días | Herramientas internas, batch jobs |
| 99.9% | 43.8 minutos | 8.77 horas | APIs de producción, servicios web |
| 99.95% | 21.9 minutos | 4.38 horas | Servicios críticos de negocio |
| 99.99% | 4.38 minutos | 52.6 minutos | Infraestructura de pagos, auth |
## Prácticas
- Eliminar toil mediante automatización
- Postmortems blameless después de incidentes
- Capacity planning basado en datos
- Chaos engineering para probar resiliencia
## ¿Por qué importa?
SRE aplica principios de ingeniería de software a las operaciones. En lugar de procesos manuales y heroísmo, define SLOs medibles, automatiza la respuesta a incidentes y trata la confiabilidad como una feature que se diseña, no como algo que simplemente ocurre.
## Referencias
- [Site Reliability Engineering](https://sre.google/sre-book/table-of-contents/) — Google, libro gratuito.
- [The Site Reliability Workbook](https://sre.google/workbook/table-of-contents/) — Google, ejercicios prácticos.
- [SRE Resources](https://sre.google/resources/) — Google, 2024. Recursos adicionales de SRE incluyendo artículos y presentaciones.
---
# Service Mesh
Type: concept
Status: seed
Summary: Infrastructure layer dedicated to managing communication between microservices, providing observability, security, and traffic control transparently.
Concepts: kubernetes, microservices
## ¿Qué es?
Un service mesh es una capa de infraestructura que gestiona la comunicación entre [microservicios](/concepts/microservices) de forma transparente. Cada servicio tiene un proxy sidecar que intercepta todo el tráfico de red, proporcionando observabilidad, seguridad y control sin modificar el código de la aplicación.
## Capacidades
| Capacidad | Qué resuelve | Sin mesh | Con mesh |
|-----------|-------------|----------|----------|
| Observabilidad | Visibilidad del tráfico | Instrumentar cada servicio manualmente | [Métricas](/concepts/metrics-monitoring), [traces](/concepts/distributed-tracing) y logs automáticos |
| Seguridad | Cifrado entre servicios | Configurar TLS en cada servicio | mTLS automático, rotación de certificados |
| Control de tráfico | Deploys seguros | Todo o nada | Canary, traffic splitting, circuit breakers |
| Políticas | Gobernanza | Implementar en cada servicio | Rate limiting y access control centralizados |
## Implementaciones
| Service Mesh | Proxy | Características |
|-------------|-------|----------------|
| Istio | Envoy | El más completo, complejo |
| Linkerd | linkerd2-proxy | Ligero, simple |
| AWS App Mesh | Envoy | Integración AWS nativa |
| Consul Connect | Envoy | Multi-plataforma |
## ¿Cuándo necesitas un service mesh?
- Muchos microservicios (>10) comunicándose entre sí
- Necesitas mTLS entre servicios
- Requieres observabilidad detallada del tráfico
- Canary deployments o traffic splitting
## ¿Por qué importa?
Un service mesh gestiona la comunicación entre microservicios de forma transparente: mTLS, circuit breaking, observabilidad y traffic management sin modificar el código de la aplicación. Es la capa de red que hace operables los sistemas distribuidos complejos.
## Referencias
- [Istio Documentation](https://istio.io/latest/docs/) — Documentación oficial.
- [Linkerd](https://linkerd.io/) — Service mesh ligero.
- [Envoy Proxy](https://www.cncf.io/projects/envoy/) — CNCF, 2024. Proxy de alto rendimiento usado por la mayoría de service meshes.
---
# Serverless
Type: concept
Status: seed
Summary: Cloud computing model where the provider manages infrastructure automatically, allowing code execution without provisioning or managing servers, paying only for actual usage.
Concepts: aws-lambda, infrastructure-as-code
## ¿Qué es?
Serverless es un modelo de ejecución en la nube donde el proveedor asigna recursos dinámicamente y cobra solo por el cómputo consumido. No significa «sin servidores» — significa que el desarrollador no los gestiona. El proveedor se encarga del aprovisionamiento, escalado, parches y disponibilidad.
## Características fundamentales
- **Sin gestión de servidores**: no hay instancias que configurar ni mantener
- **Escalado automático**: de cero a miles de instancias según demanda
- **Pago por uso**: se cobra por invocación/duración, no por tiempo idle
- **Event-driven**: las funciones se ejecutan en respuesta a eventos
## Servicios serverless en AWS
| Servicio | Función |
|----------|---------|
| [Lambda](/concepts/aws-lambda) | Funciones como servicio (FaaS) |
| [API Gateway](/concepts/aws-api-gateway) | APIs HTTP/REST/WebSocket |
| [DynamoDB](/concepts/aws-dynamodb) | Base de datos NoSQL |
| [S3](/concepts/aws-s3) | Almacenamiento de objetos |
| [Step Functions](/concepts/aws-step-functions) | Orquestación de workflows |
| [EventBridge](/concepts/aws-eventbridge) | Bus de eventos |
| [SQS](/concepts/aws-sqs) / [SNS](/concepts/aws-sns) | Mensajería |
## Patrones comunes
- **API backend**: API Gateway → Lambda → DynamoDB
- **Procesamiento de eventos**: S3 upload → Lambda → procesamiento
- **Workflows**: Step Functions orquestando múltiples Lambdas
- **Cron jobs**: EventBridge schedule → Lambda
## Ventajas
- Tiempo al mercado rápido
- Costo cero cuando no hay tráfico
- Escalado sin intervención
- Menos superficie de ataque (sin OS que parchear)
## Limitaciones
- **Cold starts**: latencia en la primera invocación
- **Duración máxima**: Lambda tiene límite de 15 minutos
- **Vendor lock-in**: APIs específicas de cada proveedor
- **Debugging**: más complejo que aplicaciones monolíticas
- **Estado**: las funciones son stateless por diseño
## ¿Por qué importa?
Serverless elimina la gestión de servidores y el pago por capacidad ociosa. Para cargas de trabajo con tráfico variable — APIs, procesamiento de eventos, tareas programadas — el modelo de pago por ejecución puede reducir costos dramáticamente mientras escala automáticamente.
## Referencias
- [Serverless Architectures - AWS](https://aws.amazon.com/serverless/) — Documentación oficial.
- [Serverless Land](https://serverlessland.com/) — Patrones y recursos de AWS.
- [Serverless Framework](https://www.serverless.com/framework/docs) — Serverless Inc, 2024. Framework multi-cloud para aplicaciones serverless.
---
# Server Components
Type: concept
Status: seed
Summary: React paradigm where components execute on the server, sending only HTML to the client, reducing the JavaScript bundle and improving performance.
Concepts: nextjs, react
## ¿Qué es?
React Server Components (RSC) son componentes que se ejecutan exclusivamente en el servidor. No envían JavaScript al cliente — solo el HTML resultante. Esto reduce drásticamente el bundle size y permite acceder directamente a bases de datos, APIs y el filesystem.
## Server vs Client Components
| Aspecto | Server Component | Client Component |
|---------|-----------------|------------------|
| Ejecución | Servidor | Navegador |
| JavaScript al cliente | No | Sí |
| Interactividad | No (sin useState, onClick) | Sí |
| Acceso a DB/FS | Directo | Via API |
| Marcador | Por defecto en Next.js | `'use client'` |
## Cuándo usar cada uno
- **Server**: fetch de datos, acceso a DB, contenido estático, layouts
- **Client**: interactividad, event handlers, hooks de estado, browser APIs
## Impacto en rendimiento
- Menos JavaScript enviado al cliente
- Streaming SSR para carga progresiva
- Datos fetched en el servidor (sin waterfalls)
## ¿Por qué importa?
Los Server Components cambian fundamentalmente cómo se construyen aplicaciones React al mover el renderizado al servidor. Reducen el JavaScript enviado al cliente, simplifican el acceso a datos y mejoran el rendimiento percibido — sin sacrificar la interactividad donde se necesita.
## Referencias
- [React Server Components](https://react.dev/reference/rsc/server-components) — Documentación oficial.
- [Server Components — Next.js](https://nextjs.org/docs/app/building-your-application/rendering/server-components) — Vercel, 2024. Implementación de Server Components en Next.js.
- [Rendering — Next.js](https://nextjs.org/docs/app/building-your-application/rendering) — Vercel, 2024. Guía completa de renderizado en Next.js App Router.
---
# Semantic Search
Type: concept
Status: growing
Summary: Information retrieval technique that uses vector embeddings to find results by meaning, not just exact keyword matching.
Concepts: artificial-intelligence, retrieval-augmented-generation, ai-agents
## ¿Qué es?
La búsqueda semántica es una técnica de recuperación de información que va más allá de la coincidencia literal de palabras. En lugar de buscar si un documento contiene exactamente los términos de la consulta, convierte tanto la consulta como los documentos en vectores numéricos — llamados **embeddings** — y mide la similitud entre ellos en un espacio vectorial de alta dimensión.
Si un usuario busca «cómo desplegar en la nube», una búsqueda por palabras clave solo encontraría documentos que contengan esas palabras exactas. La búsqueda semántica también encontraría documentos sobre «deployment en AWS», «infraestructura serverless» o «CI/CD con contenedores» — porque entiende que el *significado* es similar.
## ¿Cómo funciona?
El proceso tiene tres fases:
### 1. Generación de embeddings
Un modelo de lenguaje transforma texto en vectores de dimensión fija. Cada vector captura el significado semántico del texto en un espacio donde textos similares quedan cerca entre sí.
Los modelos más comunes para esto son:
- **all-MiniLM-L6-v2** — 384 dimensiones, ligero, buena calidad general
- **text-embedding-3-small** (OpenAI) — 1536 dimensiones, API comercial
- **Cohere Embed v3** — multilingüe, optimizado para recuperación
### 2. Indexación
Los embeddings de todos los documentos se almacenan en una estructura que permite búsqueda eficiente por similitud. Las opciones van desde un simple arreglo en memoria hasta bases de datos vectoriales especializadas.
### 3. Consulta
La consulta del usuario se convierte en un embedding con el mismo modelo, y se calcula la similitud coseno contra todos los documentos indexados. Los resultados se ordenan por similitud.
```
consulta → embedding → similitud coseno → resultados ordenados
```
## Implementación en este sitio
### El primer intento (cliente)
La primera implementación de búsqueda semántica en este sitio usó [Transformers.js](https://huggingface.co/docs/transformers.js) con el modelo `Xenova/all-MiniLM-L6-v2` ejecutándose directamente en el navegador vía WebAssembly. Los embeddings se pre-computaban en build time y se pasaban como props a la página de búsqueda.
**¿Por qué se removió?** Cuatro problemas lo hicieron inviable en producción:
1. **Descarga de ~30 MB en la primera búsqueda** — el modelo ONNX se descargaba silenciosamente mientras el usuario veía «Buscando...» sin resultados. Para un sitio personal, esto es inaceptable.
2. **Inconsistencias en la API de tensores** — Transformers.js v3 devuelve tensores con formatos diferentes entre Node.js y el runtime WASM del navegador. `tolist()`, `.data` y `output[0]` se comportaban distinto según el contexto, causando fallos silenciosos.
3. **Problemas de despliegue en Vercel** — el runtime WASM tenía incompatibilidades en producción que no se reproducían localmente.
4. **Complejidad vs. valor** — con pocos artículos, la búsqueda semántica no ofrece ventaja significativa sobre la búsqueda por palabras clave.
La decisión y los detalles técnicos están documentados en el [issue #9](https://github.com/jonmatum/jonmatum.com/issues/9) del repositorio.
### El estado actual
La búsqueda actual es por palabras clave: coincidencia instantánea contra títulos, resúmenes y tags. Cero dependencias, funciona sincrónicamente, sin estado de carga.
Los embeddings pre-computados siguen generándose en build time (`scripts/generate-embeddings.ts`) y se almacenan en `public/embeddings.json` — listos para uso futuro.
## Enfoques de producción
Para implementar búsqueda semántica de forma robusta, hay varias opciones según la escala:
### Servidor con modelo local
Ejecutar el modelo de embeddings en una API route de Node.js (no en el navegador). El modelo se carga una vez al iniciar el servidor y procesa consultas en milisegundos. Viable para sitios con tráfico moderado.
### Base de datos vectorial
Para colecciones grandes, una base de datos vectorial especializada maneja la indexación y búsqueda eficiente:
- **Pinecone** — servicio gestionado, escala automática
- **Weaviate** — open source, soporta búsqueda híbrida
- **pgvector** — extensión de PostgreSQL, ideal si ya se usa Postgres
- **Qdrant** — open source, alto rendimiento
### API de embeddings + búsqueda en memoria
Para sitios estáticos con pocas decenas de documentos, pre-computar embeddings en build time y hacer la búsqueda coseno en el cliente es viable — siempre que el modelo no se descargue en el navegador. Los embeddings pre-computados pesan kilobytes, no megabytes.
### Búsqueda híbrida
La combinación de búsqueda por palabras clave y búsqueda semántica suele dar mejores resultados que cualquiera de las dos por separado. El enfoque típico es:
1. Ejecutar ambas búsquedas en paralelo
2. Normalizar los scores de cada una
3. Combinar con un peso configurable (por ejemplo, 0.7 semántico + 0.3 keyword)
## Beneficios
- **Comprensión de sinónimos y paráfrasis** — encuentra resultados relevantes aunque no compartan palabras exactas con la consulta
- **Búsqueda multilingüe** — con modelos multilingües, una consulta en español puede encontrar documentos en inglés y viceversa
- **Tolerancia a errores tipográficos** — los embeddings capturan significado, no ortografía exacta
- **Descubrimiento de contenido relacionado** — la similitud vectorial permite sugerir artículos relacionados sin configuración manual
- **Escalabilidad** — funciona igual de bien con 10 documentos que con 10 millones (con la infraestructura adecuada)
## ¿Cuándo vale la pena?
La búsqueda semántica agrega valor real cuando:
- El corpus tiene más de ~20 documentos
- Los usuarios buscan con lenguaje natural, no con términos exactos
- El contenido es multilingüe
- Se necesita descubrimiento de contenido relacionado
Para colecciones pequeñas con vocabulario predecible, la búsqueda por palabras clave es más simple, más rápida y suficientemente efectiva.
## ¿Por qué importa?
La búsqueda por palabras clave falla cuando el usuario no conoce la terminología exacta. La búsqueda semántica cierra esa brecha al entender la intención detrás de la consulta, lo que la hace esencial para bases de conocimiento, documentación técnica y cualquier sistema donde la experiencia de descubrimiento importa.
## Referencias
- [Sentence-BERT: Sentence Embeddings using Siamese BERT-Networks](https://arxiv.org/abs/1908.10084) — Reimers y Gurevych, 2019. El paper que popularizó los sentence embeddings para búsqueda semántica.
- [Transformers.js](https://huggingface.co/docs/transformers.js) — Hugging Face. Librería para ejecutar modelos Transformer en JavaScript/WASM.
- [all-MiniLM-L6-v2](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2) — Sentence Transformers. Modelo ligero de 384 dimensiones para sentence embeddings.
- [pgvector](https://github.com/pgvector/pgvector) — Andrew Kane. Extensión de PostgreSQL para búsqueda vectorial.
- [Issue #9: Re-evaluate semantic search implementation](https://github.com/jonmatum/jonmatum.com/issues/9) — jonmatum.com. Documentación de la decisión de remover búsqueda semántica del cliente.
---
# Self-Service Infrastructure
Type: concept
Status: seed
Summary: Model where development teams can provision and manage infrastructure autonomously through automated interfaces, without depending on operations tickets.
Concepts: platform-engineering, infrastructure-as-code, golden-paths
## ¿Qué es?
Infraestructura de autoservicio permite a los desarrolladores crear, modificar y destruir recursos de infraestructura sin abrir tickets ni esperar a un equipo de operaciones. La plataforma proporciona interfaces controladas con guardrails automáticos.
## Modelos
| Modelo | Mecanismo | Ejemplo | Mejor para |
|--------|-----------|---------|-----------|
| Templates | Catálogo de configuraciones pre-aprobadas | [Backstage](/concepts/backstage) Software Templates | Equipos que necesitan crear servicios nuevos |
| [GitOps](/concepts/gitops) | PR a repo de infra → despliegue automático | ArgoCD + Terraform | Equipos con experiencia en Git |
| Portal | UI web con formularios | [Backstage](/concepts/backstage), Port, Humanitec | Equipos que prefieren interfaces visuales |
| CLI | Comandos para aprovisionar | `platform create service --type=api` | Desarrolladores que prefieren la terminal |
## Guardrails
Self-service no significa sin control:
- Políticas de costo (límites por equipo)
- Compliance automático (encriptación, tags obligatorios)
- Aprobaciones para recursos de alto costo
- TTL automático para ambientes temporales
## Beneficios
- Eliminar cuellos de botella de operaciones
- Reducir tiempo de aprovisionamiento de días a minutos
- Estandarizar configuraciones
- Empoderar equipos de desarrollo
## Anti-patrones
- **Portal sin adopción**: construir la plataforma sin validar que los desarrolladores la necesitan
- **Libertad total**: self-service sin guardrails resulta en sprawl de recursos y costos descontrolados
- **Automatización frágil**: scripts ad-hoc en lugar de módulos probados y versionados
## ¿Por qué importa?
La infraestructura self-service elimina el cuello de botella de los tickets a equipos de plataforma. Cuando los desarrolladores pueden provisionar lo que necesitan a través de interfaces controladas, la velocidad de entrega aumenta sin sacrificar gobernanza.
## Referencias
- [Platform Engineering](https://platformengineering.org/) — Comunidad y recursos de platform engineering.
- [Humanitec Platform Orchestrator](https://humanitec.com/products/platform-orchestrator) — Humanitec, 2024. Orquestador de plataforma para infraestructura self-service.
- [Software Templates — Backstage](https://backstage.io/docs/features/software-templates/) — Backstage, 2024. Templates como mecanismo de self-service.
---
# Secure Coding
Type: concept
Status: seed
Summary: Development practices preventing security vulnerabilities from design, including input validation, error handling, and defense-in-depth principles.
Concepts: code-quality, devsecops
## ¿Qué es?
Secure coding son prácticas de desarrollo que previenen vulnerabilidades de seguridad desde el diseño del código. No es solo usar herramientas de escaneo — es escribir código que sea seguro por construcción.
## OWASP Top 10 (2021)
1. Broken Access Control
2. Cryptographic Failures
3. Injection
4. Insecure Design
5. Security Misconfiguration
6. Vulnerable Components
7. Authentication Failures
8. Software Integrity Failures
9. Logging Failures
10. Server-Side Request Forgery
## Principios
- **Validar inputs**: nunca confiar en datos del usuario
- **Sanitizar outputs**: escapar datos según el contexto
- **Mínimo privilegio**: dar solo los permisos necesarios
- **Defensa en profundidad**: múltiples capas de protección
- **Fail securely**: los errores no deben exponer información
## Prácticas específicas
| Vulnerabilidad | Código inseguro | Código seguro |
|---------------|----------------|---------------|
| SQL Injection | `query("SELECT * FROM users WHERE id=" + id)` | `query("SELECT * FROM users WHERE id=$1", [id])` |
| XSS | `innerHTML = userInput` | `textContent = userInput` o sanitizar con DOMPurify |
| Path Traversal | `readFile("/uploads/" + filename)` | Validar que `filename` no contiene `..` |
| Hardcoded secrets | `const key = "sk-abc123"` | `const key = process.env.API_KEY` |
| Insecure crypto | `md5(password)` | `bcrypt.hash(password, 12)` |
Reglas generales:
- Usar prepared statements (no concatenar SQL)
- Escapar HTML para prevenir XSS
- Validar y sanitizar file uploads
- No exponer stack traces en producción
- Usar bibliotecas de crypto probadas (no implementar propias)
## ¿Por qué importa?
La seguridad no se añade al final — se construye desde el código. Las prácticas de codificación segura previenen vulnerabilidades antes de que lleguen a producción, donde el costo de remediarlas es órdenes de magnitud mayor.
## Referencias
- [OWASP Top 10](https://owasp.org/www-project-top-ten/) — Vulnerabilidades más comunes.
- [OWASP Cheat Sheets](https://cheatsheetseries.owasp.org/) — Guías prácticas.
- [CWE Top 25](https://cwe.mitre.org/top25/archive/2023/2023_top25_list.html) — MITRE, 2023. Las 25 debilidades de software más peligrosas.
---
# Secrets Management
Type: concept
Status: seed
Summary: Practices and tools for securely storing, distributing, and rotating credentials, API keys, and other sensitive data in applications and pipelines.
Concepts: platform-engineering, aws-iam
## ¿Qué es?
Secrets management es la práctica de gestionar datos sensibles (contraseñas, API keys, certificados, tokens) de forma segura a lo largo del ciclo de vida de las aplicaciones. El principio fundamental: los secretos nunca deben estar en código.
## Anti-patrones
- Secretos hardcodeados en código fuente
- Secretos en variables de entorno sin encriptar
- Secretos compartidos por Slack/email
- Un solo secreto compartido entre todos los ambientes
## Herramientas
| Herramienta | Tipo |
|-------------|------|
| AWS Secrets Manager | Managed, rotación automática |
| AWS SSM Parameter Store | Managed, más simple |
| HashiCorp Vault | Self-hosted, muy completo |
| 1Password/Doppler | SaaS, developer-friendly |
| SOPS | Encriptación de archivos en Git |
## Mejores prácticas
- Rotación automática de secretos
- Principio de mínimo privilegio
- Auditoría de acceso a secretos
- Diferentes secretos por ambiente
- Detección de secretos en código (GitLeaks, TruffleHog)
## ¿Por qué importa?
Los secretos hardcodeados en código o variables de entorno son una de las causas más comunes de brechas de seguridad. Un sistema de gestión de secretos centralizado — con rotación automática, auditoría y acceso basado en roles — es infraestructura de seguridad básica.
## Referencias
- [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/) — Documentación oficial.
- [HashiCorp Vault](https://www.vaultproject.io/) — HashiCorp, 2024. Solución líder de gestión de secretos.
- [Secrets Manager Best Practices](https://docs.aws.amazon.com/secretsmanager/latest/userguide/best-practices.html) — AWS, 2024. Mejores prácticas oficiales.
---
# SDK Design
Type: concept
Status: seed
Summary: Principles for designing development kits that are intuitive, consistent, and facilitate service integration across multiple programming languages.
Concepts: api-design, developer-experience, api-documentation
## ¿Qué es?
Un SDK (Software Development Kit) es una biblioteca que abstrae la complejidad de interactuar con un servicio, proporcionando una interfaz idiomática en el lenguaje del desarrollador. Un buen SDK hace que la integración sea natural.
## Principios de diseño
- **Idiomático**: seguir las convenciones del lenguaje target
- **Consistente**: patrones predecibles entre métodos
- **Tipado**: aprovechar el sistema de tipos del lenguaje
- **Documentado**: ejemplos para cada operación
- **Versionado**: semver, backward compatibility
## Capas de un SDK
| Capa | Responsabilidad | Ejemplo |
|------|----------------|---------|
| HTTP client | Comunicación con la API | `fetch`, `axios`, `httpx` |
| Serialización | JSON ↔ objetos del lenguaje | Zod, Pydantic, Jackson |
| Autenticación | Manejo de tokens/keys | OAuth refresh, API key headers |
| Retry/Error handling | Reintentos y errores tipados | Exponential backoff, error codes |
| Interfaz pública | Métodos que el desarrollador usa | `client.users.list()` |
## Generación automática
| Herramienta | Input | Output | Tradeoff |
|-------------|-------|--------|----------|
| OpenAPI Generator | OpenAPI spec | SDKs multi-lenguaje | Código genérico, poco idiomático |
| [Smithy](https://smithy.io/) | Smithy model | SDKs AWS-style | Más control, más setup |
| Stainless | OpenAPI spec | SDKs idiomáticos | Comercial, alta calidad |
## Anti-patrones
- **SDK genérico**: código generado sin adaptar a las convenciones del lenguaje — se siente ajeno
- **Errores opacos**: mensajes como «request failed» sin contexto de qué falló ni cómo resolverlo
- **Acoplamiento a versión de API**: cambios en la API rompen el SDK sin path de migración
## ¿Por qué importa?
Un SDK bien diseñado multiplica la adopción de tu API. Reduce la fricción de integración, maneja errores de forma idiomática y proporciona tipos que guían al desarrollador. Un SDK mal diseñado genera tickets de soporte y frustración.
## Referencias
- [Azure SDK Design Guidelines](https://azure.github.io/azure-sdk/general_introduction.html) — Microsoft, 2023. Ejemplo de guías de diseño de SDK.
- [Smithy](https://smithy.io/) — AWS, 2024. Lenguaje de definición de interfaces para generar SDKs.
- [AWS Developer Tools](https://aws.amazon.com/developer/tools/) — AWS, 2024. Ejemplo de ecosistema de SDKs multi-lenguaje.
---
# Saga Pattern
Type: concept
Status: seed
Summary: Pattern for managing distributed transactions in microservices through a sequence of local transactions with compensating actions to handle failures.
Concepts: microservices, event-driven-architecture, cqrs, event-sourcing, distributed-tracing
## ¿Qué es?
El patrón Saga gestiona transacciones que abarcan múltiples [microservicios](/concepts/microservices). En lugar de una transacción ACID distribuida (costosa y frágil), una saga es una secuencia de transacciones locales donde cada paso tiene una acción de compensación en caso de fallo.
## Tipos
### Coreografía
Cada servicio escucha eventos y decide qué hacer:
```
Pedido creado → Inventario reservado → Pago procesado → Pedido confirmado
↓ (fallo)
Inventario liberado ← Pago rechazado
```
### Orquestación
Un orquestador central coordina los pasos:
```
Orquestador → Reservar inventario → Procesar pago → Confirmar pedido
← Compensar si falla algún paso
```
## Coreografía vs Orquestación
| Aspecto | Coreografía | Orquestación |
|---------|-------------|---------------|
| Acoplamiento | Bajo | Medio |
| Visibilidad | Difícil de rastrear | Flujo claro |
| Complejidad | Crece con servicios | Centralizada |
## ¿Cuándo usarlo?
- Transacciones que cruzan múltiples servicios (pedidos, pagos, inventario)
- Cuando la consistencia eventual es aceptable
- Procesos de negocio de larga duración (días o semanas)
## ¿Cuándo no usarlo?
- Si puedes resolver con una sola base de datos — no agregues complejidad innecesaria
- Cuando necesitas consistencia fuerte inmediata (transferencias bancarias en tiempo real)
- Si tienes menos de 3 servicios involucrados — probablemente no vale la pena
## Principios de diseño
- **Idempotencia** — cada paso debe poder ejecutarse múltiples veces sin efectos secundarios
- **Compensaciones explícitas** — cada transacción local necesita su reversa definida de antemano
- **Observabilidad** — sin [trazabilidad distribuida](/concepts/distributed-tracing), depurar sagas es una pesadilla
- **Timeouts** — definir cuánto esperar antes de considerar un paso como fallido
## ¿Por qué importa?
En sistemas distribuidos, las transacciones ACID no cruzan fronteras de servicio. El patrón saga coordina transacciones distribuidas mediante una secuencia de transacciones locales con compensaciones, manteniendo la consistencia eventual sin bloqueos distribuidos.
## Referencias
- [Saga Pattern](https://microservices.io/patterns/data/saga.html) — Chris Richardson. Referencia canónica del patrón.
- [Sagas](https://www.cs.cornell.edu/andru/cs711/2002fa/reading/sagas.pdf) — Hector Garcia-Molina, Kenneth Salem, 1987. El paper original de Princeton.
- [Saga Pattern — Azure](https://learn.microsoft.com/en-us/azure/architecture/reference-architectures/saga/saga) — Microsoft, 2024. Guía de implementación del patrón saga.
---
# Retrieval-Augmented Generation (RAG)
Type: concept
Status: seed
Summary: Architectural pattern that combines information retrieval from external sources with LLM text generation, reducing hallucinations and keeping knowledge current without retraining the model.
Concepts: semantic-search, llms-txt, ai-agents
## ¿Qué es?
RAG (Retrieval-Augmented Generation) es un patrón que mejora las respuestas de un [LLM](/concepts/large-language-models) inyectando información relevante recuperada de fuentes externas directamente en el contexto del prompt. En lugar de depender solo del conocimiento almacenado en los pesos del modelo, el sistema busca documentos relevantes y los incluye como contexto antes de generar la respuesta.
El concepto fue formalizado por Lewis et al. en 2020, pero se ha convertido en el patrón dominante para aplicaciones empresariales de IA generativa.
## ¿Cómo funciona?
El flujo típico de RAG tiene tres etapas:
### 1. Indexación (offline)
Los documentos fuente se procesan y almacenan para búsqueda eficiente:
- Los documentos se dividen en fragmentos (chunks) de tamaño manejable
- Cada fragmento se convierte en un [embedding](/concepts/embeddings) — un vector numérico que captura su significado semántico
- Los vectores se almacenan en una [base de datos vectorial](/concepts/vector-databases) o índice de búsqueda
### 2. Recuperación (runtime)
Cuando llega una consulta del usuario:
- La consulta se convierte en un embedding usando el mismo modelo
- Se buscan los fragmentos más similares por distancia vectorial (coseno, producto punto)
- Se seleccionan los top-K fragmentos más relevantes
### 3. Generación (runtime)
- Los fragmentos recuperados se inyectan en el prompt como contexto
- El LLM genera una respuesta basada en la consulta Y el contexto proporcionado
- Opcionalmente, se incluyen citas a las fuentes originales
## Patrones avanzados
- **RAG híbrido**: combina búsqueda vectorial con búsqueda por palabras clave (BM25) para mejor cobertura
- **RAG iterativo**: el agente realiza múltiples rondas de recuperación, refinando la búsqueda según resultados intermedios
- **RAG con reranking**: un modelo secundario reordena los resultados de búsqueda por relevancia antes de pasarlos al LLM
- **GraphRAG**: utiliza [grafos de conocimiento](/concepts/knowledge-graphs) en lugar de (o además de) búsqueda vectorial
## ¿Por qué no solo fine-tuning?
| Aspecto | RAG | Fine-tuning |
|---------|-----|-------------|
| Actualización de datos | Inmediata (cambiar documentos) | Requiere reentrenar |
| Costo | Bajo (infraestructura de búsqueda) | Alto (GPU, datos etiquetados) |
| Trazabilidad | Alta (citas a fuentes) | Baja (conocimiento en pesos) |
| Alucinaciones | Reducidas (contexto factual) | Persisten |
| Conocimiento especializado | Bueno con buenos documentos | Mejor para estilo/formato |
En la práctica, muchos sistemas combinan ambos: fine-tuning para el estilo y formato, RAG para el conocimiento factual.
## Conexión con llms.txt
El estándar [llms.txt](/concepts/llms-txt) es un ejemplo práctico de RAG: proporciona a los agentes un documento estructurado que pueden recuperar y usar como contexto para responder preguntas sobre un sitio o proyecto.
## Limitaciones
- **Calidad del chunking**: fragmentos mal divididos producen contexto irrelevante
- **Límite de contexto**: no se pueden inyectar documentos infinitos — la ventana de contexto del LLM es finita
- **Latencia**: la etapa de recuperación añade tiempo a cada consulta
- **Garbage in, garbage out**: si los documentos fuente tienen errores, el LLM los propagará con confianza
## ¿Por qué importa?
RAG es la técnica más práctica para dar a los LLMs acceso a información actualizada y específica del dominio sin fine-tuning. Combina la capacidad generativa del modelo con datos recuperados en tiempo real, reduciendo alucinaciones y manteniendo las respuestas fundamentadas en fuentes verificables.
## Referencias
- [Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks](https://arxiv.org/abs/2005.11401) — Lewis et al., 2020. El paper original que formalizó RAG.
- [From Local to Global: A Graph RAG Approach](https://arxiv.org/abs/2404.16130) — Microsoft Research, 2024. GraphRAG para consultas sobre corpus completos.
- [RAGAS: Automated Evaluation of RAG](https://arxiv.org/abs/2309.15217) — Es et al., 2023. Framework de evaluación para sistemas RAG.
---
# React
Type: concept
Status: seed
Summary: JavaScript library for building user interfaces through declarative, reusable components, with an ecosystem spanning from SPAs to full-stack applications with Server Components.
Concepts: typescript, micro-frontends
## ¿Qué es?
React es una biblioteca de JavaScript para construir interfaces de usuario. Su modelo mental: la UI es una función del estado. Cuando el estado cambia, React actualiza eficientemente solo las partes del DOM que necesitan cambiar.
## Conceptos clave
| Concepto | Función |
|----------|---------|
| Components | Bloques reutilizables de UI |
| JSX | Sintaxis que combina JavaScript y HTML |
| Props | Datos que fluyen de padre a hijo |
| State | Datos internos que cambian con el tiempo |
| Hooks | Funciones para usar estado y efectos en componentes funcionales |
| Virtual DOM | Representación en memoria para diffing eficiente |
## Evolución
| Era | Modelo |
|-----|--------|
| 2013-2018 | Class components, lifecycle methods |
| 2019-2023 | Hooks, functional components |
| 2023+ | Server Components, streaming SSR |
## Ecosistema
- **[Next.js](/concepts/nextjs)**: framework full-stack
- **[Tailwind CSS](/concepts/tailwindcss)**: utility-first CSS
- **React Router / TanStack Router**: routing
- **Zustand / Jotai**: state management
## ¿Por qué importa?
React definió el paradigma de UI basada en componentes que domina el desarrollo web moderno. Su ecosistema — Next.js, React Native, Server Components — lo hace relevante tanto para web como para móvil. Entender su modelo mental de renderizado es fundamental para cualquier desarrollador frontend.
## Referencias
- [React Documentation](https://react.dev/) — Documentación oficial.
- [React Learn](https://react.dev/learn) — React, 2024. Tutorial oficial interactivo.
- [React Blog](https://react.dev/blog) — React, 2024. Anuncios y novedades del equipo de React.
---
# Prompt Engineering
Type: concept
Status: growing
Summary: The discipline of designing effective instructions for language models, combining clarity, structure, and examples to obtain consistent, high-quality responses.
Concepts: artificial-intelligence, ai-agents, mcp
La ingeniería de prompts es el proceso de diseñar instrucciones que guían a un modelo de lenguaje para generar respuestas que cumplan con requisitos específicos de formato, tono, precisión y contenido. No es simplemente «hacer preguntas a una IA» — es una disciplina que combina claridad comunicativa, pensamiento estructurado y experimentación iterativa.
## ¿Qué es?
Un prompt es la entrada de texto que recibe un modelo de lenguaje. La ingeniería de prompts consiste en optimizar esa entrada para maximizar la calidad de la salida. Dado que los modelos son no determinísticos, obtener resultados consistentes requiere técnicas específicas que van más allá de la intuición.
Cada proveedor de modelos publica guías oficiales con recomendaciones adaptadas a las fortalezas de sus modelos. Aunque las técnicas fundamentales son universales, los detalles de implementación varían.
## Principios universales
Estas técnicas funcionan con cualquier modelo de lenguaje moderno:
### Ser claro y directo
Instrucciones específicas producen mejores resultados que instrucciones vagas. En lugar de «escribe algo sobre X», especificar formato, longitud, tono y audiencia.
### Proporcionar contexto
Incluir la información relevante que el modelo necesita para resolver el problema. No asumir que el modelo tiene todo el contexto necesario — tratarlo como un colaborador brillante pero nuevo que no conoce los detalles de tu proyecto.
### Usar ejemplos (few-shot prompting)
Mostrar al modelo qué aspecto tiene una respuesta correcta. Entre 3 y 5 ejemplos diversos suelen ser suficientes para establecer el patrón deseado. Los ejemplos son una de las formas más confiables de controlar formato, tono y estructura.
### Estructurar el prompt
Separar instrucciones, contexto, ejemplos y datos de entrada usando delimitadores claros — ya sea con etiquetas XML, encabezados Markdown o separadores de texto. Esto reduce la ambigüedad y mejora la interpretación.
### Asignar un rol
Definir quién es el modelo en el prompt del sistema enfoca su comportamiento y tono. Incluso una sola oración marca diferencia.
### Descomponer tareas complejas
En lugar de un prompt monolítico, dividir en pasos secuenciales (encadenamiento de prompts) o en subtareas paralelas que se agregan al final.
### Iterar
El diseño de prompts es iterativo. Reformular, cambiar el orden del contenido, probar con diferentes niveles de detalle y medir resultados.
## Guía por proveedor
### Anthropic (Claude)
Anthropic enfatiza la estructura y la claridad como pilares fundamentales. Sus recomendaciones clave:
- **Etiquetas XML**: Claude responde especialmente bien a prompts estructurados con etiquetas como ``, ``, ``. Usar nombres descriptivos y consistentes.
- **Pensamiento extendido**: para tareas complejas, habilitar el modo de pensamiento adaptativo permite que Claude calibre su razonamiento según la complejidad de cada consulta.
- **Contexto largo**: colocar documentos extensos al inicio del prompt y las instrucciones al final — esto puede mejorar la calidad hasta un 30%.
- **Anclar en citas**: para tareas con documentos largos, pedir que cite las partes relevantes antes de responder.
- **Sistemas agénticos**: para tareas autónomas de larga duración, incluir instrucciones explícitas sobre persistencia, verificación de progreso y gestión de estado. Usar git para rastrear estado entre sesiones.
- **Evitar sobre-ingeniería**: los modelos Claude 4.x siguen instrucciones con alta fidelidad — prompts más simples y directos suelen funcionar mejor que prompts excesivamente elaborados.
### OpenAI (GPT)
OpenAI distingue entre modelos GPT y modelos de razonamiento, cada uno con estrategias diferentes:
- **Roles de mensaje**: usar el parámetro `instructions` o roles de mensaje (`developer`, `user`) para establecer jerarquía de autoridad en las instrucciones.
- **Markdown y XML**: combinar encabezados Markdown para secciones y etiquetas XML para delimitar datos de contexto. Estructura recomendada: identidad, instrucciones, ejemplos, contexto.
- **Modelos GPT vs razonamiento**: los modelos GPT se benefician de instrucciones precisas y explícitas (como un colaborador junior). Los modelos de razonamiento funcionan mejor con objetivos de alto nivel (como un colaborador senior).
- **Prompts reutilizables**: OpenAI ofrece plantillas de prompts almacenadas que aceptan variables, útiles para estandarizar prompts en producción.
- **Evaluaciones**: construir evals que midan el comportamiento de los prompts para monitorear rendimiento al iterar o cambiar versiones de modelo.
### Google (Gemini)
Google promueve el framework PTCF (Persona, Task, Context, Format) y enfatiza los ejemplos:
- **Framework PTCF**: estructurar cada prompt con persona (quién es el modelo), tarea (qué debe hacer), contexto (información relevante) y formato (cómo debe responder).
- **Completado parcial**: proporcionar el inicio de la respuesta deseada para guiar al modelo en la dirección correcta — especialmente útil para controlar formato de salida.
- **Parámetros del modelo**: experimentar con temperatura, topK y topP. Para Gemini 3, se recomienda mantener la temperatura en su valor predeterminado de 1.0.
- **Instrucciones del sistema**: colocar restricciones de comportamiento críticas y definiciones de rol en las instrucciones del sistema, no en el prompt del usuario.
- **Contexto largo**: para grandes volúmenes de datos, colocar todo el contexto primero y las instrucciones al final. Usar una frase de transición como «basándote en la información anterior» para anclar la consulta.
- **Razonamiento explícito**: para tareas complejas, pedir al modelo que planifique en sub-tareas y se auto-critique antes de dar la respuesta final.
### Meta (Llama)
Los modelos Llama son open-source y requieren atención especial al formato de tokens:
- **Tokens especiales**: Llama usa tokens de control como `<|begin_of_text|>`, `<|start_header_id|>` y `<|eot_id|>` para delimitar roles y turnos de conversación.
- **Instrucciones positivas**: formular lo que el modelo debe hacer, no lo que debe evitar. Las instrucciones positivas producen mejores resultados.
- **Inicio de respuesta**: comenzar el prompt con la primera palabra o frase de la respuesta deseada para guiar la dirección del modelo.
- **Iteración simple**: comenzar con un prompt simple y conciso, luego refinar. Colocar instrucciones al inicio o al final del prompt donde el modelo presta más atención.
### Amazon Bedrock
Bedrock es una plataforma que ofrece acceso a múltiples modelos, con herramientas adicionales de gestión:
- **Gestión de prompts**: Bedrock Prompt Management permite versionar, optimizar y colaborar en prompts dentro de un flujo estructurado.
- **RAG para reducir alucinaciones**: combinar prompts con Retrieval Augmented Generation para proporcionar al modelo acceso a datos relevantes y actualizados.
- **Caché de prompts**: para prefijos de prompt repetidos, el caché reduce latencia y costos al reutilizar el procesamiento previo.
- **Guardrails**: capa determinística de seguridad que complementa las técnicas probabilísticas de prompt engineering con filtrado de contenido y verificación automatizada.
## Técnicas avanzadas
| Técnica | Mecanismo | Cuándo usar |
|---------|-----------|-------------|
| [Chain-of-Thought](/concepts/chain-of-thought) | Pedir «piensa paso a paso» antes de responder | Razonamiento, matemáticas, lógica |
| Prompt chaining | Salida de un prompt alimenta el siguiente | Tareas complejas con pasos secuenciales |
| Self-consistency | Generar múltiples respuestas y seleccionar la más frecuente | Reducir errores en razonamiento |
| [RAG](/concepts/retrieval-augmented-generation) | Combinar prompt con información de fuentes externas | Reducir [alucinaciones](/concepts/hallucination-mitigation), mantener respuestas actualizadas |
| Few-shot | Incluir ejemplos de entrada/salida en el prompt | Controlar formato y estilo de respuesta |
## ¿Por qué importa?
La calidad de la entrada determina la calidad de la salida. A medida que los modelos de lenguaje se integran en más herramientas y flujos de trabajo — desde asistentes de código hasta agentes autónomos — la capacidad de comunicarse efectivamente con ellos se convierte en una habilidad fundamental.
No se trata de memorizar trucos, sino de desarrollar un modelo mental de cómo procesan información estos sistemas y usar ese entendimiento para obtener resultados predecibles y de alta calidad.
## Referencias
- [Prompting best practices](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/claude-prompting-best-practices) — Anthropic. Guía oficial de mejores prácticas para Claude.
- [Prompt engineering overview](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview) — Anthropic. Introducción al prompt engineering con Claude.
- [Prompt engineering guide](https://platform.openai.com/docs/guides/prompt-engineering) — OpenAI. Guía oficial para modelos GPT y de razonamiento.
- [Best practices for prompt engineering](https://help.openai.com/en/articles/6654000-best-practices-for-prompt-engineering-with-the-openai-api) — OpenAI. Referencia rápida de mejores prácticas.
- [Prompt design strategies](https://ai.google.dev/gemini-api/docs/prompting-strategies) — Google. Estrategias oficiales para modelos Gemini.
- [Prompt engineering whitepaper](https://www.kaggle.com/whitepaper-prompt-engineering) — Google, 2025. Playbook de 68 páginas sobre prompt engineering.
- [Prompt engineering concepts](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-engineering-guidelines.html) — AWS. Guía oficial de Amazon Bedrock.
- [Best prompting practices for Meta Llama 3](https://aws.amazon.com/blogs/machine-learning/best-prompting-practices-for-using-meta-llama-3-with-amazon-sagemaker-jumpstart/) — AWS, 2024. Mejores prácticas para modelos Llama en SageMaker.
---
# Prompt Caching
Type: concept
Status: seed
Summary: Technique that stores the internal computation of reused prompt prefixes across LLM calls, reducing costs by up to 90% and latency by up to 85% in applications with repetitive context.
Concepts: inference-optimization, context-windows, cost-optimization, large-language-models
## ¿Qué es?
El caché de prompts es una optimización ofrecida por proveedores de [LLMs](/concepts/large-language-models) que almacena el cómputo interno (los estados de atención) de prefijos de prompt que se repiten entre llamadas a la API. En lugar de reprocesar miles de tokens idénticos en cada request, el modelo reutiliza el cómputo previo y solo procesa los tokens nuevos.
A diferencia del caché tradicional en software — que almacena *salidas* como respuestas HTTP o resultados de consultas — el caché de prompts almacena *entradas procesadas*, porque las salidas de un LLM son dinámicas y varían con cada generación.
## ¿Cómo funciona?
El proceso sigue tres pasos:
1. **Primera llamada**: el proveedor procesa el prompt completo y almacena el estado interno del prefijo
2. **Llamadas subsecuentes**: el sistema detecta que el prefijo coincide con uno almacenado y reutiliza el cómputo
3. **Solo lo nuevo**: el modelo procesa únicamente los tokens que difieren del prefijo cacheado
El caché tiene una ventana de tiempo limitada — típicamente entre 5 y 10 minutos de inactividad antes de expirar.
## Implementaciones por proveedor
| Proveedor | Tipo | Mínimo de tokens | Descuento | Latencia |
|-----------|------|-------------------|-----------|----------|
| Anthropic (Claude) | Explícito — requiere marcar bloques con `cache_control` | 1.024 | 90% en tokens cacheados | Hasta 85% menos |
| OpenAI (GPT-4o, o1) | Automático — sin cambios de código | 1.024 | 50% en tokens cacheados | Reducción variable |
| Google (Gemini) | Explícito — requiere configuración manual | Variable | Hasta 75% | Variable |
| DeepSeek | Automático | 1.024 | Hasta 90% | Variable |
### Ejemplo con Anthropic
```python
response = client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=1024,
system=[{
"type": "text",
"text": documento_largo, # Miles de tokens
"cache_control": {"type": "ephemeral"}
}],
messages=[{"role": "user", "content": pregunta}]
)
```
El bloque marcado con `cache_control` se almacena tras la primera llamada. Las siguientes llamadas con el mismo prefijo pagan solo el precio de lectura de caché.
## ¿Cuándo usarlo?
El caché de prompts es más efectivo cuando:
- **Documentos largos como contexto**: análisis repetido del mismo documento con diferentes preguntas
- **System prompts extensos**: instrucciones complejas que se repiten en cada llamada
- **Conversaciones con historial**: el historial crece pero el prefijo se mantiene
- **Few-shot learning**: los mismos ejemplos se envían en cada request
- **Agentes con herramientas**: la definición de herramientas se repite en cada iteración del loop
## Consideraciones
- **Orden importa**: el caché funciona por coincidencia de prefijo — cambiar el orden de los bloques invalida el caché
- **Costo de escritura**: la primera escritura al caché puede costar más que un request normal (25% más en Anthropic)
- **Ventana de expiración**: el caché expira tras minutos de inactividad
- **No es semántico**: requiere coincidencia exacta de tokens, no similitud de significado
## ¿Por qué importa?
En aplicaciones de IA con contexto repetitivo — agentes, RAG, análisis de documentos — el costo de tokens de entrada domina la factura. El caché de prompts convierte un gasto lineal en uno casi constante: el primer request paga el precio completo, pero los siguientes pagan una fracción. Para un agente que itera 10 veces con el mismo system prompt y herramientas, la diferencia puede ser de 10x en costo.
## Referencias
- [Prompt Caching — OpenAI Docs](https://platform.openai.com/docs/guides/prompt-caching) — Documentación oficial de OpenAI.
- [Prompt Caching: Cost & Performance Analysis](https://artificialanalysis.ai/models/caching) — Artificial Analysis. Comparativa entre proveedores.
- [Prompt Caching — Anthropic](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching) — Anthropic, 2024. Implementación de prompt caching en Claude.
---
# Progressive Web Apps
Type: concept
Status: seed
Summary: Web applications using modern technologies to deliver native app-like experiences: installable, offline-capable, and with push notifications.
Concepts: react, serverless
## ¿Qué es?
Una Progressive Web App (PWA) es una aplicación web que usa Service Workers, Web App Manifest y otras APIs modernas para ofrecer una experiencia similar a una app nativa: instalable en el home screen, funcional offline y con notificaciones push.
## Características
- **Instalable**: se agrega al home screen sin app store
- **Offline**: funciona sin conexión (Service Worker + cache)
- **Responsive**: se adapta a cualquier pantalla
- **Push notifications**: notificaciones como app nativa
- **Linkable**: accesible vía URL
## Tecnologías clave
- **Service Worker**: proxy de red que intercepta requests y gestiona cache
- **Web App Manifest**: metadata para instalación (nombre, icono, colores)
- **Cache API**: almacenamiento de recursos para uso offline
- **Background Sync**: sincronizar datos cuando vuelve la conexión
## PWA vs App Nativa
| Aspecto | PWA | Nativa |
|---------|-----|--------|
| Distribución | URL (sin app store) | App Store |
| Instalación | Opcional, ligera | Requerida |
| Actualizaciones | Automáticas | Manual/auto |
| Acceso a hardware | Limitado | Completo |
| Costo de desarrollo | Menor (una codebase) | Mayor (por plataforma) |
## ¿Por qué importa?
Las PWAs combinan lo mejor de la web y las apps nativas: instalables, funcionan offline y se actualizan automáticamente. Para productos que no justifican el costo de mantener apps nativas en múltiples plataformas, son la alternativa pragmática.
## Referencias
- [web.dev PWA](https://web.dev/progressive-web-apps/) — Guía de Google.
- [Learn PWA](https://web.dev/learn/pwa/) — Google, 2024. Curso completo de PWAs.
- [Progressive Web Apps — MDN](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps) — MDN, 2024. Documentación de referencia.
---
# Policy as Code
Type: concept
Status: seed
Summary: Practice of defining security, compliance, and governance policies as versioned, executable code, automating their verification in CI/CD pipelines.
Concepts: infrastructure-as-code, platform-engineering
## ¿Qué es?
Policy as Code define reglas de seguridad, compliance y gobernanza como código que se versiona en Git y se ejecuta automáticamente. En lugar de checklists manuales, las políticas se verifican programáticamente.
## Herramientas
| Herramienta | Uso |
|-------------|-----|
| OPA (Open Policy Agent) | Políticas generales (K8s, APIs, Terraform) |
| HashiCorp Sentinel | Políticas para Terraform Enterprise |
| AWS Config Rules | Compliance en AWS |
| Checkov | Escaneo de IaC |
| Kyverno | Políticas nativas de Kubernetes |
## Ejemplos de políticas
- Todo bucket S3 debe tener encriptación habilitada
- Ningún security group puede tener puerto 22 abierto al mundo
- Todos los recursos deben tener tags de costo
- Las imágenes de contenedores deben venir de registros aprobados
## Beneficios
- Compliance automatizado y consistente
- Feedback temprano (shift-left)
- Auditable (historial en Git)
- Escalable (mismas políticas para todos los equipos)
## ¿Por qué importa?
Las políticas manuales no escalan. Policy as code permite definir, versionar y aplicar automáticamente reglas de seguridad, compliance y gobernanza. Cada cambio de infraestructura se valida contra las políticas antes de aplicarse, cerrando la brecha entre intención y realidad.
## Referencias
- [Open Policy Agent](https://www.openpolicyagent.org/) — Motor de políticas CNCF.
- [OPA Documentation](https://www.openpolicyagent.org/docs/latest/) — OPA, 2024. Documentación completa del motor de políticas.
- [Kyverno](https://kyverno.io/) — CNCF, 2024. Motor de políticas nativo de Kubernetes.
---
# Platform Engineering
Type: concept
Status: seed
Summary: Discipline designing and building internal self-service platforms so development teams can deploy and operate applications autonomously.
Concepts: devops, developer-experience
## ¿Qué es?
Platform Engineering es la disciplina de diseñar y construir plataformas internas que permiten a los equipos de desarrollo desplegar y operar aplicaciones de forma autónoma, sin depender de un equipo de operaciones centralizado.
## ¿Por qué?
DevOps prometió «you build it, you run it», pero la carga cognitiva de gestionar infraestructura, CI/CD, observabilidad y seguridad es demasiada para equipos de producto. Platform Engineering abstrae esa complejidad.
## Componentes de una plataforma interna
- **[Golden paths](/concepts/golden-paths)**: caminos recomendados para tareas comunes
- **[Self-service](/concepts/self-service-infrastructure)**: portales donde los devs crean recursos sin tickets
- **Templates**: scaffolding de proyectos con mejores prácticas
- **Guardrails**: [políticas automáticas](/concepts/policy-as-code) (no gates manuales)
- **[Observabilidad](/concepts/observability)**: dashboards y alertas pre-configurados
## Plataforma vs herramientas sueltas
| Enfoque | Herramientas sueltas | Plataforma interna |
|---------|---------------------|-------------------|
| Onboarding | Cada equipo configura su stack | Template + golden path en minutos |
| Compliance | Revisión manual por seguridad | [Policy as code](/concepts/policy-as-code) automático |
| Infraestructura | Tickets al equipo de ops | [Self-service](/concepts/self-service-infrastructure) con guardrails |
| Observabilidad | Cada equipo configura Grafana | Dashboards pre-configurados por tipo de servicio |
| Carga cognitiva | Alta — cada dev es también ops | Baja — la plataforma abstrae la complejidad |
## Errores comunes
- **Construir sin usuarios**: la plataforma debe resolver problemas reales de los equipos, no ser un proyecto de infraestructura
- **Forzar adopción**: la mejor señal de éxito es la adopción voluntaria
- **Plataforma como gate**: la plataforma habilita, no bloquea — guardrails, no gates
## Métricas de éxito
- Tiempo de onboarding de nuevos servicios
- Frecuencia de deploys
- Satisfacción del desarrollador
- Adopción voluntaria de la plataforma
## ¿Por qué importa?
Platform engineering es la disciplina que construye la capa de abstracción entre los equipos de producto y la infraestructura. Su objetivo es que los desarrolladores puedan desplegar, observar y operar sus servicios sin necesitar un equipo de infraestructura dedicado para cada tarea.
## Referencias
- [Platform Engineering](https://platformengineering.org/) — Comunidad y recursos.
- [Team Topologies](https://teamtopologies.com/) — Matthew Skelton & Manuel Pais.
- [Internal Developer Platform](https://internaldeveloperplatform.org/) — IDP, 2024. Recursos y definiciones de plataformas internas.
---
# OpenTofu
Type: concept
Status: evergreen
Summary: Open source fork of Terraform maintained by the Linux Foundation. Compatible with HCL and Terraform providers, created in response to HashiCorp's license change to BSL 1.1.
Concepts: terraform, infrastructure-as-code, devops-practices
**OpenTofu** es un fork de Terraform creado en septiembre de 2023 cuando HashiCorp cambió la licencia de Terraform de MPL 2.0 (open source) a BSL 1.1 (source-available, con restricciones comerciales). La Linux Foundation adoptó el proyecto para garantizar que una alternativa verdaderamente open source existiera.
## ¿Por qué existe?
### La cronología
1. **2014-2023** — Terraform bajo licencia MPL 2.0 (open source permisiva)
2. **Agosto 2023** — HashiCorp cambia a BSL 1.1 (prohíbe productos competitivos)
3. **Septiembre 2023** — Manifiesto OpenTF firmado por 100+ empresas
4. **Octubre 2023** — Linux Foundation adopta el proyecto como OpenTofu
5. **Enero 2024** — OpenTofu 1.6.0 (primera release estable)
### ¿Qué prohíbe BSL 1.1?
La licencia BSL 1.1 de Terraform permite usar, copiar y modificar el código, pero **prohíbe ofrecer un producto competitivo** basado en él. Esto afecta a:
- Empresas que ofrecen Terraform-as-a-Service
- Plataformas de IaC que integran Terraform
- Managed services que compiten con Terraform Cloud
Para usuarios finales que solo usan Terraform internamente, el impacto práctico es mínimo.
## Compatibilidad
OpenTofu mantiene compatibilidad con el ecosistema Terraform:
```bash
# Migración básica
# 1. Instalar OpenTofu
brew install opentofu
# 2. Reemplazar comandos (drop-in replacement)
tofu init # en lugar de terraform init
tofu plan # en lugar de terraform plan
tofu apply # en lugar de terraform apply
# 3. El state file es compatible
# No se requiere migración de estado
```
### ¿Qué es compatible?
- Archivos `.tf` en HCL — 100% compatible
- Providers del Terraform Registry — funcionan directamente
- Módulos existentes — sin cambios
- State files — formato compatible
- Backend configurations — S3, GCS, Azure, etc.
### ¿Qué diverge?
OpenTofu ha comenzado a agregar features propias:
- **State encryption** — encriptación nativa del state file (no disponible en Terraform OSS)
- **Early variable/locals evaluation** — evaluación temprana de variables
- **Registry propio** — registry.opentofu.org como alternativa
## ¿Cuándo elegir OpenTofu?
**Elegir OpenTofu cuando:**
- La licencia open source es un requisito (compliance, política corporativa)
- Construyes productos o servicios sobre la herramienta de IaC
- Quieres contribuir al desarrollo del proyecto
- Necesitas state encryption nativo
- Prefieres gobernanza de la Linux Foundation
**Quedarse con Terraform cuando:**
- Usas Terraform Cloud/Enterprise y sus features exclusivas
- El equipo ya está capacitado en Terraform y no hay razón de licencia para cambiar
- Necesitas soporte comercial de HashiCorp
- La estabilidad del ecosistema establecido es prioridad
## Comparación directa
| Aspecto | Terraform | OpenTofu |
|---------|-----------|----------|
| Licencia | BSL 1.1 | MPL 2.0 (open source) |
| Gobernanza | HashiCorp | Linux Foundation |
| CLI | `terraform` | `tofu` |
| HCL compatible | Sí | Sí |
| Providers | Terraform Registry | Compatible + registry propio |
| State encryption | Solo en Enterprise | Incluido (gratis) |
| Soporte comercial | HashiCorp | Spacelift, env0, Scalr |
| Community | Establecida | Creciendo |
## Ejemplo práctico
```hcl
# main.tf — funciona igual en Terraform y OpenTofu
terraform {
required_version = ">= 1.6.0"
required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 5.0"
}
}
backend "s3" {
bucket = "my-state-bucket"
key = "prod/terraform.tfstate"
region = "us-east-1"
}
}
provider "aws" {
region = "us-east-1"
}
module "vpc" {
source = "terraform-aws-modules/vpc/aws"
version = "5.5.0"
name = "production"
cidr = "10.0.0.0/16"
}
```
### State encryption (exclusivo de OpenTofu)
```hcl
# Solo en OpenTofu
terraform {
encryption {
key_provider "pbkdf2" "main" {
passphrase = var.state_passphrase
}
method "aes_gcm" "main" {
keys = key_provider.pbkdf2.main
}
state {
method = method.aes_gcm.main
}
}
}
```
## Ecosistema y adopción
Empresas que respaldan OpenTofu:
- **Spacelift** — plataforma de IaC, contribuidor principal
- **env0** — plataforma de IaC
- **Scalr** — gestión de Terraform/OpenTofu
- **Gruntwork** — herramientas de IaC (Terragrunt)
- **Harness** — plataforma de CI/CD
## ¿Por qué importa?
El cambio de licencia de Terraform a BSL fue un punto de inflexión para el ecosistema de IaC. OpenTofu garantiza que la inversión en conocimiento de HCL y módulos existentes no quede atrapada en una licencia restrictiva. Para organizaciones que valoran el open source como principio, no solo como conveniencia, OpenTofu es la alternativa viable.
## Referencias
- [OpenTofu Documentation](https://opentofu.org/docs/) — Linux Foundation, 2024. Documentación oficial.
- [OpenTofu Manifesto](https://opentofu.org/manifesto/) — OpenTofu, 2023. El manifiesto original con los firmantes.
- [HashiCorp BSL FAQ](https://www.hashicorp.com/bsl) — HashiCorp, 2023. Explicación oficial del cambio de licencia.
- [OpenTofu vs Terraform](https://opentofu.org/docs/intro/migration/) — OpenTofu, 2024. Guía oficial de migración.
- [The Future of Terraform Must Be Open](https://blog.gruntwork.io/the-future-of-terraform-must-be-open-ab0b9ba65bca) — Yevgeniy Brikman, 2023. Perspectiva del autor de «Terraform: Up & Running».
---
# Observability
Type: concept
Status: seed
Summary: Ability to understand a system's internal state from its external outputs: logs, metrics, and traces, enabling problem diagnosis without direct system access.
Concepts: devops-practices, platform-engineering, ai-observability
## ¿Qué es?
Observabilidad es la capacidad de entender qué está pasando dentro de un sistema basándose en los datos que produce. A diferencia del monitoreo (que verifica condiciones conocidas), la observabilidad permite investigar problemas desconocidos.
## Los tres pilares
### Logs
Registros textuales de eventos:
- Structured logging (JSON) para búsqueda eficiente
- Niveles: DEBUG, INFO, WARN, ERROR
- Correlación con trace IDs
### Métricas
Mediciones numéricas agregadas en el tiempo:
- Counters: valores que solo incrementan
- Gauges: valores que suben y bajan
- Histograms: distribución de valores
### Traces
Seguimiento de requests a través de servicios distribuidos:
- Span: unidad de trabajo
- Trace: conjunto de spans relacionados
- Context propagation: pasar trace ID entre servicios
## OpenTelemetry
Estándar CNCF que unifica la instrumentación de logs, métricas y traces con SDKs para todos los lenguajes principales.
## Herramientas
| Herramienta | Tipo |
|-------------|------|
| Grafana | Dashboards |
| Prometheus | Métricas |
| Jaeger/Tempo | Traces |
| Loki | Logs |
| Datadog | All-in-one |
| AWS CloudWatch | AWS native |
## ¿Por qué importa?
La observabilidad es lo que permite entender el comportamiento de un sistema en producción sin predecir de antemano qué preguntas necesitarás responder. A diferencia del monitoreo tradicional, que verifica condiciones conocidas, la observabilidad permite investigar lo desconocido.
## Referencias
- [OpenTelemetry](https://opentelemetry.io/) — Estándar de observabilidad.
- [Observability Engineering](https://www.oreilly.com/library/view/observability-engineering/9781492076438/) — Charity Majors et al.
- [OpenTelemetry Documentation](https://opentelemetry.io/docs/) — OpenTelemetry, 2024. Documentación completa del estándar.
---
# OAuth & OIDC
Type: concept
Status: seed
Summary: Industry standards for delegated authorization (OAuth 2.0) and federated authentication (OpenID Connect), enabling third-party login and secure API access.
Concepts: api-design, aws-iam
## ¿Qué es?
- **OAuth 2.0**: protocolo de autorización que permite a aplicaciones acceder a recursos en nombre de un usuario sin conocer sus credenciales
- **OpenID Connect (OIDC)**: capa de identidad sobre OAuth 2.0 que añade autenticación
## Flujos OAuth 2.0
| Flujo | Uso |
|-------|-----|
| Authorization Code | Apps web con backend |
| Authorization Code + PKCE | SPAs, mobile apps |
| Client Credentials | Machine-to-machine |
| Device Code | Dispositivos sin browser |
## Tokens
| Token | Propósito | Duración | Estándar |
|-------|-----------|----------|----------|
| Access Token | Autoriza acceso a recursos | Corta (minutos-horas) | OAuth 2.0 |
| Refresh Token | Obtiene nuevos access tokens | Larga (días-semanas) | OAuth 2.0 |
| ID Token | Contiene información del usuario | Corta | OIDC (siempre JWT) |
## JWT (JSON Web Token)
Formato común para tokens: header.payload.signature. Permite verificar integridad sin llamar al servidor de autenticación.
## Proveedores
- Auth0, Okta (SaaS)
- AWS Cognito, Azure AD B2C (cloud)
- Keycloak (open-source)
## ¿Por qué importa?
OAuth 2.0 y OpenID Connect son los estándares de autenticación y autorización de la web moderna. Implementarlos correctamente protege a los usuarios y a la aplicación. Implementarlos mal crea vulnerabilidades que los atacantes conocen bien.
## Referencias
- [OAuth 2.0](https://oauth.net/2/) — Especificación.
- [OpenID Connect](https://openid.net/connect/) — Especificación.
- [RFC 6749 — OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc6749) — IETF, 2012. Especificación original de OAuth 2.0.
---
# Next.js
Type: concept
Status: seed
Summary: React framework for full-stack web applications with Server Components, file-based routing, SSR/SSG, and built-in performance optimizations.
Concepts: react, serverless
## ¿Qué es?
Next.js es el framework de [React](/concepts/react) más popular para aplicaciones web de producción. Proporciona routing, rendering (SSR, SSG, ISR), optimizaciones y API routes out of the box.
## App Router (Next.js 13+)
| Concepto | Función | Ejemplo |
|----------|---------|---------|
| Server Components | Componentes que se ejecutan en el servidor (por defecto) | Fetch de datos sin `useEffect` |
| Client Components | Componentes interactivos (`'use client'`) | Formularios, event handlers |
| Layouts | UI compartida entre rutas | Header, sidebar persistentes |
| Loading/Error | Estados de carga y error por ruta | Skeleton screens, error boundaries |
| Route Handlers | API endpoints | `app/api/data/route.ts` |
## Estrategias de rendering
| Estrategia | Cuándo | Uso |
|------------|--------|-----|
| SSG | Build time | Contenido estático |
| SSR | Request time | Datos dinámicos |
| ISR | Revalidación periódica | Contenido semi-estático |
| Streaming | Progresivo | UX rápida con datos lentos |
## Este sitio usa Next.js
jonmatum.com está construido con Next.js App Router, usando SSG para las páginas de contenido y API routes para el knowledge graph.
## ¿Por qué importa?
Next.js es el framework React más adoptado para producción. Server Components, App Router y optimizaciones automáticas de rendimiento lo hacen la opción por defecto para aplicaciones web que necesitan SEO, velocidad y experiencia de desarrollo moderna.
## Referencias
- [Next.js Documentation](https://nextjs.org/docs) — Documentación oficial.
- [Next.js Blog](https://nextjs.org/blog) — Vercel, 2024. Anuncios y novedades de Next.js.
- [Next.js on Vercel](https://vercel.com/frameworks/nextjs) — Vercel, 2024. Guía de despliegue y optimización.
---
# Neural Networks
Type: concept
Status: evergreen
Summary: Computational models inspired by brain structure that learn patterns from data, forming the foundation of modern artificial intelligence systems.
Concepts: artificial-intelligence, large-language-models, embeddings
## ¿Qué es?
Una red neuronal es un modelo computacional compuesto por capas de nodos (neuronas) interconectados que procesan información. Cada conexión tiene un peso que se ajusta durante el entrenamiento para que la red aprenda a mapear entradas a salidas deseadas.
El concepto se originó en 1943 con el modelo de McCulloch-Pitts, pero las redes neuronales modernas despegaron a partir de 2012 cuando AlexNet demostró que las redes profundas podían superar a los métodos tradicionales en clasificación de imágenes. Hoy son la base de los [LLMs](/concepts/large-language-models), los sistemas de visión por computadora y los modelos generativos.
## Arquitecturas
| Arquitectura | Estructura | Aplicación principal | Ejemplo |
|-------------|-----------|---------------------|---------|
| Feedforward (MLP) | Capas densas conectadas secuencialmente | Clasificación, regresión | Predicción de precios |
| Convolucional (CNN) | Filtros que detectan patrones espaciales | Visión por computadora | ResNet, EfficientNet |
| Recurrente (RNN/LSTM) | Conexiones que mantienen estado temporal | Secuencias (texto, audio) | Traducción pre-2017 |
| Transformer | Mecanismo de atención sin recurrencia | NLP, visión, multimodal | GPT, BERT, ViT |
| Autoencoder | Encoder-decoder que comprime y reconstruye | [Embeddings](/concepts/embeddings), generación | VAE, difusión |
| GAN | Generador vs discriminador en competencia | Generación de imágenes | StyleGAN, DALL-E 1 |
La arquitectura Transformer — introducida en el paper «Attention Is All You Need» (Vaswani et al., 2017) — domina la [IA](/concepts/artificial-intelligence) actual porque paraleliza mejor que las RNNs y captura dependencias de largo alcance.
## Cómo aprenden
El entrenamiento de una red neuronal sigue un ciclo:
1. **Forward pass**: los datos fluyen por la red y producen una predicción
2. **Loss function**: se calcula el error entre la predicción y el valor esperado
3. **Backpropagation**: el error se propaga hacia atrás, calculando el gradiente de cada peso
4. **Optimización**: los pesos se ajustan usando el gradiente (SGD, Adam, AdamW)
Este ciclo se repite miles o millones de veces sobre el dataset de entrenamiento. La clave es que backpropagation — formalizado por Rumelhart, Hinton y Williams en 1986 — permite calcular eficientemente cómo cada peso contribuye al error total.
Los hiperparámetros del entrenamiento — learning rate, batch size, número de épocas, scheduler — tienen un impacto enorme en el resultado final. Encontrar la combinación correcta es más arte que ciencia, aunque técnicas como learning rate warmup y cosine annealing han estandarizado buenas prácticas.
## Conceptos clave
| Concepto | Qué hace | Por qué importa |
|----------|---------|-----------------|
| Función de activación | Introduce no-linealidad (ReLU, GELU, sigmoid) | Sin ella, la red solo puede aprender funciones lineales |
| Dropout | Desactiva neuronas aleatoriamente durante entrenamiento | Previene overfitting |
| Batch normalization | Normaliza activaciones entre capas | Estabiliza y acelera el entrenamiento |
| Learning rate | Controla el tamaño de los ajustes de pesos | Muy alto diverge, muy bajo no converge |
| Transfer learning | Reutilizar pesos pre-entrenados en nueva tarea | Reduce datos y tiempo de entrenamiento |
## Cuándo NO usar redes neuronales
- **Datos tabulares pequeños** (< 10K filas) — XGBoost o random forests suelen ganar
- **Requisitos de interpretabilidad** — los modelos lineales o árboles de decisión son más explicables
- **Sin GPU disponible** — el entrenamiento de redes profundas sin aceleración es prohibitivamente lento
- **Datos insuficientes** — las redes profundas necesitan grandes volúmenes de datos o transfer learning
## ¿Por qué importa?
Las redes neuronales son el componente fundamental de toda la IA moderna — desde los [LLMs](/concepts/large-language-models) que generan código hasta los modelos de visión que conducen vehículos autónomos. Entender sus arquitecturas, limitaciones y costos de entrenamiento es esencial para tomar decisiones informadas sobre qué modelo usar, cuándo entrenar uno propio y cuándo un enfoque más simple es suficiente. La elección entre fine-tuning de un modelo existente y entrenar desde cero define el costo y el timeline de cualquier proyecto de IA.
## Referencias
- [Deep Learning](https://www.deeplearningbook.org/) — Goodfellow, Bengio y Courville, 2016. El libro de referencia sobre redes neuronales y deep learning.
- [CS231n: Convolutional Neural Networks for Visual Recognition](https://cs231n.github.io/) — Stanford, 2024. Curso de Stanford sobre redes neuronales y visión por computadora.
- [Build the Neural Network](https://pytorch.org/tutorials/beginner/basics/buildmodel_tutorial.html) — PyTorch, 2024. Tutorial oficial para construir redes neuronales con PyTorch.
- [Neural Networks](https://www.3blue1brown.com/topics/neural-networks) — 3Blue1Brown, 2024. Serie visual que explica la intuición detrás de las redes neuronales.
---
# Multi-Agent Systems
Type: concept
Status: seed
Summary: Architectures where multiple specialized AI agents collaborate, compete, or coordinate to solve complex problems that exceed a single agent's capability.
Concepts: ai-agents, strands-agents, agentic-workflows, ai-orchestration
## ¿Qué es?
Un sistema multi-agente es una arquitectura donde múltiples [agentes de IA](/concepts/ai-agents) especializados trabajan juntos para resolver problemas complejos. Cada agente tiene un rol, herramientas y conocimiento específico, y se coordinan mediante patrones de comunicación definidos.
La idea no es nueva — viene de la investigación en sistemas distribuidos de los 90s — pero los [LLMs](/concepts/large-language-models) la han revitalizado al hacer posible agentes que se comunican en lenguaje natural.
## Topologías de coordinación
### Orquestador centralizado
Un agente principal delega tareas a agentes especializados:
```
Orquestador
├── Agente de investigación
├── Agente de código
└── Agente de revisión
```
Ventaja: control claro. Desventaja: cuello de botella en el orquestador.
### Swarm (enjambre)
Agentes autónomos que se pasan el control entre sí según reglas:
```
Agente A → (condición) → Agente B → (condición) → Agente C
```
Ventaja: flexible, descentralizado. Desventaja: difícil de debuggear.
### Debate/Competencia
Múltiples agentes proponen soluciones y un juez selecciona la mejor:
```
Agente 1 → Propuesta
Agente 2 → Propuesta → Juez → Mejor solución
Agente 3 → Propuesta
```
### Grafo de agentes
Agentes conectados en un grafo dirigido con flujos condicionales:
```
Entrada → Clasificador → [Ruta A: Agente 1 → Agente 2]
→ [Ruta B: Agente 3]
→ Sintetizador → Salida
```
## Frameworks
| Framework | Enfoque |
|-----------|---------|
| [Strands Agents](/concepts/strands-agents) | Agents-as-tools, graph, swarm |
| CrewAI | Roles y tareas estructuradas |
| AutoGen | Conversaciones multi-agente |
| LangGraph | Grafos de estado con agentes |
## Desafíos
- **Coordinación**: evitar que agentes se contradigan o dupliquen trabajo
- **Costo**: N agentes × M iteraciones = muchos tokens
- **Debugging**: rastrear decisiones a través de múltiples agentes
- **Consistencia**: mantener contexto compartido entre agentes
- **Evaluación**: medir el rendimiento del sistema, no solo de agentes individuales
## ¿Cuándo usar multi-agente?
- La tarea requiere expertise en múltiples dominios
- Un solo agente no puede mantener todo el contexto necesario
- Se necesitan checks and balances (un agente revisa a otro)
- El problema se descompone naturalmente en subtareas independientes
## ¿Por qué importa?
Los sistemas multi-agente permiten descomponer tareas complejas en subtareas especializadas, donde cada agente tiene su propio contexto, herramientas y modelo. Es el patrón que escala las capacidades de IA más allá de lo que un solo agente puede manejar.
## Referencias
- [Communicative Agents for Software Development](https://arxiv.org/abs/2307.07924) — Qian et al., 2023. ChatDev: agentes que colaboran para desarrollar software.
- [Agent-to-Agent Protocol](https://github.com/google/A2A) — Google, 2025. Protocolo abierto para comunicación entre agentes.
- [AutoGen: Enabling Next-Gen LLM Applications](https://arxiv.org/abs/2308.08155) — Wu et al., 2023. Framework de Microsoft para sistemas multi-agente.
---
# Monorepos
Type: concept
Status: evergreen
Summary: Code organization strategy where multiple projects coexist in a single repository, sharing dependencies, configuration, and build tooling.
Concepts: git, github-flow, devops-practices
Un **monorepo** es un repositorio único que contiene múltiples proyectos distintos con relaciones bien definidas entre ellos. No es simplemente «todo el código en una carpeta» — es una estrategia arquitectónica con herramientas especializadas.
## ¿Qué problema resuelve?
En un modelo **polyrepo** (un repositorio por proyecto), los equipos enfrentan:
- **Dependency hell** — sincronizar versiones entre repos es manual y propenso a errores
- **Cambios atómicos imposibles** — un refactor que toca 3 repos requiere 3 PRs coordinados
- **Duplicación de configuración** — ESLint, TypeScript, CI/CD copiados en cada repo
- **Descubrimiento difícil** — ¿dónde está el código que necesito? ¿qué versión usa el otro equipo?
El monorepo centraliza todo en un solo lugar con herramientas que manejan la complejidad.
## ¿Cuándo usarlo?
**Buena opción cuando:**
- Múltiples paquetes comparten código común (tipos, utilidades, componentes)
- El equipo necesita hacer cambios atómicos que cruzan boundaries
- Quieres una sola fuente de verdad para configuración (linting, testing, CI)
- Los proyectos tienen ciclos de release coordinados
**Evitar cuando:**
- Proyectos completamente independientes sin código compartido
- Equipos con ciclos de release muy diferentes
- Restricciones de acceso estrictas (el monorepo implica visibilidad compartida)
- El repo crecería a tamaños que Git no maneja bien (>10GB, millones de archivos)
## Herramientas principales
| Herramienta | Enfoque | Lenguaje | Características clave |
|-------------|---------|----------|----------------------|
| **Turborepo** | Build caching | JS/TS | Caché remoto, pipelines declarativos, zero-config |
| **Nx** | Full-featured | JS/TS | Generators, affected commands, graph visualization |
| **pnpm workspaces** | Package manager | JS/TS | Symlinks eficientes, strict dependencies |
| **Lerna** | Publishing | JS/TS | Versioning coordinado, changelogs (ahora parte de Nx) |
| **Bazel** | Hermetic builds | Políglota | Reproducibilidad, escalabilidad extrema (Google-scale) |
| **Pants** | Hermetic builds | Python/Go/Java | Similar a Bazel, mejor DX |
| **Rush** | Enterprise | JS/TS | Políticas estrictas, phantom dependencies detection |
### Turborepo vs Nx
La comparación más común en el ecosistema JavaScript:
**Turborepo** — minimalista, se integra con tu setup existente, excelente caché remoto con Vercel. Ideal si ya tienes un monorepo y quieres acelerar builds sin cambiar mucho.
**Nx** — más opinionado, incluye generators para scaffolding, plugins para frameworks específicos, visualización de dependencias. Mejor si empiezas de cero o quieres estructura guiada.
## Estructura típica
```
monorepo/
├── apps/
│ ├── web/ # Next.js app
│ ├── mobile/ # React Native app
│ └── api/ # Backend service
├── packages/
│ ├── ui/ # Shared components
│ ├── utils/ # Shared utilities
│ └── config/ # Shared ESLint, TS configs
├── turbo.json # Pipeline configuration
├── pnpm-workspace.yaml
└── package.json
```
## Patrones clave
### 1. Internal packages
Paquetes que nunca se publican a npm — solo se consumen dentro del monorepo:
```json
{
"name": "@repo/ui",
"private": true,
"exports": {
".": "./src/index.ts"
}
}
```
### 2. Task pipelines
Definir dependencias entre tareas para paralelización correcta:
```json
{
"pipeline": {
"build": {
"dependsOn": ["^build"],
"outputs": ["dist/**"]
},
"test": {
"dependsOn": ["build"]
}
}
}
```
### 3. Caché remoto
El build de un paquete que no cambió se recupera del caché en lugar de re-ejecutarse:
```bash
# Primera vez: ejecuta build
turbo build # 45s
# Segunda vez (sin cambios): recupera del caché
turbo build # 0.3s
```
## Anti-patrones
- **Monolito disfrazado** — todo en un repo pero sin boundaries claros entre paquetes
- **Caché sin invalidación correcta** — builds que no detectan cambios en dependencias
- **Circular dependencies** — paquete A importa B que importa A
- **God package** — un `@repo/utils` que crece sin control y todos dependen de él
## Este sitio es un monorepo
jonmatum.com usa Turborepo + pnpm workspaces con `apps/web` (Next.js) y `packages/knowledge` (pipeline de contenido). El caché de Turborepo reduce el build de ~45s a menos de 1s cuando solo cambia contenido MDX.
## ¿Por qué importa?
La decisión entre monorepo y polyrepo afecta la velocidad de desarrollo, la complejidad del CI/CD y la capacidad de compartir código entre equipos. No hay respuesta universal — pero entender los trade-offs evita meses de migración dolorosa cuando la elección inicial no escala.
## Referencias
- [Monorepo Explained](https://monorepo.tools/) — Nrwl, 2023. Comparativa exhaustiva de herramientas y patrones.
- [Turborepo Handbook](https://turbo.build/repo/docs/handbook) — Vercel, 2024. Guía oficial con mejores prácticas.
- [Why Google Stores Billions of Lines of Code in a Single Repository](https://research.google/pubs/pub45424/) — Google Research, 2016. El paper seminal sobre monorepos a escala.
- [Monorepos: Please don't!](https://medium.com/@mattklein123/monorepos-please-dont-e9a279be011b) — Matt Klein, 2019. Perspectiva crítica sobre cuándo evitarlos.
---
# Microservices
Type: concept
Status: seed
Summary: Architectural style structuring an application as a collection of small, independent, deployable services, each with its own business logic and data.
Concepts: monorepos, event-driven-architecture
## ¿Qué es?
Los microservicios son un estilo arquitectónico donde una aplicación se compone de servicios pequeños e independientes que se comunican por red (HTTP, mensajes, eventos). Cada servicio es dueño de su dominio, datos y ciclo de despliegue.
## Características
- **Independencia de despliegue**: cada servicio se despliega por separado
- **Ownership de datos**: cada servicio tiene su propia base de datos
- **Tecnología heterogénea**: cada servicio puede usar diferente stack
- **Equipos autónomos**: un equipo por servicio (o grupo de servicios)
## Microservicios vs Monolito
| Aspecto | Monolito | Microservicios |
|---------|----------|----------------|
| Despliegue | Todo junto | Independiente |
| Escalado | Vertical | Horizontal por servicio |
| Complejidad | En el código | En la infraestructura |
| Consistencia | Transacciones ACID | Consistencia eventual |
## Cuándo NO usar microservicios
- Equipos pequeños (menos de 5 personas)
- Producto en fase temprana (dominio no definido)
- Sin experiencia en sistemas distribuidos
- Cuando un monolito modular es suficiente
## Patrones asociados
- [API Gateway](/concepts/api-gateway-pattern)
- [Event-driven](/concepts/event-driven-architecture)
- [Saga](/concepts/saga-pattern)
- [CQRS](/concepts/cqrs)
## ¿Por qué importa?
Los microservicios permiten que equipos independientes desarrollen, desplieguen y escalen servicios de forma autónoma. Pero su complejidad operacional es significativa — requieren observabilidad, service mesh, gestión de datos distribuidos y una cultura de ownership. No son la respuesta por defecto.
## Referencias
- [Microservices](https://martinfowler.com/articles/microservices.html) — Martin Fowler, 2014.
- [Building Microservices](https://www.oreilly.com/library/view/building-microservices-2nd/9781492034018/) — Sam Newman, 2021.
- [Microservice Patterns](https://microservices.io/patterns/microservices.html) — Chris Richardson, 2024. Catálogo de patrones de microservicios.
---
# Micro Frontends
Type: concept
Status: seed
Summary: Architectural pattern extending microservices to the frontend, allowing independent teams to develop and deploy parts of a web application autonomously.
Concepts: react, monorepos, microservices
## ¿Qué es?
Micro frontends extienden el concepto de [microservicios](/concepts/microservices) al frontend. En lugar de un monolito frontend, la aplicación se compone de fragmentos independientes desarrollados por equipos autónomos, integrados en runtime o build time.
## Estrategias de integración
| Estrategia | Integración | Ejemplo |
|------------|-------------|----------|
| Build-time | npm packages | Monorepo con packages |
| Runtime (JS) | Module Federation | Webpack/Vite MF |
| Runtime (iframe) | iframes | Legacy integration |
| Server-side | SSI/ESI | Edge composition |
## Module Federation
La técnica más popular: cada micro frontend expone módulos que otros pueden consumir en runtime, sin necesidad de rebuild.
## Cuándo usar
- Múltiples equipos trabajando en el mismo producto
- Necesidad de despliegues independientes por sección
- Migración gradual de tecnologías
- Aplicaciones enterprise grandes
## Cuándo NO usar
- Equipo pequeño (un solo equipo)
- Aplicación simple
- Cuando la complejidad de integración supera el beneficio
## ¿Por qué importa?
Los micro-frontends aplican los principios de microservicios al frontend, permitiendo que equipos independientes desarrollen, desplieguen y escalen partes de la interfaz de forma autónoma. Son la solución cuando un monolito frontend se convierte en cuello de botella organizacional.
## Referencias
- [Micro Frontends](https://martinfowler.com/articles/micro-frontends.html) — Martin Fowler.
- [Module Federation](https://module-federation.io/) — Documentación oficial.
- [single-spa](https://single-spa.js.org/) — single-spa, 2024. Framework para micro frontends.
---
# Metrics & Monitoring
Type: concept
Status: seed
Summary: Collection and visualization of numerical system measurements over time to understand performance, detect anomalies, and make data-driven decisions.
Concepts: observability, site-reliability-engineering
## ¿Qué es?
Métricas son mediciones numéricas agregadas en el tiempo que describen el comportamiento del sistema. El monitoreo es el proceso de recolectar, almacenar, visualizar y alertar sobre esas métricas.
## Tipos de métricas
| Tipo | Comportamiento | Ejemplo | Cuándo usar |
|------|---------------|---------|-------------|
| Counter | Solo incrementa | Requests totales, errores acumulados | Tasas (requests/s) |
| Gauge | Sube y baja | Memoria usada, conexiones activas | Estado actual del recurso |
| Histogram | Distribución de valores (server-side) | Latencia p50/p95/p99 | Percentiles de latencia |
| Summary | Distribución de valores (client-side) | Latencia precalculada | Cuando no se puede agregar en servidor |
## The Four Golden Signals (Google SRE)
1. **Latency**: tiempo de respuesta
2. **Traffic**: volumen de requests
3. **Errors**: tasa de errores
4. **Saturation**: qué tan «lleno» está el sistema
## Stack típico
```
Aplicación → Prometheus (recolección) → Grafana (visualización) → Alertmanager (alertas)
```
## Mejores prácticas
- USE method para recursos: Utilization, Saturation, Errors
- RED method para servicios: Rate, Errors, Duration
- Dashboards por servicio con los 4 golden signals
- Alertas basadas en SLOs, no en métricas arbitrarias
## ¿Por qué importa?
Lo que no se mide no se mejora. Las métricas y el monitoreo convierten la intuición en datos, permitiendo detectar degradaciones antes de que impacten a los usuarios y tomar decisiones de capacidad basadas en evidencia.
## Referencias
- [Prometheus](https://prometheus.io/) — Sistema de monitoreo CNCF.
- [Grafana](https://grafana.com/) — Plataforma de visualización.
- [OpenTelemetry Metrics](https://opentelemetry.io/docs/concepts/signals/metrics/) — OpenTelemetry, 2024. Estándar abierto para métricas.
---
# Model Context Protocol (MCP)
Type: concept
Status: growing
Summary: Open protocol created by Anthropic that standardizes how AI applications connect with external tools, data, and services through a universal interface.
Concepts: ai-agents, artificial-intelligence, spec-driven-development, ai-orchestration, strands-agents
## ¿Qué es?
El Model Context Protocol (MCP) es un estándar abierto lanzado por Anthropic en noviembre de 2024 que define cómo las aplicaciones de IA se conectan con herramientas y fuentes de datos externas. Es al ecosistema de IA lo que el Language Server Protocol (LSP) fue para los editores de código: una interfaz universal que elimina la necesidad de integraciones punto a punto.
Antes de MCP, cada herramienta de IA necesitaba su propia integración personalizada con cada servicio externo. Si tenías 10 herramientas de IA y 10 servicios, necesitabas 100 integraciones. Con MCP, cada servicio implementa un servidor MCP una vez, y cualquier cliente MCP puede conectarse a él.
## Arquitectura
MCP utiliza mensajes JSON-RPC 2.0 y define tres roles:
- **Host**: la aplicación de IA que inicia la conexión (ej: Claude Desktop, Kiro CLI, un IDE)
- **Client**: el conector dentro del host que gestiona la comunicación con un servidor específico
- **Server**: el servicio que expone herramientas, recursos y contexto al modelo
```mermaid
graph LR
subgraph "Host (IDE / CLI)"
A[LLM] --> B[MCP Client]
end
B -->|JSON-RPC| C[MCP Server A Base de datos]
B -->|JSON-RPC| D[MCP Server B API externa]
B -->|JSON-RPC| E[MCP Server C Sistema de archivos]
```
## Capacidades principales
### Herramientas (Tools)
Funciones que el modelo puede invocar. Cada herramienta tiene un nombre, descripción y esquema de entrada tipado. El modelo decide cuándo y cómo usarlas.
```json
{
"name": "create_todo",
"description": "Create a new todo item",
"inputSchema": {
"type": "object",
"properties": {
"title": { "type": "string" }
},
"required": ["title"]
}
}
```
### Recursos (Resources)
Datos que el servidor expone al modelo: archivos, registros de base de datos, documentación. A diferencia de las herramientas, los recursos son datos que el modelo lee pero no modifica.
### Prompts
Plantillas de instrucciones que el servidor puede ofrecer al host para guiar la interacción del usuario con el modelo.
## Transportes
MCP soporta dos mecanismos de transporte:
| Transporte | Uso | Limitación |
|---|---|---|
| **stdio** | Desarrollo local. El host ejecuta el servidor como proceso hijo. | Un solo cliente por servidor. |
| **HTTP + SSE** | Producción. Conexión remota con Server-Sent Events para streaming. | Requiere autenticación (OAuth 2.1 desde la spec de 2025). |
## Evolución de la especificación
- **2024-11**: lanzamiento inicial. Herramientas, recursos, prompts, transporte stdio.
- **2025-03**: conexiones remotas con SSE, mejoras en descubrimiento de herramientas.
- **2025-06**: OAuth 2.0, indicadores de recursos, mejoras de seguridad.
- **2025-11**: OAuth 2.1 obligatorio con PKCE, ejecución asíncrona, metadatos de cliente, preparación empresarial.
## Patrones de implementación de servidores
### Registro dinámico de herramientas
Un servidor MCP registra sus herramientas al iniciar la conexión. El host descubre las capacidades disponibles mediante `tools/list` y presenta las herramientas al modelo como funciones invocables:
```typescript
server.tool("search_docs", {
description: "Search documentation by query",
inputSchema: {
type: "object",
properties: {
query: { type: "string", description: "Search query" }
},
required: ["query"]
}
}, async ({ query }) => {
const results = await searchIndex(query);
return { content: [{ type: "text", text: JSON.stringify(results) }] };
});
```
Las herramientas pueden actualizarse en tiempo de ejecución — el servidor notifica al cliente mediante `notifications/tools/list_changed` cuando cambian las herramientas disponibles.
### Patrones comunes de servidor
- **Wrapper de API**: expone una API REST existente como herramientas MCP con esquemas tipados
- **Base de datos**: ofrece consultas y operaciones CRUD como herramientas, con recursos para esquemas y datos
- **Sistema de archivos**: acceso controlado a archivos locales con permisos granulares
- **Pipeline de datos**: combina herramientas de transformación con recursos que exponen datasets
### Seguridad
Desde la especificación de 2025, los servidores remotos requieren OAuth 2.1 con PKCE. El flujo de autorización sigue el estándar:
1. El cliente descubre los metadatos del servidor (`/.well-known/oauth-authorization-server`)
2. Inicia el flujo de autorización con PKCE
3. Obtiene un token de acceso
4. Incluye el token en cada request al servidor
## ¿Por qué importa?
MCP resuelve un problema fundamental: **la fragmentación de integraciones en el ecosistema de IA**. Sin un estándar, cada combinación de herramienta de IA + servicio externo requiere código personalizado. Con MCP:
- Los desarrolladores de herramientas implementan un servidor una vez
- Los desarrolladores de aplicaciones de IA implementan un cliente una vez
- Cualquier cliente puede conectarse a cualquier servidor
- Las herramientas son descubribles y auto-documentadas
Esto es especialmente relevante para [agentes de IA](/concepts/ai-agents) que necesitan acceder a múltiples herramientas de forma dinámica.
## Referencias
- [Model Context Protocol — Especificación](https://modelcontextprotocol.io/specification/latest) — Especificación oficial y autoritativa del protocolo.
- [Introducing the Model Context Protocol](https://www.anthropic.com/news/model-context-protocol) — Anuncio original de Anthropic, noviembre 2024.
- [MCP GitHub Organization](https://github.com/modelcontextprotocol) — SDKs oficiales para TypeScript y Python.
- [Python MCP SDK](https://github.com/modelcontextprotocol/python-sdk) — Implementación de referencia en Python.
- [TypeScript MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk) — Implementación de referencia en TypeScript.
---
# Maturity Models
Type: concept
Status: growing
Summary: Structured frameworks for progressively assessing and improving organizational capabilities, from CMMI to modern approaches like DORA and simplified models.
Concepts: devops, artificial-intelligence
## ¿Qué es un modelo de madurez?
Un modelo de madurez es un framework que describe una progresión de capacidades en un dominio específico. Define niveles discretos que representan estados de sofisticación creciente, permitiendo a una organización ubicarse en la escala y trazar un camino de mejora.
La premisa fundamental: no se puede mejorar lo que no se puede medir, y no se puede medir sin un marco de referencia.
## Modelos clásicos
### CMMI (Capability Maturity Model Integration)
Desarrollado por el SEI de Carnegie Mellon en los 90s, CMMI es el abuelo de los modelos de madurez. Define 5 niveles:
| Nivel | Nombre | Descripción |
|-------|--------|-------------|
| 1 | Initial | Procesos impredecibles, reactivos |
| 2 | Managed | Procesos gestionados a nivel de proyecto |
| 3 | Defined | Procesos estandarizados a nivel organizacional |
| 4 | Quantitatively Managed | Procesos medidos y controlados |
| 5 | Optimizing | Mejora continua basada en datos |
CMMI fue un avance significativo en su momento. Introdujo la idea de que las organizaciones maduran de forma predecible y que se puede acelerar esa maduración con prácticas específicas. Pero tiene problemas reales:
- **Pesado**: La evaluación formal (SCAMPI) requiere meses y consultores certificados
- **Rígido**: Los 5 niveles son secuenciales — no puedes estar en nivel 4 sin completar el 3
- **Costoso**: La certificación formal cuesta decenas de miles de dólares
- **Lento**: El ciclo de evaluación-mejora-reevaluación toma años
### ITIL Maturity Model
Similar a CMMI pero enfocado en gestión de servicios IT. Misma escala de 5 niveles, mismos problemas de complejidad. Útil como referencia pero raramente implementado de forma completa fuera de grandes corporaciones.
## Modelos modernos
### DORA (DevOps Research and Assessment)
DORA cambió el paradigma al enfocarse en métricas de resultado en lugar de prácticas de proceso. Define 4 métricas clave:
- **Deployment Frequency**: Con qué frecuencia se despliega a producción
- **Lead Time for Changes**: Tiempo desde commit hasta producción
- **Change Failure Rate**: Porcentaje de despliegues que causan fallos
- **Time to Restore Service**: Tiempo para recuperarse de un fallo
Y clasifica a los equipos en 4 niveles de rendimiento (Elite, High, Medium, Low) basándose en estas métricas.
Lo que DORA hizo bien:
- **Basado en datos**: Las métricas son objetivas y medibles automáticamente
- **Orientado a resultados**: Mide lo que importa (velocidad + estabilidad), no el proceso
- **Validado estadísticamente**: Respaldado por años de investigación (Accelerate, State of DevOps Report)
Lo que DORA no cubre:
- Solo aplica a delivery de software — no evalúa arquitectura, seguridad, cultura, o prácticas de plataforma
- Las métricas son de equipo/organización, no de prácticas individuales
- No ofrece un camino prescriptivo de mejora
### Spotify Health Check
Un modelo ligero donde los equipos evalúan su salud en dimensiones como velocidad, calidad, diversión, y aprendizaje usando un sistema de semáforo (verde/amarillo/rojo). Simple y efectivo para generar conversación, pero subjetivo y difícil de agregar a nivel organizacional.
### Team Topologies Maturity
Enfocado en la estructura de equipos y sus interacciones. Evalúa si los equipos están organizados como stream-aligned, platform, enabling, o complicated-subsystem teams. Útil para evaluar la topología organizacional pero no las prácticas técnicas.
## El espectro de complejidad
```mermaid
graph LR
A[Spotify Health Check] --> B[DORA Metrics]
B --> C[AxiSight 3-Level]
C --> D[CMMI 5-Level]
D --> E[CMMI + SCAMPI Formal]
style A fill:#22c55e,color:#000
style B fill:#60a5fa,color:#000
style C fill:#a78bfa,color:#000
style D fill:#f59e0b,color:#000
style E fill:#ef4444,color:#000
```
De izquierda a derecha: más precisión, más costo, menos frecuencia de uso.
El punto óptimo depende del contexto. Para un equipo de 5 personas, Spotify Health Check es suficiente. Para una organización de 500 personas que necesita benchmarks entre equipos, se necesita algo más estructurado.
## El caso por la simplicidad
La mayoría de organizaciones no necesitan la granularidad de CMMI. Lo que necesitan es:
1. **Saber dónde están**: Un snapshot rápido del estado actual
2. **Saber qué mejorar**: Identificar gaps claros
3. **Medir progreso**: Comparar evaluaciones en el tiempo
Un sistema de 3 niveles (Not Started / Partial / Complete) con criterios explícitos de éxito logra esto con una fracción del costo cognitivo. La pregunta en cada ítem se reduce a: ¿existe o no existe? ¿Está completo o no?
La simplificación tiene un trade-off: se pierde granularidad en los niveles intermedios. Pero en la práctica, la diferencia entre un «3» y un «4» en una escala de 5 es donde la mayoría de las discusiones improductivas ocurren.
Ver [AxiSight](/experiments/axisight-maturity-assessment) para una implementación práctica de este enfoque simplificado.
## ¿Cuándo usar cada modelo?
| Necesidad | Modelo recomendado |
|-----------|-------------------|
| Conversación de equipo rápida | Spotify Health Check |
| Métricas de delivery objetivas | DORA |
| Evaluación amplia con acción rápida | Modelo de 3 niveles (AxiSight) |
| Certificación formal / compliance | CMMI |
| Estructura organizacional | Team Topologies |
## ¿Por qué importa?
Los modelos de madurez proporcionan un lenguaje común para evaluar dónde está un equipo y hacia dónde debe ir. Sin ellos, las conversaciones sobre mejora son subjetivas. Con ellos, las inversiones en mejora se priorizan con criterio.
## Referencias
- [CMMI Institute](https://cmmiinstitute.com/cmmi/intro) — Sitio oficial del CMMI, administrado por ISACA. Desarrollado originalmente en el Software Engineering Institute (SEI) de Carnegie Mellon University.
- [DORA](https://dora.dev/) — Programa de investigación de DevOps Research and Assessment de Google Cloud. El programa de investigación más grande y de mayor duración sobre rendimiento en entrega de software.
- [DORA Research](https://dora.dev/research/) — Google Cloud, 2024. Investigación sobre rendimiento en entrega de software y métricas DORA.
- Forsgren, N., Humble, J., & Kim, G. (2018). *[Accelerate: The Science of Lean Software and DevOps](https://www.goodreads.com/en/book/show/35747076)*. IT Revolution Press. — El libro que presenta la investigación detrás de las métricas DORA.
- Kniberg, H. & Lindwall, K. (2014). «[Squad Health Check model – visualizing what to improve](https://labs.spotify.com/2014/09/16/squad-health-check-model/)». Spotify Engineering Blog. — El artículo original del modelo de Health Check de Spotify.
- Skelton, M. & Pais, M. (2019). *[Team Topologies: Organizing Business and Technology Teams for Fast Flow](https://teamtopologies.com/book/)*. IT Revolution Press. — El libro que define los cuatro tipos fundamentales de equipos y sus patrones de interacción.
---
# Logging Strategies
Type: concept
Status: seed
Summary: Practices for implementing effective logging in distributed systems: structured logging, levels, correlation, and centralized aggregation.
Concepts: observability, serverless, distributed-tracing
## ¿Qué es?
El logging efectivo en sistemas distribuidos va más allá de `console.log`. Requiere estructura, correlación entre servicios, niveles apropiados y agregación centralizada para ser útil en debugging y auditoría.
## Structured Logging
Logs en formato JSON en lugar de texto plano:
```json
{"level":"info","msg":"Order created","orderId":"123","userId":"456","traceId":"abc","timestamp":"2026-03-16T10:00:00Z"}
```
Beneficios: búsqueda eficiente, filtrado por campos, parsing automático.
## Niveles
| Nivel | Uso |
|-------|-----|
| DEBUG | Detalle para desarrollo |
| INFO | Eventos normales de negocio |
| WARN | Situaciones inesperadas no críticas |
| ERROR | Fallos que requieren atención |
## Correlación
Incluir `traceId` y `requestId` en cada log para rastrear una request a través de múltiples servicios.
## Herramientas de agregación
- ELK Stack (Elasticsearch, Logstash, Kibana)
- Grafana Loki
- AWS CloudWatch Logs
- Datadog Logs
## Anti-patrones
- **Logging excesivo**: loguear todo genera ruido y costos de almacenamiento — loguear lo que ayuda a diagnosticar
- **Logs sin contexto**: un mensaje como «error occurred» sin request ID, usuario o stack trace es inútil
- **Datos sensibles en logs**: PII, tokens o contraseñas que terminan en sistemas de agregación
## ¿Por qué importa?
Los logs son la primera herramienta de diagnóstico cuando algo falla. Logs estructurados, con niveles apropiados y correlación entre servicios, convierten la depuración de horas en minutos. Logs desordenados son ruido que oculta la señal.
## Referencias
- [Structured Logging](https://www.structlog.org/) — structlog, 2024. Biblioteca Python de referencia para logging estructurado.
- [OpenTelemetry Logs](https://opentelemetry.io/docs/concepts/signals/logs/) — OpenTelemetry, 2024. Estándar abierto para logs.
- [Elastic Common Schema](https://www.elastic.co/guide/en/ecs/current/index.html) — Elastic, 2024. Esquema estándar para logs estructurados.
---
# Local Development
Type: concept
Status: seed
Summary: Practices and tools for creating productive development environments on the developer's machine, replicating production as closely as possible.
Concepts: devcontainers, docker-compose
## ¿Qué es?
El desarrollo local es el entorno donde los desarrolladores escriben y prueban código antes de enviarlo a CI/CD. Un buen setup local replica producción lo suficiente para detectar problemas temprano, mientras mantiene un feedback loop rápido.
## Componentes
| Componente | Qué incluye | Herramienta típica |
|-----------|------------|-------------------|
| Runtime | Lenguaje y versión correcta | nvm, pyenv, asdf |
| Dependencias | Bases de datos, caches, message queues | [Docker Compose](/concepts/docker-compose), [devcontainers](/concepts/devcontainers) |
| Herramientas | Linters, formatters, test runners | [ESLint](/concepts/linting-formatting), Prettier, Vitest |
| Configuración | Variables de entorno, secrets de desarrollo | `.env.local`, dotenv |
## Estrategias
| Estrategia | Pros | Contras |
|------------|------|----------|
| Instalación nativa | Rápido | Conflictos de versiones |
| [Docker Compose](/concepts/docker-compose) | Aislado, reproducible | Overhead de recursos |
| [Dev Containers](/concepts/devcontainers) | Completamente reproducible | Requiere Docker |
| Cloud dev environments | Sin setup local | Latencia, costo |
## Mejores prácticas
- Un comando para levantar todo (`make dev`, `pnpm dev`)
- Seeds de datos para desarrollo
- Hot reload para feedback instantáneo
- Mocks para servicios externos costosos
## ¿Por qué importa?
La calidad del entorno de desarrollo local determina la productividad diaria del equipo. Si compilar tarda minutos, si las dependencias fallan o si el setup requiere un documento de 20 pasos, cada desarrollador pierde tiempo que se multiplica por el tamaño del equipo.
## Referencias
- [Dev Containers](https://containers.dev/) — Especificación oficial.
- [Docker Desktop Dev Environments](https://docs.docker.com/desktop/dev-environments/) — Docker, 2024. Entornos de desarrollo con Docker.
- [Dev Containers in VS Code](https://code.visualstudio.com/docs/devcontainers/containers) — Microsoft, 2024. Desarrollo local con contenedores en VS Code.
---
# llms.txt
Type: concept
Status: growing
Summary: Proposed standard for publishing a Markdown file at a website's root that enables language models to efficiently understand and use the site's content at inference time.
Concepts: artificial-intelligence, mcp
## ¿Qué es?
`llms.txt` es un estándar propuesto por Jeremy Howard (fast.ai) en septiembre de 2024 para colocar un archivo Markdown en la ruta `/llms.txt` de un sitio web. Su propósito es ofrecer a los modelos de lenguaje una versión concisa, estructurada y legible del contenido más importante del sitio — sin el ruido del HTML, la navegación, los anuncios ni el JavaScript.
Es análogo a `robots.txt` y `sitemap.xml`, pero con un objetivo diferente:
- `robots.txt` indica a los rastreadores qué acceso es aceptable
- `sitemap.xml` lista todas las páginas indexables para motores de búsqueda
- `llms.txt` ofrece un resumen curado y enlaces a contenido detallado para modelos de lenguaje
## ¿Por qué importa?
Los modelos de lenguaje enfrentan una limitación fundamental al interactuar con sitios web: las ventanas de contexto son demasiado pequeñas para procesar un sitio completo, y convertir HTML complejo a texto plano es impreciso y ruidoso.
`llms.txt` resuelve esto proporcionando:
1. **Contexto inmediato** — un resumen del sitio que cabe en una ventana de contexto
2. **Navegación estructurada** — enlaces a archivos Markdown detallados organizados por sección
3. **Información curada** — solo el contenido relevante, sin duplicación ni ruido
4. **Formato legible por humanos y máquinas** — Markdown es el formato más ampliamente entendido por los LLMs actuales
## ¿Cómo se usa?
### En la inferencia
El caso de uso principal es durante la **inferencia** — cuando un usuario pide información a un modelo de lenguaje. Por ejemplo:
- Un desarrollador incluye la documentación de una librería en su IDE con asistente de IA
- Un chatbot con capacidad de búsqueda consulta un sitio para responder preguntas
- Un [agente de IA](/concepts/ai-agents) necesita entender la estructura de un servicio para interactuar con él
### Formato del archivo
El archivo sigue una estructura específica en Markdown:
```markdown
# Nombre del proyecto
> Descripción breve con información clave
Detalles adicionales sobre el proyecto.
## Sección
- [Título del enlace](https://url): Notas opcionales sobre el archivo
## Optional
- [Título del enlace](https://url): Contenido secundario que puede omitirse
```
La sección «Optional» tiene un significado especial: los enlaces allí pueden omitirse si se necesita un contexto más corto.
### Variantes comunes
Muchos sitios publican variantes expandidas:
- `/llms.txt` — el archivo base con resumen y enlaces
- `/llms-full.txt` — versión expandida con el contenido completo de cada enlace incrustado
## Implementación en este sitio
Este sitio publica dos archivos generados automáticamente en el pipeline de conocimiento:
- [`/llms.txt`](/llms.txt) — índice con título, tipo y resumen en inglés de cada nodo de conocimiento
- [`/llms-full.txt`](/llms-full.txt) — contenido completo de cada artículo en formato plano
Ambos se regeneran con cada ejecución de `pnpm generate` y se sirven como archivos estáticos desde `public/`.
## Relación con otros estándares
| Estándar | Audiencia | Propósito |
|---|---|---|
| `robots.txt` | Rastreadores | Control de acceso |
| `sitemap.xml` | Motores de búsqueda | Índice de páginas |
| `llms.txt` | Modelos de lenguaje | Resumen curado del sitio |
| [MCP](/concepts/mcp) | Agentes de IA | Protocolo de herramientas y contexto |
`llms.txt` y MCP son complementarios: `llms.txt` proporciona contenido estático legible, mientras que MCP habilita interacciones dinámicas con herramientas y servicios.
## Adopción
Desde su propuesta en 2024, `llms.txt` ha sido adoptado por proyectos de documentación técnica, sitios de comercio electrónico, instituciones educativas y sitios personales. La especificación es deliberadamente simple — un archivo Markdown con convenciones mínimas — lo que facilita su adopción sin herramientas especializadas.
## Referencias
- [The /llms.txt file](https://llmstxt.org/) — Jeremy Howard, 2024. Especificación original del estándar.
- [llms.txt in Different Domains](https://llmstxt.org/) — llmstxt.org. Sitio oficial del estándar llms.txt.
- [FastHTML llms.txt](https://llmstxt.org/) — llmstxt.org. Sitio oficial con especificación y ejemplos de implementación.
- [What is llms.txt? A practical guide](https://usehall.com/guides/what-is-llms-txt-practical-guide) — Hall, 2025. Guía práctica de implementación.
---
# Linting & Formatting
Type: concept
Status: seed
Summary: Automated tools that verify style, detect potential errors, and format code consistently, eliminating style debates and improving quality.
Concepts: code-quality, typescript, ci-cd
## ¿Qué es?
Linting analiza código estáticamente para encontrar errores, anti-patrones y violaciones de estilo. Formatting aplica un estilo consistente automáticamente. Juntos eliminan debates de estilo y atrapan bugs antes de runtime.
## Herramientas
| Herramienta | Tipo | Lenguajes |
|-------------|------|----------|
| ESLint | Linter | JavaScript/TypeScript |
| Prettier | Formatter | Multi-lenguaje |
| Biome | Linter + Formatter | JS/TS (rápido, Rust) |
| Ruff | Linter + Formatter | Python (rápido, Rust) |
| Stylelint | Linter | CSS |
## Integración
| Punto | Cuándo ejecuta | Herramienta |
|-------|---------------|-------------|
| IDE | Feedback en tiempo real mientras escribes | Extensiones de ESLint, Prettier |
| Pre-commit hooks | Antes de cada commit | lint-staged + husky |
| CI | Gate que bloquea PRs con errores | GitHub Actions, GitLab CI |
| Auto-fix | Corrección automática de problemas | `eslint --fix`, `prettier --write` |
## Biome como alternativa
Biome reemplaza ESLint + Prettier con una sola herramienta escrita en Rust, hasta 35x más rápida.
## Estrategia recomendada
Empezar con Biome o Ruff (según el lenguaje) para linting + formatting en una sola herramienta. Configurar auto-fix en pre-commit hooks para que el formato nunca sea tema de discusión en code reviews.
## ¿Por qué importa?
El linting y el formateo automático eliminan discusiones subjetivas sobre estilo en code reviews. Cuando las reglas se aplican automáticamente, los reviews se enfocan en lógica y diseño — lo que realmente importa.
## Referencias
- [ESLint](https://eslint.org/) — Linter de JavaScript.
- [Biome](https://biomejs.dev/) — Toolchain rápido.
- [Prettier](https://prettier.io/docs/en/) — Prettier, 2024. Formateador de código opinado.
---
# Large Language Models
Type: concept
Status: seed
Summary: Massive neural networks based on the Transformer architecture, trained on enormous text corpora to understand and generate natural language with emergent capabilities like reasoning, translation, and code generation.
Concepts: neural-networks, artificial-intelligence, prompt-engineering
## ¿Qué es?
Un modelo de lenguaje de gran escala (LLM) es una red neuronal con miles de millones de parámetros, entrenada sobre cantidades masivas de texto para predecir la siguiente palabra en una secuencia. Esta tarea aparentemente simple — predecir qué palabra viene después — produce capacidades emergentes sorprendentes cuando se escala lo suficiente.
Los LLMs actuales no solo completan texto: siguen instrucciones complejas, razonan paso a paso, escriben código, traducen entre idiomas y mantienen conversaciones coherentes de largo contexto.
## ¿Cómo funcionan?
### La arquitectura Transformer
Introducida en el paper «Attention Is All You Need» (2017), la arquitectura Transformer reemplazó las redes recurrentes con un mecanismo de **atención** que permite al modelo considerar todas las palabras de una secuencia simultáneamente, capturando relaciones de largo alcance.
Componentes clave:
- **Tokenización**: el texto se divide en tokens (subpalabras) que el modelo procesa numéricamente
- **Embeddings**: cada token se convierte en un vector denso que captura su significado semántico
- **Capas de atención**: múltiples capas que aprenden qué partes del contexto son relevantes para cada predicción
- **Ventana de contexto**: la cantidad máxima de tokens que el modelo puede procesar en una sola inferencia
### Entrenamiento en dos fases
1. **Pre-entrenamiento**: el modelo aprende patrones generales del lenguaje procesando billones de tokens de texto. Esta fase es extremadamente costosa en cómputo
2. **Ajuste fino (Fine-tuning)**: el modelo se especializa para seguir instrucciones, alinearse con preferencias humanas (RLHF) o adaptarse a dominios específicos
## Capacidades emergentes
A medida que los modelos escalan, surgen capacidades que no fueron explícitamente programadas:
- **Razonamiento en cadena (Chain-of-Thought)**: capacidad de descomponer problemas complejos en pasos intermedios
- **Aprendizaje en contexto (In-Context Learning)**: aprender de ejemplos proporcionados en el prompt sin actualizar pesos
- **Uso de herramientas**: invocar APIs, ejecutar código o consultar bases de datos cuando se les configura para hacerlo
- **Seguimiento de instrucciones**: interpretar y ejecutar instrucciones complejas en lenguaje natural
## Modelos relevantes
| Modelo | Organización | Características |
|--------|-------------|-----------------|
| GPT-4o | OpenAI | Multimodal, razonamiento avanzado |
| Claude | Anthropic | Contexto largo (200K tokens), seguridad |
| Gemini | Google | Multimodal nativo, integración con búsqueda |
| Llama | Meta | Open-source, comunidad activa |
| Mistral | Mistral AI | Eficiente, modelos abiertos competitivos |
| Command R | Cohere | Optimizado para RAG y empresas |
## Limitaciones
- **Alucinaciones**: generan información plausible pero incorrecta con alta confianza
- **Conocimiento estático**: su conocimiento tiene una fecha de corte del entrenamiento
- **Costo de inferencia**: los modelos más grandes requieren hardware especializado
- **Ventana de contexto finita**: aunque crece, sigue siendo una limitación para documentos muy largos
- **Sesgo**: reflejan sesgos presentes en los datos de entrenamiento
## ¿Por qué importa?
Los LLMs son la tecnología fundacional detrás de la revolución actual en [inteligencia artificial](/concepts/artificial-intelligence). Son el motor que impulsa los [agentes de IA](/concepts/ai-agents), las técnicas de [prompt engineering](/concepts/prompt-engineering) y los sistemas de [búsqueda semántica](/concepts/semantic-search). Entender cómo funcionan — y sus limitaciones — es esencial para construir aplicaciones de IA efectivas.
## Referencias
- [Attention Is All You Need](https://arxiv.org/abs/1706.03762) — Vaswani et al., 2017. El paper que introdujo la arquitectura Transformer.
- [Scaling Laws for Neural Language Models](https://arxiv.org/abs/2001.08361) — Kaplan et al., 2020. Leyes de escalamiento que predicen el rendimiento de LLMs.
- [Sparks of Artificial General Intelligence](https://arxiv.org/abs/2303.12712) — Microsoft Research, 2023. Análisis de capacidades emergentes en GPT-4.
---
# Kubernetes
Type: concept
Status: seed
Summary: Container orchestration platform that automates deployment, scaling, and management of containerized applications at scale, becoming the de facto standard for cloud native.
Concepts: docker, cloud-native
## ¿Qué es?
Kubernetes (K8s) es una plataforma de orquestación de contenedores que automatiza el despliegue, escalado y operación de aplicaciones containerizadas. Originado en Google y ahora mantenido por CNCF, es el estándar de facto para [cloud native](/concepts/cloud-native).
## Conceptos clave
| Recurso | Función | Ejemplo |
|---------|---------|---------|
| Pod | Unidad mínima de despliegue (uno o más contenedores) | Pod con app + sidecar de logging |
| Deployment | Gestiona réplicas de pods con rolling updates | 3 réplicas de un API server |
| Service | Expone pods con IP estable y load balancing | ClusterIP, LoadBalancer, NodePort |
| Ingress | Enrutamiento HTTP/HTTPS externo | Rutas por dominio o path |
| ConfigMap/Secret | Configuración y secretos externalizados | Variables de entorno, certificados |
| Namespace | Aislamiento lógico de recursos | `production`, `staging`, `dev` |
## Kubernetes vs ECS
| Aspecto | Kubernetes | ECS |
|---------|------------|-----|
| Portabilidad | Multi-cloud | AWS only |
| Complejidad | Alta | Menor |
| Ecosistema | Enorme (CNCF) | AWS tools |
| Costo | Control plane fee | Sin fee |
## Cuándo usar Kubernetes
- Necesitas portabilidad multi-cloud
- Tienes equipo con experiencia K8s
- Requieres el ecosistema CNCF (service mesh, GitOps)
- Workloads complejos con muchos microservicios
## Managed Kubernetes
- **EKS** (AWS)
- **GKE** (Google Cloud)
- **AKS** (Azure)
## ¿Por qué importa?
Kubernetes es el estándar de facto para orquestación de contenedores. Su modelo declarativo, auto-healing y escalado automático lo hacen indispensable para cargas de trabajo complejas. Pero su complejidad operacional es real — no todo necesita Kubernetes.
## Referencias
- [Kubernetes Documentation](https://kubernetes.io/docs/) — Documentación oficial.
- [Kubernetes Patterns](https://k8spatterns.io/) — Patrones de diseño.
- [Kubernetes Documentation](https://kubernetes.io/docs/home/) — Kubernetes, 2024. Documentación oficial.
---
# Knowledge Graphs
Type: concept
Status: seed
Summary: Data structures representing knowledge as networks of entities and relationships, enabling reasoning, connection discovery, and semantic queries over complex domains.
Concepts: semantic-search, artificial-intelligence
## ¿Qué es?
Un grafo de conocimiento es una estructura que representa información como una red de entidades (nodos) conectadas por relaciones (aristas). A diferencia de una base de datos tabular, un grafo captura naturalmente las conexiones entre conceptos, permitiendo descubrir relaciones implícitas y razonar sobre dominios complejos.
Este sitio usa un grafo de conocimiento: cada concepto es un nodo, y las relaciones entre conceptos son aristas que forman una red navegable.
## Estructura básica
```
(Entidad) --[Relación]--> (Entidad)
(Git) --[es base de]--> (GitHub)
(GitHub) --[tiene feature]--> (GitHub Actions)
(GitHub Actions) --[implementa]--> (CI/CD)
```
### Tripletas
La unidad fundamental es la tripleta: **sujeto → predicado → objeto**.
```
(LLM) --[usa]--> (Transformer)
(RAG) --[reduce]--> (Alucinaciones)
(MCP) --[estandariza]--> (Tool Use)
```
## Tipos de grafos de conocimiento
- **Taxonómicos**: jerarquías de clasificación (es-un, parte-de)
- **Semánticos**: relaciones ricas con tipos definidos (ontologías)
- **Property graphs**: nodos y aristas con propiedades arbitrarias
- **RDF**: estándar W3C para datos enlazados en la web
## Aplicaciones con IA
### GraphRAG
Combinar grafos de conocimiento con [RAG](/concepts/retrieval-augmented-generation):
- Navegar relaciones para encontrar contexto relevante
- Responder preguntas que requieren conectar múltiples hechos
- Mejor que RAG vectorial para preguntas sobre relaciones
### Grounding
Usar el grafo como fuente de verdad para reducir [alucinaciones](/concepts/hallucination-mitigation).
### Descubrimiento
Encontrar conexiones no obvias entre conceptos — exactamente lo que hace la página `/graph` de este sitio.
## Herramientas
| Herramienta | Tipo |
|-------------|------|
| Neo4j | Base de datos de grafos |
| Amazon Neptune | Grafo managed en AWS |
| NetworkX | Biblioteca Python para grafos |
| D3.js / vis.js | Visualización de grafos |
## ¿Por qué importa?
Los knowledge graphs representan información como entidades y relaciones, lo que permite descubrir conexiones que no son evidentes en datos tabulares. Son la base de sistemas de recomendación, búsqueda semántica y bases de conocimiento como la que impulsa este sitio.
## Referencias
- [Knowledge Graphs](https://arxiv.org/abs/2003.02320) — Hogan et al., 2021. Survey comprehensivo.
- [From Local to Global: A Graph RAG Approach](https://arxiv.org/abs/2404.16130) — Microsoft Research, 2024.
- [Neo4j Graph Database](https://neo4j.com/developer/graph-database/) — Neo4j, 2024. Introducción a bases de datos de grafos.
---
# Internal Developer Platforms
Type: concept
Status: seed
Summary: Internally built platforms abstracting infrastructure and operations complexity, providing self-service to development teams.
Concepts: platform-engineering, developer-portals, backstage
## ¿Qué es?
Una Internal Developer Platform (IDP) es el producto que construye el equipo de [platform engineering](/concepts/platform-engineering). Abstrae la complejidad de infraestructura, CI/CD, observabilidad y seguridad detrás de interfaces de self-service.
## Capas de una IDP
- **Developer portal**: UI para descubrir y gestionar servicios
- **Service catalog**: inventario de componentes disponibles
- **Infrastructure orchestration**: aprovisionamiento automatizado
- **Environment management**: crear/destruir ambientes on-demand
- **Deployment pipeline**: CI/CD estandarizado
## Build vs Buy
| Enfoque | Pros | Contras |
|---------|------|----------|
| Build (Backstage + plugins) | Personalizable | Requiere equipo dedicado |
| Buy (Humanitec, Cortex) | Rápido de implementar | Menos flexible |
| Hybrid | Balance | Complejidad de integración |
## Principio clave
Una IDP es un producto interno — necesita product management, UX research y feedback loops como cualquier producto.
## Señales de que necesitas una IDP
- Los desarrolladores esperan días para obtener un ambiente de pruebas
- Cada equipo tiene su propio pipeline de CI/CD con configuraciones distintas
- El conocimiento de infraestructura está concentrado en una o dos personas
## ¿Por qué importa?
Una plataforma interna de desarrollo reduce la carga cognitiva de los equipos de producto al abstraer la complejidad de infraestructura detrás de interfaces self-service. Es lo que permite que los desarrolladores se enfoquen en entregar valor de negocio en lugar de gestionar Kubernetes.
## Referencias
- [Internal Developer Platform](https://internaldeveloperplatform.org/) — Recursos y guías sobre IDPs.
- [Software Catalog — Backstage](https://backstage.io/docs/features/software-catalog/) — Backstage, 2024. Catálogo de software como componente central de un IDP.
- [Score](https://score.dev/) — Humanitec, 2024. Especificación abierta para workloads independientes de plataforma.
---
# InnerSource
Type: concept
Status: seed
Summary: Application of open-source development practices within an organization, allowing teams to contribute to other teams' projects with transparent processes.
Concepts: monorepos, developer-experience, github
## ¿Qué es?
InnerSource aplica las prácticas del open-source dentro de una organización. Cualquier equipo puede ver, usar y contribuir al código de otros equipos, siguiendo procesos transparentes de contribución.
## Principios
- **Transparencia**: código visible para toda la organización
- **Contribución abierta**: cualquiera puede enviar PRs
- **Revisión de código**: maintainers revisan contribuciones
- **Documentación**: README, CONTRIBUTING, AGENTS.md
- **Gobernanza**: roles claros (contributor, trusted committer, maintainer)
## Beneficios
- Reducir duplicación de código entre equipos
- Acelerar desarrollo reutilizando soluciones existentes
- Mejorar calidad mediante más ojos en el código
- Desarrollar talento cross-team
## Conexión con monorepos
Los [monorepos](/concepts/monorepos) facilitan InnerSource al tener todo el código en un lugar con tooling compartido.
## Niveles de madurez InnerSource
| Nivel | Prácticas | Señales |
|-------|-----------|---------|
| 1. Código visible | Repos internos accesibles a todos | Los equipos pueden leer código ajeno |
| 2. Contribuciones ad-hoc | PRs entre equipos aceptados | Algunos PRs cross-team por trimestre |
| 3. Proceso formal | CONTRIBUTING.md, trusted committers | Roles definidos, SLAs de revisión |
| 4. Cultura establecida | Contribuir fuera del equipo es normal | >20% de PRs son cross-team |
## Prerrequisitos para InnerSource
- Documentación clara de contribución (CONTRIBUTING.md) en cada repositorio
- Code owners definidos para revisiones rápidas
- Cultura de feedback constructivo en code reviews — sin esto, nadie contribuye fuera de su equipo
## ¿Por qué importa?
Inner source aplica las prácticas del open source dentro de la organización. Permite que cualquier equipo contribuya a cualquier repositorio, reduciendo silos y duplicación. Es especialmente valioso en organizaciones grandes donde los equipos resuelven problemas similares de forma independiente.
## Referencias
- [InnerSource Commons](https://innersourcecommons.org/) — Comunidad y patrones de InnerSource.
- [InnerSource Patterns](https://innersourcecommons.org/learn/patterns/) — InnerSource Commons, 2024. Catálogo de patrones de InnerSource.
- [InnerSource Patterns — GitHub](https://github.com/InnerSourceCommons/InnerSourcePatterns) — InnerSource Commons, 2024. Repositorio de patrones.
---
# Infrastructure as Code
Type: concept
Status: evergreen
Summary: Practice of defining and managing infrastructure through versioned configuration files instead of manual processes. Foundation of modern operations automation.
Concepts: devops, devops-practices, ci-cd
**Infrastructure as Code (IaC)** es tratar la infraestructura exactamente como código: versionada en Git, revisada en PRs, testeada en CI, y aplicada de forma automatizada y reproducible.
## ¿Qué problema resuelve?
Sin IaC:
- **Snowflake servers** — cada servidor es único, configurado a mano, imposible de reproducir
- **Configuration drift** — los entornos divergen silenciosamente
- **Documentación desactualizada** — el wiki dice una cosa, la realidad es otra
- **Auditoría imposible** — ¿quién cambió qué, cuándo, por qué?
- **Disaster recovery lento** — reconstruir manualmente toma horas o días
Con IaC: `terraform apply` y la infraestructura completa se recrea en minutos.
## Enfoques
### Declarativo vs imperativo
| Enfoque | Descripción | Herramientas |
|---------|-------------|--------------|
| **Declarativo** | Describes el estado deseado, la herramienta calcula cómo llegar | Terraform, CloudFormation, Kubernetes YAML |
| **Imperativo** | Describes los pasos a ejecutar en orden | Scripts bash, Ansible (parcialmente), Pulumi |
```hcl
# Declarativo (Terraform) — "quiero esto"
resource "aws_instance" "web" {
ami = "ami-0c55b159cbfafe1f0"
instance_type = "t3.micro"
}
```
```python
# Imperativo (Pulumi) — "haz esto"
server = aws.ec2.Instance("web",
ami="ami-0c55b159cbfafe1f0",
instance_type="t3.micro")
```
### Mutable vs inmutable
- **Mutable** — actualizar servidores existentes (Ansible, Chef, Puppet)
- **Inmutable** — destruir y recrear (Terraform + AMIs, contenedores)
La infraestructura inmutable elimina configuration drift por diseño.
## Herramientas principales
| Herramienta | Tipo | Cloud | Lenguaje | Estado |
|-------------|------|-------|----------|--------|
| **Terraform** | Provisioning | Multi-cloud | HCL | Remote state |
| **OpenTofu** | Provisioning | Multi-cloud | HCL | Remote state |
| **Pulumi** | Provisioning | Multi-cloud | TS, Python, Go | Managed/self-hosted |
| **AWS CDK** | Provisioning | AWS | TS, Python, Java | CloudFormation |
| **CloudFormation** | Provisioning | AWS | YAML/JSON | AWS-managed |
| **Ansible** | Config mgmt | Agnostic | YAML | Stateless |
| **Crossplane** | Provisioning | Multi-cloud | YAML (K8s CRDs) | Kubernetes |
## Principios fundamentales
### 1. Todo en Git
```
infra/
├── modules/
│ ├── networking/
│ ├── compute/
│ └── database/
├── environments/
│ ├── dev/
│ ├── staging/
│ └── production/
├── .github/workflows/
│ └── terraform.yml
└── README.md
```
### 2. Idempotencia
Aplicar el mismo código N veces produce el mismo resultado:
```bash
terraform apply # Crea 3 instancias
terraform apply # No changes. Infrastructure is up-to-date.
terraform apply # No changes. Infrastructure is up-to-date.
```
### 3. State management
El estado es la fuente de verdad sobre qué existe:
```hcl
# Backend remoto (compartido entre equipo)
terraform {
backend "s3" {
bucket = "my-terraform-state"
key = "prod/terraform.tfstate"
region = "us-east-1"
dynamodb_table = "terraform-locks"
encrypt = true
}
}
```
### 4. Módulos reutilizables
```hcl
module "vpc" {
source = "terraform-aws-modules/vpc/aws"
version = "5.0.0"
name = "production"
cidr = "10.0.0.0/16"
azs = ["us-east-1a", "us-east-1b"]
private_subnets = ["10.0.1.0/24", "10.0.2.0/24"]
public_subnets = ["10.0.101.0/24", "10.0.102.0/24"]
enable_nat_gateway = true
}
```
### 5. Plan antes de apply
```bash
terraform plan # Ver qué va a cambiar
# + aws_instance.web (create)
# ~ aws_security_group.web (modify)
# - aws_instance.old (destroy)
terraform apply # Aplicar después de revisar
```
## Pipeline de IaC
```yaml
# .github/workflows/terraform.yml
name: Terraform
on:
pull_request:
paths: ['infra/**']
push:
branches: [main]
paths: ['infra/**']
jobs:
plan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: hashicorp/setup-terraform@v3
- run: terraform init
- run: terraform validate
- run: terraform plan -out=plan.tfplan
- uses: actions/upload-artifact@v4
with:
name: plan
path: plan.tfplan
apply:
needs: plan
if: github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
environment: production
steps:
- uses: actions/checkout@v4
- uses: hashicorp/setup-terraform@v3
- uses: actions/download-artifact@v4
with:
name: plan
- run: terraform apply plan.tfplan
```
## Testing de IaC
| Nivel | Herramienta | Qué valida |
|-------|-------------|------------|
| **Lint** | `terraform validate`, `tflint` | Sintaxis y convenciones |
| **Static** | Checkov, tfsec, Trivy | Seguridad y compliance |
| **Unit** | Terratest, `terraform test` | Lógica de módulos |
| **Integration** | Terratest | Infraestructura real temporal |
| **Policy** | OPA, Sentinel | Políticas organizacionales |
## Anti-patrones
- **ClickOps** — crear recursos manualmente y luego «importarlos» como parche
- **Mega-state** — toda la infra en un solo state file. Dividir por dominio/entorno.
- **Sin locks** — dos personas aplicando simultáneamente corrompen el estado
- **Hardcoded values** — usar variables y tfvars para parametrizar
- **Sin plan review** — aplicar sin revisar el plan es como mergear sin code review
- **Ignorar drift** — no detectar cambios manuales que divergen del código
## ¿Por qué importa?
Sin IaC, la infraestructura es conocimiento tácito que vive en la cabeza de quien la configuró. Con IaC, cada cambio es rastreable, revisable y reproducible. Es el fundamento sobre el que se construyen prácticas como GitOps, disaster recovery automatizado y self-service infrastructure.
## Referencias
- [Infrastructure as Code, 2nd Edition](https://www.oreilly.com/library/view/infrastructure-as-code/9781098114664/) — Kief Morris, 2020. El libro definitivo sobre IaC.
- [Terraform: Up & Running, 3rd Edition](https://www.terraformupandrunning.com/) — Yevgeniy Brikman, 2022. Guía práctica de Terraform con patrones reales.
- [The Twelve-Factor App](https://12factor.net/) — Adam Wiggins, 2011. Principios de aplicaciones cloud-native que complementan IaC.
- [Terraform Best Practices](https://www.terraform-best-practices.com/) — Anton Babenko, 2024. Guía comunitaria de mejores prácticas.
- [Pulumi Documentation](https://www.pulumi.com/docs/) — Pulumi, 2024. Documentación oficial de la alternativa imperativa.
---
# Inference Optimization
Type: concept
Status: seed
Summary: Techniques to reduce cost, latency, and resources needed to run language models in production, from quantization to distributed serving.
Concepts: large-language-models, serverless, prompt-caching
## ¿Qué es?
La optimización de inferencia abarca las técnicas para hacer que los [LLMs](/concepts/large-language-models) sean más rápidos, baratos y eficientes en producción. Mientras que el entrenamiento ocurre una vez, la inferencia ocurre millones de veces — pequeñas mejoras tienen impacto masivo.
## Técnicas principales
### Cuantización
Reducir la precisión numérica de los pesos del modelo:
- **FP16**: de 32-bit a 16-bit flotante (estándar)
- **INT8**: 8-bit entero (~2x reducción de memoria)
- **INT4/GPTQ/AWQ**: 4-bit (~4x reducción, mínima pérdida de calidad)
### KV Cache
Almacenar los key-value pairs de capas de atención para no recalcularlos en cada token generado. Esencial para generación autoregresiva eficiente.
### Batching
- **Static batching**: agrupar múltiples requests en un batch
- **Continuous batching**: agregar/remover requests dinámicamente del batch
- **Speculative decoding**: un modelo pequeño genera candidatos que el grande verifica
### Serving distribuido
- **Tensor parallelism**: dividir el modelo entre múltiples GPUs
- **Pipeline parallelism**: diferentes capas en diferentes GPUs
- **Expert parallelism**: para modelos Mixture-of-Experts (MoE)
## Frameworks de serving
| Framework | Características |
|-----------|-----------------|
| vLLM | PagedAttention, continuous batching |
| TensorRT-LLM | Optimización NVIDIA, alta performance |
| Ollama | Local, fácil de usar |
| llama.cpp | CPU inference, cuantización agresiva |
## Métricas clave
- **TTFT (Time to First Token)**: latencia hasta el primer token generado
- **TPS (Tokens Per Second)**: velocidad de generación
- **Throughput**: requests por segundo del sistema
- **Costo por token**: precio de inferencia por token generado
## Serverless inference
Servicios como [AWS Bedrock](/concepts/aws-bedrock) y APIs de proveedores eliminan la gestión de infraestructura. Se paga por token consumido, ideal para cargas variables.
## ¿Por qué importa?
En producción, la inferencia ocurre millones de veces. Cada milisegundo de latencia y cada token procesado tiene un costo. Las técnicas de optimización — cuantización, KV cache, batching — son la diferencia entre un sistema de IA viable económicamente y uno que quiebra el presupuesto.
## Referencias
- [Efficient Large Language Model Inference](https://arxiv.org/abs/2404.14294) — Survey de técnicas de optimización.
- [vLLM: Easy, Fast, and Cheap LLM Serving](https://arxiv.org/abs/2309.06180) — Kwon et al., 2023.
- [Efficient LLM Inference Survey](https://arxiv.org/abs/2401.01313) — Zhou et al., 2024. Survey de técnicas de optimización de inferencia.
---
# Incident Management
Type: concept
Status: seed
Summary: Processes and practices for detecting, responding to, resolving, and learning from production incidents in a structured and effective way.
Concepts: site-reliability-engineering, devops-practices, observability
## ¿Qué es?
Incident management es el proceso estructurado para manejar problemas en producción: desde la detección hasta la resolución y el aprendizaje posterior. Un buen proceso minimiza el impacto y previene recurrencias.
## Fases
1. **Detección**: alertas, reportes de usuarios, monitoreo
2. **Triage**: evaluar severidad e impacto
3. **Respuesta**: asignar roles, comunicar, mitigar
4. **Resolución**: restaurar el servicio
5. **Postmortem**: analizar y aprender
## Roles durante un incidente
- **Incident Commander**: coordina la respuesta
- **Tech Lead**: lidera la investigación técnica
- **Communications**: actualiza stakeholders
- **Scribe**: documenta timeline y acciones
## Postmortems blameless
El objetivo es aprender, no culpar. Preguntas clave:
- ¿Qué pasó? (timeline)
- ¿Por qué pasó? (5 whys)
- ¿Cómo prevenimos que vuelva a pasar? (action items)
## Herramientas
- PagerDuty, Opsgenie (on-call)
- Statuspage (comunicación)
- Jira, Linear (tracking de action items)
## Severidades
| Nivel | Impacto | Respuesta |
|-------|---------|-----------|
| SEV1 | Servicio caído, todos los usuarios afectados | Respuesta inmediata, all-hands |
| SEV2 | Funcionalidad degradada, subconjunto de usuarios | Respuesta en minutos, equipo on-call |
| SEV3 | Problema menor, workaround disponible | Siguiente día hábil |
## ¿Por qué importa?
La forma en que un equipo responde a incidentes define su madurez operacional. Un proceso claro — detección, triaje, comunicación, resolución, postmortem — reduce el tiempo de recuperación y convierte cada incidente en una oportunidad de mejora sistémica.
## Referencias
- [Incident Management - PagerDuty](https://response.pagerduty.com/) — Guía completa.
- [Managing Incidents — SRE Book](https://sre.google/sre-book/managing-incidents/) — Google, 2016. Capítulo sobre gestión de incidentes.
- [Incident Management Guide](https://firehydrant.com/resources/guides/incident-management/) — FireHydrant, 2024. Guía práctica de gestión de incidentes.
---
# Hexagonal Architecture
Type: concept
Status: seed
Summary: Architectural pattern isolating business logic from the outside world through ports and adapters, facilitating testing and technology changes.
Concepts: domain-driven-design, microservices
## ¿Qué es?
La arquitectura hexagonal (también llamada Ports & Adapters) organiza el código en capas donde la lógica de negocio está en el centro, completamente aislada de detalles técnicos como bases de datos, APIs o frameworks.
## Estructura
```
[Adaptador HTTP] → [Puerto de entrada] → [Dominio] → [Puerto de salida] → [Adaptador DB]
```
- **Dominio**: lógica de negocio pura, sin dependencias externas
- **Puertos**: interfaces que definen cómo el dominio interactúa con el exterior
- **Adaptadores**: implementaciones concretas de los puertos
## Beneficios
- Testing del dominio sin infraestructura
- Cambiar base de datos sin tocar lógica de negocio
- Múltiples interfaces (HTTP, CLI, eventos) para la misma lógica
- Separación clara de responsabilidades
## Relación con otras arquitecturas
| Arquitectura | Autor | Capas | Diferencia clave |
|-------------|-------|-------|-----------------|
| Hexagonal (Ports & Adapters) | Alistair Cockburn, 2005 | Dominio → Puertos → Adaptadores | Enfoque en puertos como contratos |
| Clean Architecture | Robert Martin, 2012 | Entities → Use Cases → Adapters → Frameworks | Capas concéntricas, dependencias hacia adentro |
| Onion Architecture | Jeffrey Palermo, 2008 | Domain Model → Domain Services → Application → Infrastructure | Similar a Clean, énfasis en el modelo de dominio |
Las tres comparten el principio fundamental: las dependencias apuntan hacia adentro, protegiendo la lógica de negocio de los detalles de infraestructura.
## ¿Por qué importa?
La arquitectura hexagonal protege la lógica de negocio de los detalles de infraestructura. Cuando la base de datos, el framework web o el proveedor de cloud cambian, solo se modifican los adaptadores — el dominio permanece intacto. Es la inversión en mantenibilidad a largo plazo.
## Referencias
- [Hexagonal Architecture](https://alistair.cockburn.us/hexagonal-architecture/) — Alistair Cockburn, 2005.
- [Ready for Changes with Hexagonal Architecture](https://netflixtechblog.com/ready-for-changes-with-hexagonal-architecture-b315ec967749) — Netflix Tech Blog, 2020. Caso de estudio de Netflix.
- [DDD, Hexagonal, Onion, Clean, CQRS](https://herbertograca.com/2017/11/16/explicit-architecture-01-ddd-hexagonal-onion-clean-cqrs-how-i-put-it-all-together/) — Herberto Graça, 2017. Comparación de arquitecturas.
---
# Helm
Type: concept
Status: seed
Summary: Package manager for Kubernetes that simplifies installation and management of complex applications through reusable and configurable charts.
Concepts: kubernetes, infrastructure-as-code, gitops
## ¿Qué es?
Helm es el gestor de paquetes de [Kubernetes](/concepts/kubernetes). Un «chart» de Helm empaqueta todos los manifiestos K8s necesarios para desplegar una aplicación, con valores configurables que permiten personalizar el despliegue sin modificar los templates.
## Conceptos clave
| Concepto | Función | Ejemplo |
|----------|---------|---------|
| Chart | Paquete de manifiestos K8s con templates | `nginx-ingress`, `prometheus` |
| Release | Instancia de un chart desplegado | `my-app-production` |
| Values | Configuración que personaliza el chart | `values.yaml` con réplicas, imagen, recursos |
| Repository | Colección de charts publicados | Artifact Hub, OCI registries |
## Comandos esenciales
```bash
helm repo add bitnami https://charts.bitnami.com/bitnami
helm install my-db bitnami/postgresql --set auth.postgresPassword=secret
helm upgrade my-db bitnami/postgresql --set resources.requests.memory=512Mi
helm rollback my-db 1
```
## Cuándo usar Helm
- Desplegar aplicaciones de terceros en K8s
- Estandarizar despliegues internos
- Gestionar configuración por ambiente
- Rollbacks rápidos
## Helm vs Kustomize
| Aspecto | Helm | Kustomize |
|---------|------|-----------|
| Enfoque | Templating con valores | Patches sobre manifiestos base |
| Complejidad | Mayor (Go templates) | Menor (overlays declarativos) |
| Ecosistema | Charts de terceros en Artifact Hub | Nativo en kubectl |
## ¿Por qué importa?
Helm es el gestor de paquetes estándar para Kubernetes. Los charts permiten empaquetar, versionar y distribuir aplicaciones complejas como una unidad, con valores configurables por entorno. Es la forma más adoptada de gestionar despliegues en Kubernetes.
## Referencias
- [Helm Documentation](https://helm.sh/docs/) — Helm, 2024. Documentación oficial.
- [Artifact Hub](https://artifacthub.io/) — CNCF, 2024. Catálogo de charts.
- [Chart Best Practices](https://helm.sh/docs/chart_best_practices/) — Helm, 2024. Mejores prácticas para crear charts.
---
# Hallucination Mitigation
Type: concept
Status: seed
Summary: Techniques to reduce LLMs generating false but plausible information, from RAG to factual verification and prompt design.
Concepts: large-language-models, retrieval-augmented-generation
## ¿Qué es?
Las alucinaciones son respuestas de [LLMs](/concepts/large-language-models) que suenan correctas pero contienen información fabricada. El modelo genera texto plausible basándose en patrones estadísticos, no en hechos verificados. Mitigar alucinaciones es crítico para aplicaciones donde la precisión importa.
## Tipos de alucinaciones
| Tipo | Ejemplo | Detección | Mitigación |
|------|---------|-----------|------------|
| Factual | Datos incorrectos como hechos | Verificación contra fuentes | [RAG](/concepts/retrieval-augmented-generation) con citas |
| Fabricación | Inventar URLs, papers, citas | Validar que las fuentes existen | Instruir «no sé» + verificación |
| Inconsistencia | Contradecirse en la misma respuesta | Comparar afirmaciones | [Chain-of-thought](/concepts/chain-of-thought) |
| Extrapolación | Generalizar de ejemplos limitados | Evaluar confianza del modelo | Limitar scope del prompt |
## Estrategias de mitigación
### Grounding con RAG
[RAG](/concepts/retrieval-augmented-generation) ancla las respuestas en documentos reales:
- El modelo cita fuentes específicas
- Se puede verificar la información contra los documentos originales
- Reduce (no elimina) la fabricación de hechos
### Diseño de prompts
- Instruir al modelo a decir «no sé» cuando no tiene información
- Pedir que cite fuentes para afirmaciones factuales
- Usar [chain-of-thought](/concepts/chain-of-thought) para hacer el razonamiento explícito
- Separar claramente hechos de opiniones
### Verificación post-generación
- Modelos secundarios que verifican afirmaciones factuales
- Búsqueda web para validar claims específicos
- Comparación con bases de conocimiento estructuradas
### Calibración de confianza
- Pedir al modelo que indique su nivel de certeza
- Generar múltiples respuestas y comparar consistencia
- Detectar patrones lingüísticos asociados con alucinaciones
## Métricas de evaluación
- **Faithfulness**: ¿la respuesta es fiel al contexto proporcionado?
- **Factuality**: ¿los hechos son verificablemente correctos?
- **Attribution**: ¿las citas son reales y relevantes?
## Limitaciones
No existe solución perfecta. Incluso con RAG, el modelo puede:
- Malinterpretar el contexto recuperado
- Combinar información de formas incorrectas
- Inventar detalles que «completan» la información
La mitigación reduce la frecuencia, no elimina el problema.
## ¿Por qué importa?
Las alucinaciones son el riesgo más visible de los sistemas de IA en producción. Un modelo que genera información falsa con confianza puede causar daño real. Las técnicas de mitigación — RAG, grounding, verificación — son requisitos de ingeniería, no mejoras opcionales.
## Referencias
- [Survey of Hallucination in Natural Language Generation](https://arxiv.org/abs/2202.03629) — Ji et al., 2023.
- [FActScore: Fine-grained Atomic Evaluation of Factual Precision](https://arxiv.org/abs/2305.14251) — Min et al., 2023.
- [A Survey on Hallucination in LLMs](https://arxiv.org/abs/2311.05232) — Huang et al., 2023. Survey completo sobre alucinaciones en LLMs.
---
# Golden Paths
Type: concept
Status: seed
Summary: Recommended, pre-configured paths for common development tasks incorporating best practices, reducing cognitive load for teams.
Concepts: platform-engineering, developer-experience, developer-portals, backstage, ci-cd
## ¿Qué es?
Golden paths son caminos recomendados (no obligatorios) para tareas comunes de desarrollo. Son templates, workflows y configuraciones pre-construidas que incorporan las mejores prácticas de la organización.
## Ejemplos
- Template para nuevo microservicio (con CI/CD, observabilidad, tests)
- Workflow estándar para desplegar a producción
- Configuración de base de datos con backups y monitoreo
- Pipeline de ML con tracking de experimentos
## Golden Path vs Mandato
| Golden Path | Mandato |
|-------------|----------|
| Recomendado | Obligatorio |
| Fácil de seguir | Forzado por políticas |
| Adoptado por valor | Adoptado por compliance |
| Flexible | Rígido |
## Principio clave
Hacer lo correcto debe ser más fácil que hacer lo incorrecto. Si el golden path es más difícil que el camino ad-hoc, nadie lo usará.
## ¿Cómo construir un golden path?
1. **Identificar la tarea repetitiva** — ¿qué hacen los equipos una y otra vez?
2. **Documentar el camino actual** — ¿cuáles son los pasos que sigue el equipo más efectivo?
3. **Automatizar** — convertir esos pasos en un template o script
4. **Hacer que sea el default** — que el golden path sea lo que aparece cuando alguien empieza un proyecto nuevo
5. **Iterar** — recoger feedback y mejorar continuamente
## ¿Por qué importa?
Los golden paths reducen la carga cognitiva al proporcionar caminos probados y documentados para tareas comunes. En lugar de que cada equipo reinvente cómo crear un servicio, desplegar una aplicación o configurar observabilidad, siguen un camino que ya funciona.
## Referencias
- [Golden Paths](https://engineering.atspotify.com/2020/08/how-we-use-golden-paths-to-solve-fragmentation-in-our-software-ecosystem/) — Spotify Engineering, 2020. Cómo Spotify usa golden paths para reducir fragmentación.
- [Team Topologies](https://teamtopologies.com/) — Skelton y Pais, 2019. El concepto de «platform as a product» que fundamenta los golden paths.
- [Software Templates — Backstage](https://backstage.io/docs/features/software-templates/) — Backstage, 2024. Implementación de golden paths con templates.
---
# GitOps
Type: concept
Status: seed
Summary: Operational practice using Git as single source of truth for infrastructure and configuration, with automatic reconciliation between desired and actual state.
Concepts: ci-cd, infrastructure-as-code, kubernetes
## ¿Qué es?
GitOps es una práctica donde Git es la fuente única de verdad para el estado deseado de la infraestructura y aplicaciones. Un operador (ArgoCD, Flux) monitorea el repositorio y reconcilia automáticamente el estado real con el declarado en Git.
## Principios
1. **Declarativo**: el estado deseado se describe, no los pasos
2. **Versionado**: todo en Git con historial completo
3. **Automático**: cambios en Git se aplican automáticamente
4. **Reconciliación**: el operador corrige drift continuamente
## Flujo
```
Dev → PR → Review → Merge → Git repo
↓
Operador GitOps detecta cambio
↓
Aplica cambios al cluster
↓
Reconcilia estado continuamente
```
## Herramientas
| Herramienta | Enfoque |
|-------------|--------|
| ArgoCD | UI rica, multi-cluster |
| Flux | Ligero, CNCF |
| Crossplane | Infraestructura cloud via K8s |
## ¿Cuándo no usar GitOps?
- Aplicaciones que requieren despliegues imperativos con lógica condicional compleja
- Equipos sin experiencia en Kubernetes — la curva de aprendizaje se multiplica
- Secretos que no deben vivir en Git (requiere herramientas adicionales como Sealed Secrets o External Secrets)
## ¿Por qué importa?
GitOps convierte Git en la fuente de verdad para la infraestructura y las aplicaciones. Cada cambio pasa por un PR, es revisado y se aplica automáticamente. Esto proporciona auditoría completa, rollback instantáneo y un flujo de trabajo que los desarrolladores ya conocen.
## Referencias
- [OpenGitOps](https://opengitops.dev/) — Principios y estándar.
- [ArgoCD](https://argo-cd.readthedocs.io/) — Documentación oficial.
- [Flux CD](https://fluxcd.io/flux/) — CNCF, 2024. Herramienta GitOps nativa de Kubernetes.
---
# GitHub
Type: concept
Status: evergreen
Summary: Collaborative development platform built on Git. More than repository hosting — it's the central hub for code review, CI/CD, project management, and open source collaboration.
Concepts: git, github-actions
**GitHub** es una plataforma que extiende Git con colaboración, automatización y gestión de proyectos. Fundada en 2008, adquirida por Microsoft en 2018, hoy aloja más de 200 millones de repositorios y es el estándar de facto para desarrollo open source.
## ¿Qué agrega sobre Git?
Git es el motor de control de versiones. GitHub agrega:
- **Pull Requests** — propuestas de cambio con code review integrado
- **Issues** — tracking de bugs, features y tareas
- **Actions** — CI/CD nativo con workflows declarativos
- **Projects** — tableros Kanban y planificación
- **Discussions** — foros por repositorio
- **Codespaces** — entornos de desarrollo en la nube
- **Copilot** — asistente de código con IA
- **Security** — Dependabot, secret scanning, code scanning
## Pull Requests
El flujo central de colaboración:
1. Crear rama desde `main`
2. Hacer commits con cambios
3. Abrir Pull Request (PR)
4. Code review — comentarios, sugerencias, aprobaciones
5. CI checks pasan
6. Merge a `main`
### Anatomía de un buen PR
```markdown
## Descripción
Qué cambia y por qué.
## Tipo de cambio
- [ ] Bug fix
- [ ] Nueva feature
- [ ] Breaking change
- [ ] Documentación
## Testing
Cómo se probó este cambio.
## Screenshots (si aplica)
```
### Merge strategies
| Estrategia | Resultado | Cuándo usar |
|------------|-----------|-------------|
| **Merge commit** | Preserva todos los commits + merge commit | Historial completo importa |
| **Squash and merge** | Un solo commit en main | PRs con muchos commits WIP |
| **Rebase and merge** | Commits individuales sin merge commit | Historial lineal limpio |
## GitHub Actions
CI/CD declarativo en YAML. Los workflows viven en `.github/workflows/`.
```yaml
name: CI
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
cache: 'pnpm'
- run: pnpm install
- run: pnpm test
- run: pnpm build
```
### Conceptos clave
- **Workflow** — archivo YAML que define la automatización
- **Job** — conjunto de steps que corren en el mismo runner
- **Step** — comando individual o action reutilizable
- **Action** — unidad reutilizable (ej: `actions/checkout@v4`)
- **Runner** — máquina que ejecuta el job (GitHub-hosted o self-hosted)
- **Secret** — variable encriptada para tokens y credenciales
### Triggers comunes
```yaml
on:
push: # cualquier push
pull_request: # PRs abiertos/actualizados
schedule:
- cron: '0 0 * * *' # diario a medianoche UTC
workflow_dispatch: # manual desde UI
release:
types: [published] # cuando se publica un release
```
## Branch protection
Reglas para proteger ramas críticas:
- Requerir PR antes de merge
- Requerir N aprobaciones
- Requerir status checks (CI debe pasar)
- Requerir conversaciones resueltas
- Requerir firma de commits
- Bloquear force push
Configurar en: Settings → Branches → Add rule
## GitHub CLI (`gh`)
Interactuar con GitHub desde la terminal:
```bash
# Autenticación
gh auth login
# Repositorios
gh repo create mi-proyecto --public
gh repo clone owner/repo
gh repo fork owner/repo
# Pull Requests
gh pr create --title "feat: add login" --body "Description"
gh pr list
gh pr checkout 123
gh pr merge 123 --squash
gh pr review 123 --approve
# Issues
gh issue create --title "Bug: login fails"
gh issue list --label bug
gh issue close 456
# Actions
gh run list
gh run view 789
gh run watch 789
# Releases
gh release create v1.0.0 --generate-notes
```
## GitHub vs alternativas
| Plataforma | Fortaleza | Consideración |
|------------|-----------|---------------|
| **GitHub** | Ecosistema, comunidad, Actions | Propiedad de Microsoft |
| **GitLab** | DevOps completo, self-hosted | UI más compleja |
| **Bitbucket** | Integración Atlassian (Jira) | Menos comunidad open source |
| **Azure DevOps** | Enterprise, integración Azure | Curva de aprendizaje |
## Buenas prácticas
1. **Commits atómicos** — cada commit hace una cosa
2. **Conventional commits** — `feat:`, `fix:`, `chore:`, `docs:`
3. **PRs pequeños** — más fáciles de revisar, menos riesgo
4. **Branch protection** — nunca push directo a main
5. **CODEOWNERS** — asignar reviewers automáticamente
6. **Templates** — PR e issue templates para consistencia
7. **Dependabot** — actualizaciones de seguridad automáticas
## Archivos especiales
```
.github/
├── workflows/ # GitHub Actions
├── CODEOWNERS # Asignación automática de reviewers
├── PULL_REQUEST_TEMPLATE.md
├── ISSUE_TEMPLATE/
│ ├── bug_report.md
│ └── feature_request.md
├── FUNDING.yml # Sponsors
└── dependabot.yml # Configuración Dependabot
```
## ¿Por qué importa?
GitHub no es solo un hosting de repositorios — es la plataforma donde convergen el código, la revisión, el CI/CD, la gestión de proyectos y la colaboración. Dominar sus capacidades nativas (Actions, branch protection, CLI) reduce la dependencia de herramientas externas y acelera el ciclo de desarrollo.
## Referencias
- [GitHub Docs](https://docs.github.com/) — GitHub, 2024. Documentación oficial completa.
- [GitHub Skills](https://skills.github.com/) — GitHub, 2024. Cursos interactivos gratuitos.
- [GitHub CLI Manual](https://cli.github.com/manual/) — GitHub, 2024. Referencia completa de `gh`.
- [Awesome GitHub Actions](https://github.com/sdras/awesome-actions) — Sarah Drasner, 2024. Colección curada de actions.
---
# GitHub Flow
Type: concept
Status: evergreen
Summary: Minimalist branching model designed for continuous deployment. Only two elements — main and feature branches — with PRs as the integration point and immediate deploy after merge.
Concepts: git, github, gitflow
**GitHub Flow** es un modelo de branching simplificado creado por GitHub en 2011 como alternativa ligera a GitFlow. Su premisa: `main` siempre está deployable, y cada cambio pasa por un Pull Request.
## ¿Por qué existe?
GitFlow fue diseñado para software con releases programados. Pero para equipos que hacen deploy múltiples veces al día, sus múltiples ramas (`develop`, `release/*`, `hotfix/*`) agregan fricción sin beneficio.
GitHub Flow reduce todo a lo esencial:
```
main: ──●────●────●────●────●──
\ / \ / \ /
feature: ● ● ●
```
## Las 6 reglas
1. **`main` siempre es deployable** — cualquier commit en main puede ir a producción
2. **Crear rama descriptiva desde main** — `feature/add-login`, `fix/header-overflow`
3. **Commits frecuentes a la rama** — push temprano y seguido para backup y visibilidad
4. **Abrir PR cuando necesites feedback** — no esperar a terminar; PRs draft existen para esto
5. **Merge solo después de review** — al menos una aprobación antes de mergear
6. **Deploy inmediatamente después de merge** — o incluso antes (deploy desde la rama)
## Flujo completo
```bash
# 1. Crear rama desde main actualizado
git checkout main
git pull origin main
git checkout -b feature/user-notifications
# 2. Trabajar y hacer commits
git add .
git commit -m "feat: add notification preferences UI"
git push -u origin feature/user-notifications
# 3. Abrir PR en GitHub
gh pr create --title "feat: user notifications" --body "Adds notification preferences"
# 4. Iterar basado en review
git commit -m "fix: address review comments"
git push
# 5. Merge después de aprobación (squash recomendado)
gh pr merge --squash
# 6. Deploy automático (CI/CD se encarga)
# main → staging → producción
```
## ¿Cuándo usarlo?
**Ideal para:**
- Aplicaciones web con un solo entorno de producción
- Equipos que practican continuous deployment
- Startups y equipos pequeños-medianos
- Proyectos donde la velocidad importa más que el control ceremonial
- SaaS, APIs, microservicios
**Considerar alternativas cuando:**
- Necesitas mantener múltiples versiones en producción (v1, v2, v3)
- Releases requieren QA formal de varios días
- Software empaquetado con ciclos de release largos
- Regulaciones requieren trazabilidad estricta de releases
## GitHub Flow vs GitFlow
| Aspecto | GitHub Flow | GitFlow |
|---------|-------------|---------|
| Ramas permanentes | 1 (`main`) | 2 (`main`, `develop`) |
| Ramas temporales | `feature/*` | `feature/*`, `release/*`, `hotfix/*` |
| Complejidad | Mínima | Alta |
| Deploy | Continuo | Por release |
| Hotfixes | Igual que features | Rama especial desde main |
| Ideal para | Web apps, SaaS | Software versionado, enterprise |
## Patrones complementarios
### Feature flags
Permiten mergear código incompleto a main sin exponerlo a usuarios:
```typescript
if (featureFlags.isEnabled('new-checkout')) {
return ;
}
return ;
```
Beneficios:
- PRs más pequeños y frecuentes
- Testing en producción con usuarios seleccionados
- Rollback instantáneo sin deploy
### Branch deploy
Deployar la rama antes de mergear para validar en un entorno real:
```yaml
# .github/workflows/branch-deploy.yml
on:
pull_request:
types: [labeled]
jobs:
deploy-preview:
if: github.event.label.name == 'deploy-preview'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: ./deploy-to-preview.sh
```
### Conventional commits
Estructura los mensajes para generar changelogs automáticos:
```
feat: add user notifications
fix: resolve header overflow on mobile
docs: update API documentation
chore: upgrade dependencies
```
## CI/CD típico
```yaml
name: CI/CD
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm ci
- run: npm test
- run: npm run lint
deploy:
needs: test
if: github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm ci
- run: npm run build
- run: ./deploy.sh
```
## Anti-patrones
- **PRs gigantes** — difíciles de revisar, alto riesgo. Dividir en PRs pequeños.
- **Main roto** — si main no es deployable, el modelo colapsa. CI obligatorio.
- **Ramas de larga vida** — más de 2-3 días acumula conflictos. Mergear frecuentemente.
- **Saltarse el review** — merge directo a main sin PR elimina la red de seguridad.
- **Deploy manual** — si el deploy no es automático, se acumula trabajo y aumenta el riesgo.
## ¿Por qué importa?
GitHub Flow es el modelo de branching más adoptado en equipos que practican continuous delivery. Su simplicidad — una sola rama principal, feature branches cortas, deploy tras merge — elimina la ceremonia de modelos más complejos como GitFlow y reduce el tiempo entre escribir código y ponerlo en producción.
## Referencias
- [GitHub Flow](https://docs.github.com/en/get-started/using-github/github-flow) — GitHub, 2024. Documentación oficial.
- [Understanding the GitHub Flow](https://guides.github.com/introduction/flow/) — GitHub Guides, 2024. Guía visual del flujo.
- [Scott Chacon on GitHub Flow](https://scottchacon.com/2011/08/31/github-flow) — Scott Chacon, 2011. Post original explicando por qué GitHub abandonó GitFlow.
- [Ship Small, Ship Fast](https://mcfunley.com/ship-small-diffs) — Dan McKinley, 2017. Por qué PRs pequeños reducen riesgo.
---
# GitHub Actions
Type: concept
Status: evergreen
Summary: GitHub's native CI/CD platform. Declarative YAML workflows that automate build, test, deploy, and any development lifecycle task — directly from the repository.
Concepts: github, ci-cd, devops
**GitHub Actions** es la plataforma de automatización integrada en GitHub. Cada repositorio puede definir workflows en YAML que se ejecutan en respuesta a eventos — push, PR, schedule, release, o cualquier webhook.
## ¿Por qué elegirlo?
- **Integración nativa** — vive dentro del repositorio, sin configurar servicios externos
- **Marketplace** — más de 20,000 actions reutilizables
- **Runners gratuitos** — 2,000 minutos/mes en repos públicos (ilimitado), privados con límite por plan
- **Matrix builds** — testear en múltiples OS/versiones en paralelo
- **Secrets management** — variables encriptadas a nivel repo, environment y org
## Anatomía de un workflow
```yaml
# .github/workflows/ci.yml
name: CI # Nombre del workflow
on: # Triggers
push:
branches: [main]
pull_request:
branches: [main]
permissions: # Permisos del GITHUB_TOKEN
contents: read
env: # Variables globales
NODE_VERSION: 20
jobs: # Uno o más jobs
build:
runs-on: ubuntu-latest # Runner
steps:
- uses: actions/checkout@v4 # Action reutilizable
- uses: actions/setup-node@v4
with:
node-version: ${{ env.NODE_VERSION }}
cache: 'pnpm'
- run: pnpm install # Comando shell
- run: pnpm test
- run: pnpm build
```
## Triggers principales
```yaml
on:
# Push y PRs
push:
branches: [main, 'release/**']
paths: ['src/**', 'package.json'] # solo si estos archivos cambian
pull_request:
types: [opened, synchronize, reopened]
# Programado (cron UTC)
schedule:
- cron: '0 6 * * 1' # lunes a las 6:00 UTC
# Manual desde UI o API
workflow_dispatch:
inputs:
environment:
description: 'Deploy target'
required: true
type: choice
options: [staging, production]
# Cuando se publica un release
release:
types: [published]
# Cuando otro workflow termina
workflow_run:
workflows: [CI]
types: [completed]
```
## Jobs y dependencias
```yaml
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: pnpm lint
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: pnpm test
# Deploy solo si lint y test pasan
deploy:
needs: [lint, test]
if: github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
steps:
- run: ./deploy.sh
```
## Matrix strategy
Testear en múltiples combinaciones:
```yaml
jobs:
test:
strategy:
matrix:
os: [ubuntu-latest, macos-latest, windows-latest]
node: [18, 20, 22]
fail-fast: false # no cancelar otros si uno falla
runs-on: ${{ matrix.os }}
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node }}
- run: npm test
```
## Secrets y variables
```yaml
jobs:
deploy:
runs-on: ubuntu-latest
environment: production # environment con protecciones
steps:
- run: ./deploy.sh
env:
API_KEY: ${{ secrets.API_KEY }}
DEPLOY_URL: ${{ vars.DEPLOY_URL }}
```
Niveles de secrets:
- **Repository** — disponibles en todos los workflows del repo
- **Environment** — requieren aprobación y tienen reglas de protección
- **Organization** — compartidos entre repos de la org
## Caching
```yaml
- uses: actions/cache@v4
with:
path: |
~/.pnpm-store
node_modules
key: ${{ runner.os }}-pnpm-${{ hashFiles('pnpm-lock.yaml') }}
restore-keys: |
${{ runner.os }}-pnpm-
```
## Artifacts
Compartir archivos entre jobs o descargar después:
```yaml
- uses: actions/upload-artifact@v4
with:
name: build-output
path: dist/
retention-days: 7
# En otro job:
- uses: actions/download-artifact@v4
with:
name: build-output
```
## Reusable workflows
Definir workflows que otros repos pueden llamar:
```yaml
# .github/workflows/reusable-deploy.yml
on:
workflow_call:
inputs:
environment:
required: true
type: string
secrets:
deploy_key:
required: true
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- run: echo "Deploying to ${{ inputs.environment }}"
```
```yaml
# Llamar desde otro workflow
jobs:
deploy:
uses: org/repo/.github/workflows/reusable-deploy.yml@main
with:
environment: production
secrets:
deploy_key: ${{ secrets.DEPLOY_KEY }}
```
## Composite actions
Crear actions propias combinando steps:
```yaml
# .github/actions/setup-project/action.yml
name: Setup Project
description: Install dependencies and build
runs:
using: composite
steps:
- uses: actions/setup-node@v4
with:
node-version: 20
cache: 'pnpm'
- run: pnpm install --frozen-lockfile
shell: bash
- run: pnpm build
shell: bash
```
## Seguridad
```yaml
# Principio de mínimo privilegio
permissions:
contents: read
pull-requests: write
# Pinear actions por SHA (no por tag)
- uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
# Limitar permisos del GITHUB_TOKEN por defecto
# Settings → Actions → General → Workflow permissions → Read repository contents
```
## Costos y límites
| Plan | Minutos/mes | Storage |
|------|-------------|---------|
| Free | 2,000 | 500 MB |
| Team | 3,000 | 2 GB |
| Enterprise | 50,000 | 50 GB |
Repos públicos: minutos ilimitados en runners Linux.
## Anti-patrones
- **Workflows monolíticos** — un YAML de 500 líneas. Dividir en reusable workflows.
- **Sin caché** — reinstalar dependencias en cada run desperdicia minutos.
- **Secrets en logs** — `echo $SECRET` los expone. GitHub los enmascara pero no confiar ciegamente.
- **Tags mutables en actions** — `@v4` puede cambiar. Pinear por SHA para seguridad.
- **Sin timeout** — jobs que cuelgan consumen minutos. Siempre definir `timeout-minutes`.
## ¿Por qué importa?
GitHub Actions eliminó la necesidad de mantener un servidor de CI separado para la mayoría de los proyectos. Al vivir junto al código, los workflows son versionados, revisados en PRs y ejecutados sin configuración externa. Para proyectos open source, los minutos gratuitos lo hacen la opción por defecto.
## Referencias
- [GitHub Actions Documentation](https://docs.github.com/en/actions) — GitHub, 2024. Documentación oficial completa.
- [GitHub Actions Marketplace](https://github.com/marketplace?type=actions) — GitHub, 2024. Catálogo de actions reutilizables.
- [Security Hardening for GitHub Actions](https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions) — GitHub, 2024. Guía oficial de seguridad.
- [Awesome Actions](https://github.com/sdras/awesome-actions) — Sarah Drasner, 2024. Colección curada de actions por categoría.
- [GitHub Actions: The Full Course](https://www.youtube.com/watch?v=R8_veQiYBjI) — Fireship, 2023. Introducción visual en 100 segundos + tutorial.
---
# GitFlow
Type: concept
Status: evergreen
Summary: Branching model for Git proposed by Vincent Driessen in 2010. Defines branches with fixed roles (main, develop, feature, release, hotfix) for managing structured releases.
Concepts: git, github, github-flow
**GitFlow** es un modelo de branching que asigna roles específicos a las ramas y define cómo y cuándo interactúan. Fue propuesto por Vincent Driessen en 2010 y se convirtió en el estándar para equipos con releases programados.
## ¿Cómo funciona?
### Ramas permanentes
- **`main`** — siempre refleja el código en producción. Cada commit es un release.
- **`develop`** — rama de integración. Aquí se acumulan features terminados para el próximo release.
### Ramas temporales
- **`feature/*`** — una por feature, nace de `develop`, se mergea de vuelta a `develop`
- **`release/*`** — preparación del release, nace de `develop`, se mergea a `main` y `develop`
- **`hotfix/*`** — corrección urgente en producción, nace de `main`, se mergea a `main` y `develop`
### Flujo visual
```
main: ──●──────────────────●──────────●──
\ / \ / \
release: \ ──●──● \ / \
\ / \ / \
develop: ──●────●────●────●───●───●──●───●───●──
\ / \ /
feature: ●──●──● ●──●──●
```
## Ejemplo completo
```bash
# 1. Iniciar un feature
git checkout develop
git checkout -b feature/user-auth
# ... trabajar, hacer commits ...
git commit -m "feat: add login form"
git commit -m "feat: add JWT validation"
# 2. Terminar el feature
git checkout develop
git merge --no-ff feature/user-auth
git branch -d feature/user-auth
# 3. Preparar release
git checkout develop
git checkout -b release/1.2.0
# ... solo bug fixes y preparación ...
git commit -m "fix: typo in login page"
git commit -m "chore: bump version to 1.2.0"
# 4. Publicar release
git checkout main
git merge --no-ff release/1.2.0
git tag -a v1.2.0 -m "Release 1.2.0"
git checkout develop
git merge --no-ff release/1.2.0
git branch -d release/1.2.0
# 5. Hotfix urgente
git checkout main
git checkout -b hotfix/1.2.1
git commit -m "fix: critical security vulnerability"
git checkout main
git merge --no-ff hotfix/1.2.1
git tag -a v1.2.1 -m "Hotfix 1.2.1"
git checkout develop
git merge --no-ff hotfix/1.2.1
git branch -d hotfix/1.2.1
```
## ¿Cuándo usarlo?
**Buena opción cuando:**
- Releases programados (cada 2 semanas, mensual, etc.)
- Múltiples versiones en producción simultáneamente
- Equipo grande con features paralelos que necesitan integración controlada
- Software con ciclo QA formal antes de cada release
- Productos con soporte a largo plazo (LTS)
**Evitar cuando:**
- Continuous deployment — si haces deploy varias veces al día, GitFlow agrega fricción innecesaria
- Equipo pequeño (1-5 personas) — la ceremonia no justifica el overhead
- Aplicaciones web con un solo entorno de producción
- Proyectos que priorizan velocidad sobre control
## Alternativas
### GitHub Flow
Modelo simplificado: solo `main` + feature branches. Ideal para continuous deployment.
```
main: ──●────●────●────●──
\ / \ /
feature: ● ●
```
1. Crear rama desde `main`
2. Hacer commits
3. Abrir PR
4. Review + CI
5. Merge a `main`
6. Deploy
### Trunk-Based Development
Todos trabajan en `main` (o ramas de vida muy corta). Requiere feature flags y CI robusto.
```
main: ──●──●──●──●──●──●──●──
```
- Commits directos a `main` o ramas que viven < 1 día
- Feature flags para código incompleto
- Releases por tags o desde `main` directamente
### Comparación
| Aspecto | GitFlow | GitHub Flow | Trunk-Based |
|---------|---------|-------------|-------------|
| Complejidad | Alta | Baja | Baja |
| Ramas permanentes | 2 (main, develop) | 1 (main) | 1 (main) |
| Releases | Programados | Continuos | Continuos |
| Ideal para | Enterprise, versioned software | SaaS, web apps | Equipos maduros con CI fuerte |
| Overhead | Alto | Bajo | Mínimo |
## Herramientas
```bash
# git-flow CLI (extensión oficial)
brew install git-flow-avh
# Inicializar en un repo
git flow init
# Usar comandos simplificados
git flow feature start user-auth
git flow feature finish user-auth
git flow release start 1.2.0
git flow release finish 1.2.0
git flow hotfix start 1.2.1
git flow hotfix finish 1.2.1
```
## Anti-patrones
- **Develop eternamente divergente de main** — si develop y main divergen mucho, los merges son dolorosos
- **Feature branches de larga vida** — ramas que viven semanas acumulan conflictos
- **Saltarse release branches** — mergear features directo a main rompe el modelo
- **No eliminar ramas terminadas** — acumulación de ramas muertas dificulta la navegación
## ¿Por qué importa?
Entender GitFlow sigue siendo relevante porque muchos equipos lo usan y porque sus limitaciones enseñan por qué la industria migró hacia modelos más simples. Saber cuándo GitFlow es apropiado — y cuándo no — es una decisión arquitectónica que afecta la velocidad de entrega de todo el equipo.
## Referencias
- [A Successful Git Branching Model](https://nvie.com/posts/a-successful-git-branching-model/) — Vincent Driessen, 2010. El post original que definió GitFlow.
- [Note of Reflection (2020)](https://nvie.com/posts/a-successful-git-branching-model/) — Vincent Driessen, 2020. El propio autor reconoce que GitFlow no es ideal para continuous delivery.
- [GitHub Flow](https://docs.github.com/en/get-started/using-github/github-flow) — GitHub, 2024. Documentación oficial del modelo simplificado.
- [Trunk-Based Development](https://trunkbaseddevelopment.com/) — Paul Hammant, 2024. Referencia completa del modelo trunk-based.
---
# Git
Type: concept
Status: evergreen
Summary: Distributed version control system created by Linus Torvalds in 2005. Foundation of every modern development workflow — from local commits to global collaboration.
Concepts: monorepos, github, gitflow, github-flow
**Git** es un sistema de control de versiones distribuido donde cada clon es un repositorio completo con historial total. No depende de un servidor central para funcionar — puedes hacer commits, branches y merges completamente offline.
## ¿Por qué importa?
Git es la infraestructura invisible sobre la que se construye todo el desarrollo de software moderno. Cada desarrollador tiene una copia completa del historial, branching y merging son operaciones de milisegundos, y la integridad criptográfica garantiza que cada commit verifica todo su contenido y ancestros. GitHub, GitLab, Bitbucket y Azure DevOps — todos están construidos sobre Git. Entender su modelo interno (objetos, refs, DAG de commits) es lo que separa a quien usa Git de quien realmente lo domina.
## Modelo mental
```
Working Directory → Staging Area (Index) → Local Repository → Remote Repository
edit git add git commit git push
```
Los tres árboles de Git:
1. **Working tree** — los archivos que ves en disco
2. **Index (staging area)** — lo que irá en el próximo commit
3. **HEAD** — el último commit de la rama actual
## Comandos esenciales con ejemplos
### Configuración inicial
```bash
# Identidad (obligatorio antes del primer commit)
git config --global user.name "Tu Nombre"
git config --global user.email "tu@email.com"
# Editor por defecto
git config --global core.editor "code --wait"
# Ver toda la configuración activa
git config --list --show-origin
# Alias útiles
git config --global alias.st status
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.lg "log --oneline --graph --all --decorate"
```
### Crear y clonar
```bash
# Nuevo repositorio
git init mi-proyecto
cd mi-proyecto
# Clonar existente
git clone https://github.com/user/repo.git
# Clonar solo la última revisión (rápido para CI)
git clone --depth 1 https://github.com/user/repo.git
# Clonar rama específica
git clone -b develop https://github.com/user/repo.git
```
### Staging y commits
```bash
# Ver estado actual
git status
git status -s # formato corto
# Agregar archivos al staging
git add archivo.ts # archivo específico
git add src/ # directorio completo
git add -A # todo (nuevos, modificados, eliminados)
git add -p # interactivo: elegir hunks individuales
# Quitar del staging (sin perder cambios)
git restore --staged archivo.ts # Git 2.23+
git reset HEAD archivo.ts # forma clásica
# Commit
git commit -m "feat: add user authentication"
git commit -am "fix: typo in header" # add + commit (solo tracked files)
git commit --amend # modificar último commit
git commit --amend --no-edit # mismo mensaje, agregar archivos olvidados
git commit --allow-empty -m "trigger CI" # commit vacío
```
### Branches
```bash
# Listar ramas
git branch # locales
git branch -r # remotas
git branch -a # todas
git branch -v # con último commit
# Crear y cambiar
git branch feature/login
git checkout feature/login
git checkout -b feature/login # crear + cambiar en un paso
git switch -c feature/login # Git 2.23+ (preferido)
# Renombrar
git branch -m viejo-nombre nuevo-nombre
git branch -m nuevo-nombre # renombrar la rama actual
# Eliminar
git branch -d feature/login # solo si ya fue mergeada
git branch -D feature/login # forzar eliminación
git push origin --delete feature/login # eliminar rama remota
```
### Merge y rebase
```bash
# Merge: incorporar cambios de otra rama
git checkout main
git merge feature/login # merge commit (no fast-forward si divergen)
git merge --no-ff feature/login # forzar merge commit (útil para historial)
git merge --squash feature/login # aplastar todos los commits en uno
git merge --abort # cancelar merge con conflictos
# Rebase: reescribir historial sobre otra rama
git checkout feature/login
git rebase main # mover commits encima de main
git rebase -i HEAD~3 # rebase interactivo (últimos 3 commits)
git rebase --abort # cancelar rebase
git rebase --continue # después de resolver conflictos
# Rebase interactivo — opciones por commit:
# pick = usar commit tal cual
# reword = cambiar mensaje
# edit = pausar para modificar
# squash = combinar con el anterior
# fixup = combinar sin mensaje
# drop = eliminar commit
```
### Inspección del historial
```bash
# Log básico
git log
git log --oneline # una línea por commit
git log --oneline --graph --all # grafo visual de todas las ramas
git log --since="2 weeks ago"
git log --author="nombre"
git log -- archivo.ts # historial de un archivo
git log -p -- archivo.ts # con diffs
# Buscar en el historial
git log --grep="fix" # commits cuyo mensaje contiene "fix"
git log -S "functionName" # commits que agregaron/eliminaron ese texto
git log -G "regex" # búsqueda por regex en diffs
# Diferencias
git diff # working tree vs staging
git diff --staged # staging vs último commit
git diff main..feature/login # entre dos ramas
git diff HEAD~3..HEAD # últimos 3 commits
git diff --stat # resumen de archivos cambiados
git diff --name-only # solo nombres de archivos
# Quién escribió cada línea
git blame archivo.ts
git blame -L 10,20 archivo.ts # solo líneas 10-20
# Mostrar un commit específico
git show abc1234
git show HEAD~2:archivo.ts # archivo en un commit anterior
```
### Stash
```bash
# Guardar cambios temporalmente
git stash # stash con mensaje automático
git stash push -m "work in progress" # con mensaje descriptivo
git stash push -p # stash interactivo (elegir hunks)
git stash --include-untracked # incluir archivos nuevos
# Recuperar
git stash pop # aplicar y eliminar del stash
git stash apply # aplicar sin eliminar
git stash apply stash@{2} # aplicar un stash específico
# Gestionar
git stash list # ver todos los stashes
git stash show -p stash@{0} # ver contenido de un stash
git stash drop stash@{0} # eliminar un stash
git stash clear # eliminar todos
```
### Remotos
```bash
# Ver remotos configurados
git remote -v
# Agregar remoto
git remote add upstream https://github.com/original/repo.git
# Traer cambios sin merge
git fetch origin
git fetch --all # de todos los remotos
git fetch --prune # eliminar refs de ramas remotas borradas
# Traer y merge
git pull # fetch + merge
git pull --rebase # fetch + rebase (historial lineal)
git pull --rebase --autostash # stash automático antes de rebase
# Enviar cambios
git push origin main
git push -u origin feature/login # push + set upstream
git push --force-with-lease # force push seguro (verifica que nadie más pusheó)
git push origin --tags # enviar todos los tags
```
### Deshacer cambios
```bash
# Descartar cambios en working tree
git restore archivo.ts # Git 2.23+
git checkout -- archivo.ts # forma clásica
# Deshacer último commit (mantener cambios)
git reset --soft HEAD~1 # cambios quedan en staging
git reset --mixed HEAD~1 # cambios quedan en working tree (default)
git reset --hard HEAD~1 # ⚠️ eliminar cambios completamente
# Revertir un commit (crea nuevo commit inverso — seguro para ramas compartidas)
git revert abc1234
git revert HEAD # revertir último commit
git revert --no-commit HEAD~3..HEAD # revertir rango sin commits individuales
# Recuperar commits «perdidos»
git reflog # historial de movimientos de HEAD
git checkout abc1234 # ir a un commit del reflog
git branch recovery abc1234 # crear rama desde commit recuperado
```
### Tags
```bash
# Crear
git tag v1.0.0 # tag ligero
git tag -a v1.0.0 -m "Release 1.0.0" # tag anotado (recomendado)
git tag -a v1.0.0 abc1234 # tag en commit específico
# Listar y ver
git tag
git tag -l "v1.*" # filtrar por patrón
git show v1.0.0
# Publicar
git push origin v1.0.0 # un tag
git push origin --tags # todos los tags
# Eliminar
git tag -d v1.0.0 # local
git push origin --delete v1.0.0 # remoto
```
### Cherry-pick y bisect
```bash
# Aplicar un commit específico a la rama actual
git cherry-pick abc1234
git cherry-pick abc1234 def5678 # múltiples commits
git cherry-pick --no-commit abc1234 # aplicar sin commit
# Encontrar el commit que introdujo un bug (búsqueda binaria)
git bisect start
git bisect bad # el commit actual tiene el bug
git bisect good v1.0.0 # este commit estaba bien
# Git te lleva a commits intermedios — marcas good/bad hasta encontrar el culpable
git bisect reset # volver al estado normal
# Bisect automático con un script de test
git bisect start HEAD v1.0.0
git bisect run npm test
```
### Limpieza y mantenimiento
```bash
# Eliminar archivos no rastreados
git clean -n # dry run (ver qué se eliminaría)
git clean -fd # eliminar archivos y directorios
git clean -fdx # incluir archivos ignorados por .gitignore
# Optimizar repositorio
git gc # garbage collection
git gc --aggressive # compresión más agresiva
# Verificar integridad
git fsck
```
## .gitignore
```gitignore
# Patrones comunes
node_modules/
dist/
.env
.env.local
*.log
.DS_Store
.next/
coverage/
```
Regla clave: **nunca commitear secretos**. Si un secreto llega al historial, rotarlo inmediatamente — `git filter-branch` o BFG Repo-Cleaner pueden eliminarlo del historial, pero asume que ya fue comprometido.
## Referencias
- [Pro Git Book](https://git-scm.com/book/en/v2) — Scott Chacon & Ben Straub, 2014. El libro definitivo, gratuito y oficial.
- [Git Reference](https://git-scm.com/docs) — Git Project. Documentación oficial de cada comando.
- [Oh Shit, Git!?!](https://ohshitgit.com/) — Katie Sylor-Miller. Guía práctica para salir de situaciones comunes.
- [Atlassian Git Tutorials](https://www.atlassian.com/git/tutorials) — Atlassian, 2024. Tutoriales visuales con explicaciones claras.
- [Git Flight Rules](https://github.com/k88hudson/git-flight-rules) — Kate Hudson, 2023. Recetas para escenarios específicos estilo «flight rules» de la NASA.
---
# Function Calling
Type: concept
Status: seed
Summary: LLM capability to generate structured calls to external functions based on natural language, enabling integration with APIs, databases, and real-world tools.
Concepts: ai-agents, mcp, large-language-models
## ¿Qué es?
Function calling es la capacidad de un [LLM](/concepts/large-language-models) para decidir cuándo invocar una función externa y generar los argumentos necesarios en formato estructurado (típicamente JSON). El modelo no ejecuta la función — genera la especificación de la llamada que el sistema anfitrión ejecuta.
Esta capacidad transforma a los LLMs de generadores de texto a orquestadores de acciones.
## ¿Cómo funciona?
1. **Definición**: se le proporciona al modelo un esquema de funciones disponibles (nombre, descripción, parámetros)
2. **Decisión**: ante una consulta, el modelo decide si necesita llamar una función o responder directamente
3. **Generación**: si decide llamar, genera JSON con el nombre de la función y argumentos
4. **Ejecución**: el sistema anfitrión ejecuta la función real
5. **Continuación**: el resultado se devuelve al modelo para que formule la respuesta final
## Ejemplo de flujo
```
Usuario: "¿Qué clima hace en Madrid?"
Modelo genera:
{
"function": "get_weather",
"arguments": { "city": "Madrid", "units": "celsius" }
}
Sistema ejecuta get_weather("Madrid", "celsius") → "18°C, parcialmente nublado"
Modelo responde: "En Madrid hace 18°C con cielo parcialmente nublado."
```
## Relación con MCP
El [Model Context Protocol](/concepts/mcp) estandariza cómo los modelos descubren y llaman herramientas. Function calling es el mecanismo subyacente; MCP es el protocolo que lo hace interoperable entre diferentes sistemas.
## Patrones de uso
- **Herramientas simples**: calculadora, conversión de unidades, fecha/hora
- **APIs externas**: clima, búsqueda, bases de datos
- **Acciones del sistema**: crear archivos, enviar emails, ejecutar código
- **Llamadas paralelas**: múltiples funciones en una sola respuesta
- **Llamadas encadenadas**: el resultado de una función alimenta la siguiente
## Consideraciones
- **Validación**: siempre validar los argumentos generados antes de ejecutar
- **Seguridad**: limitar qué funciones están disponibles según el contexto
- **Manejo de errores**: el modelo debe poder interpretar y recuperarse de errores
- **Descripciones claras**: la calidad de las descripciones de funciones afecta directamente la precisión
## ¿Por qué importa?
Function calling es el mecanismo que convierte a los LLMs de generadores de texto en agentes que interactúan con el mundo real. Sin él, los modelos solo pueden responder con texto. Con él, pueden consultar bases de datos, llamar APIs y ejecutar acciones concretas.
## Referencias
- [Function Calling - OpenAI](https://platform.openai.com/docs/guides/function-calling) — Documentación oficial de OpenAI.
- [Tool Use - Anthropic](https://docs.anthropic.com/en/docs/build-with-claude/tool-use) — Guía de uso de herramientas con Claude.
- [Function Calling — Gemini](https://ai.google.dev/gemini-api/docs/function-calling) — Google, 2024. Implementación de function calling en Gemini.
---
# Fine-Tuning
Type: concept
Status: seed
Summary: Process of specializing a pre-trained model for a specific task or domain through additional training with curated data, adapting its behavior without starting from scratch.
Concepts: large-language-models, artificial-intelligence, synthetic-data
## ¿Qué es?
Fine-tuning es el proceso de tomar un [modelo de lenguaje](/concepts/large-language-models) pre-entrenado y entrenarlo adicionalmente con datos específicos para adaptarlo a una tarea, dominio o estilo particular. En lugar de entrenar desde cero (costoso e impráctico), se aprovecha el conocimiento general del modelo base y se especializa.
## ¿Cuándo usar fine-tuning vs RAG?
| Escenario | Mejor opción |
|-----------|--------------|
| Conocimiento factual actualizable | [RAG](/concepts/retrieval-augmented-generation) |
| Estilo de escritura específico | Fine-tuning |
| Formato de salida consistente | Fine-tuning |
| Datos que cambian frecuentemente | RAG |
| Terminología de dominio | Fine-tuning + RAG |
## Técnicas de fine-tuning
### Full fine-tuning
Actualiza todos los parámetros del modelo. Produce los mejores resultados pero requiere:
- GPUs con mucha memoria
- Datasets grandes (miles de ejemplos)
- Riesgo de «olvido catastrófico» del conocimiento base
### LoRA (Low-Rank Adaptation)
Congela el modelo base y entrena pequeñas matrices de adaptación. Ventajas:
- 10-100x menos parámetros entrenables
- Múltiples adaptadores para diferentes tareas
- Fácil de compartir y combinar
### QLoRA
LoRA sobre un modelo cuantizado (4-bit). Permite fine-tuning de modelos grandes en hardware consumer.
### RLHF (Reinforcement Learning from Human Feedback)
Alinea el modelo con preferencias humanas usando un modelo de recompensa entrenado con comparaciones humanas. Es como se entrenan Claude, GPT-4 y otros modelos de chat.
## Proceso típico
1. **Preparar datos**: pares de entrada/salida en el formato deseado
2. **Elegir modelo base**: balance entre capacidad y costo
3. **Configurar entrenamiento**: learning rate, epochs, batch size
4. **Entrenar**: monitorear loss y métricas de validación
5. **Evaluar**: probar en casos de uso reales
6. **Iterar**: ajustar datos o hiperparámetros según resultados
## Consideraciones
- **Calidad > cantidad**: 100 ejemplos excelentes superan a 10,000 mediocres
- **Formato consistente**: el modelo aprende patrones — mantener estructura uniforme
- **Evaluación rigurosa**: es fácil sobreajustar a los datos de entrenamiento
- **Costo de mantenimiento**: cada actualización requiere reentrenar
## ¿Por qué importa?
El fine-tuning permite adaptar un modelo general a un dominio específico con datos propios. Es la técnica que convierte un LLM genérico en un experto en tu terminología, formato de respuesta y casos de uso particulares — cuando el prompting no es suficiente.
## Referencias
- [LoRA: Low-Rank Adaptation of Large Language Models](https://arxiv.org/abs/2106.09685) — Hu et al., 2021.
- [QLoRA: Efficient Finetuning of Quantized LLMs](https://arxiv.org/abs/2305.14314) — Dettmers et al., 2023.
- [Hugging Face Training](https://huggingface.co/docs/transformers/en/training) — Hugging Face, 2024. Guía práctica de fine-tuning con Transformers.
---
# Feature Flags
Type: concept
Status: seed
Summary: Technique enabling activation or deactivation of features in production without deploying new code, enabling progressive releases and experimentation.
Concepts: ci-cd, platform-engineering
## ¿Qué es?
Feature flags (o feature toggles) son condicionales en el código que permiten activar o desactivar funcionalidades sin desplegar. Separan el despliegue de código del release de features.
## Tipos
| Tipo | Duración | Uso |
|------|----------|-----|
| Release | Temporal | Activar feature gradualmente |
| Experiment | Temporal | A/B testing |
| Ops | Permanente | Circuit breakers, kill switches |
| Permission | Permanente | Features por plan/rol |
## Beneficios
- Desplegar código sin activar features
- Rollback instantáneo (desactivar flag)
- Canary releases (activar para % de usuarios)
- A/B testing en producción
## Herramientas
- LaunchDarkly, Split.io (SaaS)
- Unleash, Flagsmith (open-source)
- AWS AppConfig, CloudWatch Evidently
## Riesgos
- Deuda técnica: flags que nunca se limpian
- Complejidad: combinaciones de flags difíciles de testear
- Inconsistencia: estado diferente entre usuarios
## ¿Por qué importa?
Los feature flags desacoplan el deploy del release. Permiten desplegar código a producción sin activarlo para los usuarios, habilitar funcionalidades gradualmente y revertir cambios sin rollback de código. Son la red de seguridad que hace posible el continuous deployment.
## Referencias
- [Feature Toggles](https://martinfowler.com/articles/feature-toggles.html) — Pete Hodgson, Martin Fowler.
- [LaunchDarkly](https://launchdarkly.com/) — LaunchDarkly, 2024. Plataforma líder de feature management.
- [OpenFeature](https://openfeature.dev/) — CNCF, 2024. Estándar abierto para feature flags.
---
# Event Sourcing
Type: concept
Status: seed
Summary: Pattern where application state is derived from an immutable sequence of events, providing complete audit trail and the ability to reconstruct state at any point in time.
Concepts: cqrs, event-driven-architecture
## ¿Qué es?
Event sourcing almacena el estado como una secuencia de eventos inmutables en lugar de solo el estado actual. Para conocer el estado actual, se reproducen todos los eventos desde el inicio. Cada evento representa algo que ocurrió y no puede modificarse.
## Estado tradicional vs Event Sourcing
| Tradicional | Event Sourcing |
|-------------|----------------|
| Almacena estado actual | Almacena eventos |
| UPDATE sobrescribe | Append-only |
| Sin historial | Historial completo |
| Un modelo | Múltiples proyecciones |
## Ejemplo
```
Evento 1: CuentaCreada { id: 123, titular: "Ana" }
Evento 2: DepósitoRealizado { id: 123, monto: 1000 }
Evento 3: RetiroRealizado { id: 123, monto: 200 }
Estado actual: { id: 123, titular: "Ana", saldo: 800 }
```
## Beneficios
- Auditoría completa e inmutable
- Reconstruir estado en cualquier punto del tiempo
- Múltiples proyecciones de los mismos eventos
- Debugging: reproducir exactamente qué pasó
## Desafíos
- Evolución de schemas de eventos
- Performance con muchos eventos (snapshots)
- Complejidad conceptual
## ¿Por qué importa?
Event sourcing almacena cada cambio de estado como un evento inmutable, proporcionando una auditoría completa y la capacidad de reconstruir el estado en cualquier punto del tiempo. Es especialmente valioso en dominios financieros, legales y de compliance donde la trazabilidad es obligatoria.
## Referencias
- [Event Sourcing](https://martinfowler.com/eaaDev/EventSourcing.html) — Martin Fowler.
- [Event Store](https://www.eventstore.com/) — Event Store, 2024. Base de datos diseñada para event sourcing.
- [Event Sourcing Pattern — Azure](https://learn.microsoft.com/en-us/azure/architecture/patterns/event-sourcing) — Microsoft, 2024. Guía de implementación del patrón.
---
# Event-Driven Architecture
Type: concept
Status: seed
Summary: Architectural pattern where components communicate through asynchronous events, enabling decoupled, scalable, and reactive systems.
Concepts: serverless, aws-eventbridge
## ¿Qué es?
La arquitectura orientada a eventos es un patrón donde los componentes producen y consumen eventos de forma asíncrona. Un evento representa algo que ocurrió — un pedido creado, un archivo subido, un usuario registrado. Los productores no saben quién consume sus eventos; los consumidores no saben quién los produce.
## Componentes
- **Evento**: registro inmutable de algo que ocurrió
- **Productor**: componente que emite eventos
- **Consumidor**: componente que reacciona a eventos
- **Broker/Bus**: infraestructura que enruta eventos
## Patrones
- **Event notification**: notificar que algo ocurrió (sin datos completos)
- **Event-carried state transfer**: el evento contiene todos los datos necesarios
- **Event sourcing**: el estado se deriva de la secuencia de eventos
- **CQRS**: separar lecturas de escrituras usando eventos
## Comparación de brokers
| Broker | Modelo | Ordenamiento | Retención | Caso de uso |
|--------|--------|-------------|-----------|-------------|
| [AWS SQS](/concepts/aws-sqs) | Cola (point-to-point) | FIFO opcional | 14 días máx | Desacoplamiento simple entre servicios |
| [AWS SNS](/concepts/aws-sns) | Pub/sub (fan-out) | No garantizado | Sin retención | Notificaciones a múltiples suscriptores |
| [AWS EventBridge](/concepts/aws-eventbridge) | Bus de eventos | Por partición | 24h replay | Routing basado en contenido, integración SaaS |
| Apache Kafka | Log distribuido | Por partición | Configurable | Streaming de alto volumen, event sourcing |
| RabbitMQ | Cola con exchanges | Por cola | Configurable | Routing complejo, protocolos múltiples |
## Beneficios
- **Desacoplamiento**: productores y consumidores evolucionan independientemente
- **Escalabilidad**: agregar consumidores sin modificar productores
- **Resiliencia**: fallos aislados, reintentos automáticos
- **Auditabilidad**: historial completo de eventos
## Desafíos
- Consistencia eventual (no inmediata)
- Debugging más complejo (flujos distribuidos)
- Ordenamiento de eventos
- Idempotencia en consumidores
## ¿Por qué importa?
Las arquitecturas event-driven desacoplan servicios en el tiempo y el espacio. Un servicio publica un evento sin saber quién lo consume, lo que permite escalar, modificar y reemplazar componentes de forma independiente. Es el patrón que habilita sistemas verdaderamente modulares.
## Referencias
- [What do you mean by Event-Driven?](https://martinfowler.com/articles/201701-event-driven.html) — Martin Fowler, 2017.
- [AsyncAPI](https://www.asyncapi.com/) — AsyncAPI Initiative, 2024. Especificación para APIs asíncronas y event-driven.
- [EventBridge Documentation](https://docs.aws.amazon.com/eventbridge/) — AWS, 2024. Servicio de bus de eventos serverless.
---
# AI Evaluation Metrics
Type: concept
Status: seed
Summary: Frameworks and metrics for measuring AI system performance, quality, and safety, from standard benchmarks to domain-specific evaluations.
Concepts: artificial-intelligence, maturity-models, ai-observability
## ¿Qué es?
Evaluar sistemas de [IA](/concepts/artificial-intelligence) es fundamentalmente diferente a evaluar software tradicional. No hay una respuesta «correcta» única — la calidad es subjetiva, contextual y multidimensional. Las métricas de evaluación proporcionan frameworks para medir qué tan bien funciona un sistema de IA en diferentes dimensiones.
## Dimensiones de evaluación
### Calidad de respuesta
- **Relevancia**: ¿la respuesta aborda la pregunta?
- **Precisión factual**: ¿los hechos son correctos?
- **Completitud**: ¿cubre todos los aspectos relevantes?
- **Coherencia**: ¿es lógica y bien estructurada?
### Benchmarks estándar
| Benchmark | Mide |
|-----------|------|
| MMLU | Conocimiento general multitarea |
| HumanEval | Generación de código |
| GSM8K | Razonamiento matemático |
| TruthfulQA | Veracidad y resistencia a mitos |
| MT-Bench | Calidad conversacional |
### Evaluación de RAG
- **Faithfulness**: fidelidad al contexto recuperado
- **Answer relevancy**: relevancia de la respuesta a la pregunta
- **Context precision**: precisión del contexto recuperado
- **Context recall**: cobertura del contexto necesario
### Evaluación de agentes
- **Task completion rate**: porcentaje de tareas completadas exitosamente
- **Efficiency**: pasos/tokens necesarios para completar la tarea
- **Tool selection accuracy**: selección correcta de herramientas
- **Error recovery**: capacidad de recuperarse de errores
## Métodos de evaluación
- **Automática**: métricas computables (BLEU, ROUGE, BERTScore)
- **LLM-as-judge**: usar un LLM para evaluar las respuestas de otro
- **Humana**: evaluadores humanos califican respuestas
- **A/B testing**: comparar sistemas en producción con usuarios reales
## Frameworks
- **RAGAS**: evaluación de pipelines RAG
- **DeepEval**: evaluación de LLMs con métricas predefinidas
- **Promptfoo**: testing de prompts con assertions
## ¿Por qué importa?
Sin métricas de evaluación rigurosas, es imposible saber si un sistema de IA está mejorando o degradándose. Los benchmarks genéricos no capturan el rendimiento en tu dominio específico — las evaluaciones custom son lo que separa los sistemas de IA confiables de los que alucinan sin que nadie lo detecte.
## Referencias
- [Judging LLM-as-a-Judge](https://arxiv.org/abs/2306.05685) — Zheng et al., 2023.
- [RAGAS: Automated Evaluation of RAG](https://arxiv.org/abs/2309.15217) — Es et al., 2023.
- [A Survey on Evaluation of LLMs](https://arxiv.org/abs/2307.03025) — Chang et al., 2023. Survey completo de métricas de evaluación para LLMs.
---
# Embeddings
Type: concept
Status: seed
Summary: Dense vector representations that capture the semantic meaning of text, images, or other data in a numerical space where proximity reflects conceptual similarity.
Concepts: neural-networks, semantic-search, large-language-models
## ¿Qué es?
Un embedding es una representación numérica de un dato — texto, imagen, audio — en forma de vector denso de dimensión fija. La propiedad fundamental es que datos semánticamente similares producen vectores cercanos en el espacio, mientras que datos diferentes quedan distantes.
Por ejemplo, los embeddings de «perro» y «cachorro» estarán cerca, mientras que «perro» y «economía» estarán lejos. Esto permite a las máquinas operar con «significado» de forma matemática.
## ¿Cómo funcionan?
### Generación
Un modelo de embeddings (como `text-embedding-3-small` de OpenAI o `all-MiniLM-L6-v2` de Sentence Transformers) toma un texto de entrada y produce un vector de dimensión fija — típicamente entre 384 y 3072 dimensiones.
El modelo aprende estas representaciones durante el entrenamiento, optimizando para que textos con significado similar produzcan vectores cercanos.
### Métricas de similitud
Para comparar embeddings se usan métricas de distancia:
- **Similitud coseno**: mide el ángulo entre vectores (la más común)
- **Producto punto**: similar al coseno pero sensible a la magnitud
- **Distancia euclidiana**: distancia geométrica directa entre puntos
### Tipos de embeddings
- **Word embeddings**: un vector por palabra (Word2Vec, GloVe) — históricos pero limitados
- **Sentence embeddings**: un vector por oración o párrafo — el estándar actual
- **Multimodales**: vectores que representan texto e imágenes en el mismo espacio (CLIP)
## Aplicaciones
| Aplicación | Cómo usa embeddings | Métrica de similitud |
|------------|---------------------|---------------------|
| [Búsqueda semántica](/concepts/semantic-search) | Compara embedding de la query con embeddings de documentos | Similitud coseno |
| [RAG](/concepts/retrieval-augmented-generation) | Recupera fragmentos relevantes para dar contexto al LLM | Similitud coseno + reranking |
| Clasificación | Agrupa documentos por cercanía en el espacio vectorial | Distancia euclidiana o coseno |
| Detección de duplicados | Identifica contenido con alta similitud | Umbral de similitud (> 0.9) |
| Recomendaciones | Sugiere contenido cercano al perfil del usuario | k-nearest neighbors |
## Consideraciones prácticas
- **Dimensionalidad vs. rendimiento**: más dimensiones capturan más matices pero requieren más almacenamiento y cómputo
- **Modelo importa**: el mismo texto produce embeddings diferentes con modelos diferentes — no son intercambiables
- **Chunking**: para documentos largos, es mejor generar embeddings por fragmento que por documento completo
- **Normalización**: algunos modelos requieren normalizar los vectores antes de comparar
## ¿Por qué importa?
Los embeddings son la base de la búsqueda semántica, los sistemas RAG y la clasificación de contenido. Sin ellos, las aplicaciones de IA quedan limitadas a coincidencias exactas de texto. Entender sus propiedades — dimensionalidad, distancia coseno, limitaciones por idioma — es esencial para construir sistemas de recuperación de información efectivos.
## Referencias
- [Efficient Estimation of Word Representations in Vector Space](https://arxiv.org/abs/1301.3781) — Mikolov et al., 2013. El paper original de Word2Vec.
- [Sentence-BERT](https://arxiv.org/abs/1908.10084) — Reimers & Gurevych, 2019. Embeddings de oraciones eficientes basados en BERT.
- [Text Embeddings by Weakly-Supervised Contrastive Pre-training](https://arxiv.org/abs/2212.03533) — Wang et al., 2022. E5, embeddings de texto de propósito general.
---
# Domain-Driven Design
Type: concept
Status: seed
Summary: Software design approach centering development on the business domain, using a ubiquitous language shared between developers and domain experts.
Concepts: microservices, api-design
## ¿Qué es?
Domain-Driven Design (DDD) es un enfoque de diseño de software que prioriza el modelado del dominio del negocio. La premisa: la complejidad real está en el dominio, no en la tecnología. DDD proporciona patrones para manejar esa complejidad.
## Conceptos estratégicos
- **Bounded Context**: límite explícito donde un modelo de dominio es consistente
- **Ubiquitous Language**: vocabulario compartido entre devs y negocio
- **Context Map**: relaciones entre bounded contexts
- **Subdomain**: área del negocio (core, supporting, generic)
## Conceptos tácticos
- **Entity**: objeto con identidad única
- **Value Object**: objeto definido por sus atributos (inmutable)
- **Aggregate**: cluster de entidades con una raíz
- **Repository**: abstracción de persistencia
- **Domain Event**: algo que ocurrió en el dominio
- **Domain Service**: lógica que no pertenece a una entidad
## DDD y microservicios
Los bounded contexts de DDD mapean naturalmente a [microservicios](/concepts/microservices). Cada microservicio implementa un bounded context con su propio modelo y datos.
## Cuándo aplicar DDD
| Situación | ¿DDD? | Alternativa |
|-----------|-------|-------------|
| Dominio complejo con reglas de negocio ricas | Sí — DDD brilla aquí | — |
| CRUD simple sin lógica de negocio | No | Arquitectura en capas tradicional |
| Equipo sin acceso a expertos de dominio | Parcial — patrones tácticos sin el estratégico | — |
| Startup en exploración | No — demasiada ceremonia | Módulos simples, refactorizar después |
| Sistema legacy que se va a migrar | Sí — bounded contexts guían la descomposición | [Strangler fig](/concepts/strangler-fig-pattern) |
## Errores comunes
- **DDD sin expertos de dominio**: el lenguaje ubicuo requiere conversaciones reales con el negocio, no suposiciones del equipo técnico
- **Bounded contexts demasiado pequeños**: un bounded context no es un microservicio por defecto — puede contener múltiples servicios
- **Aggregate roots demasiado grandes**: si un aggregate tiene más de 3-4 entidades, probablemente necesita descomponerse
- **Ignorar el context map**: las relaciones entre bounded contexts (customer-supplier, conformist, anticorruption layer) son tan importantes como los contexts mismos
## ¿Por qué importa?
DDD proporciona un lenguaje para alinear el código con el dominio del negocio. En sistemas complejos, los bounded contexts definen fronteras claras entre equipos y servicios, evitando el acoplamiento que convierte los monolitos en sistemas imposibles de modificar.
## Referencias
- [Domain-Driven Design](https://www.domainlanguage.com/ddd/) — Eric Evans, 2003. El libro original.
- [Implementing Domain-Driven Design](https://www.oreilly.com/library/view/implementing-domain-driven-design/9780133039900/) — Vaughn Vernon, 2013.
- [DomainDrivenDesign](https://martinfowler.com/bliki/DomainDrivenDesign.html) — Martin Fowler, 2020. Resumen del concepto de DDD.
---
# Documentation as Code
Type: concept
Status: seed
Summary: Practice of treating documentation with the same tools and processes as code: versioned in Git, reviewed in PRs, and automatically generated when possible.
Concepts: spec-driven-development, llms-txt
## ¿Qué es?
Documentation as Code es la práctica de tratar la documentación como código: vive en el mismo repositorio, se versiona con Git, se revisa en pull requests, y se genera/valida automáticamente en CI.
## Principios
| Principio | Qué significa | Ejemplo |
|-----------|-------------|---------|
| Colocación | Docs cerca del código que documentan | README en cada paquete, JSDoc en funciones |
| Versionado | La documentación evoluciona con el código | Docs en el mismo repo, mismos PRs |
| Automatización | Generar docs de código cuando sea posible | TypeDoc, Swagger/OpenAPI, Storybook |
| Validación | Verificar links, ejemplos, formato en CI | Markdown lint, link checker en CI |
## Herramientas
| Herramienta | Uso |
|-------------|-----|
| Markdown | Formato universal |
| MDX | Markdown + componentes React |
| Docusaurus | Sitios de documentación |
| Storybook | Documentación de componentes |
| TypeDoc/JSDoc | Docs generadas de código |
| OpenAPI | Docs de API generadas |
## Conexión con llms.txt
El estándar [llms.txt](/concepts/llms-txt) es documentación como código optimizada para agentes de IA — un archivo Markdown que describe el proyecto para consumo por LLMs.
## ¿Por qué importa?
La documentación que vive separada del código se desactualiza inevitablemente. Tratarla como código — versionada en Git, revisada en PRs, generada desde fuentes autoritativas — es la única forma de mantenerla sincronizada con la realidad del sistema.
## Referencias
- [Docs as Code](https://www.writethedocs.org/guide/docs-as-code/) — Write the Docs.
- [MkDocs](https://www.mkdocs.org/) — MkDocs, 2024. Generador de sitios de documentación desde Markdown.
- [Docusaurus](https://docusaurus.io/) — Meta, 2024. Framework de documentación con versionado y i18n.
---
# Docker
Type: concept
Status: seed
Summary: Container platform that packages applications with all dependencies into portable, consistent units that run identically in any environment.
Concepts: devcontainers, aws-ecs
## ¿Qué es?
Docker es una plataforma que permite empaquetar aplicaciones en contenedores — unidades ligeras que incluyen el código, runtime, bibliotecas y configuración necesarios para ejecutarse. Un contenedor se ejecuta igual en tu laptop, en CI/CD y en producción.
## Conceptos clave
| Concepto | Función | Ejemplo |
|----------|---------|---------|
| Image | Plantilla inmutable con el sistema de archivos | `node:22-alpine`, imagen custom |
| Container | Instancia en ejecución de una imagen | `docker run my-app` |
| Dockerfile | Receta para construir una imagen | `FROM`, `COPY`, `RUN`, `CMD` |
| Registry | Repositorio de imágenes | Docker Hub, ECR, GHCR |
| Volume | Almacenamiento persistente fuera del contenedor | Datos de base de datos, uploads |
## Dockerfile básico
```dockerfile
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
EXPOSE 3000
CMD ["node", "server.js"]
```
## Docker vs VMs
| Aspecto | Docker | VM |
|---------|--------|----|
| Overhead | Mínimo (comparte kernel) | Alto (OS completo) |
| Startup | Segundos | Minutos |
| Tamaño | MBs | GBs |
| Aislamiento | Proceso | Hardware |
## Mejores prácticas
- Usar imágenes base oficiales y mínimas (alpine)
- Multi-stage builds para imágenes pequeñas
- No correr como root
- Un proceso por contenedor
- .dockerignore para excluir archivos innecesarios
## ¿Por qué importa?
Docker estandarizó el empaquetado de aplicaciones. Un contenedor funciona igual en desarrollo, CI y producción. Esta consistencia eliminó una categoría entera de bugs de entorno y habilitó prácticas como CI/CD, microservicios e infraestructura inmutable.
## Referencias
- [Docker Documentation](https://docs.docker.com/) — Documentación oficial.
- [Dockerfile Best Practices](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/) — Guía oficial.
- [Docker Overview](https://docs.docker.com/get-started/overview/) — Docker, 2024. Documentación oficial de Docker.
---
# Docker Compose
Type: concept
Status: seed
Summary: Tool for defining and running multi-container applications with a YAML file, simplifying local development of systems with multiple services.
Concepts: docker, local-development
## ¿Qué es?
Docker Compose es una herramienta para definir y ejecutar aplicaciones que consisten en múltiples contenedores [Docker](/concepts/docker). Un archivo `compose.yaml` describe todos los servicios, redes y volúmenes, y un solo comando los levanta todos.
## compose.yaml básico
```yaml
services:
web:
build: .
ports:
- "3000:3000"
depends_on:
- db
environment:
DATABASE_URL: postgres://db:5432/app
db:
image: postgres:16
volumes:
- pgdata:/var/lib/postgresql/data
environment:
POSTGRES_DB: app
volumes:
pgdata:
```
## Comandos esenciales
- `docker compose up`: levantar todos los servicios
- `docker compose up -d`: levantar en background
- `docker compose down`: detener y eliminar contenedores
- `docker compose logs -f`: seguir logs de todos los servicios
- `docker compose exec web sh`: shell en un servicio
## Casos de uso
- Desarrollo local de microservicios
- Ambientes de testing con dependencias reales
- Demos y prototipos rápidos
- CI/CD para tests de integración
## Compose vs Kubernetes
| Aspecto | Docker Compose | [Kubernetes](/concepts/kubernetes) |
|---------|---------------|------------|
| Propósito | Desarrollo local, CI | Producción, orquestación a escala |
| Complejidad | Baja — un archivo YAML | Alta — múltiples recursos (Deployments, Services, Ingress) |
| Escalado | Manual (`scale: 3`) | Automático (HPA, VPA) |
| Networking | Red bridge por defecto | CNI plugins, service discovery |
| Estado | Stateful con volúmenes locales | StatefulSets, PersistentVolumes |
| Migración | — | Kompose convierte compose files a manifiestos K8s |
## ¿Por qué importa?
Docker Compose permite definir aplicaciones multi-contenedor como código. Para desarrollo local, reemplaza scripts de setup complejos con un solo comando que levanta bases de datos, caches y servicios auxiliares en el orden correcto.
## Referencias
- [Docker Compose Documentation](https://docs.docker.com/compose/) — Documentación oficial.
- [Compose File Reference](https://docs.docker.com/compose/compose-file/) — Docker, 2024. Referencia completa del formato de archivo.
- [Docker Overview](https://docs.docker.com/get-started/overview/) — Docker, 2024. Contexto general de Docker y Compose.
---
# Distributed Tracing
Type: concept
Status: seed
Summary: Observability technique tracking requests across multiple services in distributed systems, enabling bottleneck identification and failure diagnosis.
Concepts: observability, microservices, ai-observability
## ¿Qué es?
El trazado distribuido rastrea una request desde su origen hasta su destino a través de todos los servicios que toca. Cada servicio genera un «span» con timing y metadata, y todos los spans se agrupan en un «trace» que muestra el flujo completo.
## Conceptos
| Concepto | Descripción | Ejemplo |
|----------|-------------|---------|
| Trace | El viaje completo de una request | Request HTTP desde el cliente hasta la respuesta |
| Span | Una operación dentro del trace (inicio, fin, metadata) | Llamada a base de datos, invocación de servicio |
| Context propagation | Pasar el trace ID entre servicios | Header `traceparent` (W3C Trace Context) |
| Sampling | No trazar el 100% de requests para reducir costo | Head-based (1%), tail-based (solo errores) |
## Flujo
```
Cliente → API Gateway (span 1)
→ Auth Service (span 2)
→ Product Service (span 3)
→ Database (span 4)
→ Response
```
## Herramientas
| Herramienta | Tipo |
|-------------|------|
| Jaeger | Open-source (CNCF) |
| Grafana Tempo | Open-source, integrado con Grafana |
| AWS X-Ray | Managed AWS |
| Datadog APM | SaaS |
| OpenTelemetry | Estándar de instrumentación |
## ¿Por qué importa?
En sistemas distribuidos, un request atraviesa múltiples servicios. Sin trazado distribuido, diagnosticar latencia o errores es como buscar una aguja en un pajar. Las trazas conectan los puntos entre servicios y revelan dónde se pierde el tiempo.
## Referencias
- [OpenTelemetry Tracing](https://opentelemetry.io/docs/concepts/signals/traces/) — Documentación oficial.
- [Jaeger](https://www.jaegertracing.io/) — CNCF, 2024. Sistema de tracing distribuido open source.
- [Zipkin](https://zipkin.io/) — OpenZipkin, 2024. Sistema de tracing distribuido.
---
# DevSecOps
Type: concept
Status: seed
Summary: Integration of security practices throughout the software development lifecycle, automating security controls in the CI/CD pipeline.
Concepts: devops, ci-cd, supply-chain-security, vulnerability-scanning, secure-coding
## ¿Qué es?
DevSecOps integra la seguridad como parte del proceso de desarrollo, no como un gate al final. «Shift left» significa mover los controles de seguridad lo más temprano posible en el ciclo de desarrollo.
## ¿Por qué importa?
El modelo tradicional — desarrollar primero, auditar seguridad al final — no escala. Cuando un equipo hace 50 deploys por semana, no puede esperar una revisión manual de seguridad para cada uno. DevSecOps automatiza esos controles para que la seguridad viaje a la misma velocidad que el desarrollo.
El costo de corregir una vulnerabilidad crece exponencialmente con el tiempo: arreglarla en código cuesta minutos, en producción puede costar millones.
## Seguridad en cada etapa
| Etapa | Controles |
|-------|----------|
| Código | SAST, secrets scanning, dependency check |
| Build | Container scanning, SBOM |
| Test | DAST, penetration testing |
| Deploy | Policy as code, admission control |
| Runtime | WAF, anomaly detection, RASP |
## Herramientas
| Categoría | Qué detecta | Herramientas | Cuándo ejecutar |
|-----------|------------|-------------|----------------|
| SAST | Vulnerabilidades en código fuente | Semgrep, SonarQube, CodeQL | En cada PR |
| SCA | Dependencias vulnerables | Snyk, Dependabot, Trivy | En cada PR + diario |
| Secrets | Credenciales en el código | GitLeaks, TruffleHog | Pre-commit + CI |
| Container | Vulnerabilidades en imágenes | Trivy, Grype | En build de imagen |
| DAST | Vulnerabilidades en runtime | OWASP ZAP, Burp Suite | En staging |
## Principios
- Automatizar todo lo posible
- Feedback rápido (no bloquear por días)
- Shared responsibility (no solo el equipo de seguridad)
- Compliance as code
## Referencias
- [OWASP DevSecOps Guideline](https://owasp.org/www-project-devsecops-guideline/) — OWASP.
- [DevSecOps — Snyk](https://snyk.io/learn/devsecops/) — Snyk, 2024. Guía práctica de DevSecOps.
- [What is DevSecOps?](https://www.redhat.com/en/topics/devops/what-is-devsecops) — Red Hat, 2024. Introducción a DevSecOps.
---
# DevOps
Type: concept
Status: evergreen
Summary: Culture and set of practices that unify development (Dev) and operations (Ops) to deliver software with greater speed, quality, and reliability. It's not a role — it's a way of working.
Concepts: ci-cd, github-actions
**DevOps** es un movimiento cultural y técnico que elimina los silos entre desarrollo y operaciones. Nació de la frustración con el modelo tradicional donde Dev «lanza código por encima del muro» y Ops «lo mantiene vivo» — sin responsabilidad compartida.
## ¿Qué problema resuelve?
En el modelo tradicional:
- Dev quiere cambios rápidos → Ops quiere estabilidad → conflicto permanente
- Deploys manuales cada semanas/meses → acumulación de riesgo
- «Funciona en mi máquina» → problemas en producción
- Blame culture → nadie quiere hacer deploy los viernes
DevOps alinea incentivos: **el equipo que construye el software es responsable de operarlo**.
## Los tres caminos
Principios fundamentales del libro *The Phoenix Project*:
### 1. Flow (sistemas de izquierda a derecha)
Optimizar el flujo de trabajo desde desarrollo hasta producción:
- Hacer el trabajo visible (tableros Kanban)
- Limitar work in progress (WIP)
- Reducir batch sizes
- Eliminar handoffs y colas
- Automatizar todo lo repetitivo
### 2. Feedback (de derecha a izquierda)
Crear loops de retroalimentación rápidos:
- Monitoring y alertas en producción
- Tests automatizados en CI
- Code review en PRs
- Post-mortems sin culpa
- Telemetría de usuario
### 3. Continual learning
Cultura de experimentación y mejora:
- Blameless post-mortems
- Chaos engineering
- Game days (simulacros de incidentes)
- 20% time para mejoras técnicas
- Compartir conocimiento (tech talks, documentación)
## CALMS framework
Modelo para evaluar la adopción de DevOps:
| Pilar | Significado | Ejemplo |
|-------|-------------|---------|
| **C**ulture | Colaboración sobre silos | Equipos cross-funcionales |
| **A**utomation | Eliminar trabajo manual | CI/CD, IaC, auto-scaling |
| **L**ean | Eliminar desperdicio | Limitar WIP, reducir batch size |
| **M**easurement | Medir todo | DORA metrics, SLOs, error budgets |
| **S**haring | Compartir conocimiento | Post-mortems, runbooks, tech talks |
## Prácticas esenciales
### Infrastructure as Code (IaC)
Definir infraestructura en archivos versionados:
```hcl
# Terraform
resource "aws_lambda_function" "api" {
function_name = "api-handler"
runtime = "nodejs20.x"
handler = "index.handler"
filename = "lambda.zip"
}
```
Beneficios: reproducibilidad, auditoría, rollback, review en PRs.
### Monitoring y observabilidad
Los tres pilares:
- **Logs** — eventos discretos (qué pasó)
- **Metrics** — valores numéricos en el tiempo (cuánto)
- **Traces** — flujo de una request a través de servicios (dónde)
### SLOs y error budgets
- **SLI** (Service Level Indicator) — métrica medible (latencia p99, availability)
- **SLO** (Service Level Objective) — objetivo interno (99.9% availability)
- **SLA** (Service Level Agreement) — compromiso contractual con consecuencias
- **Error budget** — margen permitido de fallo (0.1% = 43 min/mes de downtime)
Si el error budget se agota → congelar features, priorizar estabilidad.
### Blameless post-mortems
Después de cada incidente:
1. **Timeline** — qué pasó, cuándo, quién hizo qué
2. **Root cause** — análisis de los 5 porqués
3. **Impact** — usuarios afectados, duración, datos perdidos
4. **Action items** — mejoras concretas con owners y deadlines
5. **Lessons learned** — qué funcionó bien, qué no
Regla cardinal: **culpar al sistema, no a las personas**.
### Chaos engineering
Inyectar fallos deliberadamente para descubrir debilidades:
- Apagar instancias aleatorias (Chaos Monkey)
- Inyectar latencia en la red
- Llenar discos
- Simular fallos de dependencias
## DevOps vs SRE
| Aspecto | DevOps | SRE |
|---------|--------|-----|
| Origen | Comunidad (2009) | Google (2003) |
| Enfoque | Cultura + prácticas | Ingeniería de confiabilidad |
| Definición | Movimiento | Rol/disciplina |
| Relación | Filosofía | Implementación de DevOps con ingeniería |
Como dijo Ben Treynor (creador de SRE en Google): «SRE es lo que pasa cuando le pides a un ingeniero de software que diseñe un equipo de operaciones».
## Evolución: Platform Engineering
La evolución natural de DevOps en organizaciones grandes:
- **DevOps** — «you build it, you run it» (cada equipo opera su software)
- **Platform Engineering** — un equipo construye la plataforma interna que otros equipos consumen
La plataforma abstrae la complejidad: el desarrollador hace `git push` y la plataforma se encarga de build, test, deploy, monitoring.
## Anti-patrones
- **DevOps team** — crear un equipo llamado «DevOps» que se convierte en el nuevo silo
- **Automation sin cultura** — herramientas sin cambio cultural no resuelven nada
- **Heroísmo** — depender de una persona que «sabe todo» en lugar de documentar
- **Métricas vanidosas** — medir deploys/día sin medir calidad o impacto
- **Tool obsession** — cambiar de herramienta cada 6 meses sin resolver problemas de fondo
## ¿Por qué importa?
DevOps no es un rol ni una herramienta — es un cambio cultural que elimina la barrera entre quienes escriben el código y quienes lo operan. Las organizaciones que lo adoptan efectivamente entregan software más rápido, con menos fallos y con recuperación más ágil. Las que lo tratan como un título de puesto pierden el punto.
## Referencias
- [The Phoenix Project](https://itrevolution.com/product/the-phoenix-project/) — Gene Kim, Kevin Behr & George Spafford, 2013. La novela que popularizó DevOps.
- [The DevOps Handbook](https://itrevolution.com/product/the-devops-handbook-second-edition/) — Gene Kim et al., 2021. Guía práctica de implementación (segunda edición).
- [Accelerate](https://itrevolution.com/product/accelerate/) — Nicole Forsgren, Jez Humble & Gene Kim, 2018. Investigación científica sobre métricas DORA.
- [Google SRE Books](https://sre.google/books/) — Google, 2016-2024. Tres libros gratuitos sobre Site Reliability Engineering.
- [State of DevOps Report](https://dora.dev/research/) — DORA/Google Cloud, 2024. Investigación anual sobre prácticas y rendimiento.
- [The Twelve-Factor App](https://12factor.net/) — Adam Wiggins, 2011. Metodología para construir aplicaciones cloud-native.
---
# DevOps Practices
Type: concept
Status: evergreen
Summary: Set of technical and cultural practices that implement DevOps principles — from Infrastructure as Code to blameless post-mortems. The "how" behind the philosophy.
Concepts: devops, ci-cd, github-actions
Las **prácticas DevOps** son las implementaciones concretas de la filosofía DevOps. Mientras DevOps es el «qué» y el «por qué», estas prácticas son el «cómo».
## Infrastructure as Code (IaC)
Definir y gestionar infraestructura mediante archivos de configuración versionados.
### Herramientas principales
| Herramienta | Enfoque | Lenguaje |
|-------------|---------|----------|
| **Terraform** | Multi-cloud, declarativo | HCL |
| **Pulumi** | Multi-cloud, imperativo | TypeScript, Python, Go |
| **AWS CDK** | AWS, imperativo | TypeScript, Python, Java |
| **CloudFormation** | AWS, declarativo | YAML/JSON |
| **Ansible** | Configuración, agentless | YAML |
### Ejemplo Terraform
```hcl
resource "aws_s3_bucket" "data" {
bucket = "my-data-bucket"
versioning {
enabled = true
}
server_side_encryption_configuration {
rule {
apply_server_side_encryption_by_default {
sse_algorithm = "AES256"
}
}
}
}
```
### Principios IaC
- **Idempotencia** — aplicar múltiples veces produce el mismo resultado
- **Versionado** — toda la infra en Git con historial completo
- **Review** — cambios de infra pasan por PR como código
- **Módulos** — reutilizar patrones comunes
- **State management** — estado remoto compartido (S3, Terraform Cloud)
## Configuration Management
Mantener servidores en un estado deseado de forma automatizada.
```yaml
# Ansible playbook
- hosts: webservers
tasks:
- name: Install nginx
apt:
name: nginx
state: present
- name: Copy config
template:
src: nginx.conf.j2
dest: /etc/nginx/nginx.conf
notify: restart nginx
handlers:
- name: restart nginx
service:
name: nginx
state: restarted
```
## Containerization
Empaquetar aplicaciones con todas sus dependencias.
```dockerfile
# Multi-stage build
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
EXPOSE 3000
CMD ["node", "dist/index.js"]
```
### Mejores prácticas Docker
- Imágenes base mínimas (Alpine, distroless)
- Multi-stage builds para reducir tamaño
- Un proceso por contenedor
- No correr como root
- `.dockerignore` para excluir archivos innecesarios
- Pinear versiones de imágenes base
## GitOps
Usar Git como fuente de verdad para infraestructura y deployments.
### Principios
1. **Declarativo** — el estado deseado está en Git
2. **Versionado** — Git es el historial de cambios
3. **Automático** — agentes reconcilian el estado real con el deseado
4. **Auditable** — cada cambio tiene autor, timestamp y razón
### Herramientas
- **ArgoCD** — Kubernetes GitOps controller
- **Flux** — Kubernetes GitOps toolkit
- **Atlantis** — Terraform pull request automation
```yaml
# ArgoCD Application
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: my-app
spec:
source:
repoURL: https://github.com/org/repo
path: k8s/
targetRevision: main
destination:
server: https://kubernetes.default.svc
namespace: production
syncPolicy:
automated:
prune: true
selfHeal: true
```
## Feature Flags
Separar deployment de release — código en producción pero funcionalidad controlada.
```typescript
// Ejemplo con LaunchDarkly / Unleash / custom
if (featureFlags.isEnabled('new-checkout', { userId })) {
return ;
}
return ;
```
### Casos de uso
- **Canary releases** — habilitar para % de usuarios
- **Beta testing** — habilitar para usuarios específicos
- **Kill switch** — deshabilitar feature problemática sin deploy
- **A/B testing** — comparar variantes
- **Trunk-based development** — mergear código incompleto
## Observability
Los tres pilares para entender sistemas en producción:
### Logs
```json
{
"timestamp": "2024-01-15T10:30:00Z",
"level": "error",
"service": "api",
"trace_id": "abc123",
"message": "Payment failed",
"user_id": "user_456",
"error_code": "INSUFFICIENT_FUNDS"
}
```
Structured logging — JSON parseable, no texto libre.
### Metrics
```
# Prometheus format
http_requests_total{method="GET", status="200"} 1234
http_request_duration_seconds{quantile="0.99"} 0.25
```
Tipos: counters, gauges, histograms, summaries.
### Traces
Seguir una request a través de múltiples servicios:
```
[API Gateway] → [Auth Service] → [User Service] → [Database]
2ms 5ms 3ms 10ms
```
Herramientas: Jaeger, Zipkin, AWS X-Ray, Datadog APM.
## Incident Management
### On-call
- Rotaciones definidas (PagerDuty, Opsgenie)
- Runbooks para incidentes comunes
- Escalation paths claros
- Compensación por on-call
### Incident response
1. **Detect** — alertas, usuarios, monitoring
2. **Triage** — severidad, impacto, quién responde
3. **Mitigate** — restaurar servicio (rollback, scale, failover)
4. **Resolve** — fix permanente
5. **Learn** — post-mortem
### Severities
| Sev | Impacto | Response time | Ejemplo |
|-----|---------|---------------|---------|
| 1 | Servicio caído | Inmediato | Sitio no carga |
| 2 | Degradación mayor | < 30 min | Pagos fallan |
| 3 | Degradación menor | < 4 horas | Feature secundaria rota |
| 4 | Bajo impacto | Siguiente día hábil | Bug cosmético |
## Chaos Engineering
Inyectar fallos controlados para descubrir debilidades.
### Principios
1. Definir «estado estable» (métricas normales)
2. Hipótesis: el sistema tolera X fallo
3. Introducir variables del mundo real (latencia, fallos, particiones)
4. Intentar refutar la hipótesis
5. Minimizar blast radius
### Herramientas
- **Chaos Monkey** — termina instancias aleatorias
- **Gremlin** — plataforma de chaos engineering
- **Litmus** — chaos engineering para Kubernetes
- **AWS Fault Injection Simulator** — chaos nativo en AWS
## Security Practices (DevSecOps)
Integrar seguridad en todo el pipeline:
### Shift left
- **SAST** — análisis estático de código (SonarQube, Semgrep)
- **SCA** — análisis de dependencias (Snyk, Dependabot)
- **Secret scanning** — detectar credenciales en código
- **Container scanning** — vulnerabilidades en imágenes (Trivy)
### Runtime
- **DAST** — testing dinámico de aplicaciones
- **WAF** — firewall de aplicaciones web
- **Runtime protection** — detectar comportamiento anómalo
## ¿Por qué importa?
Estas prácticas no son opcionales para equipos que operan software en producción. Cada una reduce un tipo específico de riesgo: IaC elimina la configuración manual, los feature flags desacoplan deploy de release, la observabilidad convierte incidentes en aprendizaje. Adoptarlas incrementalmente es más efectivo que intentar implementar todo a la vez.
## Referencias
- [Infrastructure as Code](https://www.oreilly.com/library/view/infrastructure-as-code/9781098114664/) — Kief Morris, 2020. El libro definitivo sobre IaC.
- [Site Reliability Engineering](https://sre.google/sre-book/table-of-contents/) — Google, 2016. Prácticas de SRE incluyendo incident management.
- [Observability Engineering](https://www.oreilly.com/library/view/observability-engineering/9781492076438/) — Charity Majors et al., 2022. Guía moderna de observabilidad.
- [Chaos Engineering](https://www.oreilly.com/library/view/chaos-engineering/9781492043850/) — Casey Rosenthal & Nora Jones, 2020. Principios y prácticas.
- [GitOps and Kubernetes](https://www.manning.com/books/gitops-and-kubernetes) — Billy Yuen et al., 2021. Implementación práctica de GitOps.
- [The Practice of Cloud System Administration](https://the-cloud-book.com/) — Limoncelli, Chalup & Hogan, 2014. Prácticas de operaciones a escala.
---
# Developer Portals
Type: concept
Status: seed
Summary: Centralized platforms providing developers with documentation, APIs, tools, and service catalogs in one place.
Concepts: developer-experience, platform-engineering, backstage, api-documentation, golden-paths
## ¿Qué es?
Un portal de desarrollador es una plataforma centralizada donde los desarrolladores encuentran todo lo que necesitan: catálogo de servicios, documentación de APIs, templates de proyectos, dashboards de salud y herramientas de self-service.
## Componentes
| Componente | Función | Ejemplo |
|-----------|---------|---------|
| Catálogo de servicios | Inventario de microservicios, owners, dependencias | [Backstage](/concepts/backstage) Software Catalog |
| Documentación | Docs técnicas centralizadas y buscables | TechDocs, Docusaurus |
| Templates | Scaffolding con mejores prácticas | [Golden paths](/concepts/golden-paths) |
| Plugins | Integraciones con CI/CD, cloud, [observabilidad](/concepts/observability) | Kubernetes, Grafana, PagerDuty |
| Scorecards | Evaluación de madurez de servicios | Cortex, OpsLevel |
## Backstage
Backstage (Spotify, CNCF) es la plataforma open-source más popular para developer portals. Extensible mediante plugins.
## Beneficios
- Reducir tiempo buscando información
- Visibilidad del ecosistema de servicios
- Self-service para tareas comunes
- Onboarding acelerado
## ¿Cuándo no construir uno?
- Equipos pequeños (menos de 20 desarrolladores) — el overhead de mantener el portal no se justifica
- Si no hay equipo de plataforma dedicado — un portal sin mantenimiento se convierte en otro sistema abandonado
- Cuando un buen README y un wiki resuelven el problema
## ¿Por qué importa?
Un portal de desarrolladores centraliza el acceso a servicios, documentación, APIs y herramientas internas. Sin él, los desarrolladores pierden tiempo buscando información dispersa en wikis, Slack y repositorios. Es la capa de descubrimiento que hace escalable la plataforma interna.
## Referencias
- [Backstage](https://backstage.io/) — Plataforma open-source de Spotify para developer portals.
- [Port](https://www.getport.io/) — Alternativa comercial con enfoque en self-service.
- [Adopting Backstage](https://backstage.io/docs/overview/adopting/) — Backstage, 2024. Guía de adopción del portal de desarrolladores más popular.
---
# Developer Onboarding
Type: concept
Status: seed
Summary: Structured process for new developers to become productive quickly, from environment setup to understanding team architecture and processes.
Concepts: developer-experience, documentation-as-code, golden-paths, local-development
## ¿Qué es?
El onboarding de desarrolladores es el proceso de llevar a un nuevo miembro del equipo desde «acabo de llegar» hasta «soy productivo». Un buen onboarding reduce este tiempo de semanas a días.
## Componentes
- **Setup del entorno**: [dev containers](/concepts/devcontainers), scripts de setup
- **Documentación**: AGENTS.md, README, architecture decision records
- **Primer PR**: tarea pequeña para familiarizarse con el flujo
- **Buddy system**: un compañero asignado para preguntas
- **Checklist**: lista verificable de pasos completados
## Métricas
| Métrica | Objetivo | Cómo medir |
|---------|----------|-----------|
| Tiempo hasta primer commit | < 1 día | Fecha de inicio → primer commit |
| Tiempo hasta primer PR mergeado | < 1 semana | Fecha de inicio → primer merge |
| Tiempo hasta primer deploy a producción | < 2 semanas | Fecha de inicio → primer deploy |
| Satisfacción del nuevo desarrollador | > 4/5 | Survey a los 30 días |
## Automatización
- `pnpm install && pnpm dev` debe funcionar en menos de 5 minutos
- Dev containers eliminan «funciona en mi máquina»
- AGENTS.md como guía para humanos y agentes de IA
## Anti-patrones
- **«Pregúntale a Juan»** — todo el conocimiento en una persona, no en documentación
- **Setup de 3 días** — si el onboarding tarda más de medio día, el entorno necesita automatización
- **Documentación de onboarding desactualizada** — peor que no tener, porque genera frustración y desconfianza
## ¿Por qué importa?
El tiempo de onboarding es una métrica directa de la salud de la plataforma de desarrollo. Si un nuevo ingeniero tarda semanas en ser productivo, el problema no es el ingeniero — es la falta de documentación, golden paths y entornos reproducibles.
## Referencias
- [The Manager's Path](https://www.oreilly.com/library/view/the-managers-path/9781491973882/) — Camille Fournier. Incluye secciones sobre onboarding efectivo.
- [An Elegant Puzzle](https://press.stripe.com/an-elegant-puzzle) — Will Larson, 2019. Sistemas de gestión de ingeniería incluyendo onboarding.
- [DX: Developer Experience](https://dx.addy.ie/) — Addy Osmani, 2024. Libro sobre experiencia de desarrollador incluyendo onboarding.
---
# Developer Experience
Type: concept
Status: seed
Summary: Discipline focused on optimizing developer productivity, satisfaction, and effectiveness through well-designed tools, processes, and environments.
Concepts: devops-practices, monorepos, developer-onboarding, developer-portals, golden-paths, ci-cd, user-experience
## ¿Qué es?
Developer Experience (DX) es la experiencia total de un desarrollador al usar herramientas, APIs, frameworks y procesos. Una buena DX reduce fricción, acelera el feedback loop y hace que el trabajo sea más satisfactorio.
## Dimensiones de DX
- **Onboarding**: tiempo desde clonar el repo hasta primer commit productivo
- **Feedback loop**: tiempo desde cambio hasta ver resultado (build, tests, deploy)
- **Documentación**: claridad, actualización, ejemplos
- **Tooling**: CLI, IDE integration, debugging
- **Ergonomía de API**: intuitividad, consistencia, manejo de errores
## Métricas
| Métrica | Framework | Qué mide | Objetivo |
|---------|-----------|----------|----------|
| Tiempo de onboarding | SPACE | Días hasta primer PR productivo | < 1 semana |
| Tiempo de build local | DORA | Minutos de feedback loop | < 2 minutos |
| Deploy frequency | DORA | Deploys por día/semana | Múltiples por día |
| Developer satisfaction | SPACE | Encuesta periódica | > 4/5 |
| Lead time for changes | DORA | Commit → producción | < 1 día |
## Prácticas que mejoran DX
- [Dev containers](/concepts/devcontainers) para entornos reproducibles
- [Monorepos](/concepts/monorepos) con tooling integrado
- CI/CD rápido con feedback inmediato
- Documentación como código (actualizada automáticamente)
- APIs con buenos mensajes de error
## Anti-patrones de DX
- **«Funciona en mi máquina»** — entornos no reproducibles que desperdician horas de setup
- **Documentación fantasma** — docs que existen pero están desactualizadas, peor que no tener docs
- **CI de 45 minutos** — feedback loops tan lentos que los desarrolladores dejan de correr tests localmente
- **Configuración tribal** — conocimiento que solo existe en la cabeza de una persona
## ¿Por qué importa?
La experiencia del desarrollador determina la velocidad y satisfacción de los equipos de ingeniería. Herramientas lentas, documentación desactualizada y procesos burocráticos son fricciones que se multiplican por cada desarrollador y cada día. Invertir en DX es invertir en productividad organizacional.
## Referencias
- [SPACE Framework](https://queue.acm.org/detail.cfm?id=3454124) — Microsoft Research, 2021. Framework para medir productividad de desarrolladores.
- [DevEx: What Actually Drives Productivity](https://queue.acm.org/detail.cfm?id=3595878) — Noda, Storey, Forsgren, Greiler, 2023. Tres dimensiones de DX: feedback loops, flow state, carga cognitiva.
- [Developer Effectiveness](https://martinfowler.com/articles/developer-effectiveness.html) — Tim Cochran, 2021. Cómo medir y mejorar la efectividad del desarrollador.
---
# Dev Containers
Type: concept
Status: seed
Summary: Specification for defining reproducible development environments in containers, eliminating 'works on my machine' problems and accelerating onboarding.
Concepts: docker, developer-experience
## ¿Qué es?
Dev Containers es una especificación abierta para definir entornos de desarrollo en contenedores [Docker](/concepts/docker). Un archivo `devcontainer.json` describe el entorno completo: imagen base, extensiones de editor, herramientas, variables de entorno. Cualquier desarrollador puede abrir el proyecto y tener el mismo entorno en minutos.
## Problema que resuelve
- «Funciona en mi máquina» → entorno idéntico para todos
- Onboarding de días → onboarding de minutos
- Conflictos de versiones → aislamiento por proyecto
- Setup manual → automatizado y versionado
## devcontainer.json básico
```json
{
"name": "Node.js",
"image": "mcr.microsoft.com/devcontainers/javascript-node:20",
"features": {
"ghcr.io/devcontainers/features/aws-cli:1": {}
},
"customizations": {
"vscode": {
"extensions": ["dbaeumer.vscode-eslint"]
}
},
"postCreateCommand": "npm install"
}
```
## Soporte
- VS Code (Dev Containers extension)
- GitHub Codespaces
- JetBrains (Gateway)
- DevPod (open source)
## Features
Componentes reutilizables que agregan herramientas al contenedor:
- AWS CLI, Azure CLI, gcloud
- Node.js, Python, Go, Rust
- Docker-in-Docker
- Git, GitHub CLI
## ¿Por qué importa?
Los devcontainers eliminan el problema de «funciona en mi máquina» al definir el entorno de desarrollo como código. Cada desarrollador obtiene el mismo entorno reproducible, con las herramientas y dependencias correctas, sin contaminar su sistema local.
## Referencias
- [Dev Containers Specification](https://containers.dev/) — Especificación oficial.
- [Available Features](https://containers.dev/features) — Catálogo de features.
- [Dev Container Specification](https://containers.dev/implementors/spec/) — Dev Containers, 2024. Especificación oficial del formato.
---
# Design Systems
Type: concept
Status: seed
Summary: Collection of reusable components, patterns, and guidelines ensuring visual and interaction consistency in digital products at scale.
Concepts: react, accessibility, tailwindcss, web-components, developer-experience
## ¿Qué es?
Un sistema de diseño es una colección de componentes reutilizables, design tokens, patrones y documentación que permite construir productos consistentes a escala. No es solo una librería de componentes — incluye principios, guías de uso y gobernanza.
## Capas
- **Design tokens**: colores, tipografía, espaciado, sombras
- **Componentes**: botones, inputs, cards, modals
- **Patrones**: formularios, navegación, layouts
- **Documentación**: guías de uso, do's and don'ts
- **Gobernanza**: proceso de contribución y evolución
## Sistemas de diseño conocidos
| Sistema | Organización |
|---------|-------------|
| Material Design | Google |
| Fluent | Microsoft |
| Carbon | IBM |
| Primer | GitHub |
| shadcn/ui | Comunidad |
## Beneficios
- Consistencia visual entre productos
- Velocidad de desarrollo (no reinventar componentes)
- [Accesibilidad](/concepts/accessibility) integrada
- Lenguaje compartido entre diseño y desarrollo
## Anti-patrones
- **Biblioteca sin documentación**: componentes existen pero nadie sabe cómo usarlos
- **Diseño por comité**: demasiados stakeholders sin un owner claro ralentizan la evolución
- **Componentes inflexibles**: tan rígidos que los equipos los evitan y construyen los suyos
## ¿Por qué importa?
Un design system no es una librería de componentes — es un lenguaje compartido entre diseño e ingeniería. Reduce la toma de decisiones repetitiva, garantiza consistencia visual y acelera el desarrollo al proporcionar primitivas probadas y documentadas.
## Referencias
- [Design Systems](https://www.designsystems.com/) — Recursos y ejemplos de sistemas de diseño.
- [Storybook](https://storybook.js.org/) — Storybook, 2024. Herramienta estándar para desarrollo de componentes UI.
- [Atomic Design](https://atomicdesign.bradfrost.com/) — Brad Frost, 2016. Metodología para crear sistemas de diseño.
---
# CQRS
Type: concept
Status: seed
Summary: Pattern separating read and write operations into distinct models, optimizing each independently for performance and scalability.
Concepts: event-driven-architecture, domain-driven-design
## ¿Qué es?
CQRS (Command Query Responsibility Segregation) separa las operaciones de escritura (commands) de las de lectura (queries) en modelos diferentes. Cada lado puede usar su propia base de datos, schema y estrategia de escalado.
## ¿Por qué separar?
- Las lecturas y escrituras tienen patrones de acceso diferentes
- Las lecturas suelen ser más frecuentes (10:1 o más)
- Cada lado puede escalar independientemente
- Los modelos de lectura pueden estar desnormalizados para velocidad
## Flujo típico
```
Command → Write Model → Event → Read Model (projection)
Query → Read Model → Response
```
## CQRS + Event Sourcing
CQRS se combina frecuentemente con [event sourcing](/concepts/event-sourcing): los commands generan eventos, y las proyecciones de lectura se construyen a partir de esos eventos.
## Cuándo usar
- Patrones de lectura/escritura muy diferentes
- Necesidad de múltiples vistas de los mismos datos
- Sistemas con alta carga de lectura
## Cuándo NO usar
- CRUD simple
- Consistencia inmediata requerida
- Equipo sin experiencia en sistemas distribuidos
## ¿Por qué importa?
CQRS permite optimizar lecturas y escrituras de forma independiente, lo cual es esencial en sistemas donde los patrones de consulta difieren radicalmente de los de escritura. Combinado con event sourcing, habilita auditoría completa y proyecciones especializadas.
## Referencias
- [CQRS](https://martinfowler.com/bliki/CQRS.html) — Martin Fowler.
- [CQRS Pattern — Azure](https://learn.microsoft.com/en-us/azure/architecture/patterns/cqrs) — Microsoft, 2024. Guía de implementación del patrón.
- [CQRS Pattern — Event Store](https://www.eventstore.com/cqrs-pattern) — Event Store, 2024. CQRS con event sourcing.
---
# Cost Optimization
Type: concept
Status: seed
Summary: Practices and strategies to minimize cloud spending without sacrificing performance, including right-sizing, reservations, spot instances, and eliminating idle resources.
Concepts: aws-well-architected, serverless
## ¿Qué es?
La optimización de costos en cloud es el proceso continuo de reducir el gasto sin impactar negativamente el rendimiento o la disponibilidad. Es uno de los pilares del [AWS Well-Architected Framework](/concepts/aws-well-architected) y una disciplina conocida como FinOps.
## Estrategias principales
### Right-sizing
Ajustar el tamaño de recursos al uso real:
- Analizar métricas de CPU, memoria, I/O
- Reducir instancias sobredimensionadas
- AWS Compute Optimizer proporciona recomendaciones
### Modelos de compra
| Modelo | Descuento | Compromiso |
|--------|-----------|------------|
| On-demand | 0% | Ninguno |
| Savings Plans | ~30-70% | 1-3 años |
| Reserved Instances | ~30-70% | 1-3 años |
| Spot Instances | ~60-90% | Ninguno (interrumpible) |
### Serverless
[Serverless](/concepts/serverless) optimiza costos automáticamente:
- Pago por uso real (no por capacidad reservada)
- Escala a cero cuando no hay tráfico
- Sin costo de infraestructura ociosa
### Eliminación de desperdicio
- Recursos huérfanos (EBS volumes, EIPs no asociados)
- Ambientes de desarrollo encendidos 24/7
- Snapshots y backups antiguos
## Herramientas AWS
- Cost Explorer: análisis de gastos
- Budgets: alertas de presupuesto
- Trusted Advisor: recomendaciones de ahorro
## ¿Por qué importa?
En la nube, el costo es una métrica de ingeniería. Sin optimización activa, los gastos crecen más rápido que el valor entregado. Las prácticas de FinOps — right-sizing, reservas, tagging, eliminación de recursos ociosos — son responsabilidad de ingeniería, no solo de finanzas.
## Referencias
- [AWS Cost Optimization](https://aws.amazon.com/aws-cost-management/) — Herramientas oficiales.
- [FinOps Foundation](https://www.finops.org/) — Framework y comunidad.
- [FinOps Framework](https://www.finops.org/framework/) — FinOps Foundation, 2024. Marco de referencia para gestión financiera en la nube.
---
# Context Windows
Type: concept
Status: seed
Summary: The maximum number of tokens an LLM can process in a single interaction, determining how much information it can consider simultaneously to generate responses.
Concepts: large-language-models, prompt-engineering
## ¿Qué es?
La ventana de contexto es el límite máximo de tokens (palabras y subpalabras) que un [LLM](/concepts/large-language-models) puede procesar en una sola interacción. Incluye tanto la entrada (prompt, contexto, historial) como la salida generada. Es la «memoria de trabajo» del modelo.
## Evolución del tamaño
| Año | Modelo | Ventana |
|-----|--------|---------|
| 2022 | GPT-3.5 | 4K tokens |
| 2023 | GPT-4 | 8K–32K tokens |
| 2023 | Claude 2 | 100K tokens |
| 2024 | Claude 3 | 200K tokens |
| 2024 | Gemini 1.5 | 1M–2M tokens |
| 2025 | GPT-4.1 | 1M tokens |
Para referencia: 1K tokens ≈ 750 palabras en inglés, ≈ 600 en español.
## ¿Por qué importa?
La ventana de contexto es la restricción fundamental que define qué puede y qué no puede hacer un LLM en una sola interacción. En RAG, determina cuántos documentos recuperados caben en el prompt. En conversaciones, limita el historial que el modelo recuerda. En agentes, afecta cuántas iteraciones de razonamiento caben en una sesión. Diseñar sistemas que trabajan dentro de estos límites — con chunking, summarización y gestión de contexto — es una habilidad arquitectónica esencial para cualquier aplicación basada en LLMs.
## El problema «Lost in the Middle»
Los modelos no prestan atención uniforme a todo el contexto. Investigaciones muestran que la información al inicio y al final del contexto se procesa mejor que la del medio. Esto tiene implicaciones prácticas para cómo ordenar la información en prompts largos.
## Estrategias para contextos largos
- **Chunking inteligente**: dividir documentos y procesar por partes
- **Resumen progresivo**: resumir secciones anteriores para liberar espacio
- **Priorización**: colocar información crítica al inicio o final del contexto
- **RAG selectivo**: recuperar solo los fragmentos más relevantes en lugar de documentos completos
## Costo y rendimiento
Más contexto = más cómputo. La atención en Transformers escala cuadráticamente con la longitud de la secuencia (O(n²)), aunque técnicas como atención sparse, sliding window y ring attention reducen esto en la práctica.
## Referencias
- [Lost in the Middle](https://arxiv.org/abs/2307.03172) — Liu et al., 2023. Cómo los LLMs usan contextos largos.
- [Extending Context Window of Large Language Models](https://arxiv.org/abs/2401.04088) — Survey de técnicas de extensión de contexto.
- [Prompt Caching — Anthropic](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching) — Anthropic, 2024. Optimización de uso de ventana de contexto.
---
# Container Security
Type: concept
Status: seed
Summary: Practices and tools for securing containers throughout their lifecycle: image building, runtime, orchestration, and compliance.
Concepts: docker, kubernetes
## ¿Qué es?
La seguridad de contenedores abarca las prácticas para proteger aplicaciones containerizadas en todo su ciclo de vida: desde la construcción de imágenes hasta la ejecución en producción.
## Capas de seguridad
### Imagen
- Usar imágenes base oficiales y mínimas
- Escanear vulnerabilidades (Trivy, Snyk, ECR scanning)
- No incluir secretos en imágenes
- Multi-stage builds para reducir superficie de ataque
### Build
- Firmar imágenes (cosign)
- Verificar procedencia (SLSA)
- CI/CD gates que bloquean imágenes vulnerables
### Runtime
- No ejecutar como root
- Read-only filesystem cuando sea posible
- Limitar capabilities del kernel
- Network policies para aislar tráfico
### Orquestación
- RBAC en [Kubernetes](/concepts/kubernetes)
- Pod Security Standards
- Secrets management (no en variables de entorno planas)
- Admission controllers para políticas
## Herramientas
| Herramienta | Función |
|-------------|--------|
| Trivy | Escaneo de vulnerabilidades |
| Falco | Detección de amenazas runtime |
| OPA/Gatekeeper | Políticas de admisión |
| cosign | Firma de imágenes |
## ¿Por qué importa?
Los contenedores no son seguros por defecto. Imágenes con vulnerabilidades conocidas, ejecución como root y secretos embebidos son errores comunes que convierten contenedores en vectores de ataque. La seguridad de contenedores debe ser parte del pipeline, no una revisión posterior.
## Referencias
- [NIST Container Security Guide](https://csrc.nist.gov/publications/detail/sp/800-190/final) — SP 800-190.
- [Container Security Best Practices](https://sysdig.com/learn-cloud-native/container-security/) — Sysdig, 2024. Guía práctica de seguridad de contenedores.
- [Dockerfile Best Practices](https://docs.docker.com/build/building/best-practices/) — Docker, 2024. Mejores prácticas para imágenes seguras.
---
# Container Registries
Type: concept
Status: seed
Summary: Repositories for storing, versioning, and distributing container images, from public registries like Docker Hub to private registries like ECR.
Concepts: docker, ci-cd
## ¿Qué es?
Un registro de contenedores es un repositorio para almacenar y distribuir imágenes [Docker](/concepts/docker). Funciona como npm para paquetes Node.js, pero para imágenes de contenedores.
## Registros populares
| Registro | Tipo | Características |
|----------|------|----------------|
| Docker Hub | Público/Privado | El más grande, imágenes oficiales |
| Amazon ECR | Privado (AWS) | Integración nativa con ECS/EKS |
| GitHub GHCR | Público/Privado | Integración con GitHub Actions |
| Google Artifact Registry | Privado (GCP) | Multi-formato |
| Azure ACR | Privado (Azure) | Geo-replicación |
## Flujo típico en CI/CD
```
Code push → CI build → Docker build → Push to registry → Deploy from registry
```
## Seguridad
- Escaneo de vulnerabilidades en imágenes
- Firma de imágenes (cosign, Notary)
- Políticas de retención para limpiar imágenes antiguas
- Acceso basado en IAM/RBAC
## ¿Por qué importa?
Un registro de contenedores es infraestructura crítica en cualquier pipeline de CI/CD basado en contenedores. La elección entre registros públicos, privados y gestionados afecta la seguridad, la latencia de despliegue y los costos operacionales.
## Referencias
- [Amazon ECR](https://docs.aws.amazon.com/ecr/) — Documentación oficial.
- [Docker Hub](https://docs.docker.com/docker-hub/) — Docker, 2024. Registro de contenedores más usado.
- [Distribution](https://github.com/distribution/distribution) — CNCF, 2024. Implementación de referencia del OCI Distribution Spec.
---
# Code Quality
Type: concept
Status: seed
Summary: Practices, tools, and metrics for maintaining readable, maintainable, testable, and defect-free code over time.
Concepts: ci-cd, developer-experience, linting-formatting
## ¿Qué es?
La calidad de código es un conjunto de atributos que hacen que el código sea fácil de entender, modificar y mantener. No es solo «funciona» — es «funciona, es legible, es testeable, y el próximo desarrollador lo entenderá».
## Dimensiones
| Dimensión | Pregunta clave | Cómo medir |
|-----------|---------------|------------|
| Legibilidad | ¿Se entiende sin explicación? | Code review, cognitive complexity |
| Mantenibilidad | ¿Es fácil de modificar? | Coupling, cohesión, tamaño de módulos |
| Testeabilidad | ¿Se puede probar en aislamiento? | Inyección de dependencias, mocks necesarios |
| Consistencia | ¿Sigue convenciones del proyecto? | [Linting](/concepts/linting-formatting), formateo automático |
| Complejidad | ¿Es más simple de lo necesario? | Complejidad ciclomática, líneas por función |
## Herramientas
| Categoría | Herramientas |
|-----------|-------------|
| Linting | ESLint, Biome, Ruff |
| Formatting | Prettier, Black |
| Type checking | TypeScript, mypy |
| Static analysis | SonarQube, CodeClimate |
| Testing | Jest, Vitest, pytest |
## Automatización en CI
```yaml
- lint: eslint, prettier --check
- typecheck: tsc --noEmit
- test: vitest run
- coverage: vitest --coverage
```
## ¿Por qué importa?
La calidad del código no es un lujo — es lo que determina la velocidad de desarrollo a largo plazo. Código limpio se modifica con confianza, código desordenado genera miedo al cambio. Las prácticas de calidad son una inversión que se paga en cada iteración futura.
## Referencias
- [Clean Code](https://www.oreilly.com/library/view/clean-code-a/9780136083238/) — Robert Martin, 2008. Principios de código limpio y mantenible.
- [Refactoring](https://refactoring.com/) — Martin Fowler, 2018. Catálogo de técnicas para mejorar código existente.
- [ESLint Getting Started](https://eslint.org/docs/latest/use/getting-started) — ESLint, 2024. Herramienta estándar de linting para JavaScript.
---
# Cloud Native
Type: concept
Status: seed
Summary: Development approach leveraging cloud advantages: containers, microservices, immutable infrastructure, and declarative automation for scalable and resilient systems.
Concepts: serverless, docker, kubernetes
## ¿Qué es?
Cloud native es un enfoque para construir aplicaciones que aprovechan al máximo el modelo de computación en la nube. No es solo «correr en la nube» — es diseñar sistemas que explotan elasticidad, automatización y servicios managed.
## Pilares
| Pilar | Principio | Tecnología clave |
|-------|-----------|-----------------|
| [Contenedores](/concepts/docker) | Empaquetado consistente y portable | Docker, containerd |
| [Microservicios](/concepts/microservices) | Componentes pequeños, independientes, desplegables | [Kubernetes](/concepts/kubernetes), [ECS](/concepts/aws-ecs) |
| Infraestructura inmutable | Reemplazar en lugar de modificar | [IaC](/concepts/infrastructure-as-code), AMIs, imágenes |
| APIs declarativas | Describir el estado deseado, no los pasos | Kubernetes manifests, [CDK](/concepts/aws-cdk) |
## CNCF (Cloud Native Computing Foundation)
Organización que gobierna proyectos cloud native:
- Kubernetes (orquestación)
- Prometheus (monitoreo)
- Envoy (service mesh)
- Helm (packaging)
- Argo (GitOps, workflows)
## Cloud Native vs Cloud Hosted
| Aspecto | Cloud Native | Cloud Hosted |
|---------|--------------|---------------|
| Diseño | Para la nube | Migrado a la nube |
| Escalado | Automático, horizontal | Manual o vertical |
| Resiliencia | Diseñada | Añadida después |
| Despliegue | Continuo | Releases grandes |
## ¿Por qué importa?
Cloud-native no es simplemente «ejecutar en la nube». Es un conjunto de prácticas — contenedores, microservicios, CI/CD, infraestructura inmutable — que permiten construir sistemas que escalan, se recuperan de fallos y se actualizan sin downtime.
## Referencias
- [CNCF Cloud Native Definition](https://github.com/cncf/toc/blob/main/DEFINITION.md) — Definición oficial.
- [Cloud Native Landscape](https://landscape.cncf.io/) — Ecosistema de proyectos.
- [CNCF Annual Survey 2023](https://www.cncf.io/reports/cncf-annual-survey-2023/) — CNCF, 2023. Estado de adopción cloud-native.
---
# CLI Design
Type: concept
Status: seed
Summary: Principles for designing intuitive, consistent, and productive command-line interfaces that developers enjoy using.
Concepts: developer-experience, sdk-design
## ¿Qué es?
Un CLI (Command Line Interface) bien diseñado es una herramienta que los desarrolladores usan con placer. Sigue convenciones establecidas, proporciona feedback claro y es descubrible sin leer documentación extensa.
## Principios
| Principio | Qué significa | Ejemplo |
|-----------|-------------|---------|
| Convenciones Unix | Flags cortos y largos, pipes, exit codes | `-v` / `--verbose`, exit 0 = éxito |
| Feedback | Indicar progreso y estado al usuario | Progress bars, spinners, colores |
| Descubribilidad | Fácil de aprender sin documentación externa | `--help` útil, sugerencias ante errores |
| Composabilidad | Output parseable, compatible con pipes | `--json` flag, stdin/stdout |
| Idempotencia | Ejecutar dos veces produce el mismo resultado | `create --if-not-exists` |
## Herramientas para construir CLIs
| Lenguaje | Herramienta |
|----------|-------------|
| Node.js | Commander, oclif, yargs |
| Python | Click, Typer |
| Go | Cobra |
| Rust | clap |
## Ejemplos de CLIs bien diseñados
- `git`: subcomandos, flags consistentes
- `gh` (GitHub CLI): interactivo + scriptable
- `aws`: estructura service → operation
- `pnpm`: rápido, output limpio
## ¿Por qué importa?
Una CLI bien diseñada es la interfaz más eficiente para desarrolladores y scripts de automatización. Los principios de diseño — consistencia, composabilidad, mensajes de error claros — determinan si una herramienta se adopta o se abandona por una alternativa.
## Referencias
- [CLI Guidelines](https://clig.dev/) — Guía de diseño de CLIs.
- [12 Factor CLI Apps](https://12factor.net/) — Heroku, 2012. Principios aplicables al diseño de CLIs.
- [oclif](https://github.com/oclif/oclif) — Salesforce, 2024. Framework para construir CLIs en Node.js.
---
# CI/CD
Type: concept
Status: evergreen
Summary: Continuous Integration and Continuous Delivery/Deployment — practices that automate code integration, testing, and delivery to production. Foundation of modern software engineering.
Concepts: github, github-flow, devops
**CI/CD** son dos prácticas complementarias que automatizan el camino del código desde el commit hasta producción. Juntas eliminan el «integration hell» y permiten releases frecuentes con confianza.
## Continuous Integration (CI)
Integrar código frecuentemente (mínimo diario) a una rama compartida, con verificación automática.
### Principios
1. **Un solo repositorio** — todo el código en un lugar
2. **Commits frecuentes** — integrar cambios pequeños, no acumular
3. **Build automatizado** — cada commit dispara build + tests
4. **Tests rápidos** — feedback en minutos, no horas
5. **Arreglar builds rotos inmediatamente** — prioridad máxima
### Pipeline típico de CI
```
commit → build → lint → unit tests → integration tests → artifact
```
```yaml
# Ejemplo GitHub Actions
jobs:
ci:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
cache: 'pnpm'
- run: pnpm install --frozen-lockfile
- run: pnpm lint
- run: pnpm test
- run: pnpm build
```
## Continuous Delivery vs Continuous Deployment
Dos conceptos distintos que a menudo se confunden:
### Continuous Delivery
El código **puede** ir a producción en cualquier momento — el deploy es manual pero el proceso está automatizado.
```
CI → staging auto → aprobación manual → producción
```
### Continuous Deployment
El código **va** a producción automáticamente si pasa todos los checks — sin intervención humana.
```
CI → staging auto → producción auto
```
| Aspecto | Delivery | Deployment |
|---------|----------|------------|
| Deploy a producción | Manual (botón) | Automático |
| Frecuencia típica | Diaria/semanal | Múltiples veces al día |
| Requiere | Tests confiables | Tests + feature flags + monitoring |
| Riesgo | Menor | Requiere madurez |
## Pipeline completo
```
┌─────────────────────────────────────────────────────────────────┐
│ CI/CD Pipeline │
├─────────┬─────────┬─────────┬─────────┬─────────┬──────────────┤
│ Build │ Test │ Scan │ Package │ Deploy │ Monitor │
├─────────┼─────────┼─────────┼─────────┼─────────┼──────────────┤
│ compile │ unit │ SAST │ docker │ staging │ logs │
│ lint │ integ │ DAST │ helm │ canary │ metrics │
│ deps │ e2e │ secrets │ artifact│ prod │ alerts │
└─────────┴─────────┴─────────┴─────────┴─────────┴──────────────┘
```
### Stages explicados
1. **Build** — compilar, verificar sintaxis, resolver dependencias
2. **Test** — unit, integration, e2e (pirámide de testing)
3. **Scan** — seguridad estática (SAST), dinámica (DAST), secretos
4. **Package** — crear artefacto deployable (Docker image, binary, bundle)
5. **Deploy** — staging → canary → producción
6. **Monitor** — observabilidad post-deploy
## Estrategias de deployment
### Blue-Green
Dos entornos idénticos. Cambiar tráfico instantáneamente.
```
┌─────────┐
Users ───┤ Router ├──► Blue (v1) ← activo
└────┬────┘
└──────► Green (v2) ← standby/nuevo
```
Rollback: cambiar router de vuelta a Blue.
### Canary
Enviar porcentaje pequeño de tráfico a la nueva versión.
```
Users ──┬── 95% ──► v1 (estable)
└── 5% ──► v2 (canary)
```
Incrementar gradualmente si métricas son buenas.
### Rolling
Actualizar instancias una por una.
```
[v1] [v1] [v1] [v1] → [v2] [v1] [v1] [v1] → [v2] [v2] [v2] [v2]
```
## Métricas clave (DORA)
Las cuatro métricas de DevOps Research and Assessment:
| Métrica | Elite | High | Medium | Low |
|---------|-------|------|--------|-----|
| **Deployment frequency** | On-demand (múltiples/día) | Diario-semanal | Semanal-mensual | Mensual+ |
| **Lead time for changes** | < 1 hora | 1 día - 1 semana | 1 semana - 1 mes | 1 mes+ |
| **Change failure rate** | 0-15% | 16-30% | 31-45% | 46%+ |
| **Time to restore** | < 1 hora | < 1 día | < 1 semana | 1 semana+ |
## Herramientas por categoría
| Categoría | Herramientas |
|-----------|--------------|
| **CI/CD Platforms** | GitHub Actions, GitLab CI, Jenkins, CircleCI, Travis CI |
| **Artifact Registry** | Docker Hub, GitHub Packages, AWS ECR, Google Artifact Registry |
| **Infrastructure** | Terraform, Pulumi, AWS CDK, CloudFormation |
| **Kubernetes** | ArgoCD, Flux, Helm, Kustomize |
| **Testing** | Jest, Playwright, Cypress, k6 |
| **Security** | Snyk, Trivy, SonarQube, OWASP ZAP |
| **Monitoring** | Datadog, Grafana, Prometheus, New Relic |
## Anti-patrones
- **Tests lentos** — si CI tarda 30+ minutos, los desarrolladores evitan integrar
- **Flaky tests** — tests que fallan aleatoriamente destruyen la confianza
- **Deploy manual** — si requiere pasos manuales, se acumula trabajo
- **Sin rollback** — cada deploy debe poder revertirse en minutos
- **Secrets en código** — usar secret managers, nunca hardcodear
- **Ignorar alertas** — alert fatigue lleva a ignorar problemas reales
## ¿Por qué importa?
CI/CD es el multiplicador de velocidad más importante en ingeniería de software. Sin CI, los bugs se acumulan y los merges son dolorosos. Sin CD, el código aprobado espera días o semanas para llegar a producción. Las métricas DORA demuestran consistentemente que los equipos con CI/CD maduro entregan más rápido y con mayor estabilidad.
## Referencias
- [Continuous Delivery](https://continuousdelivery.com/) — Jez Humble & David Farley, 2010. El libro que definió la práctica.
- [Accelerate](https://itrevolution.com/product/accelerate/) — Nicole Forsgren, Jez Humble & Gene Kim, 2018. Investigación científica sobre métricas DORA y alto rendimiento.
- [The DevOps Handbook](https://itrevolution.com/product/the-devops-handbook-second-edition/) — Gene Kim et al., 2021. Guía práctica de implementación.
- [Google SRE Book](https://sre.google/sre-book/table-of-contents/) — Google, 2016. Prácticas de Site Reliability Engineering incluyendo CI/CD.
- [Martin Fowler on CI](https://martinfowler.com/articles/continuousIntegration.html) — Martin Fowler, 2006. Artículo seminal que popularizó CI.
---
# Chaos Engineering
Type: concept
Status: seed
Summary: Discipline of experimenting on production systems to discover weaknesses before they cause incidents, by injecting controlled failures.
Concepts: site-reliability-engineering, testing-strategies
## ¿Qué es?
Chaos Engineering es la práctica de inyectar fallos controlados en sistemas para descubrir debilidades antes de que causen incidentes reales. Popularizada por Netflix con Chaos Monkey.
## Principios
1. Definir el estado estable del sistema
2. Hipotetizar que el estado se mantiene ante perturbaciones
3. Introducir variables del mundo real (fallos de red, latencia, crashes)
4. Buscar diferencias entre hipótesis y realidad
## Tipos de experimentos
| Tipo | Qué simula | Qué valida |
|------|-----------|------------|
| Terminar instancias | Fallo de servidor | Auto-healing, redundancia |
| Inyectar latencia | Red degradada | Timeouts, circuit breakers |
| Fallo de dependencias | Servicio externo caído | Fallbacks, graceful degradation |
| Agotar recursos | CPU/memoria/disco al límite | Autoscaling, alertas |
| Corrupción de datos | Datos inconsistentes | Validación, reconciliación |
## Herramientas
| Herramienta | Enfoque |
|-------------|--------|
| Chaos Monkey | Terminar instancias (Netflix) |
| Gremlin | Plataforma SaaS completa |
| Litmus | Kubernetes-native (CNCF) |
| AWS FIS | Fault Injection Simulator |
## Precauciones
- Empezar en ambientes no productivos
- Tener rollback automático
- Comunicar experimentos al equipo
- Minimizar blast radius
## ¿Por qué importa?
Los sistemas distribuidos fallan de formas impredecibles. Chaos engineering convierte esas fallas en eventos planificados y controlados, revelando debilidades antes de que se conviertan en incidentes en producción. Es la práctica que construye confianza real en la resiliencia del sistema.
## Referencias
- [Principles of Chaos Engineering](https://principlesofchaos.org/) — Manifiesto.
- [Chaos Monkey](https://netflix.github.io/chaosmonkey/) — Netflix, 2024. La herramienta original de chaos engineering.
- [Chaos Engineering: History, Principles, and Practice](https://www.gremlin.com/community/tutorials/chaos-engineering-the-history-principles-and-practice) — Gremlin, 2024. Historia y principios de chaos engineering.
---
# Chain-of-Thought
Type: concept
Status: seed
Summary: Prompting technique that improves LLM reasoning by asking them to decompose complex problems into explicit intermediate steps before reaching a conclusion.
Concepts: prompt-engineering, ai-agents
## ¿Qué es?
Chain-of-Thought (CoT) es una técnica de [prompt engineering](/concepts/prompt-engineering) que mejora dramáticamente la capacidad de razonamiento de los [LLMs](/concepts/large-language-models) al pedirles que «piensen paso a paso». En lugar de saltar directamente a la respuesta, el modelo genera pasos intermedios de razonamiento que lo guían hacia conclusiones más precisas.
Introducido por Wei et al. en 2022, CoT demostró que los modelos grandes pueden resolver problemas de matemáticas, lógica y sentido común que antes fallaban consistentemente.
## ¿Por qué funciona?
Los LLMs predicen tokens secuencialmente. Cuando generan pasos intermedios:
- Cada paso proporciona contexto para el siguiente
- Los errores se hacen visibles y corregibles
- El modelo «trabaja» el problema en lugar de adivinar
- Se activan capacidades de razonamiento latentes en el modelo
## Variantes
### Zero-shot CoT
Simplemente agregar «Pensemos paso a paso» al prompt:
```
¿Cuántas manzanas quedan si tengo 15 y regalo 7?
Pensemos paso a paso.
```
### Few-shot CoT
Proporcionar ejemplos con razonamiento explícito:
```
Ejemplo: Si tengo 10 naranjas y como 3, quedan 10-3=7 naranjas.
Pregunta: Si tengo 15 manzanas y regalo 7, ¿cuántas quedan?
```
### Self-Consistency
Generar múltiples cadenas de razonamiento y elegir la respuesta más frecuente. Mejora la precisión a costa de más tokens.
### Tree of Thoughts
Explorar múltiples ramas de razonamiento en paralelo, evaluando y podando caminos menos prometedores.
## Aplicaciones
- **Matemáticas**: problemas de aritmética, álgebra, word problems
- **Lógica**: puzzles, deducciones, análisis de argumentos
- **Código**: debugging, diseño de algoritmos
- **Planificación**: descomponer tareas complejas en pasos ejecutables
- **Agentes**: los [agentes de IA](/concepts/ai-agents) usan CoT internamente para decidir acciones
## Limitaciones
- **Costo**: más tokens = más latencia y costo
- **No infalible**: el razonamiento puede ser plausible pero incorrecto
- **Modelos pequeños**: CoT funciona mejor en modelos grandes (>10B parámetros)
## ¿Por qué importa?
Chain-of-thought es la técnica de prompting que más consistentemente mejora el rendimiento de los LLMs en tareas de razonamiento. Entender cuándo y cómo aplicarla — y sus limitaciones — es una habilidad fundamental para cualquier ingeniero que construya aplicaciones con modelos de lenguaje.
## Referencias
- [Chain-of-Thought Prompting Elicits Reasoning in Large Language Models](https://arxiv.org/abs/2201.11903) — Wei et al., 2022.
- [Self-Consistency Improves Chain of Thought Reasoning](https://arxiv.org/abs/2203.11171) — Wang et al., 2022.
- [Tree of Thoughts](https://arxiv.org/abs/2305.10601) — Yao et al., 2023.
---
# Backstage
Type: concept
Status: seed
Summary: Spotify's open-source platform for building developer portals, with service catalog, templates, and extensible plugin system.
Concepts: internal-developer-platforms, developer-portals, golden-paths, developer-experience
## ¿Qué es?
Backstage es una plataforma open-source creada por Spotify y donada a CNCF para construir [portales de desarrollador](/concepts/developer-portals). Proporciona un catálogo de servicios, templates de proyectos y un sistema de plugins extensible.
## Componentes core
- **Software Catalog**: inventario de todos los servicios, bibliotecas y recursos
- **Software Templates**: scaffolding de nuevos proyectos
- **TechDocs**: documentación como código integrada
- **Search**: búsqueda unificada across plugins
## Plugins populares
- Kubernetes: estado de deployments
- CI/CD: GitHub Actions, Jenkins, ArgoCD
- Cloud: AWS, GCP cost dashboards
- Observability: Grafana, PagerDuty
## Cuándo usar Backstage
- Organización con >50 desarrolladores
- Múltiples equipos y servicios
- Necesidad de estandarización
- Equipo de plataforma dedicado para mantenerlo
## Alternativas a Backstage
| Plataforma | Tipo | Fortaleza | Limitación |
|-----------|------|-----------|------------|
| Backstage | Open source (CNCF) | Máxima personalización, ecosistema de plugins | Requiere equipo dedicado para mantener |
| Port | Comercial | Setup rápido, UI pulida | Menos personalizable, costo por usuario |
| Cortex | Comercial | Scorecards de madurez de servicios | Enfocado en catálogo, menos extensible |
| OpsLevel | Comercial | Integraciones pre-construidas | Menos flexible que Backstage |
## ¿Por qué importa?
Backstage transformó la idea de un portal de desarrolladores de un proyecto interno de Spotify a un estándar de la industria. Para organizaciones con decenas de servicios y equipos, es la forma de hacer que la infraestructura, la documentación y las herramientas sean descubribles desde un solo lugar.
## Referencias
- [Backstage](https://backstage.io/) — Spotify, 2020. Sitio oficial.
- [Backstage Plugins](https://backstage.io/plugins) — Catálogo de plugins de la comunidad.
- [What is Backstage?](https://backstage.io/docs/overview/what-is-backstage/) — Backstage, 2024. Documentación oficial.
---
# Backend for Frontend
Type: concept
Status: seed
Summary: Pattern where each client type (web, mobile, IoT) has its own dedicated backend adapting microservice APIs to that client's specific needs.
Concepts: micro-frontends, api-design, api-gateway-pattern, microservices
## ¿Qué es?
Backend for Frontend (BFF) es un patrón donde cada tipo de cliente tiene su propio backend dedicado. En lugar de un API Gateway genérico, cada BFF adapta, agrega y transforma datos específicamente para su cliente.
## ¿Por qué?
- Web necesita datos diferentes que mobile
- Cada cliente tiene diferentes restricciones de red
- Evita un API Gateway «god object» que intenta servir a todos
- Cada equipo frontend controla su BFF
## Estructura
```
Web App → BFF Web → Microservicios
Mobile App → BFF Mobile → Microservicios
IoT Device → BFF IoT → Microservicios
```
## Cuándo usar
- Múltiples tipos de cliente con necesidades diferentes
- Equipos frontend que necesitan autonomía
- APIs de microservicios demasiado granulares para consumo directo
## ¿Cuándo no usar?
- Un solo tipo de cliente — un API Gateway genérico es suficiente
- Equipos pequeños donde mantener múltiples BFFs es overhead
- Cuando las diferencias entre clientes son mínimas (solo formato de respuesta)
## BFF vs API Gateway
| Aspecto | BFF | API Gateway |
|---------|-----|-------------|
| Propósito | Adaptar datos por cliente | Enrutar y proteger |
| Propiedad | Equipo frontend | Equipo de plataforma |
| Lógica | Agregación y transformación | Routing y auth |
| Cantidad | Uno por tipo de cliente | Uno centralizado |
Un BFF puede vivir detrás de un [API Gateway](/concepts/api-gateway-pattern) — no son mutuamente excluyentes.
## ¿Por qué importa?
El patrón BFF resuelve el problema de una API genérica que intenta servir a múltiples clientes con necesidades diferentes. En lugar de sobrecargar un solo backend, cada frontend tiene su propio backend optimizado para sus patrones de acceso específicos.
## Referencias
- [BFF Pattern](https://samnewman.io/patterns/architectural/bff/) — Sam Newman. El artículo original que definió el patrón.
- [Backends for Frontends](https://learn.microsoft.com/en-us/azure/architecture/patterns/backends-for-frontends) — Microsoft, Azure Architecture Center.
- [The Back-end for Front-end Pattern](https://philcalcado.com/2015/09/18/the_back_end_for_front_end_pattern_bff.html) — Phil Calçado, 2015. Análisis detallado del patrón BFF.
---
# AWS Well-Architected Framework
Type: concept
Status: seed
Summary: AWS framework with six pillars of best practices for designing and operating reliable, secure, efficient, and cost-effective cloud systems.
Concepts: maturity-models, devops-practices, site-reliability-engineering
## ¿Qué es?
El AWS Well-Architected Framework es un conjunto de mejores prácticas organizadas en seis pilares para evaluar y mejorar arquitecturas cloud. Funciona como un [modelo de madurez](/concepts/maturity-models) específico para AWS.
## Los seis pilares
| Pilar | Pregunta clave | Herramientas AWS |
|-------|---------------|-----------------|
| Excelencia operacional | ¿Cómo operas y mejoras tus workloads? | CloudWatch, Systems Manager, CloudFormation |
| Seguridad | ¿Cómo proteges datos y sistemas? | [IAM](/concepts/aws-iam), KMS, GuardDuty, Security Hub |
| Confiabilidad | ¿Cómo te recuperas de fallos? | Auto Scaling, Route 53, [S3](/concepts/aws-s3) cross-region |
| Eficiencia de rendimiento | ¿Usas los recursos correctos? | Compute Optimizer, [Lambda](/concepts/aws-lambda), ElastiCache |
| Optimización de costos | ¿Eliminas gastos innecesarios? | Cost Explorer, Savings Plans, [S3 tiers](/concepts/aws-s3) |
| Sostenibilidad | ¿Minimizas el impacto ambiental? | Graviton, Spot Instances, right-sizing |
## Well-Architected Tool
AWS proporciona una herramienta en la consola para realizar reviews guiadas de tus workloads contra los pilares, generando un plan de mejora priorizado.
## Lenses especializadas
- Serverless Lens
- SaaS Lens
- Machine Learning Lens
- Data Analytics Lens
## ¿Cuándo hacer un review?
- Al diseñar un nuevo workload (antes de construir)
- Antes de ir a producción
- Periódicamente (cada 6-12 meses) para workloads existentes
- Después de un incidente significativo
## ¿Por qué importa?
El Well-Architected Framework es la guía de referencia para evaluar arquitecturas en AWS. Sus seis pilares — excelencia operacional, seguridad, confiabilidad, eficiencia, optimización de costos y sostenibilidad — proporcionan un lenguaje común para discutir trade-offs arquitectónicos.
## Referencias
- [Well-Architected Framework](https://docs.aws.amazon.com/wellarchitected/latest/framework/) — AWS, 2024. Documentación oficial.
- [Well-Architected Labs](https://wellarchitectedlabs.com/) — AWS, 2024. Ejercicios prácticos.
- [Well-Architected Pillars](https://docs.aws.amazon.com/wellarchitected/latest/framework/the-pillars-of-the-framework.html) — AWS, 2024. Los seis pilares del framework.
---
# AWS Step Functions
Type: concept
Status: seed
Summary: AWS serverless orchestration service that coordinates multiple services into visual workflows, with built-in error handling, retries, and parallel execution.
Concepts: serverless, agentic-workflows
## ¿Qué es?
AWS Step Functions es un servicio de orquestación que coordina múltiples servicios AWS en workflows serverless. Define flujos como máquinas de estado con pasos, condiciones, paralelismo y manejo de errores — todo visual y declarativo.
## Tipos de workflow
| Tipo | Duración | Costo | Uso |
|------|----------|-------|-----|
| Standard | Hasta 1 año | Por transición | Workflows largos, durables |
| Express | Hasta 5 min | Por ejecución/duración | Alto volumen, baja latencia |
## Estados disponibles
| Estado | Función | Ejemplo |
|--------|---------|---------|
| Task | Ejecuta trabajo | Lambda, ECS, API call |
| Choice | Branching condicional | Validar input, rutas por tipo |
| Parallel | Ejecución paralela de ramas | Procesar datos + enviar notificación |
| Map | Iteración sobre arrays | Procesar cada item de un pedido |
| Wait | Pausa por tiempo | Esperar 24h antes de retry |
| Pass | Transformación de datos | Reformatear payload entre pasos |
| Succeed/Fail | Terminación explícita | Marcar workflow como completado o fallido |
## Patrones comunes
- **Saga pattern**: transacciones distribuidas con compensación
- **Human approval**: pausar workflow esperando aprobación
- **ETL pipelines**: procesamiento de datos en pasos
- **AI/ML pipelines**: orquestar entrenamiento e inferencia
## ¿Por qué importa?
Step Functions convierte flujos de trabajo complejos en máquinas de estado visuales y auditables. En lugar de orquestar Lambda con código custom, defines el flujo declarativamente con manejo de errores, reintentos y paralelismo integrados.
## Referencias
- [Step Functions Documentation](https://docs.aws.amazon.com/step-functions/) — Documentación oficial.
- [Serverless Land - Step Functions](https://serverlessland.com/patterns?services=step-functions) — Patrones.
- [Step Functions Best Practices](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-best-practices.html) — AWS, 2024. Mejores prácticas para máquinas de estado.
---
# AWS SQS
Type: concept
Status: seed
Summary: AWS fully managed message queue service that decouples distributed application components, guaranteeing message delivery with unlimited scalability.
Concepts: serverless, event-driven-architecture, aws-sns
## ¿Qué es?
Amazon SQS (Simple Queue Service) es un servicio de colas de mensajes que desacopla productores y consumidores en sistemas distribuidos. Los mensajes se almacenan de forma durable hasta que son procesados, absorbiendo picos de carga y garantizando que ningún mensaje se pierda.
## Tipos de cola
| Tipo | Orden | Deduplicación | Throughput |
|------|-------|---------------|------------|
| Standard | Best-effort | At-least-once | Ilimitado |
| FIFO | Garantizado | Exactly-once | 3,000 msg/s (con batching) |
## Conceptos clave
- **Visibility timeout**: tiempo que un mensaje es invisible después de ser leído
- **Dead-letter queue (DLQ)**: cola para mensajes que fallan repetidamente
- **Long polling**: reduce requests vacíos esperando mensajes
- **Message groups**: paralelismo ordenado en FIFO
## Patrón típico
```
Producer → SQS Queue → Lambda (consumer)
↓ (fallos)
Dead-letter queue → Alerta
```
## ¿Cuándo usar SQS vs comunicación directa?
- Cuando el productor no necesita esperar la respuesta del consumidor
- Cuando el consumidor puede estar temporalmente caído sin perder mensajes
- Cuando necesitas controlar la tasa de procesamiento (throttling natural)
## ¿Por qué importa?
SQS es el servicio de colas más usado en AWS y la forma más simple de desacoplar componentes. Con colas estándar para alto throughput y FIFO para orden garantizado, es la base de patrones como work queues, buffering y procesamiento asíncrono.
## Referencias
- [SQS Documentation](https://docs.aws.amazon.com/sqs/) — AWS, 2024. Documentación oficial.
- [SQS Best Practices](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-best-practices.html) — AWS, 2024. Mejores prácticas para colas.
- [SQS Pricing](https://aws.amazon.com/sqs/pricing/) — AWS, 2024. Modelo de precios.
---
# AWS SNS
Type: concept
Status: seed
Summary: AWS pub/sub messaging service that distributes messages to multiple subscribers simultaneously, enabling fan-out patterns and notifications at scale.
Concepts: serverless, aws-sqs, event-driven-architecture
## ¿Qué es?
Amazon SNS (Simple Notification Service) es un servicio de mensajería pub/sub que envía mensajes a múltiples suscriptores simultáneamente. Un publicador envía un mensaje a un topic, y todos los suscriptores lo reciben.
## SNS vs SQS
| Aspecto | SNS | SQS |
|---------|-----|-----|
| Modelo | Pub/Sub (fan-out) | Queue (point-to-point) |
| Persistencia | No (push inmediato) | Sí (hasta 14 días) |
| Consumidores | Múltiples | Uno por mensaje |
| Uso típico | Notificaciones, fan-out | Desacoplamiento, buffering |
## Patrón SNS + SQS (Fan-out)
```
Producer → SNS Topic → SQS Queue A → Consumer A
→ SQS Queue B → Consumer B
→ Lambda → Processing
→ Email → Notification
```
## Tipos de suscriptores
- Lambda, SQS, HTTP/HTTPS endpoints
- Email, SMS
- Kinesis Data Firehose
- Mobile push notifications
## Buenas prácticas
- Usar filtros de suscripción para que cada consumidor reciba solo los mensajes relevantes
- Habilitar dead-letter queues en las suscripciones SQS para mensajes que fallan repetidamente
- Preferir FIFO topics cuando el orden de los mensajes importa
## ¿Por qué importa?
SNS es el pegamento de las arquitecturas event-driven en AWS. Permite desacoplar productores de consumidores con pub/sub, fan-out a múltiples destinos y entrega a SQS, Lambda, HTTP y email. Es la pieza que conecta servicios sin crear dependencias directas.
## Referencias
- [SNS Documentation](https://docs.aws.amazon.com/sns/) — AWS, 2024. Documentación oficial.
- [SNS Message Filtering](https://docs.aws.amazon.com/sns/latest/dg/sns-message-filtering.html) — AWS, 2024. Filtrado de mensajes por suscripción.
- [SNS Pricing](https://aws.amazon.com/sns/pricing/) — AWS, 2024. Modelo de precios.
---
# AWS SAM
Type: concept
Status: seed
Summary: AWS open-source framework for building serverless applications with simplified CloudFormation syntax, CLI for local development, and integrated deployment.
Concepts: serverless, aws-lambda, ci-cd
## ¿Qué es?
AWS SAM (Serverless Application Model) es un framework que simplifica la definición y despliegue de aplicaciones [serverless](/concepts/serverless). Extiende CloudFormation con recursos de alto nivel (`AWS::Serverless::Function`, `AWS::Serverless::Api`) y proporciona un CLI para desarrollo local.
## SAM vs CDK
| Aspecto | SAM | CDK |
|---------|-----|-----|
| Formato | YAML (declarativo) | TypeScript/Python (imperativo) |
| Curva de aprendizaje | Menor | Mayor |
| Desarrollo local | `sam local` integrado | Requiere herramientas adicionales |
| Flexibilidad | Serverless-focused | Cualquier recurso AWS |
## CLI destacado
- `sam init`: scaffolding de proyecto
- `sam build`: compilar funciones
- `sam local invoke`: ejecutar Lambda localmente
- `sam local start-api`: API Gateway local
- `sam deploy`: desplegar a AWS
- `sam sync`: sincronización rápida en desarrollo
## Ejemplo template.yaml
```yaml
Resources:
HelloFunction:
Type: AWS::Serverless::Function
Properties:
Handler: index.handler
Runtime: nodejs20.x
Events:
Api:
Type: Api
Properties:
Path: /hello
Method: get
```
## ¿Por qué importa?
SAM simplifica el desarrollo serverless al proporcionar una sintaxis concisa sobre CloudFormation y herramientas de desarrollo local. Para equipos que construyen APIs con Lambda y API Gateway, SAM reduce el boilerplate y permite probar funciones localmente antes de desplegar.
## Referencias
- [SAM Documentation](https://docs.aws.amazon.com/serverless-application-model/) — Documentación oficial.
- [SAM CLI Reference](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference.html) — AWS, 2024. Referencia de comandos del CLI.
- [AWS SAM](https://aws.amazon.com/serverless/sam/) — AWS, 2024. Página oficial del producto.
---
# AWS S3
Type: concept
Status: seed
Summary: AWS object storage service with 99.999999999% durability, unlimited scalability, and multiple storage classes for cost optimization.
Concepts: serverless, infrastructure-as-code
## ¿Qué es?
Amazon S3 (Simple Storage Service) es almacenamiento de objetos con durabilidad de 11 nueves (99.999999999%). Almacena cualquier cantidad de datos — desde bytes hasta petabytes — con acceso vía HTTP/HTTPS. Es la base de innumerables arquitecturas en AWS.
## Conceptos clave
- **Bucket**: contenedor de objetos (nombre globalmente único)
- **Object**: archivo + metadata (hasta 5TB por objeto)
- **Key**: ruta/nombre del objeto dentro del bucket
- **Versioning**: historial de versiones de cada objeto
## Clases de almacenamiento
| Clase | Uso | Costo |
|-------|-----|-------|
| Standard | Acceso frecuente | Base |
| Intelligent-Tiering | Acceso variable | Auto-optimiza |
| Standard-IA | Acceso infrecuente | -40% |
| Glacier | Archivos, minutos de retrieval | -70% |
| Glacier Deep Archive | Archivos, horas de retrieval | -95% |
## Integraciones serverless
- **Event notifications**: trigger Lambda cuando se sube/modifica un objeto
- **Static website hosting**: servir sitios estáticos directamente
- **CloudFront**: CDN para distribución global
- **Athena**: queries SQL sobre datos en S3
## Seguridad
- Bucket policies y ACLs para control de acceso
- Encriptación server-side (SSE-S3, SSE-KMS)
- Block Public Access por defecto
- Access Points para acceso granular
## ¿Por qué importa?
S3 es el servicio más fundamental de AWS — almacenamiento de objetos con durabilidad de 11 nueves. Es la base para data lakes, backups, hosting estático, artefactos de CI/CD y distribución de contenido. Dominar sus clases de almacenamiento y políticas de ciclo de vida es esencial para optimizar costos.
## Referencias
- [S3 Documentation](https://docs.aws.amazon.com/s3/) — Documentación oficial.
- [S3 Security Best Practices](https://docs.aws.amazon.com/AmazonS3/latest/userguide/security-best-practices.html) — AWS, 2024. Mejores prácticas de seguridad.
- [S3 Storage Classes](https://aws.amazon.com/s3/storage-classes/) — AWS, 2024. Clases de almacenamiento y optimización de costos.
---
# AWS Lambda
Type: concept
Status: seed
Summary: AWS serverless compute service that runs code in response to events without provisioning or managing servers, automatically scaling from zero to thousands of concurrent executions.
Concepts: serverless, infrastructure-as-code
## ¿Qué es?
AWS Lambda es el servicio de Functions as a Service (FaaS) de Amazon. Permite ejecutar código sin aprovisionar servidores — subes tu función, defines qué eventos la disparan, y AWS se encarga del resto: aprovisionamiento, escalado, alta disponibilidad y monitoreo.
## Modelo de ejecución
1. Un evento dispara la función (HTTP request, mensaje SQS, archivo en S3, etc.)
2. Lambda aprovisiona un entorno de ejecución (o reutiliza uno existente)
3. Tu código se ejecuta
4. Lambda cobra por duración (ms) y memoria asignada
5. El entorno puede mantenerse «caliente» para requests subsecuentes
## Características clave
- **Runtimes**: Node.js, Python, Java, Go, .NET, Ruby, o custom (container)
- **Memoria**: 128 MB a 10 GB (CPU escala proporcionalmente)
- **Duración máxima**: 15 minutos por invocación
- **Concurrencia**: hasta 1000 por defecto (ampliable)
- **Layers**: bibliotecas compartidas entre funciones
- **Provisioned concurrency**: elimina cold starts para funciones críticas
## Triggers comunes
| Trigger | Caso de uso |
|---------|-------------|
| API Gateway | APIs REST/HTTP |
| S3 | Procesamiento de archivos |
| DynamoDB Streams | Reacción a cambios en datos |
| SQS | Procesamiento de colas |
| EventBridge | Eventos programados o de servicios |
| Cognito | Hooks de autenticación |
## Cold starts
El «cold start» ocurre cuando Lambda debe inicializar un nuevo entorno:
- Típicamente 100ms-1s para runtimes interpretados
- Puede ser varios segundos para Java/.NET
- Mitigación: provisioned concurrency, mantener funciones pequeñas, SnapStart (Java)
## Mejores prácticas
- Mantener funciones pequeñas y enfocadas
- Reutilizar conexiones (DB, HTTP) fuera del handler
- Usar variables de entorno para configuración
- Implementar idempotencia para reintentos
- Monitorear con CloudWatch y X-Ray
## ¿Por qué importa?
Lambda cambió la forma de pensar sobre infraestructura: en lugar de provisionar servidores, defines funciones que se ejecutan en respuesta a eventos. Para cargas de trabajo con tráfico variable, el modelo de pago por ejecución puede reducir costos en órdenes de magnitud respecto a servidores siempre encendidos.
## Referencias
- [AWS Lambda Documentation](https://docs.aws.amazon.com/lambda/) — Documentación oficial.
- [Lambda Power Tuning](https://github.com/alexcasalboni/aws-lambda-power-tuning) — Herramienta para optimizar memoria/costo.
- [Lambda Best Practices](https://docs.aws.amazon.com/lambda/latest/dg/best-practices.html) — AWS, 2024. Mejores prácticas oficiales para funciones Lambda.
---
# AWS IAM
Type: concept
Status: seed
Summary: AWS identity and access management service controlling who can do what in your account, with granular policies based on the principle of least privilege.
Concepts: aws-lambda, infrastructure-as-code
## ¿Qué es?
AWS IAM (Identity and Access Management) controla la autenticación y autorización en AWS. Define quién (identidad) puede hacer qué (permisos) en qué recursos (scope). Es el sistema nervioso de seguridad de cualquier cuenta AWS.
## Conceptos clave
- **Users**: identidades para personas
- **Roles**: identidades para servicios y aplicaciones (preferido sobre users)
- **Policies**: documentos JSON que definen permisos
- **Groups**: colecciones de users con políticas compartidas
## Tipos de políticas
| Tipo | Alcance |
|------|--------|
| Identity-based | Adjuntas a users, groups, roles |
| Resource-based | Adjuntas a recursos (S3 bucket policy) |
| Permission boundaries | Límite máximo de permisos |
| Service control policies | Límites a nivel de organización |
## Principio de mínimo privilegio
Cada identidad debe tener solo los permisos estrictamente necesarios. En la práctica:
- Empezar sin permisos y agregar según necesidad
- Usar IAM Access Analyzer para identificar permisos no usados
- Preferir roles sobre access keys
- Rotar credenciales regularmente
## IAM y Lambda
Cada función [Lambda](/concepts/aws-lambda) tiene un execution role que define qué servicios AWS puede invocar. Definir roles específicos por función, no compartir roles genéricos.
## ¿Por qué importa?
IAM es el sistema nervioso de la seguridad en AWS. Cada llamada a la API pasa por IAM. Entender políticas, roles y el principio de mínimo privilegio no es opcional — es la base sobre la que se construye cualquier arquitectura segura en la nube.
## Referencias
- [IAM Documentation](https://docs.aws.amazon.com/iam/) — Documentación oficial.
- [IAM Best Practices](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) — AWS, 2024. Mejores prácticas de seguridad.
- [IAM Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) — AWS, 2024. Guía de políticas de acceso.
---
# AWS Fargate
Type: concept
Status: seed
Summary: Serverless compute engine for containers that eliminates server management, allowing Docker container execution paying only for consumed resources.
Concepts: aws-ecs, serverless
## ¿Qué es?
AWS Fargate es un motor de cómputo [serverless](/concepts/serverless) para contenedores. Funciona con [ECS](/concepts/aws-ecs) y EKS, eliminando la necesidad de aprovisionar y gestionar instancias EC2. Defines CPU y memoria para tu contenedor, y Fargate se encarga del resto.
## Fargate vs EC2 Launch Type
| Aspecto | Fargate | EC2 |
|---------|---------|-----|
| Gestión de servidores | Ninguna | Tú gestionas |
| Escalado | Por task | Por instancia |
| Costo | Mayor por unidad | Menor con reservas |
| Ideal para | Cargas variables, equipos pequeños | Cargas predecibles, optimización de costo |
## Cuándo usar Fargate
- Equipos que no quieren gestionar infraestructura
- Cargas de trabajo con demanda variable
- Microservicios con diferentes requisitos de recursos
- Batch jobs que necesitan más de 15 min (límite de Lambda)
## Características
- **Spot**: hasta 70% de descuento para cargas tolerantes a interrupciones
- **Ephemeral storage**: hasta 200 GB por task
- **GPU support**: para cargas de ML/AI
## ¿Por qué importa?
Fargate elimina la gestión de servidores para contenedores. No hay instancias que parchear, escalar o monitorear — solo defines CPU, memoria y tu imagen de contenedor. Es la opción por defecto para cargas de trabajo en contenedores que no requieren acceso al host.
## Referencias
- [Fargate Documentation](https://docs.aws.amazon.com/AmazonECS/latest/userguide/what-is-fargate.html) — Documentación oficial.
- [Fargate Task Definitions](https://docs.aws.amazon.com/AmazonECS/latest/userguide/fargate-task-defs.html) — AWS, 2024. Configuración de tareas en Fargate.
- [Fargate Pricing](https://aws.amazon.com/fargate/pricing/) — AWS, 2024. Modelo de precios por vCPU y memoria.
---
# AWS EventBridge
Type: concept
Status: seed
Summary: AWS serverless event bus connecting applications using events, enabling decoupled event-driven architectures with rule-based routing.
Concepts: serverless, event-driven-architecture
## ¿Qué es?
Amazon EventBridge es un bus de eventos serverless que facilita la construcción de [arquitecturas event-driven](/concepts/event-driven-architecture). Recibe eventos de fuentes AWS, aplicaciones propias y SaaS, y los enruta a targets basándose en reglas de contenido.
## Conceptos clave
| Componente | Función | Ejemplo |
|-----------|---------|---------|
| Event bus | Canal por donde fluyen los eventos | Bus default, bus custom por dominio |
| Rules | Filtros que determinan qué eventos van a qué targets | `source: "orders"` → Lambda |
| Targets | Destinos de los eventos | Lambda, SQS, [Step Functions](/concepts/aws-step-functions), API destinations |
| Schemas | Estructura de los eventos | Auto-descubierta o definida en Schema Registry |
| Pipes | Conexiones punto a punto con transformación | SQS → filtro → enriquecimiento → Lambda |
## Patrones
- **Fan-out**: un evento dispara múltiples targets
- **Event replay**: re-procesar eventos históricos
- **Cross-account**: eventos entre cuentas AWS
- **Scheduled events**: cron jobs serverless
- **SaaS integration**: eventos de Zendesk, Shopify, etc.
## Cuándo usar EventBridge vs SQS/SNS
| Aspecto | EventBridge | SQS/SNS |
|---------|-------------|----------|
| Routing | Content-based | Topic/queue |
| Schema | Registry integrado | Sin schema |
| SaaS | Integraciones nativas | Manual |
| Costo | Por evento | Por mensaje |
## ¿Por qué importa?
EventBridge es el bus de eventos serverless que conecta servicios AWS, aplicaciones propias y SaaS de terceros. Permite construir arquitecturas event-driven sin gestionar infraestructura de mensajería, con filtrado de eventos basado en contenido y entrega garantizada.
## Referencias
- [EventBridge Documentation](https://docs.aws.amazon.com/eventbridge/) — Documentación oficial.
- [EventBridge Event Patterns](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-event-patterns.html) — AWS, 2024. Patrones de filtrado de eventos.
- [Serverless Land — EventBridge](https://serverlessland.com/patterns?services=eventbridge) — AWS, 2024. Patrones serverless con EventBridge.
---
# AWS ECS
Type: concept
Status: seed
Summary: AWS container orchestration service that runs and scales Docker applications without managing the underlying cluster infrastructure.
Concepts: docker, terraform
## ¿Qué es?
Amazon ECS (Elastic Container Service) es el servicio de orquestación de contenedores de AWS. Ejecuta contenedores [Docker](/concepts/docker) a escala con dos modos de lanzamiento: EC2 (tú gestionas las instancias) y [Fargate](/concepts/aws-fargate) (serverless, AWS gestiona todo).
## Conceptos clave
| Concepto | Función | Equivalente en K8s |
|----------|---------|-------------------|
| Task Definition | Blueprint del contenedor (imagen, CPU, memoria, puertos) | Pod spec |
| Task | Instancia en ejecución de una task definition | Pod |
| Service | Mantiene N tasks corriendo con load balancing | Deployment + Service |
| Cluster | Agrupación lógica de tasks y services | Cluster + Namespace |
## ECS vs EKS
| Aspecto | ECS | EKS |
|---------|-----|-----|
| Complejidad | Menor, nativo AWS | Mayor, estándar Kubernetes |
| Portabilidad | Lock-in AWS | Multi-cloud |
| Ecosistema | AWS tools | Ecosistema K8s completo |
| Costo | Sin control plane fee | $0.10/hr por cluster |
## Patrones comunes
- **Microservicios**: cada servicio como un ECS service con ALB
- **Batch processing**: tasks que procesan y terminan
- **Sidecar**: contenedores auxiliares junto al principal
## ¿Por qué importa?
ECS es la forma más directa de ejecutar contenedores en AWS sin la complejidad operacional de Kubernetes. Con Fargate, elimina la gestión de instancias EC2, y con integración nativa a ALB, CloudWatch y IAM, es la opción pragmática para equipos que no necesitan la portabilidad de Kubernetes.
## Referencias
- [ECS Documentation](https://docs.aws.amazon.com/ecs/) — Documentación oficial.
- [ECS Best Practices Guide](https://docs.aws.amazon.com/AmazonECS/latest/bestpracticesguide/) — AWS, 2024. Mejores prácticas para contenedores en ECS.
- [ECS Pricing](https://aws.amazon.com/ecs/pricing/) — AWS, 2024. Modelo de precios.
---
# AWS DynamoDB
Type: concept
Status: seed
Summary: AWS serverless NoSQL database with single-digit millisecond latency at any scale, ideal for applications requiring high performance and automatic scalability.
Concepts: serverless, aws-lambda
## ¿Qué es?
DynamoDB es la base de datos NoSQL serverless de AWS. Ofrece latencia consistente de milisegundos sin importar el tamaño de los datos o el volumen de requests. No hay servidores que administrar, parches que aplicar ni capacidad que planificar manualmente.
## Modelo de datos
- **Tablas**: colecciones de items
- **Items**: registros individuales (similar a filas)
- **Atributos**: campos dentro de un item (schema flexible)
- **Partition Key**: clave primaria para distribución
- **Sort Key**: opcional, para ordenamiento dentro de una partición
## Modos de capacidad
| Modo | Características |
|------|----------------|
| On-demand | Pago por request, escala automática, ideal para cargas impredecibles |
| Provisioned | Capacidad reservada, más barato para cargas predecibles |
## Características clave
- **Global Tables**: replicación multi-región automática
- **Streams**: captura de cambios para event-driven architectures
- **TTL**: expiración automática de items
- **DAX**: cache in-memory para microsegundos de latencia
- **Transactions**: operaciones ACID across items
## Patrones de acceso
DynamoDB requiere diseñar el schema alrededor de los patrones de acceso, no de las entidades. Single-table design es común para minimizar queries.
## ¿Por qué importa?
DynamoDB es la base de datos serverless por defecto en AWS. Su modelo de pricing por request y su latencia de milisegundos la hacen ideal para aplicaciones de alto tráfico, pero su modelo de datos requiere pensar en patrones de acceso antes de diseñar el esquema — un cambio mental respecto a bases de datos relacionales.
## Referencias
- [DynamoDB Documentation](https://docs.aws.amazon.com/dynamodb/) — Documentación oficial.
- [The DynamoDB Book](https://www.dynamodbbook.com/) — Alex DeBrie. Guía definitiva de modelado.
- [DynamoDB Best Practices](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/best-practices.html) — AWS, 2024. Mejores prácticas de modelado y rendimiento.
---
# AWS CloudFormation
Type: concept
Status: seed
Summary: AWS native service for defining and provisioning infrastructure as code using YAML or JSON templates, with state management and automatic rollback.
Concepts: infrastructure-as-code, aws-cdk, terraform
## ¿Qué es?
AWS CloudFormation es el servicio nativo de [infraestructura como código](/concepts/infrastructure-as-code) de AWS. Define recursos en plantillas YAML/JSON, y CloudFormation se encarga de crear, actualizar y eliminar recursos en el orden correcto, con rollback automático si algo falla.
## Conceptos clave
- **Template**: archivo YAML/JSON que describe los recursos
- **Stack**: instancia de un template desplegado
- **Change set**: preview de cambios antes de aplicar
- **Drift detection**: detectar cambios manuales fuera de CloudFormation
- **StackSets**: desplegar stacks en múltiples cuentas/regiones
## CloudFormation como base
Tanto [CDK](/concepts/aws-cdk) como [SAM](/concepts/aws-sam) generan CloudFormation templates. Entender CloudFormation es fundamental para debuggear problemas en cualquiera de estos frameworks.
## Limitaciones
- Verboso comparado con CDK o Terraform
- Solo AWS (no multi-cloud)
- Límite de 500 recursos por stack
- Algunos recursos no soportados inmediatamente
## CloudFormation vs Terraform
| Aspecto | CloudFormation | Terraform |
|---------|---------------|-----------|
| Proveedor | Solo AWS | Multi-cloud |
| Lenguaje | YAML/JSON | HCL |
| Estado | Gestionado por AWS | Archivo local o remoto |
| Costo | Gratis | Gratis (open source) |
## ¿Por qué importa?
CloudFormation es el servicio nativo de IaC en AWS y la base sobre la que se construyen CDK y SAM. Entenderlo es necesario incluso si usas abstracciones de nivel superior, porque los errores de despliegue y los problemas de drift se diagnostican a nivel de CloudFormation.
## Referencias
- [CloudFormation Documentation](https://docs.aws.amazon.com/cloudformation/) — AWS, 2024. Documentación oficial.
- [CloudFormation Best Practices](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/best-practices.html) — AWS, 2024. Mejores prácticas oficiales.
- [CloudFormation Resources](https://aws.amazon.com/cloudformation/resources/) — AWS, 2024. Recursos y ejemplos de templates.
---
# AWS CDK
Type: concept
Status: seed
Summary: AWS infrastructure as code framework that allows defining cloud resources using programming languages like TypeScript, Python, or Java, generating CloudFormation.
Concepts: infrastructure-as-code, typescript
## ¿Qué es?
AWS CDK (Cloud Development Kit) es un framework de [infraestructura como código](/concepts/infrastructure-as-code) que permite definir recursos AWS usando lenguajes de programación reales en lugar de YAML/JSON. El código se sintetiza a CloudFormation para el despliegue.
## CDK vs Terraform vs CloudFormation
| Aspecto | CDK | Terraform | CloudFormation |
|---------|-----|-----------|----------------|
| Lenguaje | TypeScript, Python, etc. | HCL | YAML/JSON |
| Abstracción | Constructs de alto nivel | Recursos | Recursos |
| Multi-cloud | No | Sí | No |
| Estado | CloudFormation | Terraform state | CloudFormation |
## Conceptos clave
| Concepto | Función | Ejemplo |
|----------|---------|---------|
| App | Punto de entrada, contiene stacks | `new cdk.App()` |
| Stack | Unidad de despliegue (= CloudFormation stack) | `MyServiceStack` |
| Construct L1 | Mapeo 1:1 con CloudFormation | `CfnBucket` (bajo nivel) |
| Construct L2 | Abstracciones con defaults sensatos | `s3.Bucket` (permisos, cifrado automáticos) |
| Construct L3 | Patrones completos | `LambdaRestApi` (API + Lambda + permisos) |
## Ejemplo TypeScript
```typescript
const fn = new lambda.Function(this, 'Handler', {
runtime: lambda.Runtime.NODEJS_20_X,
handler: 'index.handler',
code: lambda.Code.fromAsset('lambda'),
});
const api = new apigateway.RestApi(this, 'Api');
api.root.addMethod('GET', new apigateway.LambdaIntegration(fn));
```
## ¿Por qué importa?
CDK permite definir infraestructura con lenguajes de programación reales, lo que habilita abstracciones, testing unitario y reutilización de patrones que no son posibles con HCL o YAML. Para equipos de desarrollo que ya dominan TypeScript o Python, reduce la barrera de entrada a IaC.
## Referencias
- [CDK Documentation](https://docs.aws.amazon.com/cdk/) — Documentación oficial.
- [CDK Patterns](https://cdkpatterns.com/) — Patrones de arquitectura.
- [CDK Best Practices](https://docs.aws.amazon.com/cdk/v2/guide/best-practices.html) — AWS, 2024. Mejores prácticas oficiales.
---
# AWS Bedrock
Type: concept
Status: seed
Summary: AWS managed service providing access to foundation models from multiple providers (Anthropic, Meta, Mistral) via API, without managing ML infrastructure.
Concepts: large-language-models, ai-agents
## ¿Qué es?
Amazon Bedrock es un servicio serverless que proporciona acceso a [modelos fundacionales](/concepts/large-language-models) de múltiples proveedores a través de una API unificada. No hay infraestructura que gestionar — solo llamas a la API y pagas por tokens consumidos.
## Modelos disponibles
| Proveedor | Modelos |
|-----------|----------|
| Anthropic | Claude 3.5 Sonnet, Claude 3 Opus/Haiku |
| Meta | Llama 3.1, Llama 3.2 |
| Mistral | Mistral Large, Mixtral |
| Amazon | Titan Text, Titan Embeddings |
| Cohere | Command R, Embed |
| Stability AI | Stable Diffusion |
## Características
| Característica | Función | Integración |
|---------------|---------|-------------|
| Knowledge Bases | [RAG](/concepts/retrieval-augmented-generation) managed | S3 como fuente, OpenSearch como vector store |
| Agents | [Agentes](/concepts/ai-agents) con herramientas y memoria | Lambda functions como tools |
| Guardrails | Filtros de contenido y PII | Aplicables a cualquier modelo |
| Fine-tuning | Personalización de modelos | Datos propios en S3 |
| Model evaluation | Comparar modelos en tus datos | Métricas automáticas + humanas |
## Integración con agentes
Bedrock Agents permite crear [agentes de IA](/concepts/ai-agents) que usan herramientas (Lambda functions) y consultan knowledge bases, todo managed.
## ¿Por qué importa?
Bedrock democratiza el acceso a modelos fundacionales sin la complejidad de gestionar infraestructura de GPU. Para equipos que ya operan en AWS, es la forma más directa de integrar IA generativa en aplicaciones existentes, con la seguridad y compliance del ecosistema AWS.
## Referencias
- [Bedrock Documentation](https://docs.aws.amazon.com/bedrock/) — Documentación oficial.
- [Bedrock Supported Models](https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html) — AWS, 2024. Modelos disponibles en Bedrock.
- [Bedrock Pricing](https://aws.amazon.com/bedrock/pricing/) — AWS, 2024. Modelo de precios por token.
---
# AWS API Gateway
Type: concept
Status: seed
Summary: AWS managed service for creating, publishing, and managing REST, HTTP, and WebSocket APIs that act as entry points to Lambda functions and other backend services.
Concepts: aws-lambda, serverless
## ¿Qué es?
AWS API Gateway es un servicio completamente administrado que facilita la creación de APIs como puerta de entrada a aplicaciones. Maneja autenticación, autorización, throttling, caching y monitoreo — permitiendo que [Lambda](/concepts/aws-lambda) se enfoque solo en la lógica de negocio.
## Tipos de API
| Tipo | Características | Costo |
|------|-----------------|-------|
| HTTP API | Simple, baja latencia, integración Lambda | Más barato |
| REST API | Features completas, transformaciones, validación | Más caro |
| WebSocket API | Conexiones bidireccionales en tiempo real | Por mensaje |
## Características clave
| Característica | Función | Ejemplo |
|---------------|---------|---------|
| Stages | Ambientes con configuración independiente | `dev`, `staging`, `prod` |
| Authorizers | Autenticación y autorización | Lambda, Cognito, IAM |
| Throttling | Límites de requests por segundo | 10,000 rps por stage |
| Caching | Respuestas cacheadas | Reducir latencia y costo en endpoints estables |
| CORS | Configuración de cross-origin | Permitir requests desde el frontend |
| Custom domains | Dominios propios con SSL | `api.example.com` con ACM |
## Patrón típico
```
Cliente → API Gateway → Lambda → DynamoDB
↓
Authorizer (JWT/Cognito)
```
## ¿Por qué importa?
API Gateway elimina la necesidad de construir y operar tu propia capa de entrada HTTP. Con integración nativa a Lambda, autorización con Cognito/IAM y throttling automático, permite exponer APIs serverless en producción sin gestionar servidores.
## Referencias
- [API Gateway Documentation](https://docs.aws.amazon.com/apigateway/) — Documentación oficial.
- [HTTP API vs REST API](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-vs-rest.html) — AWS, 2024. Comparación entre tipos de API Gateway.
- [API Gateway Pricing](https://aws.amazon.com/api-gateway/pricing/) — AWS, 2024. Modelo de precios.
---
# Artificial Intelligence
Type: concept
Status: growing
Summary: Field of computer science dedicated to creating systems capable of performing tasks that normally require human intelligence, from reasoning and perception to language generation.
Concepts: ai-agents, mcp, neural-networks
## ¿Qué es?
La inteligencia artificial es el campo de la informática que busca crear sistemas capaces de realizar tareas que tradicionalmente requieren inteligencia humana: razonar, aprender, percibir, generar lenguaje y tomar decisiones.
No es un concepto nuevo — el término fue acuñado en 1956 en la conferencia de Dartmouth — pero la convergencia de tres factores lo transformó en los últimos años: cantidades masivas de datos, poder de cómputo accesible (GPUs, TPUs) y avances en arquitecturas de redes neuronales, particularmente el Transformer introducido en 2017.
## Capas del ecosistema actual
### Modelos fundacionales (Foundation Models)
Los modelos fundacionales son redes neuronales de gran escala entrenadas con cantidades masivas de datos no etiquetados. Se llaman «fundacionales» porque sirven como base para múltiples tareas sin necesidad de reentrenamiento completo.
Ejemplos: GPT-4, Claude, Gemini, Llama, Mistral.
Su característica clave es la **emergencia**: capacidades que no fueron explícitamente programadas pero que surgen del entrenamiento a escala, como razonamiento en cadena, traducción entre idiomas o generación de código.
### Modelos de lenguaje (LLMs)
Un subconjunto de modelos fundacionales especializados en procesar y generar texto. Utilizan la arquitectura Transformer con mecanismos de atención que les permiten capturar relaciones de largo alcance en secuencias de texto.
Los LLMs actuales no solo generan texto — pueden seguir instrucciones complejas, mantener contexto en conversaciones largas y utilizar herramientas externas cuando se les configura para hacerlo.
### IA generativa
La aplicación de modelos fundacionales para crear contenido nuevo: texto, código, imágenes, audio, video. Es la capa más visible para el usuario final y la que ha impulsado la adopción masiva desde 2022.
## Paradigmas de interacción
La forma en que los humanos interactúan con sistemas de IA ha evolucionado rápidamente:
| Paradigma | Mecanismo | Limitación principal | Ejemplo |
|-----------|-----------|---------------------|---------|
| Prompting | Instrucciones en lenguaje natural | Depende del conocimiento del modelo | ChatGPT, Claude |
| [RAG](/concepts/retrieval-augmented-generation) | Consulta fuentes externas antes de responder | Calidad depende del retrieval | Perplexity, sistemas empresariales |
| Tool Use | Invoca APIs, bases de datos o servicios | Requiere definir herramientas disponibles | [Function calling](/concepts/function-calling), [MCP](/concepts/model-context-protocol) |
| [Agentes](/concepts/ai-agents) | Razonamiento + memoria + herramientas en múltiples pasos | Complejidad de orquestación y [seguridad](/concepts/ai-safety) | Copilot Workspace, Devin |
Cada paradigma construye sobre el anterior. Los [agentes de IA](/concepts/ai-agents) representan la frontera actual.
## Consideraciones prácticas
- **Alucinaciones**: los LLMs generan texto plausible pero no necesariamente correcto. Toda salida debe verificarse.
- **Ventana de contexto**: los modelos tienen un límite de tokens que pueden procesar. Esto afecta directamente qué tan larga puede ser una conversación o documento.
- **Costo**: los modelos más capaces son más costosos por token. La elección del modelo debe balancear capacidad con presupuesto.
- **Latencia**: la generación de texto es secuencial (token por token). Para aplicaciones en tiempo real, esto es un factor limitante.
## ¿Por qué importa?
La IA dejó de ser un campo de investigación para convertirse en una herramienta de ingeniería. Entender sus capas — desde modelos fundacionales hasta frameworks de agentes — permite tomar decisiones informadas sobre qué construir, qué comprar y dónde invertir el esfuerzo de aprendizaje.
## Referencias
- [Attention Is All You Need](https://arxiv.org/abs/1706.03762) — Vaswani et al., 2017. El paper que introdujo la arquitectura Transformer.
- [On the Opportunities and Risks of Foundation Models](https://arxiv.org/abs/2108.07258) — Stanford CRFM, 2021. Reporte fundacional sobre modelos de gran escala.
- [Anthropic](https://www.anthropic.com/) — Creadores de Claude y del Model Context Protocol.
- [OpenAI](https://openai.com/) — Creadores de GPT-4 y pioneros en IA generativa comercial.
---
# API Gateway Pattern
Type: concept
Status: seed
Summary: Pattern providing a single entry point for multiple microservices, handling routing, authentication, rate limiting, and response aggregation.
Concepts: microservices, aws-api-gateway, backend-for-frontend, oauth-oidc
## ¿Qué es?
El patrón API Gateway proporciona un punto de entrada único para clientes que necesitan acceder a múltiples [microservicios](/concepts/microservices). En lugar de que el cliente conozca y llame a cada servicio, el gateway enruta, agrega y transforma las requests.
## Responsabilidades
- **Routing**: dirigir requests al servicio correcto
- **Autenticación/Autorización**: verificar identidad centralmente
- **Rate limiting**: proteger servicios de sobrecarga
- **Agregación**: combinar respuestas de múltiples servicios
- **Transformación**: adaptar formatos entre cliente y servicios
- **Caching**: cachear respuestas frecuentes
## Implementaciones
| Gateway | Tipo | Fortaleza | Limitación |
|---------|------|-----------|------------|
| [AWS API Gateway](/concepts/aws-api-gateway) | Managed | Integración nativa con Lambda, sin infraestructura | Latencia añadida, costo por request |
| Kong | Open source / managed | Plugins extensibles, multi-cloud | Complejidad operacional |
| NGINX | Open source | Rendimiento extremo, configuración flexible | Sin features de API management nativos |
| Envoy | Open source | Proxy L7, base de [service meshes](/concepts/service-mesh) | Curva de aprendizaje alta |
| Traefik | Open source | Auto-discovery con Docker/K8s | Menos maduro para APIs complejas |
## Anti-patrones
- Gateway que contiene lógica de negocio
- Gateway como cuello de botella (single point of failure)
- Demasiada agregación en el gateway
## ¿Cuándo usar un API Gateway?
- Múltiples [microservicios](/concepts/microservices) que necesitan un punto de entrada unificado
- Requisitos transversales como autenticación, rate limiting o transformación de requests
- Clientes diversos (web, mobile, IoT) que necesitan respuestas adaptadas ([BFF](/concepts/backend-for-frontend))
## ¿Por qué importa?
El API gateway centraliza preocupaciones transversales — autenticación, rate limiting, transformación — que de otro modo se duplicarían en cada microservicio. Es el punto de control que simplifica tanto la operación como la experiencia del consumidor de la API.
## Referencias
- [API Gateway Pattern](https://microservices.io/patterns/apigateway.html) — Chris Richardson, 2014. Patrón original.
- [API Gateway — Azure](https://learn.microsoft.com/en-us/azure/architecture/microservices/design/gateway) — Microsoft, 2024. Guía de implementación del patrón.
- [Kong Gateway](https://konghq.com/products/kong-gateway) — Kong, 2024. API gateway open source de alto rendimiento.
---
# API Documentation
Type: concept
Status: seed
Summary: Practices and tools for documenting APIs clearly, interactively, and maintainably, from OpenAPI specifications to documentation portals.
Concepts: spec-driven-development, api-design, developer-experience
## ¿Qué es?
La documentación de APIs es la interfaz entre tu servicio y sus consumidores. Una buena documentación incluye referencia completa, ejemplos prácticos, guías de inicio rápido y manejo de errores.
## OpenAPI (Swagger)
Estándar de la industria para describir APIs REST. Un archivo YAML/JSON que define endpoints, parámetros, respuestas y schemas. Genera documentación interactiva automáticamente.
## Herramientas
| Herramienta | Uso |
|-------------|-----|
| Swagger UI | Documentación interactiva |
| Redoc | Documentación estática elegante |
| Stoplight | Design-first con editor visual |
| Postman | Colecciones + documentación |
## Mejores prácticas
- Generar docs desde la especificación (single source of truth)
- Incluir ejemplos reales para cada endpoint
- Documentar errores y códigos de estado
- Mantener changelog de cambios en la API
- Sandbox/playground para probar sin código
## Documentación como producto
La documentación de API es un producto — necesita mantenimiento, feedback de usuarios y métricas de uso. APIs con buena documentación tienen mayor adopción y menos tickets de soporte.
## ¿Por qué importa?
La documentación de API es la interfaz de usuario para desarrolladores. Si no pueden entender cómo usar tu API en minutos, buscarán una alternativa. La documentación generada desde la especificación garantiza que siempre esté sincronizada con la implementación.
## Referencias
- [OpenAPI Specification](https://spec.openapis.org/oas/latest.html) — OpenAPI Initiative, 2024. Estándar de especificación.
- [Swagger/OpenAPI](https://swagger.io/specification/) — SmartBear, 2024. Herramientas para documentación de APIs.
- [Redocly](https://redocly.com/) — Redocly, 2024. Plataforma de documentación de APIs.
---
# API Design
Type: concept
Status: seed
Summary: Principles and practices for designing clear, consistent, and evolvable programming interfaces that facilitate integration between systems.
Concepts: spec-driven-development, microservices
## ¿Qué es?
El diseño de APIs es la disciplina de crear interfaces programáticas claras, consistentes y fáciles de usar. Una API bien diseñada es predecible, documentada y evolucionable sin romper consumidores existentes.
## Estilos de API
| Estilo | Características | Ideal para |
|--------|-----------------|------------|
| REST | Recursos, HTTP verbs, stateless | CRUD, APIs públicas |
| GraphQL | Query language, schema tipado | Frontends flexibles |
| gRPC | Protocol Buffers, streaming | Microservicios internos |
| WebSocket | Bidireccional, real-time | Chat, notificaciones |
## Principios de diseño REST
- Nombres de recursos en plural (`/users`, no `/user`)
- HTTP verbs semánticos (GET, POST, PUT, DELETE)
- Códigos de estado apropiados (201 Created, 404 Not Found)
- Versionado (URL path o header)
- Paginación consistente
- HATEOAS para discoverability
## API-First / Design-First
Definir el contrato de la API antes de implementar. Herramientas como OpenAPI permiten generar documentación, SDKs y mocks desde la especificación. Conecta con [spec-driven development](/concepts/spec-driven-development).
## ¿Por qué importa?
Una API mal diseñada se convierte en un contrato que no puedes romper. Cada decisión — nomenclatura, versionado, manejo de errores — se solidifica una vez que hay consumidores. Invertir en diseño antes de publicar ahorra meses de migraciones dolorosas después.
## Referencias
- [API Design Patterns](https://www.manning.com/books/api-design-patterns) — JJ Geewax, 2021.
- [OpenAPI Specification](https://spec.openapis.org/oas/latest.html) — Estándar de la industria.
- [Google API Design Guide](https://google.aip.dev/) — Google, 2024. Guía de mejores prácticas para diseño de APIs.
---
# Alerting Strategies
Type: concept
Status: seed
Summary: Practices for configuring effective alerts that notify real problems without generating fatigue from excessive notifications.
Concepts: metrics-monitoring, site-reliability-engineering
## ¿Qué es?
Alerting es el proceso de notificar a los equipos cuando algo requiere atención. Alertas mal configuradas causan fatiga (demasiadas) o incidentes perdidos (muy pocas).
## Principios
- **Actionable**: cada alerta debe tener una acción clara
- **Basadas en síntomas**: alertar en impacto al usuario, no en causas
- **Basadas en SLOs**: alertar cuando el error budget se consume
- **Escalamiento**: si no se responde, escalar automáticamente
## Severidades
| Severidad | Respuesta | Ejemplo |
|-----------|-----------|----------|
| Critical | Inmediata (wake up) | Servicio caído |
| Warning | Horas de trabajo | Degradación de performance |
| Info | Revisar cuando sea posible | Tendencia preocupante |
## Anti-patrones
| Anti-patrón | Consecuencia | Solución |
|-------------|-------------|----------|
| Alertas que siempre se ignoran | Alert fatigue, se pierden alertas reales | Eliminar o convertir en dashboard |
| Alertas sin runbook | Respuesta lenta, depende de conocimiento tribal | Vincular runbook a cada alerta |
| Alertas por métricas internas | Ruido sin impacto visible al usuario | Alertar por síntomas, no causas |
| Umbrales arbitrarios | Falsos positivos frecuentes | Basar umbrales en [SLOs](/concepts/site-reliability-engineering) |
## ¿Por qué importa?
Las alertas mal diseñadas causan fatiga, y la fatiga causa que se ignoren alertas reales. Una estrategia de alertas efectiva es la diferencia entre detectar un incidente en minutos y enterarse por los usuarios horas después.
## Referencias
- [My Philosophy on Alerting](https://docs.google.com/document/d/199PqyG3UsyXlwieHaqbGiWVa8eMWi8zzAn0YfcApr8Q/edit) — Rob Ewaschuk, Google.
- [Monitoring Distributed Systems](https://sre.google/sre-book/monitoring-distributed-systems/) — Google SRE Book, 2016. Capítulo sobre monitoreo y alertas.
- [Grafana Alerting](https://grafana.com/docs/grafana/latest/alerting/) — Grafana, 2024. Sistema de alertas unificado.
---
# AI Safety
Type: concept
Status: seed
Summary: Field dedicated to ensuring artificial intelligence systems behave safely, aligned with human values, and predictably, minimizing risks of harm.
Concepts: artificial-intelligence, ai-agents, synthetic-data
## ¿Qué es?
AI Safety es el campo que estudia cómo garantizar que los sistemas de [inteligencia artificial](/concepts/artificial-intelligence) — especialmente los [LLMs](/concepts/large-language-models) y [agentes](/concepts/ai-agents) — se comporten de forma segura, predecible y alineada con la intención humana. No es solo un problema teórico: cada sistema de IA en producción necesita guardrails prácticos.
## Dimensiones de seguridad
### Alineación (Alignment)
Que el modelo haga lo que el usuario quiere, no lo que literalmente dice:
- **RLHF**: entrenamiento con feedback humano para alinear comportamiento
- **Constitutional AI**: el modelo sigue principios explícitos
- **Instruction hierarchy**: priorizar instrucciones del sistema sobre las del usuario
### Robustez
Que el modelo se comporte consistentemente ante entradas adversariales:
- **Prompt injection**: intentos de sobreescribir instrucciones del sistema
- **Jailbreaking**: técnicas para evadir restricciones de seguridad
- **Data poisoning**: datos maliciosos en el entrenamiento
### Guardrails en producción
Controles prácticos para sistemas desplegados:
- Filtros de entrada/salida para contenido dañino
- Límites de acciones para agentes (qué pueden y no pueden hacer)
- Monitoreo de comportamiento anómalo
- Circuit breakers para detener agentes fuera de control
## Riesgos específicos de agentes
Los [agentes de IA](/concepts/ai-agents) amplifican los riesgos porque pueden actuar en el mundo real:
- **Acciones irreversibles**: borrar datos, enviar emails, ejecutar transacciones
- **Escalada de privilegios**: un agente que obtiene más acceso del previsto
- **Loops infinitos**: agentes que consumen recursos sin converger
- **Exfiltración**: agentes que filtran información sensible
## Mejores prácticas
| Riesgo | Mitigación | Implementación |
|--------|-----------|----------------|
| Acciones irreversibles | Human-in-the-loop | Confirmación antes de delete/send/pay |
| Escalada de privilegios | Mínimo privilegio | Scopes limitados por herramienta |
| Alucinaciones | Grounding + verificación | [RAG](/concepts/retrieval-augmented-generation), fact-checking |
| Prompt injection | Instruction hierarchy | System prompt > user prompt |
| Exfiltración de datos | Filtrado de outputs | Regex + clasificación de PII |
| Loops infinitos | Límites de iteración | Max steps, timeout, cost caps |
Prácticas adicionales:
- Red teaming regular para encontrar vulnerabilidades
- Evaluaciones automatizadas de seguridad en CI/CD
- Logging exhaustivo de todas las decisiones y acciones
## ¿Por qué importa?
A medida que los sistemas de IA toman decisiones con mayor autonomía, los riesgos de comportamiento no alineado, sesgos amplificados y uso malicioso crecen proporcionalmente. La seguridad de IA no es un problema futuro — es una responsabilidad de ingeniería presente en cada sistema que se despliega hoy.
## Referencias
- [Anthropic's Responsible Scaling Policy](https://www.anthropic.com/news/anthropics-responsible-scaling-policy) — Anthropic, 2023.
- [OWASP Top 10 for LLM Applications](https://owasp.org/www-project-top-10-for-large-language-model-applications/) — OWASP, 2024.
- [NIST AI Risk Management Framework](https://www.nist.gov/artificial-intelligence) — NIST, 2023. Marco federal para gestión de riesgos de IA.
---
# AI Orchestration
Type: concept
Status: seed
Summary: Patterns and frameworks for coordinating multiple AI models, tools, and data sources in production pipelines, managing flow between components, memory, and error recovery.
Concepts: agentic-workflows, multi-agent-systems, event-driven-architecture, mcp
## ¿Qué es?
La orquestación de IA es la disciplina de coordinar múltiples modelos de lenguaje, herramientas externas, fuentes de datos y lógica de negocio en un sistema unificado que funciona en producción. Mientras que una llamada aislada a un LLM es simple, una aplicación real necesita encadenar pasos, gestionar memoria, manejar errores y seleccionar el modelo adecuado para cada tarea.
En la práctica, la mayoría de los proyectos de IA generativa se estancan entre el piloto y producción. La orquestación es lo que cierra esa brecha.
## Patrones fundamentales
### Cadenas (Chains)
Secuencia lineal de pasos donde la salida de uno alimenta la entrada del siguiente. El patrón más simple y predecible.
```
Prompt → LLM → Parser → Validación → Respuesta
```
### Enrutamiento (Routing)
Un componente analiza la entrada y la dirige al modelo o pipeline más adecuado según la complejidad, el dominio o el costo.
```
Entrada → Router → Modelo A (tareas simples, bajo costo)
→ Modelo B (razonamiento complejo)
→ Modelo C (dominio específico)
```
### Agentes con herramientas
El modelo decide dinámicamente qué herramientas invocar y en qué orden, iterando hasta completar la tarea. Es el patrón detrás de los [flujos agénticos](/concepts/agentic-workflows).
### Orquestación multi-agente
Múltiples [agentes especializados](/concepts/multi-agent-systems) colaboran en una tarea, cada uno con su propio contexto, herramientas y modelo. Un orquestador coordina la comunicación y el flujo.
## Capas de un sistema en producción
| Capa | Responsabilidad | Ejemplo |
|------|-----------------|---------|
| Modelo | Selección y fallback entre proveedores | Claude para razonamiento, GPT-4o como fallback |
| Herramientas | Integración con APIs y servicios externos | Vía [MCP](/concepts/mcp) o function calling |
| Memoria | Persistencia de contexto entre interacciones | Historial de conversación, resúmenes |
| Recuperación | Acceso a datos relevantes (RAG) | Búsqueda vectorial + reranking |
| Guardrails | Validación de entradas y salidas | Filtros de contenido, verificación de hechos |
| Observabilidad | Trazas, métricas y logs | Langfuse, Arize, LangSmith |
## Frameworks principales
| Framework | Enfoque |
|-----------|---------|
| LangChain / LangGraph | Cadenas y grafos de agentes con estado |
| LlamaIndex | RAG y pipelines de datos |
| Strands Agents | Agentes con herramientas y loop de razonamiento |
| Semantic Kernel | Orquestación empresarial (Microsoft) |
| CrewAI | Equipos de agentes colaborativos |
## Desafíos en producción
- **Latencia compuesta**: cada paso añade latencia — un pipeline de 5 pasos puede tardar 10-30 segundos
- **Costos impredecibles**: los agentes pueden iterar más de lo esperado, multiplicando el consumo de tokens
- **Depuración difícil**: rastrear por qué un agente tomó una decisión requiere trazabilidad completa
- **Manejo de errores**: un fallo en cualquier paso debe manejarse sin perder el contexto acumulado
- **Consistencia**: garantizar que el sistema produce resultados reproducibles
## ¿Por qué importa?
La diferencia entre un demo de IA y un producto en producción es la orquestación. Sin ella, las aplicaciones son frágiles, costosas e imposibles de depurar. Con ella, los equipos pueden componer sistemas complejos a partir de componentes simples, con visibilidad completa y manejo de errores robusto.
## Referencias
- [LLM Orchestration in 2025: Frameworks + Best Practices](https://orq.ai/blog/llm-orchestration) — orq.ai. Panorama de frameworks y patrones.
- [LangGraph Documentation](https://langchain-ai.github.io/langgraph/) — LangChain. Framework de grafos para agentes con estado.
- [Strands Agents — Documentation](https://strandsagents.com/) — AWS. SDK para agentes con herramientas.
---
# AI Observability
Type: concept
Status: seed
Summary: Practices and tools for monitoring, tracing, and debugging AI systems in production, covering token metrics, latency, response quality, costs, and hallucination detection.
Concepts: observability, distributed-tracing, evaluation-metrics-ai, ai-orchestration
## ¿Qué es?
La observabilidad de IA extiende las prácticas tradicionales de [observabilidad](/concepts/observability) — logs, métricas y trazas — al dominio de los sistemas de inteligencia artificial. Mientras que en software convencional se monitorean tiempos de respuesta y tasas de error, en sistemas de IA se necesita además rastrear el consumo de tokens, la calidad de las respuestas, los costos por llamada y la presencia de alucinaciones.
La diferencia fundamental es que los LLMs son no deterministas: la misma entrada puede producir salidas diferentes. Esto hace que la observabilidad no sea solo operacional sino también cualitativa.
## Los tres pilares aplicados a IA
### Trazas (Traces)
En un sistema de IA, una traza captura el recorrido completo de una solicitud a través del pipeline:
```
Usuario → Prompt → Retrieval (RAG) → LLM Call → Tool Use → LLM Call → Respuesta
│ │ │ │ │ │ │
└─ trace_id: abc-123 ─┴───────────────┴───────────┴──────────┴──────────┘
```
Cada paso registra: tokens de entrada/salida, latencia, modelo usado, costo y resultado. Esto es especialmente crítico en [flujos agénticos](/concepts/agentic-workflows) donde el modelo puede iterar múltiples veces.
### Métricas
| Métrica | Descripción | ¿Por qué importa? |
|---------|-------------|-------------------|
| TTFT (Time to First Token) | Latencia hasta el primer token | Experiencia del usuario |
| Tokens por segundo | Velocidad de generación | Throughput del sistema |
| Costo por request | Tokens × precio del modelo | Control presupuestario |
| Tasa de alucinación | Respuestas con información fabricada | Confiabilidad |
| Tasa de rechazo | Requests que el modelo no pudo completar | Cobertura funcional |
| Satisfacción del usuario | Feedback explícito o implícito | Calidad percibida |
### Logs
Registro detallado de prompts, respuestas, decisiones de herramientas y errores. A diferencia de logs tradicionales, los logs de IA incluyen el contenido completo de las interacciones para permitir reproducción y depuración.
## Herramientas del ecosistema
| Herramienta | Tipo | Características |
|-------------|------|-----------------|
| Langfuse | Open source | Trazas, evaluaciones, gestión de prompts |
| LangSmith | Comercial (LangChain) | Trazas, datasets de evaluación, playground |
| Arize Phoenix | Open source | Trazas, detección de drift, evaluaciones |
| Braintrust | Comercial | Evaluaciones, logging, comparación de modelos |
| OpenTelemetry + extensiones | Estándar abierto | Integración con infraestructura existente de [trazado distribuido](/concepts/distributed-tracing) |
## Evaluaciones en producción
La observabilidad de IA incluye evaluaciones continuas — no solo en desarrollo sino en producción:
- **LLM-as-judge**: usar un modelo para evaluar las respuestas de otro
- **Evaluaciones heurísticas**: reglas sobre longitud, formato, presencia de fuentes
- **Feedback humano**: thumbs up/down, correcciones, escalaciones
- **Métricas de negocio**: tasa de resolución, tiempo de sesión, conversión
## ¿Por qué importa?
Sin observabilidad, un sistema de IA en producción es una caja negra costosa. Los equipos no pueden:
- Detectar degradación de calidad antes de que los usuarios la reporten
- Optimizar costos identificando llamadas innecesarias o modelos sobredimensionados
- Depurar por qué un agente tomó una decisión incorrecta
- Cumplir requisitos de auditoría y compliance
## Referencias
- [OpenLLMetry](https://github.com/traceloop/openllmetry) — Traceloop. Instrumentación OpenTelemetry para LLMs.
- [Langfuse Documentation](https://langfuse.com/docs) — Langfuse. Plataforma open source de observabilidad de LLMs.
- [LLM Observability — Arize AI](https://docs.arize.com/phoenix) — Arize. Documentación de Phoenix para trazas y evaluaciones.
---
# AI Coding Assistants
Type: concept
Status: seed
Summary: Tools using LLMs to help developers write, understand, debug, and refactor code, from autocomplete to agents that implement complete features.
Concepts: ai-agents, spec-driven-development
## ¿Qué es?
Los asistentes de código con IA son herramientas que integran [LLMs](/concepts/large-language-models) en el flujo de trabajo del desarrollador para acelerar la escritura de código, explicar código existente, detectar bugs y automatizar tareas repetitivas. Van desde autocompletado inteligente hasta [agentes](/concepts/ai-agents) que implementan features completas.
## Niveles de asistencia
| Nivel | Capacidad | Autonomía | Ejemplos |
|-------|-----------|-----------|----------|
| 1 — Autocompletado | Sugerencias inline mientras escribes | Baja — el desarrollador acepta/rechaza cada sugerencia | GitHub Copilot, Codeium, Tabnine |
| 2 — Chat contextual | Conversación sobre código con contexto del proyecto | Media — genera bloques, el desarrollador revisa | Copilot Chat, Cursor, Cody |
| 3 — Agentes de código | Ejecución autónoma de tareas completas | Alta — implementa features, resuelve issues, ejecuta tests | Copilot Workspace, Cursor Composer, Kiro |
## Capacidades comunes
- **Generación**: escribir código desde descripciones en lenguaje natural
- **Explicación**: documentar y explicar código existente
- **Refactoring**: mejorar estructura sin cambiar comportamiento
- **Debugging**: identificar y sugerir fixes para bugs
- **Testing**: generar tests unitarios y de integración
- **Traducción**: convertir entre lenguajes de programación
## Integración con el flujo de trabajo
Los asistentes más efectivos se integran con:
- IDE/editor (VS Code, JetBrains, Neovim)
- Control de versiones (Git, GitHub)
- CI/CD (ejecutar tests, verificar builds)
- Documentación del proyecto (README, AGENTS.md)
## Conexión con spec-driven development
El [desarrollo dirigido por especificaciones](/concepts/spec-driven-development) maximiza la efectividad de los asistentes de código al proporcionar contexto estructurado que guía la generación.
## ¿Por qué importa?
Los asistentes de código con IA están redefiniendo la productividad del desarrollador. Saber cuándo confiar en sus sugerencias, cómo guiarlos con contexto efectivo y dónde fallan sistemáticamente es una competencia que separa a los ingenieros que los usan bien de los que generan deuda técnica con ellos.
## Referencias
- [GitHub Copilot](https://github.com/features/copilot) — Asistente de código de GitHub.
- [Cursor](https://cursor.sh/) — IDE con IA integrada.
- [Stack Overflow Developer Survey 2024](https://survey.stackoverflow.co/2024/) — Stack Overflow, 2024. Adopción de herramientas de IA entre desarrolladores.
---
# AI Agents
Type: concept
Status: growing
Summary: Autonomous systems that combine language models with reasoning, memory, and tool use to execute complex multi-step tasks with minimal human intervention.
Concepts: artificial-intelligence, mcp
## ¿Qué son?
Un agente de IA es un sistema que utiliza un modelo de lenguaje como núcleo de razonamiento, pero va más allá de responder preguntas: puede planificar, ejecutar acciones, observar resultados y ajustar su comportamiento en un ciclo cerrado.
La diferencia fundamental entre un chatbot y un agente es la **autonomía**. Un chatbot responde a una pregunta y espera la siguiente. Un agente recibe un objetivo, descompone el problema, decide qué herramientas usar, ejecuta pasos intermedios y entrega un resultado — todo con mínima intervención humana.
## Componentes de un agente
Un agente típico tiene cuatro componentes:
1. **Modelo de lenguaje (LLM)**: el cerebro que razona, planifica y genera texto. Decide qué hacer en cada paso.
2. **Memoria**: almacena el contexto de la conversación, resultados previos y conocimiento acumulado. Puede ser de corto plazo (ventana de contexto) o largo plazo (bases de datos vectoriales, archivos).
3. **Herramientas (Tools)**: funciones externas que el agente puede invocar — APIs, bases de datos, sistemas de archivos, navegadores, terminales. El [Model Context Protocol (MCP)](/concepts/mcp) estandariza cómo los agentes acceden a estas herramientas.
4. **Bucle de ejecución**: el ciclo de razonamiento-acción-observación que el agente repite hasta completar la tarea.
## Patrones de ejecución
### ReAct (Reason + Act)
El patrón más común. El agente alterna entre razonar sobre qué hacer y ejecutar acciones:
```
Pensamiento: Necesito buscar el precio actual de AAPL
Acción: buscar_precio(ticker="AAPL")
Observación: $187.50
Pensamiento: Ahora puedo responder al usuario
Respuesta: El precio actual de AAPL es $187.50
```
### Planificación y ejecución
El agente primero crea un plan completo y luego ejecuta cada paso. Útil para tareas complejas donde el orden importa.
### Multi-agente
Múltiples agentes especializados colaboran para resolver un problema. Cada agente tiene un rol específico (investigador, escritor, revisor) y se comunican entre sí.
## Frameworks actuales
| Framework | Lenguaje | Enfoque |
|---|---|---|
| [LangGraph](https://langchain-ai.github.io/langgraph/) | Python | Grafos de estado para flujos agenticos |
| [CrewAI](https://www.crewai.com/) | Python | Equipos de agentes con roles |
| [Strands Agents](https://strandsagents.com/) | Python | Agentes modulares de AWS |
| [AutoGen](https://microsoft.github.io/autogen/) | Python | Conversaciones multi-agente |
| [Vercel AI SDK](https://sdk.vercel.ai/) | TypeScript | Agentes en aplicaciones web |
## Limitaciones actuales
- **Fiabilidad**: los agentes pueden entrar en bucles, tomar decisiones incorrectas o alucinar sobre el estado del mundo.
- **Costo**: cada paso del bucle consume tokens. Una tarea compleja puede requerir decenas de llamadas al modelo.
- **Seguridad**: un agente con acceso a herramientas puede ejecutar acciones destructivas si no se limita adecuadamente.
- **Observabilidad**: depurar por qué un agente tomó una decisión específica es difícil. Los traces y logs son esenciales.
## ¿Por qué importa?
Los agentes representan el siguiente salto en aplicaciones de IA: de sistemas que responden preguntas a sistemas que completan tareas. Entender sus patrones de ejecución, limitaciones y frameworks disponibles es esencial para construir aplicaciones que van más allá del chat.
## Referencias
- [LLM Powered Autonomous Agents](https://lilianweng.github.io/posts/2023-06-23-agent/) — Lilian Weng (OpenAI), 2023. Referencia fundacional sobre arquitectura de agentes.
- [ReAct: Synergizing Reasoning and Acting in Language Models](https://arxiv.org/abs/2210.03629) — Yao et al., 2022. El paper que formalizó el patrón ReAct.
- [The Landscape of Emerging AI Agent Architectures](https://arxiv.org/abs/2404.11584) — Masterman et al., 2024. Survey de arquitecturas de agentes.
- [LangGraph Documentation](https://langchain-ai.github.io/langgraph/) — Framework de referencia para agentes basados en grafos.
---
# Agentic Workflows
Type: concept
Status: seed
Summary: Design patterns where AI agents execute complex multi-step tasks autonomously, combining reasoning, tool use, and iterative decision-making.
Concepts: ai-agents, mcp, strands-agents, ai-orchestration
## ¿Qué es?
Un flujo de trabajo agéntico es un patrón donde uno o más [agentes de IA](/concepts/ai-agents) ejecutan tareas complejas de forma autónoma, tomando decisiones en cada paso sobre qué acción realizar, qué herramienta usar y cuándo pedir intervención humana. A diferencia de un pipeline fijo, el agente adapta su comportamiento según los resultados intermedios.
## Patrones fundamentales
### Reflexión
El agente evalúa su propia salida y la mejora iterativamente:
```
Generar → Evaluar → Refinar → Evaluar → Entregar
```
Útil para: escritura, generación de código, análisis.
### Planificación (Plan-and-Execute)
El agente descompone la tarea en subtareas antes de ejecutar:
```
Analizar tarea → Crear plan → Ejecutar paso 1 → ... → Paso N → Sintetizar
```
Útil para: investigación, tareas complejas con múltiples dependencias.
### Uso de herramientas (ReAct)
El agente alterna entre razonamiento y acción:
```
Pensar → Actuar → Observar → Pensar → Actuar → Observar → Responder
```
Es el patrón más común en frameworks como [Strands Agents](/concepts/strands-agents).
### Multi-agente
Múltiples agentes especializados colaboran:
```
Orquestador → Agente investigador → Agente escritor → Agente revisor → Resultado
```
## Niveles de autonomía
1. **Asistido**: el agente sugiere, el humano aprueba cada paso
2. **Supervisado**: el agente ejecuta, el humano revisa puntos clave
3. **Autónomo**: el agente ejecuta de principio a fin, reporta resultados
4. **Colaborativo**: múltiples agentes se coordinan con intervención humana mínima
## Consideraciones de diseño
- **Guardrails**: definir límites claros de lo que el agente puede y no puede hacer
- **Observabilidad**: registrar cada decisión y acción para debugging
- **Recuperación de errores**: el agente debe manejar fallos gracefully
- **Costo**: cada iteración consume tokens — establecer límites
- **Evaluación**: medir calidad de resultados, no solo completitud
## Conexión con MCP
El [Model Context Protocol](/concepts/mcp) proporciona la capa de herramientas que los flujos agénticos necesitan. Sin un protocolo estándar para descubrir y usar herramientas, cada flujo requiere integraciones ad-hoc.
## ¿Por qué importa?
Los flujos agénticos permiten que los LLMs pasen de responder preguntas a ejecutar tareas complejas de múltiples pasos. Entender sus patrones — ReAct, planificación, reflexión — es la diferencia entre construir chatbots y construir asistentes que realmente completan trabajo.
## Referencias
- [The Landscape of Emerging AI Agent Architectures](https://arxiv.org/abs/2404.11584) — Masterman et al., 2024.
- [Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents) — Anthropic, 2024. Guía práctica de patrones agénticos.
- [Design Patterns for AI Agents](https://arxiv.org/abs/2402.05120) — Zhuge et al., 2024. Taxonomía de patrones de diseño para agentes.
---
# Accessibility
Type: concept
Status: seed
Summary: Practice of designing and developing digital products usable by all people, including those with visual, auditory, motor, or cognitive disabilities.
Concepts: design-systems, react
## ¿Qué es?
Accesibilidad web (a11y) es la práctica de hacer que los productos digitales sean usables por todas las personas, independientemente de sus capacidades. No es un feature opcional — es un requisito fundamental de calidad.
## WCAG (Web Content Accessibility Guidelines)
Estándar internacional con tres niveles:
- **A**: mínimo (contraste básico, texto alternativo)
- **AA**: recomendado (contraste 4.5:1, navegación por teclado)
- **AAA**: óptimo (contraste 7:1, lenguaje simple)
## Principios POUR
1. **Perceivable**: contenido perceptible (alt text, contraste, captions)
2. **Operable**: navegable por teclado, sin trampas de foco
3. **Understandable**: lenguaje claro, comportamiento predecible
4. **Robust**: compatible con tecnologías asistivas
## Prácticas esenciales
- HTML semántico (`