Decisiones de Arquitectura

Esta página recoge las decisiones que explican por qué el sistema está construido así. No son verdades universales; son elecciones tomadas para este proyecto personal de aprendizaje.

ADR-001: Separar el Agente Principal y los Agentes Especializados

Decisión: el coordinador coordina, el asistente de código implementa y el agente de investigación se encarga de los dominios especializados.

Motivo: un solo agente con demasiadas responsabilidades se vuelve difícil de auditar. Separar los roles permite razonar mejor sobre permisos, contexto, herramientas y fallos.

Consecuencia: hay más piezas que mantener, pero cada una es más clara.

ADR-002: Herramientas CLI Antes que Automatizaciones Opacas

Decisión: las capacidades repetibles se implementan como scripts CLI pequeños.

Motivo: una CLI se puede ejecutar, testear, registrar y documentar. Y también puede usarla una persona si el agente falla.

Consecuencia: el sistema gana trazabilidad, aunque cada herramienta exige más documentación.

ADR-003: Escribir TOOL.md Antes del Código

Decisión: cada herramienta nueva debe tener una especificación técnica antes de empezar a implementarla.

Motivo: la especificación reduce la ambigüedad, mejora el prompt que recibe el asistente de código y permite comprobar si el resultado cumple lo que se pedía.

Consecuencia: la implementación tarda un poco más en arrancar, pero suele necesitar menos correcciones.

ADR-004: Skills como Contexto Activable

Decisión: usar SKILL.md y .agents/skills para que los agentes sepan cuándo y cómo usar una capacidad.

Motivo: el contexto no debería depender solo de que el usuario se acuerde de incluirlo en cada prompt.

Consecuencia: las skills pasan a formar parte del contrato de mantenimiento.

ADR-005: Persistir Artefactos en los Pipelines Largos

Decisión: el framework de investigación escribe artefactos intermedios por fase.

Motivo: las investigaciones largas necesitan puntos de control, trazabilidad y poder reanudarse.

Consecuencia: hay más archivos, pero el sistema es más fácil de auditar.

ADR-006: Aceptar el Éxito Parcial

Decisión: succeeded_partial es un estado válido.

Motivo: en la investigación real, algunas fuentes fallan o devuelven datos incompletos. El sistema debe producir resultados útiles sin esconder las degradaciones.

Consecuencia: los informes tienen que explicar sus limitaciones y su cobertura.

ADR-007: Documentación Obligatoria en las Plantillas

Decisión: los repositorios nuevos arrancan con AGENTS.md y docs/.

Motivo: el contexto para agentes y la documentación técnica son infraestructura, no tareas de última hora.

Consecuencia: los proyectos empiezan con más estructura, pero escalan mejor.

ADR-008: Hacer Explícitos los Límites de Contexto

Decisión: prompts, skills, archivos de memoria, colas de trabajo y herramientas CLI deben declarar qué contexto consumen y qué artefactos producen.

Motivo: los límites claros facilitan auditar el comportamiento, reproducir flujos de trabajo e identificar qué componente es responsable cuando cambia un resultado.

Consecuencia: el sistema exige contratos más explícitos, pero los fallos y handoffs se vuelven más fáciles de razonar.

ADR-009: Proveedores Externos Detrás de Adaptadores

Decisión: los servicios externos de investigación se consumen mediante adaptadores, no incrustados directamente en la lógica del agente ni en las fases del pipeline.

Motivo: los adaptadores de proveedor mejoran la sustituibilidad, las pruebas y la trazabilidad. El agente solicita investigación a través de una frontera estable, mientras la implementación específica del proveedor queda aislada.

Consecuencia: la investigación externa se convierte en otra capacidad invocable. El adaptador añade una pequeña capa de integración, pero evita que los cambios de proveedor se propaguen por el worker o el pipeline de investigación.