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

Capítulo 4 — Protocolo para agentes: construí tu harness

Por: Artiko
agentesharnessprotocoloagents-mdautomation

Capítulo 4 — Protocolo para agentes: construí tu harness

Aviso al lector humano: este capítulo no está optimizado para vos. Es un protocolo ejecutable diseñado para que un agente IA lo lea y construya un harness real en el proyecto sobre el que está trabajando. Si sos humano, leé los capítulos 1, 2 y 3 primero. Después podés invocar a tu agente con: “Leé el capítulo 4 del tutorial de harness engineering y construí el harness para este proyecto”.

Aviso al agente IA: lo que sigue es para vos. Es un protocolo paso a paso. Ejecutalo en orden. No saltes pasos. No improvises. El objetivo es que cuando termines, el proyecto donde estás trabajando tenga el harness mínimo viable para que vos o cualquier otro agente pueda trabajar sobre él de forma confiable en futuras sesiones.

0. Pre-requisitos antes de empezar

Antes de ejecutar el protocolo, verificá lo siguiente. Si algo falla, detené el protocolo y pedile aclaración al usuario humano:

[ ] Estás dentro de un repositorio git (existe carpeta .git/)
[ ] Tenés permisos de escritura en el directorio
[ ] El usuario humano te dio autorización explícita para crear archivos en la raíz
[ ] Sabés qué problema concreto está tratando de resolver el usuario con este harness

Si el usuario invocó este protocolo sin contexto, pregúntale una sola vez:

  1. ¿Qué tipo de proyecto es este? (web app, CLI tool, biblioteca, infra, etc.)
  2. ¿Qué tarea grande te imaginás delegando a un agente acá? (refactor, agregar features, mantenimiento, etc.)
  3. ¿Qué agente va a usar este harness principalmente? (Claude Code, Cursor, Goose, Aider, otro)

No avances al protocolo hasta tener esas tres respuestas o tu mejor inferencia documentada.

1. Modelo mental que tenés que usar

Antes de actuar, internalizá estas tres ideas de los capítulos anteriores:

IdeaCapítuloAplicación
Agent = Model + Harness2 (Fowler)Vos sos el modelo. Lo que vas a construir es el harness
Feedforward (guías) + Feedback (sensores)2 (Fowler)Cada artefacto que crees debe ser una de las dos cosas
Iterar el harness en cada fallo recurrente3 (Hashimoto, fase 5)El primer harness es mínimo viable, no completo
Una feature por sesión, estado siempre limpio1 (Anthropic)Si el proyecto será trabajado en sesiones largas, esto es ley
Variety reduction2 (Fowler / Ashby)Restringí el espacio de decisión del agente para que un harness chico sea suficiente

Si en cualquier momento del protocolo dudás de una decisión, releé esta tabla.

2. Protocolo de ejecución en 5 fases

Fase 1: Reconocimiento del proyecto
Fase 2: Diagnóstico de harnessability
Fase 3: Construcción del harness mínimo viable
Fase 4: Verificación y handoff
Fase 5: Setup del steering loop

Ejecutá las fases en orden. No saltes a la fase 3 sin completar 1 y 2.

Fase 1 — Reconocimiento del proyecto

Objetivo: entender qué hay en el repo antes de meter archivos nuevos.

Ejecutá estos comandos y guardá las respuestas internamente:

# 1.1 ¿Qué stack es?
ls -la
cat package.json 2>/dev/null || cat pyproject.toml 2>/dev/null || cat go.mod 2>/dev/null || cat Cargo.toml 2>/dev/null

# 1.2 ¿Cuál es el árbol de carpetas top-level?
ls -la src/ 2>/dev/null
find . -maxdepth 2 -type d -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/dist/*"

# 1.3 ¿Cómo se ejecuta el proyecto?
cat README.md 2>/dev/null | head -50
cat Makefile 2>/dev/null | head -30

# 1.4 ¿Ya hay harness existente?
ls -la AGENTS.md CLAUDE.md .agent/ .goose/ .cursor/ 2>/dev/null
ls -la .agents/ docs/AGENTS.md docs/CLAUDE.md 2>/dev/null

# 1.5 ¿Hay tests?
find . -path "*/test*" -o -name "*.test.*" -o -name "*_test.go" 2>/dev/null | head -20

# 1.6 Convenciones de commits
git log --oneline -20

Construí un resumen mental con estas 6 dimensiones. Vas a usarlo en la fase 3.

Regla crítica: si encontrás un AGENTS.md o CLAUDE.md existente, NO lo sobreescribas. Leelo entero. Tu trabajo va a ser complementarlo, no reemplazarlo. Si su contenido contradice este protocolo, el archivo existente gana — fue escrito con conocimiento de este proyecto.

Fase 2 — Diagnóstico de harnessability

Objetivo: identificar qué propiedades del proyecto facilitan o dificultan que un agente trabaje bien.

Respondé estas preguntas en tu cabeza, con evidencia del repo:

PreguntaCómo verificarloSi no
¿Tipado fuerte?tsconfig.json con strict, mypy, types nativosDocumentá esto como limitación
¿Tests automatizables?comando reproducible para testPedile al usuario priorizar esto
¿Build determinístico?npm/bun build, cargo build, go build funcionaDocumentá comandos manuales
¿Linter / formatter?.eslintrc, .prettierrc, ruff.toml, gofmtSugerí cuál agregar
¿Límites de módulos claros?Carpetas con responsabilidad obviaDocumentá la convención que veas
¿Hay state externo crítico?DB, redis, API keys necesarias para correrEsto va a init.sh
¿Hay archivos peligrosos?secretos, datos de producción, configs sensiblesEsto va a gooseignore/exclusiones

Decisión de scope:

Fase 3 — Construcción del harness mínimo viable

Objetivo: crear los artefactos concretos que un agente va a leer en cada sesión futura.

Vas a crear hasta 5 archivos, en este orden:

  1. AGENTS.md (feedforward principal)
  2. .agent/init.sh (feedforward operacional)
  3. .agent/features.json (sensor + variety reduction)
  4. .agent/progress.md (memoria persistente)
  5. .agent/.gitignore (sanitización)

Antes de escribir cada archivo: si ya existe uno equivalente, leelo y mergeá en lugar de sobreescribir.

3.1 — AGENTS.md en la raíz del repo

Este es el archivo más importante. Lo va a leer cada agente en cada sesión. Sea conciso. Idealmente < 200 líneas.

Usá esta plantilla como base. Reemplazá los placeholders entre <<< >>> con info real del proyecto recogida en fase 1:

# AGENTS.md

> Archivo de referencia para agentes IA que trabajan en este repositorio.
> Última actualización: <<<YYYY-MM-DD>>>

## Qué es este proyecto

<<<UNA FRASE: qué problema resuelve, no detalles técnicos>>>

Stack: <<<lenguaje principal>>>, <<<framework>>>, <<<DB / infra crítica>>>

## Cómo levantar el entorno

```bash
bash .agent/init.sh

Si el script falla, los pasos manuales son:

  1. <<<comando 1>>>
  2. <<<comando 2>>>

Convenciones que NO podés violar

Estructura

Comandos críticos

TareaComando
Tests<<<comando test>>>
Lint<<<comando lint>>>
Build<<<comando build>>>
Dev server<<<comando dev>>>

Reglas de operación

  1. Trabajá una feature por sesión. Si la tarea es grande, dividila.
  2. Antes de declarar terminado: corré tests, corré lint, corré build.
  3. Nunca modifiques ni elimines tests existentes para “hacerlos pasar”.
  4. Si una decisión de diseño es ambigua: parate y preguntá al humano.
  5. Después de cada cambio significativo, actualizá .agent/progress.md.

Errores recurrentes a evitar

<<<Lista que crece con el tiempo — empezá vacía o con 1 ejemplo del repo>>>

Qué NO hacer

Referencias


**Reglas críticas para llenar la plantilla**:

- Si no sabés algo, **escribí `TODO:` en lugar de inventar**.
- La sección "Errores recurrentes" empieza vacía. Solo el humano debe agregar reglas verificadas en producción.
- "Convenciones que NO podés violar" debe ser corta. Si tenés más de 5, eligí las 5 más críticas.
- Nada de prosa. El archivo es para que un agente lo lea rápido en cada turno.

#### 3.2 — `.agent/init.sh`

Script de bootstrap. Debe ser **idempotente** (correrlo dos veces no debe romper nada).

```bash
#!/bin/bash
set -e

echo "🪿 Inicializando entorno del proyecto..."

# 1. Validar pre-requisitos
command -v <<<BINARIO CRÍTICO ej: node, bun, python>>> >/dev/null || {
  echo "ERROR: falta <<<binario>>>"
  exit 1
}

# 2. Instalar dependencias si cambió package.json (u equivalente)
if [ ! -d "node_modules" ] || [ package.json -nt node_modules/.package-lock.json ] 2>/dev/null; then
  echo "Instalando dependencias..."
  <<<comando install>>>
fi

# 3. Variables de entorno
if [ ! -f ".env" ] && [ -f ".env.example" ]; then
  echo "ADVERTENCIA: copiá .env.example a .env y completá los valores"
fi

# 4. Verificar que el proyecto compila
echo "Verificando build..."
<<<comando build o type check>>>

# 5. Correr tests rápidos
echo "Corriendo tests..."
<<<comando test rápido>>>

echo "✅ Entorno listo."
echo "Comandos disponibles:"
echo "  <<<comando dev>>>   - servidor de desarrollo"
echo "  <<<comando test>>>  - tests"
echo "  <<<comando build>>> - build de producción"

Hacelo ejecutable: chmod +x .agent/init.sh.

Reglas:

3.3 — .agent/features.json

Lista estructurada de features con estado. Solo crealo si el proyecto va a tener trabajo planificable en módulos. Si es mantenimiento ad-hoc, saltealo y dejá una nota en progress.md.

{
  "schema_version": 1,
  "project": "<<<nombre del proyecto>>>",
  "updated": "<<<YYYY-MM-DD>>>",
  "features": [
    {
      "id": "f001",
      "category": "functional",
      "description": "<<<Descripción de una feature concreta a implementar>>>",
      "acceptance_criteria": [
        "<<<paso 1 verificable>>>",
        "<<<paso 2 verificable>>>"
      ],
      "passes": false,
      "notes": ""
    }
  ]
}

Reglas de uso del agente:

3.4 — .agent/progress.md

Log cronológico de sesiones. Cada agente que trabaje en el proyecto va a leerlo al inicio y agregarle una entrada al final.

# Progress log

Log cronológico de sesiones de agentes IA sobre este proyecto.
Las entradas más recientes van al final.

---

## Sesión inicial — <<<YYYY-MM-DD>>>

**Agente**: <<<tu identidad: Claude Code, Cursor, etc.>>>
**Tarea**: Bootstrap del harness siguiendo el protocolo del capítulo 4 de harness engineering.

**Hecho**:
- Creé AGENTS.md con convenciones detectadas en el repo.
- Creé .agent/init.sh con setup del entorno.
- Creé este progress.md.
- <<<Otras cosas según el caso>>>

**Pendiente / TODO**:
- El humano debe revisar AGENTS.md y completar los `TODO:` que dejé.
- <<<otros pendientes>>>

**Decisiones de diseño**:
- <<<Si hubo una decisión no obvia, anotala con un párrafo de razonamiento>>>

**Próximos pasos sugeridos**:
- <<<qué haría el siguiente agente>>>

---

Reglas:

3.5 — .agent/.gitignore

# Archivos temporales del agente que no deben commitearse
*.tmp
*.local
scratch/

Pequeño y prudente.

Fase 4 — Verificación y handoff

Antes de declarar el trabajo terminado, ejecutá esta checklist:

[ ] AGENTS.md existe en la raíz y tiene contenido relevante (no solo placeholders)
[ ] `bash .agent/init.sh` corre sin errores
[ ] `.agent/progress.md` tiene tu entrada de sesión inicial
[ ] No commiteaste secretos ni archivos sensibles
[ ] El árbol del repo se ve así (mínimo):
    AGENTS.md
    .agent/
      init.sh        (executable)
      progress.md
      .gitignore
      [features.json si lo creaste]
[ ] git status muestra solo los archivos que esperás
[ ] git diff de archivos pre-existentes (si los hay) está justificado

Si cualquier ítem falla, no entregues el trabajo. Arreglalo o pedile ayuda al humano.

Handoff al usuario humano: cuando termines, respondele al humano con exactamente este formato:

✅ Harness mínimo viable creado.

ARCHIVOS NUEVOS:
- AGENTS.md
- .agent/init.sh
- .agent/progress.md
- [otros]

PARA REVISAR ANTES DE COMMITTEAR:
- AGENTS.md contiene <N> `TODO:` que necesitan tu input.
- init.sh: revisá que los comandos sean los correctos para tu workflow.
- [otros puntos]

PRÓXIMOS PASOS:
1. Completá los TODO en AGENTS.md.
2. Probá `bash .agent/init.sh` desde una shell limpia.
3. Si funciona, commit + push.
4. En la próxima sesión, el siguiente agente va a leer estos archivos automáticamente.

PREGUNTAS QUE TE HAGO AHORA (opcional):
- [Si encontraste ambigüedades durante el proceso, listalas acá]

No hagas commit vos mismo a menos que el humano te lo pida explícitamente.

Fase 5 — Setup del steering loop

El harness recién creado no es final. Es el punto de partida. El humano debe entender cómo iterarlo.

Agregá esta sección al final del AGENTS.md si aún no existe:

## Cómo iterar este harness

Cuando un agente cometa el mismo error dos veces:

1. Identificá el error concreto (no abstracto).
2. Agregá una regla en "Errores recurrentes a evitar" o "Convenciones".
3. Si necesita verificación automática, creá un script en `.agent/checks/` y referenciálo desde AGENTS.md.
4. La próxima sesión, el agente lee la regla nueva y no debería repetir el error.

Si un agente recibe instrucciones contradictorias entre este archivo y otro:
- Este archivo (`AGENTS.md`) gana.
- Si hay un README.md con instrucciones distintas, pedíle al humano que defina la fuente única de verdad.

3. Apéndice A — Decisiones rápidas

Matriz de “si X, entonces Y” para casos comunes que se van a presentar durante el protocolo:

SituaciónAcción
El repo no tiene READMECrealo simple antes de seguir, con la info que recolectaste en fase 1
Hay varias subcarpetas con proyectos distintos (monorepo)Creá un AGENTS.md en cada subcarpeta + uno en la raíz que apunte a ellos
El stack es desconocido o exóticoPedíle al humano que te describa cómo se ejecuta antes de inventar comandos
Hay tests pero todos fallanDocumentá el hecho en AGENTS.md, no los toques
Las convenciones son inconsistentes en el códigoDocumentá las convenciones del código más nuevo, no las del más viejo
El humano no contesta tus preguntas inicialesConstruí el harness con TODO: honestos y entregá. No inventes
Ya hay un AGENTS.md y dice cosas contrarias a este protocoloEl archivo existente gana. Avisá al humano de las divergencias
El proyecto es < 100 líneas de código totalEl harness es overkill. Sugerí no crearlo y guardar la energía
El humano dice “hacé todo, no me preguntes”Igual creá los TODOs. Decisiones específicas requieren contexto humano

4. Apéndice B — Anti-patterns que NO debés cometer

Estos son los errores típicos de agentes ejecutando este protocolo. Evitalos:

❌ Sobre-construir el harness en la primera pasada

Si creaste más de 5 archivos, te excediste. El harness crece con la fricción real, no con tu imaginación.

❌ Llenar AGENTS.md con prosa generada

Los agentes leen el archivo en cada turno. Cada token cuesta. Tablas > listas > párrafos.

❌ Inventar convenciones que no están en el código

Si el código existe y vos no entendés su convención: documentá lo que ves, no lo que “debería ser”. Hashimoto cap 3: el agente carece de memoria organizacional. No inventes la cultura del equipo.

❌ Crear features.json con features inventadas

Si el humano no te pasó una lista de features a implementar, no las inventes. Dejá el archivo vacío o no lo crees.

❌ Marcar features como passes: true sin verificar

Cada true es una mentira si no verificaste con un comando concreto. Mejor false honesto que true aspiracional.

❌ Modificar archivos existentes “por estética”

El protocolo te autoriza a crear archivos. No te autoriza a refactorizar el código del repo. Si ves algo feo, no lo toques.

❌ Hacer commit sin permiso

Aún si la tarea es “creá el harness y commiteá”, confirmá una vez más antes del commit con un resumen de qué vas a committear.

❌ Asumir un agente específico

No escribas el harness asumiendo que solo Claude Code va a usarlo. Mantenelo agent-agnostic salvo que el humano te haya dicho lo contrario.

5. Apéndice C — Cómo saber que el harness sirve

El harness es bueno si en la próxima sesión un agente distinto al que lo creó puede:

1. Leer AGENTS.md (< 30 segundos de tu contexto)
2. Ejecutar bash .agent/init.sh y tener el entorno listo
3. Leer progress.md y entender qué pasó antes
4. Tomar una tarea pequeña y completarla sin pedirle al humano que le explique
   convenciones básicas

Si esos 4 pasos no se cumplen, el harness está incompleto. Volvé al protocolo, fase 2.

6. Cierre

Cuando termines de ejecutar este protocolo:

Recordá: el harness emerge desde la práctica, no desde la teoría. Lo que creaste hoy es el punto de partida. Cuando el humano vuelva con “el agente cometió X error otra vez”, la respuesta correcta es: “Agregá la regla en AGENTS.md”, no “reescribí el modelo”. Esa es la lección del capítulo 3 y la diferencia entre equipos que dominan agentes y equipos que sufren con ellos.

Lecturas que asumo conoces

Si no leíste los capítulos anteriores, primero leelos. Después volvé acá y ejecutá el protocolo.

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