Chuleta del harness de agente: componentes, archivos, problemas y lista de arranque

Cinco subsistemas del harness

Orden para construirlo desde cero: retroalimentación → instrucciones → estado → entorno → herramientas.

Archivos del harness

Esqueleto de AGENTS.md

# Proyecto: backend de pagos (FastAPI, PostgreSQL)

## Arrancar
docker compose up -d && ./scripts/init.sh

## Comprobar
make check   # lint, tipos, unitarias, arch-check
make e2e     # escenarios de extremo a extremo

## Definition of Done
- make check y make e2e — código 0
- funcionalidad pasada a passing por el script scripts/verify.sh
- PROGRESS.md actualizado

## MUST
- consultas a la base solo a través de repositorios
- secretos solo desde variables de entorno

## Documentos
- docs/payments.md — cuando la tarea afecte a pagos y devoluciones
- docs/migrations.md — cuando cambie el esquema de la base

Estados de una funcionalidad

Niveles de verificación

El derecho a decir «listo» se gana solo tras superar el nivel más alto. Las pruebas unitarias en verde no equivalen a estar terminado.

Convertir las reglas en mecanismos

#!/usr/bin/env bash
fail=0
if grep -rn "from app.db" app/services/; then
  echo "POR QUÉ: los servicios no acceden directamente a la base de datos"
  echo "CORRECCIÓN: use un repositorio de app/repositories/"
  fail=1
fi
exit $fail

Problemas habituales y soluciones

Roles para tareas largas

Presupuesto del trabajo autónomo

• El objetivo cabe en una frase (por ejemplo: llevar todas las funcionalidades a passing).
• WIP=1, un límite de tiempo y de intentos por funcionalidad.
• La métrica crece de forma monótona; una regresión implica reversión inmediata.
• Migraciones, infraestructura, dinero: escalado a una persona.
• Tras varias revisiones fallidas, empezar la funcionalidad con un contexto limpio.

Lista de comprobación para arrancar al agente

1. Existe un AGENTS.md: pila tecnológica, arranque, comando de comprobación, DoD.
2. make check pasa en un clon limpio.
3. El entorno es reproducible: archivos de bloqueo, Docker o devcontainer.
4. El agente tiene los comandos que necesita; los peligrosos están prohibidos o en un entorno aislado.
5. Hay un E2E al menos para el escenario principal.
6. Existe un PROGRESS.md y una regla para leerlo al empezar la sesión.
7. Las funcionalidades están en una lista con su estado; solo una está activa.
8. El estado passing lo asigna un script.
9. Los mensajes de comprobación contienen POR QUÉ y CORRECCIÓN.
10. La tarea está formulada con criterios de aceptación y límites de alcance.
11. Está definido qué requiere una decisión humana.
12. Se ha medido la brecha de verificación antes de los cambios, como referencia.

Métricas del harness

En resumen

El harness es un circuito, no un archivo: instrucciones, herramientas, entorno, estado y retroalimentación. Empiece por las comprobaciones, mantenga AGENTS.md corto, entregue el estado de terminado a un script y revise el harness con regularidad. Todo ello se ensambla como conjunto en un proyecto de extremo a extremo en el curso de harness engineering.