Decisiones de Arquitectura
Los Architecture Decision Records (ADRs) del lab: contexto, decisión, razón y consecuencias para cada elección de diseño significativa.
Propósito
Esta página es la referencia canónica de los Architecture Decision Records del lab. Un ADR es un documento corto que captura una decisión significativa, el contexto en el que se tomó y las consecuencias.
El lab tiene 13 ADRs. Están listados abajo en orden cronológico. Los 9 primeros están accepted; los 4 últimos están planned o in flight.
Plantilla de ADR
Cada ADR tiene la siguiente estructura:
ADR-001: Aislar el main agent y los specialized agents
Status: Accepted
Date: 2026-05-09
Context. El lab empezó con un único agente que lo manejaba todo: research, coding, media, web. El diseño single-agent era simple pero creaba varios problemas: (1) el contexto del agente estaba contaminado por tareas no relacionadas; (2) un crash en una tarea tumbaba las demás; (3) el security boundary entre operaciones de bajo y alto riesgo no estaba claro.
Decision. El lab divide los agentes en dos grupos: el main agent (el Coordinator) y los specialized agents (el Coding Assistant, el Research Worker, el Media Agent, el Web Agent). Los dos grupos corren en procesos separados y se comunican a través de interfaces definidas.
Reason. La división provee (1) contexto limpio por agente, (2) aislamiento de fallos, (3) un security boundary claro y (4) la capacidad de escalar o reemplazar cada agente de forma independiente.
Consequences. Positivo: código más limpio, boundaries más claros, más fácil de testear. Negativo: más procesos que gestionar, más interfaces que mantener. El coste merece la pena a la escala del lab.
ADR-002: El Coding Assistant nunca escribe código directamente
Status: Accepted
Date: 2026-05-09
Context. El Coding Assistant es el brazo de implementación del lab. En el diseño inicial, el Assistant podía escribir código directamente cuando la tarea era pequeña. Esto creaba varios problemas: (1) los outputs del Assistant eran inconsistentes, (2) no había paso de review, (3) el usuario no tenía forma de verificar el razonamiento del Assistant.
Decision. El Coding Assistant delega toda la escritura de código a un coding sub-agent sandboxed. El Assistant revisa el código, lo integra y lo testea. El Assistant nunca escribe código a mano.
Reason. El sub-agent está diseñado para generación de código. Tiene una ventana de contexto mayor, un entorno sandboxed y un proceso de review determinista. El valor del Assistant está en el diseño y la review, no en la generación de código.
Consequences. Positivo: código consistente, proceso de review, razonamiento verificable. Negativo: turnaround más lento, dependencia del sub-agent. El coste merece la pena por la barra de calidad del lab.
ADR-003: La memoria es per-agent, no compartida
Status: Accepted
Date: 2026-05-09
Context. Los agentes del lab necesitaban memoria. El diseño inicial tenía una única capa de memoria compartida por todos los agentes. Esto creaba problemas: (1) la memoria estaba contaminada con datos específicos de agente, (2) los agentes competían por el acceso de escritura, (3) el audit trail no estaba claro.
Decision. Cada agente tiene su propia memoria. El Coordinator tiene su propio MEMORY.md y daily logs. El Research Worker tiene sus propios artefactos de misión. El Media Agent no tiene memoria persistente. Los agentes no comparten memoria.
Reason. La memoria per-agent provee boundaries limpios, elimina la contención de escritura y produce un audit trail claro. El coste es que algunos datos hay que duplicarlos (p. ej., las preferencias del usuario), pero la duplicación es pequeña.
Consequences. Positivo: boundaries limpios, audit trail claro. Negativo: cierta duplicación de datos. El coste merece la pena.
ADR-004: El research framework escribe artefactos tipados
Status: Accepted
Date: 2026-05-10
Context. La versión inicial del research framework escribía artefactos como JSON sin tipos o markdown. Esto hacía difícil validar los artefactos, reproducir las runs y razonar sobre el data flow.
Decision. Cada artefacto que escribe el research framework lo valida un esquema Pydantic. Los esquemas son el contrato entre el framework y sus consumers. Un esquema nuevo requiere un ADR.
Reason. Los artefactos tipados proveen validación, reproducibilidad y un contrato claro. Los esquemas Pydantic son fáciles de escribir y de testear.
Consequences. Positivo: validación, reproducibilidad, contrato claro. Negativo: más boilerplate (los esquemas), más acoplamiento entre el framework y sus consumers. El coste merece la pena.
ADR-005: Las API keys externas están detrás de un token pool
Status: Accepted
Date: 2026-05-10
Context. El lab usa APIs de pago (Perplexity, Tavily). Una única API key era un único punto de fallo: un rate limit en la key detenía el trabajo del lab.
Decision. El lab usa un token pool para las APIs de pago. El pool se configura en token_pool_config.json y soporta estrategias round-robin, weighted round-robin, least-used y failover. El pool escribe su estado a un fichero de runtime para observabilidad.
Reason. El pool provee redundancia, distribución de carga y observabilidad. El fichero de estado del pool es la base del audit trail del lab para uso de APIs externas.
Consequences. Positivo: redundancia, distribución de carga, observabilidad. Negativo: más configuración que gestionar, error handling más complejo. El coste merece la pena por la reliability del lab.
ADR-006: Cada llamada externa se registra en un request journal
Status: Accepted
Date: 2026-05-10
Context. El lab hace muchas llamadas externas. El diseño inicial no registraba las llamadas. Esto hacía imposible responder "¿qué hizo el lab el martes pasado?" o "¿por qué falló esta misión?".
Decision. Cada llamada externa se registra en un request journal append-only. El journal se rota cuando excede un tamaño configurado. El journal es la base del audit trail del lab para uso de APIs externas.
Reason. El journal provee observabilidad completa de las llamadas externas. El journal es append-only para prevenir tampering. El journal se rota para mantener tamaños de fichero manejables.
Consequences. Positivo: observabilidad completa, resistencia a tampering. Negativo: overhead de storage, la necesidad de redactar datos sensibles. El coste merece la pena por la auditabilidad del lab.
ADR-007: El lab es local-first
Status: Accepted
Date: 2026-05-10
Context. El lab podría ser cloud-based, pero el usuario quiere un diseño local-first por control, privacidad y aprendizaje.
Decision. El lab corre en la máquina del usuario. El único acceso de red es a providers externos (model, search, streaming) y a la red local (mDNS para device discovery). No hay un cloud control plane.
Reason. Local-first provee control, privacidad y oportunidades de aprendizaje. El usuario puede inspeccionar cada componente, modificar cada configuración y recuperarse de cada fallo sin depender de un servicio cloud.
Consequences. Positivo: control, privacidad, aprendizaje. Negativo: limitado por recursos locales, requiere backups del lado del usuario, requiere que el usuario gestione dependencias. El coste merece la pena por los valores del lab.
ADR-008: La documentación es un deliverable
Status: Accepted
Date: 2026-05-10
Context. Los proyectos del lab empezaron sin documentación. El usuario se dio cuenta de que sin documentación los proyectos eran difíciles de mantener, difíciles de onboard collaborators y difíciles de recuperar de un fallo.
Decision. Cada proyecto debe tener documentación. La documentación incluye README.md, code-reference.md y architecture.md. La documentación se actualiza con cada commit que cambie la arquitectura, los componentes o las interfaces públicas.
Reason. La documentación hace los proyectos maintainable, learnable y recoverable. El coste de escribir documentación es pequeño comparado con el coste de no tenerla.
Consequences. Positivo: maintainability, learnability, recoverability. Negativo: más trabajo por cambio. El coste merece la pena.
ADR-009: Los providers externos están detrás de adaptadores
Status: Accepted
Date: 2026-05-11
Context. El lab se integra con varios providers externos. El diseño inicial tenía código provider-specific disperso por el framework. Esto hacía difícil añadir providers nuevos, testear sin providers reales y cambiar de provider.
Decision. Los providers externos están detrás de adaptadores. El contrato de adaptador está documentado en External Providers. Un provider nuevo requiere un adaptador nuevo; el resto del framework no cambia.
Reason. Los adaptadores proveen un contrato limpio, testabilidad y swap-ability. El coste de escribir un adaptador es pequeño comparado con el coste de no tener uno.
Consequences. Positivo: contrato limpio, testabilidad, swap-ability. Negativo: más ficheros, más boilerplate. El coste merece la pena.
ADR-010: Smart Orchestrator V2
Status: Planned
Date: TBD
Context. El orquestador actual es determinista a nivel de orquestación. Las fases están predefinidas y el DAG es fijo. El usuario quiere que el orquestador sea más inteligente: que elija las fases correctas según la query, que salte fases innecesarias, que reintente con parámetros distintos y que paralelice de forma más agresiva.
Decision. El orquestador se rediseña para ser adaptativo. El orquestador usa un planner que selecciona las fases según la query, un executor que corre las fases seleccionadas y un verifier que comprueba los resultados. El DAG se genera por misión, no por proyecto.
Reason. El orquestador actual es rígido. El orquestador adaptativo es más flexible, más eficiente y más capaz.
Consequences. Positivo: flexibilidad, eficiencia, capacidad. Negativo: más complejo, más modos de fallo, más difícil de testear. El coste merece la pena por las ambiciones del lab.
Open questions.
- ¿Cómo se entrena el planner? ¿Con ejemplos? ¿Con un rule engine? ¿Con un modelo?
- ¿Cómo se diseña el verifier? ¿Qué constituye éxito?
- ¿Cómo se testea el orquestador adaptativo? ¿Con misiones grabadas? ¿Con queries sintéticas?
ADR-011: Plugin system para herramientas de dominio custom
Status: Drafting
Date: TBD
Context. El research framework actual tiene 8 herramientas de dominio hardcoded. Añadir una herramienta de dominio nueva requiere modificar el orquestador. El usuario quiere un sistema de plugins que permita a terceros añadir herramientas de dominio sin modificar el framework.
Decision. El research framework expone un plugin API. Un plugin es un paquete Python que implementa el contrato de plugin. El orquestador descubre los plugins en el arranque y los registra.
Reason. Un sistema de plugins permite al lab extenderse sin modificar el core. El coste es un plugin API y la security review de los plugins.
Consequences. Positivo: extensibilidad, contribuciones de la comunidad. Negativo: más superficie de API, más security review. El coste merece la pena por la apertura del lab.
Open questions.
- ¿Cómo se descubren los plugins? ¿Por fichero? ¿Por entry point? ¿Por configuración?
- ¿Cómo se sandboxean los plugins? ¿Qué puede acceder un plugin?
- ¿Cómo se versionan los plugins? ¿Cómo se resuelven los conflictos?
ADR-012: SQLite o PostgreSQL para almacenamiento de artefactos
Status: Planned
Date: TBD
Context. El almacenamiento de artefactos actual es el filesystem. Los artefactos son ficheros JSON en un árbol de directorios. El filesystem es simple pero tiene limitaciones: (1) no permite queries, (2) no tiene transacciones, (3) no tiene escrituras concurrentes, (4) no tiene replicación.
Decision. El almacenamiento de artefactos se migra a SQLite (para single-host) o PostgreSQL (para multi-host). La migración es transparente para los consumers; el artifact API es el mismo.
Reason. Una base de datos provee queries, transacciones, escrituras concurrentes y replicación. El coste es una migración y una base de datos que gestionar.
Consequences. Positivo: queries, transacciones, escrituras concurrentes, replicación. Negativo: esfuerzo de migración, gestión de base de datos. El coste merece la pena por la escala del lab.
Open questions.
- ¿SQLite o PostgreSQL? La decisión depende del crecimiento del lab.
- ¿Cómo se hace la migración? ¿Online? ¿Offline?
- ¿Cómo se diseña el esquema? ¿Una tabla por tipo de artefacto? ¿Una tabla para todos?
ADR-013: Cross-mission artifact reuse
Status: Drafting
Date: TBD
Context. El research framework actual no comparte artefactos entre misiones. Una misión que investiga "hoteles en Barcelona" no puede reutilizar los artefactos de una misión previa sobre el mismo tema.
Decision. El framework introduce un shared artifact store. Las misiones pueden declarar inputs de misiones previas. El shared store es content-addressed; los mismos inputs siempre producen los mismos outputs.
Reason. El cross-mission artifact reuse ahorra tiempo, reduce el uso de API y mejora la consistencia. El coste es un shared store y un esquema content-addressed.
Consequences. Positivo: eficiencia, consistencia. Negativo: almacenamiento más complejo, invalidación más compleja. El coste merece la pena por las ambiciones del lab.
Open questions.
- ¿Cómo se estructura el shared store? ¿Por tema? ¿Por usuario? ¿Por proyecto?
- ¿Cómo se hace la invalidación? ¿Por TTL? ¿Por evento?
- ¿Cómo se asegura la consistencia? ¿Con locks? ¿Con CRDTs?