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

Capítulo 16 — Biblioteca de plantillas del harness

25 de agosto de 2026 Por: Artiko

harnessplantillasagents-mdinit-shfeature-listrubrica

Capítulo 16 — Biblioteca de plantillas del harness

Estas plantillas convierten los métodos del curso en archivos que podés copiar hoy a un repositorio real. Editá el contenido para que coincida con los comandos, rutas, nombres de funciones y pasos de verificación de tu proyecto.

El paquete mínimo

flowchart LR
    A["AGENTS.md<br/>o CLAUDE.md"] --> B["init.sh"]
    B --> C["claude-progress.md"]
    C --> D["feature_list.json"]
    D -.el agente lee<br/>y actualiza.-> A

Estos cuatro archivos alcanzan para hacer que la mayoría de los flujos con agentes sean notablemente más estables. Agregá el resto a medida que el proyecto crezca.

Cuándo empezar acá: el trabajo abarca varias sesiones, hay muchas funciones y es fácil dejarlas a medias, los agentes tienden a declarar victoria demasiado pronto, o los pasos de arranque se redescubren cada vez.

1. AGENTS.md

El archivo de instrucciones raíz. Es lo primero que el agente lee al iniciar una sesión. Define las reglas operacionales: qué hacer antes de escribir código, cómo trabajar y cómo cerrar.

Usá AGENTS.md para Codex u otros agentes y CLAUDE.md si trabajás con Claude Code: la estructura es la misma.

# AGENTS.md

## Qué es este proyecto
<Una o dos frases. Qué hace y para quién.>

## Stack y versiones
- Runtime: <Node 22 / Python 3.11 / …>
- Framework: <FastAPI 0.115 / React 19 / …>
- Base de datos: <PostgreSQL 16>
- Gestor de paquetes: <bun / uv / pnpm> — NO usar otro

## Flujo de inicio de sesión (obligatorio, en orden)
1. Ejecutar `./init.sh` y confirmar que la verificación pasa
2. Leer `claude-progress.md` → sección "Estado verificado actual"
3. Leer `feature_list.json` → identificar la única función en `in_progress`,
   o elegir la de menor `priority` en `not_started`
4. Trabajar SOLO en esa función

## Reglas de trabajo
- Una función a la vez. No empezar la siguiente hasta que la actual esté `passing`
- No "aprovechar para refactorizar" mientras se implementa otra cosa
- No modificar los estados de `feature_list.json` a mano: los actualiza la verificación
- Prohibido tocar: `<rutas protegidas: migraciones aplicadas, .env, infra/>`

## Restricciones duras (no negociables)
- <Máximo 15 reglas. Ejemplo: toda API pasa por el middleware de auth>
- <Ejemplo: ninguna query construida por concatenación de strings>
- <Ejemplo: el proceso de render no accede al filesystem>

## Definición de completado
Una función está completa cuando:
1. `<comando de test unitario>` pasa
2. `<comando de test de integración>` pasa
3. `<comando de verificación end-to-end de esa función>` pasa
4. La evidencia está registrada en `feature_list.json`

"El código está escrito" NO es completado.

## Comandos de verificación
```bash
make setup   # instalar dependencias
make test    # tests
make lint    # lint
make types   # type checking
make check   # todo lo anterior
```

## Documentos temáticos (leer bajo demanda)
- `docs/api-patterns.md` — obligatorio al agregar endpoints
- `docs/database-rules.md` — obligatorio al tocar la base de datos
- `docs/testing-standards.md` — referencia al escribir tests

## Fin de sesión (obligatorio)
1. Actualizar `claude-progress.md` con el registro de la sesión
2. Actualizar `feature_list.json`
3. Ejecutar `make check` y confirmar que pasa
4. Revisar `clean-state-checklist.md`
5. Commitear todo el trabajo terminado

Qué hace por el agente: le indica leer el progreso y el estado de las funciones antes de empezar, lo obliga a trabajar en una función a la vez, requiere evidencia antes de marcar algo completado y define cómo se ve un fin de sesión limpio.

Mantené la sección de definición de completado: es la parte más importante del archivo.

2. init.sh

El script de arranque. Ejecuta la instalación de dependencias, la verificación e imprime el comando de inicio, todo en un paso.

#!/usr/bin/env bash
set -euo pipefail

# ── Editá estas tres variables ──────────────────────────────
INSTALL_CMD="${INSTALL_CMD:-make setup}"
VERIFY_CMD="${VERIFY_CMD:-make check}"
START_CMD="${START_CMD:-make dev}"
# ────────────────────────────────────────────────────────────

echo "── Directorio de trabajo ──"
pwd
echo

echo "── Instalando dependencias ──"
eval "$INSTALL_CMD"
echo

echo "── Verificación de línea base ──"
if ! eval "$VERIFY_CMD"; then
  echo
  echo "ERROR: la verificación de línea base FALLA."
  echo "Detené el trabajo de funciones y arreglá la línea base primero."
  echo "No escribas código nuevo sobre un repositorio que no verifica."
  exit 1
fi
echo

echo "── Línea base verificada ──"
echo "Comando de arranque: $START_CMD"

if [ "${RUN_START_COMMAND:-0}" = "1" ]; then
  echo "── Arrancando ──"
  eval "$START_CMD"
fi

Hacelo ejecutable con chmod +x init.sh. Si la verificación falla, el agente debe detenerse y corregir la línea base antes de hacer cualquier otra cosa.

3. feature_list.json

El rastreador de funciones. Una lista legible por máquina de cada función que el agente necesita implementar, con su estado, pasos de verificación y evidencia.

{
  "project": "knowledge-base-app",
  "wip_limit": 1,
  "features": [
    {
      "id": "F01",
      "priority": 1,
      "area": "import",
      "title": "Importar documentos desde el disco",
      "user_visible_behavior": "El usuario elige un archivo .md o .pdf y aparece en la lista de documentos con su título",
      "status": "passing",
      "verification": [
        "npm run dev",
        "Ejecutar el test e2e: npx playwright test e2e/import.spec.ts",
        "Confirmar que el documento aparece en la lista tras reiniciar la app"
      ],
      "evidence": "commit a1b2c3d — playwright 4/4 passed, log en artifacts/import-2026-08-20.txt",
      "notes": ""
    },
    {
      "id": "F02",
      "priority": 2,
      "area": "search",
      "title": "Búsqueda con fragmentos resaltados",
      "user_visible_behavior": "Al escribir en la caja de búsqueda se listan documentos coincidentes con el término resaltado",
      "status": "in_progress",
      "verification": [
        "curl 'http://localhost:3000/api/search?q=harness' | jq '.results | length > 0'",
        "Confirmar que cada resultado incluye el campo 'highlight'"
      ],
      "evidence": "",
      "notes": "Falta el caso de resultados vacíos"
    },
    {
      "id": "F03",
      "priority": 3,
      "area": "qa",
      "title": "Respuestas con citas al documento fuente",
      "user_visible_behavior": "Cada respuesta muestra al menos una cita con el documento y el fragmento usado",
      "status": "not_started",
      "verification": [],
      "evidence": "",
      "notes": ""
    }
  ]
}

Reglas de estado

Estado	Significado
`not_started`	No fue tocada
`in_progress`	La única función en la que se está trabajando (solo una a la vez)
`blocked`	No se puede avanzar por un problema documentado
`passing`	La verificación pasó y la evidencia está registrada

El agente solo debe tener una función en in_progress en cualquier momento.

4. claude-progress.md

El registro de progreso. Cada sesión escribe en este archivo y cada sesión nueva lo lee primero.

# Progreso

## Estado verificado actual
- **Raíz del repositorio**: `/home/usuario/proyectos/knowledge-base`
- **Ruta de arranque estándar**: `./init.sh` y después `npm run dev`
- **Ruta de verificación estándar**: `make check`
- **Último commit verificado**: `a1b2c3d`
- **Estado de tests**: 42/43 pasando (falla `test_pagination_edge_case`)
- **Función pendiente de mayor prioridad**: F02 — búsqueda con resaltado
- **Bloqueo actual**: ninguno

---

## Registro de sesiones

### 2026-08-20 — Sesión 4
- **Objetivo**: terminar F02 (búsqueda con resaltado)
- **Completado**: endpoint `/api/search` con paginación; falta el resaltado
- **Verificación ejecutada**: `make check` (42/43), `curl` manual al endpoint
- **Evidencia registrada**: `artifacts/search-2026-08-20.txt`
- **Commits**: `a1b2c3d`
- **Riesgos conocidos**: el endpoint devuelve 500 con `q` vacío
- **Mejor próxima acción**: agregar el campo `highlight` al serializador
  y cubrir el caso `q=""` con un test antes de seguir

### 2026-08-19 — Sesión 3
- **Objetivo**: cerrar F01 (importación)
- **Completado**: F01 marcada `passing` con evidencia de Playwright
- **Verificación ejecutada**: `npx playwright test` (4/4)
- **Commits**: `9f8e7d6`
- **Riesgos conocidos**: ninguno
- **Mejor próxima acción**: empezar F02

5. session-handoff.md

Una nota de entrega compacta entre sesiones. Es opcional para sesiones cortas; se vuelve importante cuando las sesiones son largas o el proyecto tiene varias áreas activas.

# Handoff de sesión — 2026-08-20

## Actualmente verificado
- F01 (importación) — `passing`, evidencia: `npx playwright test e2e/import.spec.ts` 4/4
- Build limpio: `npm run build` sin errores
- Lint limpio: `npm run lint` sin warnings

## Cambios de esta sesión
- Nuevo: `src/api/search.ts` con el endpoint y paginación
- Modificado: `src/db/queries.ts` — se agregó `searchDocuments()`
- Modificado: `feature_list.json` — F02 pasó a `in_progress`

## Todavía roto o sin verificar
- `GET /api/search?q=` devuelve 500 (falta validar el caso vacío)
- El campo `highlight` no está implementado; el test e2e de F02 no existe todavía
- `test_pagination_edge_case` falla desde la sesión 3 — no bloquea F02

## Mejor próxima acción
1. Validar `q` vacío y devolver 400 con un mensaje claro
2. Agregar `highlight` al serializador de resultados
3. Escribir `e2e/search.spec.ts` y marcar F02 `passing` con evidencia

**No tocar**: `src/db/migrations/` (ya aplicadas), `infra/`

## Comandos
- Arranque: `./init.sh && npm run dev`
- Verificación: `make check`
- Debug del endpoint: `curl 'http://localhost:3000/api/search?q=harness' | jq`

6. clean-state-checklist.md

Se revisa antes de cerrar cada sesión. Cubre las cinco dimensiones de la lección 12.

# Checklist de estado limpio

## 1. Build
- [ ] `npm run build` termina sin errores
- [ ] No hay imports rotos ni referencias a archivos eliminados

## 2. Tests
- [ ] `make check` pasa (o los fallos están documentados en el handoff)
- [ ] No se rompió ningún test que pasaba antes de esta sesión
- [ ] La verificación corrió en CI, no solo localmente

## 3. Progreso
- [ ] `claude-progress.md` tiene la entrada de esta sesión
- [ ] `feature_list.json` refleja el estado real (sin entradas `passing` falsas)
- [ ] Toda función `passing` tiene evidencia registrada

## 4. Artefactos
- [ ] Sin `console.log` / `print()` / `debugger` de depuración
- [ ] Sin archivos temporales (`*.tmp`, `debug-*.log`, `nul`)
- [ ] Sin bloques grandes de código comentado
- [ ] Los TODO nuevos están o resueltos o registrados en el handoff

## 5. Arranque
- [ ] `./init.sh` funciona desde cero
- [ ] La ruta de arranque estándar sigue disponible
- [ ] Una sesión nueva puede continuar sin correcciones manuales

7. evaluator-rubric.md

Una tarjeta de puntuación para revisar la calidad de salida del agente. Se usa después de una sesión o en hitos.

# Rúbrica del evaluador

Puntuá cada dimensión de 0 a 2. Cada puntuación necesita evidencia citada.

| # | Dimensión | 0 | 1 | 2 | Puntaje | Evidencia |
|---|-----------|---|---|---|---------|-----------|
| 1 | Corrección — ¿la implementación coincide con el comportamiento objetivo? | No coincide | Coincide parcialmente | Coincide y está verificada | | |
| 2 | Verificación — ¿las verificaciones requeridas se ejecutaron realmente? | No se ejecutaron | Se ejecutaron parcialmente | Todas, con evidencia | | |
| 3 | Disciplina de alcance — ¿se mantuvo dentro de la función elegida? | Tocó áreas no relacionadas | Desvíos menores | Alcance exacto | | |
| 4 | Fiabilidad — ¿el resultado sobrevive un reinicio o reejecución? | No | Con intervención | Sí, sin intervención | | |
| 5 | Mantenibilidad — ¿el código y los docs son claros para la próxima sesión? | No | Aceptable | Sí | | |
| 6 | Preparación de entrega — ¿una sesión nueva puede continuar solo con el repo? | No | Con preguntas | Sí | | |

**Total**: __ / 12

## Conclusión
- [ ] **Aceptar** — cumple el estándar (≥10 y ninguna dimensión en 0)
- [ ] **Revisar** — necesita correcciones antes de aceptar
- [ ] **Bloquear** — problemas fundamentales que hay que resolver primero

El evaluador necesita ajuste

De fábrica, los agentes son malos autojueces: identifican problemas y después se convencen de aprobar. Vas a necesitar iterar:

Ejecutá el evaluador sobre un sprint completado.
Compará sus puntuaciones con tu propio juicio.
Donde diverjan, hacé la rúbrica más específica sobre los criterios de aprobación y rechazo.
Volvé a ejecutar y verificá la alineación.
Repetí hasta que el evaluador coincida consistentemente con la revisión humana.

Planificá entre 3 y 5 rondas de ajuste. Registrá cada cambio para poder rastrear qué mejoró la alineación.

8. quality-document.md

Una instantánea de calidad que califica cada dominio de producto y cada capa arquitectónica. Rastrea la salud del código a lo largo del tiempo, no solo la salida de una sesión.

# Documento de calidad — 2026-08-20

## Dominios de producto

| Dominio | Verificación | Legible para el agente | Estabilidad de tests | Límites | Calificación |
|---------|--------------|------------------------|----------------------|---------|--------------|
| Importación de documentos | Pasa | Sí | Estable | Conforme | A |
| Indexación | Parcial | Difícil (3 archivos) | 2 tests flaky | Conforme | C |
| Q&A con citas | No implementado | — | — | — | D |

## Capas arquitectónicas

| Capa | Enforcement de límites | Legibilidad para el agente | Calificación |
|------|------------------------|----------------------------|--------------|
| Proceso principal | Script de lint activo | Alta | A |
| Preload | Script de lint activo | Media | B |
| Renderer | Sin verificación automática | Media | C |
| Servicios | Sin verificación automática | Baja | C |

## Brechas prioritarias
1. Indexación: unificar la lógica dispersa y estabilizar los 2 tests flaky
2. Renderer: agregar `scripts/check-architecture.sh` al pipeline
3. Q&A: sin implementar; es la próxima área de trabajo

Rúbrica vs. documento de calidad

Responden preguntas diferentes:

Artefacto	Pregunta que responde
Rúbrica del evaluador	”¿Hizo un buen trabajo el agente en esta sesión?”
Documento de calidad	”¿El proyecto se está fortaleciendo o debilitando con el tiempo?”

Actualizá el documento de calidad después de cada sesión significativa, antes de comparaciones de benchmark, después de pasadas de limpieza y al incorporar un modelo nuevo al proyecto.

Conexión con la simplificación del harness

El documento de calidad también sirve para simplificar el harness (lección 12). Cada componente del harness codifica un supuesto sobre lo que el modelo no puede hacer; a medida que los modelos mejoran, esos supuestos quedan obsoletos. Para verificar si un componente sigue siendo necesario:

Tomá una instantánea del documento de calidad.
Eliminá un componente del harness.
Ejecutá el conjunto de tareas de benchmark.
Tomá otra instantánea.
Compará: si las calificaciones no bajaron, el componente era sobrecarga. Si bajaron, restauralo.

Cuándo pasar al paquete avanzado

El paquete mínimo cubre la mayoría de los casos. Cuando el repositorio crezca hasta convertirse en un sistema de larga duración con varios dominios, planes activos, puntuación de calidad y políticas de fiabilidad, pasá a una estructura de repositorio más completa al estilo de la arquitectura de dominio en capas de OpenAI (lección 10), en lugar de estirar demasiado el paquete mínimo.

Anterior: Capítulo 15 — Análisis de harnesses reales · Siguiente: Capítulo 17 — Proyectos prácticos