Siempre Listo Escuela
← Volver al listado de tecnologías ← Índice de Learn Harness Engineering

Capítulo 17 — Ocho proyectos prácticos

Por: Artiko
harnessproyectospracticabenchmarkablacionloopgraph

Capítulo 17 — Ocho proyectos prácticos

Leer las lecciones no alcanza. Necesitás construir los entornos vos mismo y observar cómo se comportan Codex, Claude Code u otro agente bajo reglas distintas.

El método es siempre el mismo: cada proyecto se ejecuta dos veces —una con harness débil y otra con harness fuerte— sobre la misma tarea, con el mismo modelo. La comparación es el aprendizaje.

flowchart TD
    P1["P01 — Solo prompt vs reglas primero<br/>AGENTS.md + init.sh + feature_list.json"] --> P2["P02 — Workspace legible<br/>ARCHITECTURE.md + handoff"]
    P2 --> P3["P03 — Continuidad multi-sesión<br/>progreso + init + clean state"]
    P3 --> P4["P04 — Feedback de runtime<br/>logs + restricciones arquitectónicas"]
    P4 --> P5["P05 — Autoverificación<br/>generator + evaluator + planner"]
    P5 --> P6["P06 — Harness completo (capstone)<br/>benchmark + ablación"]
    P6 --> P7["P07 — Tu primer loop<br/>goal + timer + maker-checker"]
    P7 --> P8["P08 — Tu primer grafo<br/>nodos, aristas, routing, HITL"]

El proyecto de referencia es una aplicación Electron de base de conocimiento: ventana con lista de documentos a la izquierda, panel de preguntas y respuestas a la derecha, y un directorio de datos local. La tarea no es compleja; lo complejo es conseguir que el agente la complete de forma verificable. Podés sustituirla por cualquier aplicación tuya de complejidad similar.

Herramientas comunes: Claude Code o Codex (elegí uno y usalo en ambas ejecuciones), Git, el stack de tu proyecto y un temporizador para registrar la duración de cada corrida.

Proyecto 01 — Solo prompt vs. reglas primero

Lecciones 1 y 2

Qué construís: el esqueleto mínimo de la aplicación. Cuatro funciones concretas: lanzar la ventana, listar documentos, panel de preguntas y respuestas, y creación del directorio de datos local.

Cómo se corre:

EjecuciónQué le das al agente
A — línea baseSolo task-prompt.md con la descripción de la tarea
B — reglas primeroAGENTS.md, init.sh y feature_list.json ya colocados en el repositorio

Qué medir: cuántas de las cuatro funciones quedan verificables al final de cada corrida, cuánto contexto gasta el agente explorando antes de escribir la primera línea, y cuántas veces tuviste que intervenir.

Mecanismo de harness: harness mínimo (instrucciones + entorno + feature list).

Proyecto 02 — Workspace legible y retomable

Lecciones 3 y 4

Qué construís: importación de documentos, vista de detalle y persistencia local, completado en dos sesiones.

Cómo se corre: primero sin ayuda; después con ARCHITECTURE.md, PRODUCT.md y session-handoff.md ya colocados.

Qué medir: cuánto contexto tiene que redescubrir la segunda sesión, y si puede continuar solo desde el estado del repositorio sin que le expliques nada verbalmente.

Mecanismo de harness: workspace legible para el agente + archivos de estado persistentes.

Proyecto 03 — Continuidad tras reiniciar sesiones

Lecciones 5 y 6

Qué construís: particionado de documentos, extracción de metadatos, visualización del progreso de indexación y flujo de preguntas y respuestas con citas.

La restricción: usá feature_list.json para seguir el estado de las funciones. Una función a la vez, y prohibido marcar passing sin evidencia de verificación.

Cómo se corre: primero sin restricciones, después con aplicación estricta de reglas y con init.sh, session-handoff.md, claude-progress.md y clean-state-checklist.md en su lugar.

Qué medir: si el agente se desvía entre varias funciones o pierde estado al reiniciar; si cada función tiene evidencia concreta antes de marcarse como aprobada.

Mecanismo de harness: registro de progreso + handoff de sesión + continuidad multi-sesión.

Proyecto 04 — Feedback de runtime y control de alcance

Lecciones 7 y 8

Qué construís: observabilidad de runtime —logs de arranque, logs de importación e indexación, estados de error— más restricciones arquitectónicas que eviten violaciones entre capas.

El truco: sembrá deliberadamente un bug de runtime (por ejemplo, que el chunking se rompa con archivos grandes) para que el agente lo corrija.

Cómo se corre: primero sin logs ni restricciones, después con un logger estructurado, un scripts/check-architecture.sh y docs/ARCHITECTURE.md.

Qué medir: cuánto tarda el agente en encontrar la causa raíz sin señales de runtime; si los logs y los checks de límites hacen la corrección más rápida y menos invasiva.

Mecanismo de harness: feedback de runtime + control de alcance.

Proyecto 05 — Que el agente verifique su propio trabajo

Lecciones 9 y 10

Qué construís: separación de roles. Un generator que implementa, un evaluator que revisa y —opcionalmente— un planner que expande los requisitos.

Elegí una mejora sustancial de función (conversación multiturno, rediseño del panel de citas o filtrado de documentos) y mantenela idéntica en las tres corridas.

VarianteConfiguraciónQué comparar
Un solo rolUn agente planifica, implementa y se autoevalúaPuntuación y defectos en evaluator-rubric.md
Generator + evaluatorDos roles con evidencia de revisiónPuntuación y notas de revisión
Planner + generator + evaluatorTres roles con sprint contractsprint-contract.md y evidencia de mayor puntuación

Mecanismo de harness: autoverificación + finalización basada en evidencia.

Proyecto 06 — Harness completo (capstone)

Lecciones 11 y 12

Qué construís: el proyecto final. Ensamblá todo lo aprendido, ejecutá un benchmark completo y después hacé una pasada de limpieza para verificar que la calidad sea mantenible.

Usá un conjunto fijo de tareas multifunción que cubra un slice completo del producto: importación, indexación, preguntas y respuestas con citas, observabilidad de runtime y estado de repositorio legible y reiniciable.

Las cuatro fases:

flowchart LR
    A["1. Línea base<br/>harness débil"] --> B["2. Harness fuerte<br/>todos los mecanismos"]
    B --> C["3. Pasada de limpieza<br/>y reejecución"]
    C --> D["4. Ablación<br/>quitar un componente a la vez"]
    D --> E["¿Cuáles importan<br/>realmente?"]

El experimento de ablación es lo más valioso del proyecto: eliminá un componente por vez y observá cuáles mueven la aguja. Interpretá los resultados con el criterio de la lección 2 —la mayor caída identifica la contribución marginal, no automáticamente el cuello de botella—.

Herramientas adicionales: plantilla de documento de calidad, rúbrica de evaluación, scripts de benchmark y de escaneo de limpieza.

Proyecto 07 — Construí tu primer loop automatizado

Lección 13

Este es el proyecto de transición de “harness” a “loop”. Partí del mismo commit donde terminaste P06 y creá tres ramas: p07-goal-loop, p07-timer-loop, p07-maker-checker.

Elegí una tarea objetivo de tamaño mediano con criterios de finalización claros, por ejemplo “agregar tests unitarios a todos los módulos alcanzando 80% de cobertura”.

Experimento 1 — Loop de objetivo

  1. Escribí goal.md con objetivo claro, método de verificación, condición de parada y restricciones (“qué no tocar”).
  2. Corré la tarea manualmente primero. Registrá turnos, intervenciones y calidad. Esa es tu línea base.
  3. Corré con /goal usando el mismo goal.md.
  4. Compará turnos, intervenciones, calidad y tiempo invertido por vos.
  5. Iterá sobre goal.md si los resultados son pobres.

Experimento 2 — Loop de temporizador

  1. Elegí una tarea de monitoreo repetitiva (correr la suite de tests cada hora y arreglar fallos; chequear actualizaciones de seguridad de dependencias; escanear TODOs obsoletos).
  2. Escribí el prompt de monitoreo: qué chequear, qué hacer al encontrar problemas y cuándo llamar a un humano.
  3. Corré con /loop a un intervalo de 10-30 minutos durante al menos 2 horas.
  4. Registrá: cuántos problemas encontró, cuántos arregló solo, cuántos fueron falsos positivos, cuántos empeoró y cuánto tiempo invertiste en seguimiento.
  5. Reflexioná: ¿vale la pena automatizar esta tarea?

Experimento 3 — Loop maker-checker

El más importante de los tres. Construís un loop completo que no te necesita presente.

  1. Diseñá la estructura: agente maker (implementa), agente checker (verifica, aprueba o rechaza), archivo de estado loop-state.md (ronda actual, qué se hizo, resultados, qué sigue) y condición de parada (N aprobaciones consecutivas o rondas máximas).
  2. Escribí tres prompts: instrucciones del maker, instrucciones del checker y lógica de control del loop.
  3. Corré al menos 5 rondas registrando cada una.
  4. Retrospectiva: ¿cuántas veces interviniste y por qué? ¿Qué habría pasado si no intervenías? ¿El checker se perdió algún problema? ¿El maker repetía el mismo error? ¿Dónde está el techo de calidad: en el maker o en el checker?

Qué entregar

goal.md con al menos dos iteraciones, notas de comparación manual vs. loop, el prompt de monitoreo con su registro de 2 horas, los tres prompts del experimento 3, loop-state.md con al menos 5 rondas y una retrospectiva final sobre qué cosas son buenas candidatas para convertir en loop y cuáles no.

Proyecto 08 — Dibujá tu flujo de trabajo como un grafo

Lección 14

Proyecto de transición de “loop” a “graph”. Partí de donde terminaste P07 y creá tres ramas: p08-explicit-graph, p08-parallel, p08-human-in-the-loop. Preparate un state.md como archivo de estado compartido.

Experimento 1 — Dibujá el loop como grafo explícito

  1. Enumerá los nodos: para cada uno dejá claro responsabilidad, entradas, salidas y si es agente o código determinista.
  2. Dibujá todas las aristas, marcando con énfasis la arista condicional (pasa/falla) y la de retroceso.
  3. Escribí el estado compartido: qué campos hay y quién los lee y escribe.
  4. Escribí las reglas de routing con el if-then más simple.
  5. Volcalo en graph.md con un diagrama Mermaid, la tabla de nodos y las reglas de routing.
  6. Respondé la pregunta clave: encontrá al menos una arista que antes era implícita, una ruta de decisión escondida en el contexto del agente que ni vos sabías que existía.

Experimento 2 — Fan-out / fan-in paralelo

  1. Elegí un punto paralelizable: dos módulos independientes implementados en paralelo, o dos revisiones independientes (uno corre tests y lint, otro hace code review con instrucciones distintas).
  2. Escribí la regla de fan-out: registrá en el estado compartido que la tarea se dividió en N subtareas, cada una con context y nodo independientes.
  3. Escribí la regla de fan-in: quién fusiona y con qué criterio (¿solo si ambas revisiones pasan, o alcanza con una?).
  4. Aislá con worktrees para evitar físicamente colisiones de archivos.
  5. Registrá tiempo de reloj antes y después, consumo de tokens y calidad. ¿El paralelismo fue realmente más rápido, o el overhead de coordinación se comió el ahorro?

Experimento 3 — Arista de retroceso y aprobación humana

  1. Arista de retroceso condicional: agregá al nodo de verificación una ruta de “aprobado parcialmente” que devuelva el problema al nodo donde se originó, no siempre al de implementación. Si los tests pasan pero la revisión detecta un malentendido de requisitos, se retrocede al nodo de investigación. Esto exige que el estado compartido registre en qué capa está el problema.
  2. Nodo de aprobación humana: agregá un nodo antes del merge donde el grafo se detiene y espera a que escribas “aprobar” o “rechazar” en state.md. Puede tener regla de timeout: sin respuesta después de N horas, se rechaza o se escala automáticamente.
  3. Escribí el formato del interrupt: qué pasó, qué cambió, por qué se necesita una persona y cuáles son las consecuencias de aprobar o rechazar.
  4. Corré al menos 2 rondas completas. Registrá si tu decisión coincidió con el juicio del nodo de verificación, y si el nodo de aprobación detuvo algo que la verificación no había detenido.

Qué entregar

graph.md completo (diagrama + tabla de nodos + tabla de aristas + campos del estado + routing), la lista de aristas implícitas encontradas, las reglas de fan-out/fan-in con el registro de una ejecución paralela, las reglas de retroceso y el formato del nodo de aprobación con dos rondas registradas, y una revisión final sobre qué tareas merecen dibujarse y cuáles no.

Cómo medir en todos los proyectos

MétricaQué te dice
Tasa de completitud verificadaFunciones passing / funciones activadas
Costo de reconstrucciónMinutos hasta que la sesión nueva está en estado ejecutable
Intervenciones humanasCuántas veces tuviste que corregir el rumbo
Ratio de código efectivoLíneas que sobreviven a la verificación / líneas escritas
Tasa de escape de defectosDefectos encontrados después de que el agente declaró “listo”
Tiempo de reloj y tokensEl costo real de cada configuración

Registrá estas seis en cada corrida. Después de los ocho proyectos vas a tener tu propia curva —no la de un blog— de qué componentes del harness te sirven a vos, en tu repositorio, con tu modelo.

Anterior: Capítulo 16 — Biblioteca de plantillas · Siguiente: Capítulo 18 — El skill harness-creator y la biblioteca de referencia

← Volver al listado de tecnologías ← Índice de Learn Harness Engineering