Arquitecturas para proyectos nuevos¶
Esta guía explica cómo el harness ayuda a elegir y aplicar una arquitectura cuando el proyecto se crea desde cero (greenfield): qué estilos ofrece, cómo recomienda uno, cómo decides tú y qué hace después un experto en el estilo elegido.
Cómo activarlo¶
La función está detrás de la clave architecture.catalogue: experts de .harness/project.yaml.
harness init la escribe junto con architecture.mode: agent:
architecture:
mode: agent
catalogue: experts
Un project.yaml sin la clave conserva el comportamiento anterior: el harness no ofrece el
catálogo, no escribe el reporte ni llama al experto, y el digest de la configuración no cambia.
harness config validate muestra el valor efectivo en engineering.architecture.catalogue.
El catálogo de diez estilos¶
Los estilos son los ocho que el harness ya reconocía más dos que faltaban. Se escogieron por ser los más usados en proyectos de software de propósito general y de interfaces, y porque cada uno se puede describir con reglas de dependencia que una herramienta puede revisar (o, cuando no hay capas, con reglas de módulos o contratos).
| Estilo | Para qué sirve | Reglas de capas incluidas |
|---|---|---|
layered |
Separar presentación, servicios y datos; cada capa usa solo la de abajo | presentation, services, data |
hexagonal |
Un núcleo de negocio aislado que habla con el exterior mediante puertos y adaptadores | domain, application, adapters |
clean |
Anillos concéntricos con dependencias solo hacia adentro | entities, usecases, adapters, frameworks |
ddd |
Dominios complejos con lenguaje ubicuo y contextos acotados | domain, application, infrastructure, interfaces |
modular-monolith |
Una sola aplicación con módulos de interfaz pública explícita | no tiene plantilla: los módulos son propios de cada proyecto |
microservices |
Servicios que se despliegan y escalan por separado | no tiene plantilla: los servicios se comunican por contratos |
mvvm |
Pantallas con un modelo de vista que expone estado observable | model, viewmodel, view |
mvi |
Pantallas con un único estado inmutable y un ciclo unidireccional | model, intent, view |
event-driven |
Componentes que reaccionan a eventos publicados por otros | no tiene plantilla: productores y manejadores dependen del contrato de eventos |
cqrs |
Modelos separados para escribir (comandos) y leer (consultas) | domain, commands, queries |
Cada estilo viene empaquetado con el harness (carpeta resources/architecture del paquete,
incluida en el wheel) en un archivo con: propósito, cuándo encaja, beneficios y costos, estructura
de carpetas, mejores prácticas, reglas de dependencia y el prompt del experto. Al elegir un
estilo, el documento del estilo (sin el prompt) se copia a .harness/architecture-style.md
dentro del proyecto.
Las plantillas de capas usan rutas genéricas (por ejemplo **/domain/**). Si tu proyecto usa
otros nombres, ajusta architecture.layers en project.yaml: las capas configuradas tienen
prioridad.
El flujo, paso a paso¶
- Creas la tarea y ejecutas
harness run start --task <id>. En INTENT, si el proyecto es nuevo, el agente padre analiza la tarea y la estructura inicial y responde con dos a cuatro opciones del catálogo, marcando exactamente una como recomendada. - La ejecución queda en
BLOCKED. El mensaje indica la opción recomendada y el reporte. - Lees el reporte en
.harness/architecture-options.md(también conharness architecture show, camporecommendation). Dice qué arquitectura se recomienda, por qué y qué características del proyecto la respaldan, y lista las demás opciones con sus beneficios y costos. - Decides, siempre ligado al digest de las opciones:
# Aceptar la recomendada
harness architecture decide --run <run> --option <id-recomendada> --digest <digest> \
--rationale "Encaja con el proyecto"
# Elegir otra de las opciones propuestas
harness architecture decide --run <run> --option <otro-id> --digest <digest> \
--rationale "Preferimos esta"
# Elegir cualquier estilo del catálogo, aunque no se haya propuesto
harness architecture decide --run <run> --style cqrs --digest <digest> \
--rationale "Leemos y escribimos de forma muy distinta"
Si eliges con --style un estilo que el agente sí propuso, se usan las capas que propuso. Si no
lo propuso, se usan las capas de la plantilla del catálogo (o ninguna, para los estilos sin
plantilla). Una decisión de un actor que no es una persona, un digest desactualizado, un estilo
fuera del catálogo o usar --option y --style a la vez se rechazan (código de salida 5).
5. El harness registra la decisión como un ADR (.harness/adr/ADR-0001-architecture.md) con las
reglas de capas, y el estilo queda vigente.
6. Al reanudar, interviene el experto del estilo elegido: una llamada de solo lectura que recibe
su prompt especializado y planifica cómo organizar el proyecto (carpetas y módulos con su
propósito, y las mejores prácticas que aplican). El plan se guarda en
.harness/architecture-organization.md y en el estado; no se vuelve a pedir en las
ejecuciones siguientes.
7. En cada llamada posterior al agente (implementación, revisión), el bloque architecture de la
solicitud lleva el prompt del experto, el resumen del plan, el estilo y el camino del
documento del estilo. Las instrucciones piden al agente actuar como ese experto y mantener la
implementación alineada con el estilo.
Qué hace y qué no hace el experto¶
- La llamada del experto es de solo lectura, como el resto de las llamadas de arquitectura: propone la organización, no crea carpetas ni archivos. Quien escribe el código es el agente de implementación, que recibe el prompt del experto y el plan.
- La alineación se verifica con las reglas de capas del estilo en VERIFICATION
(
architecture.layer-violation). En los estilos sin plantilla de capas no hay verificación automática de dependencias; si quieres una, configuraarchitecture.layersyallow.
Cómo comprobar que funcionó¶
- Reporte:
.harness/architecture-options.md. - Eventos:
harness trace --run <run> --format jsonlmuestraarchitecture.options.proposed(con la opción recomendada),architecture.decided(constyleyacceptedRecommendation) yarchitecture.organization.proposed(con el digest del plan). - Evidencia: las opciones y el plan se guardan como evidencia de la ejecución.
- Solicitud al agente: el artefacto de la solicitud de implementación contiene
architecture.expert.prompt.
Archivos que genera¶
| Archivo | Para qué sirve |
|---|---|
.harness/architecture.json |
Estado: opciones, decisión, reglas y plan del experto |
.harness/architecture-options.md |
Reporte de la recomendación |
.harness/adr/ADR-0001-architecture.md |
Registro de la decisión |
.harness/architecture-style.md |
Documentación del estilo elegido |
.harness/architecture-organization.md |
Plan de organización del experto |
Proyectos existentes¶
Para un proyecto que ya tiene código, el harness no ofrece el catálogo: infiere la arquitectura existente. Consulta la guía de ingeniería inversa.