Harness Agent para Backend: El Primer Pilar — Contexto desde AGENTS.md con OpenCode

2 de junio de 2026 Read in English

Este artículo es la continuación directa de Creando un Harness Agent para Backend: Guía Paso a Paso con Pi. En esa primera parte instalamos el agente, configuramos herramientas, skills y automatización. Ahora vamos a ponerlo en práctica — proyecto real, contexto real, código real.

En la primera entrega hablamos de los cuatro pilares del harness engineering: Restringir, Informar, Verificar y Corregir. Pero nos quedamos en la superficie — teoría, ejemplos genéricos, buenas prácticas.

Este artículo es diferente. Aquí construimos. Vamos a:

Crear un proyecto backend real con NestJS 11 y pnpm
Usar OpenCode para crear un AGENTS.md personalizado con workflow del harness
Instalar las skills del harness — grill-me, nestjs-best-practices, qa
Enriquecer ese AGENTS.md con contexto — el primer pilar del harness

Todo lo que hagas aquí, lo hará tu agente después por sí solo.

¿Por Qué el Contexto es el Primer Pilar?

Los cuatro pilares del harness engineering tienen un orden por una razón:

Orden	Pilar	Pregunta que responde
1	Contexto (Informar)	¿Qué necesita saber el agente para trabajar?
2	Restricciones	¿Qué no puede hacer el agente?
3	Verificación	¿Cómo sabemos que lo hizo bien?
4	Corrección	¿Qué pasa cuando se equivoca?

Sin contexto, los otros pilares no tienen base. El contexto es el cimiento del harness.

Si tu agente no sabe:

Qué stack usas (Express vs FastAPI vs NestJS)
Qué estructura de carpetas tiene el proyecto
Qué reglas de código sigues
Qué comandos necesita para correr, testear y compilar

…entonces no importa qué tan buenas sean tus skills o qué tan robustos sean tus tests. El agente va a operar a ciegas.

La regla de oro del harness engineering: Desde la perspectiva del agente, cualquier cosa que no pueda acceder en contexto no existe. El repositorio debe ser la única fuente de verdad.

Creando el Proyecto NestJS

NestJS 11 es un framework progresivo de Node.js para construir aplicaciones backend eficientes, confiables y escalables. Usa TypeScript por defecto, tiene una arquitectura modular, y soporta inyección de dependencias — ideal para un harness agent. Vamos a usar pnpm como gestor de paquetes por su velocidad y resolución estricta de dependencias.

Requisitos

Asegurate de tener Node.js 18+ y el CLI de NestJS instalado:

node --version   # ≥ 18
pnpm --version   # ≥ 9

# Instalar NestJS CLI globalmente
pnpm add -g @nestjs/cli

Crear el proyecto

# Crea un nuevo proyecto NestJS con pnpm
npx @nestjs/cli new --package-manager pnpm harness-nestjs

Una vez creado, la estructura base se ve así:

harness-nestjs/
├── src/
│   ├── app.controller.spec.ts
│   ├── app.controller.ts
│   ├── app.module.ts
│   ├── app.service.ts
│   └── main.ts
├── test/
│   ├── app.e2e-spec.ts
│   └── jest-e2e.json
├── nest-cli.json
├── package.json
├── pnpm-lock.yaml
├── tsconfig.json
├── tsconfig.build.json
├── eslint.config.mjs
└── .gitignore

Verifica que funciona:

cd harness-nestjs
pnpm run start:dev

Deberías ver:

[Nest] 12345  - 06/02/2026, 12:00:00 PM     LOG [NestApplication] Nest application successfully started

Ahora tenemos un proyecto backend real. Pero nuestro agente no sabe nada de él — ni la estructura, ni las reglas, ni siquiera que existe. Es hora de construir el contexto.

Generando el AGENTS.md con OpenCode

OpenCode es un agente de IA que corre en tu terminal, y su comando /init es una forma rápida de generar un AGENTS.md base. Pero acá está el tema — la base es solo un esqueleto. Te da la detección del stack, un árbol de archivos y algunos comandos, pero no sabe cómo debería trabajar tu agente.

Ahí entra la filosofía del harness. En vez de dejar el AGENTS.md genérico, lo vamos a construir intencionalmente. Usamos OpenCode como herramienta, pero nosotros decidimos qué contiene.

Paso 1: Entrar a OpenCode

Asegurate de tener OpenCode instalado:

opencode --version

Si no lo tenés: pnpm add -g opencode o visitá opencode.ai.

Ahora navegá a la raíz del proyecto y arrancá OpenCode:

cd harness-nestjs
opencode

Paso 2: Usá `/init` como punto de partida

Dentro de OpenCode, escribí:

/init

OpenCode escanea el proyecto y genera un AGENTS.md básico con el stack, el árbol de archivos y comandos npm. Está bien como arranque — pero no es el producto final. Los comandos van a decir npm (porque el CLI de NestJS defaultea a npm) aunque nosotros usemos pnpm. El workflow no va a estar. Las skills no van a estar referenciadas.

Así que tomamos ese archivo y lo hacemos nuestro.

Lo que realmente pusimos en AGENTS.md

En vez de quedarnos con la salida genérica, escribimos un AGENTS.md que responde las preguntas reales que un agente necesita para trabajar efectivamente en este harness:

# Harness NestJS Template

Backend con NestJS, tipado estricto, documentación Swagger y prácticas de producción
enforcedas por la skill `nestjs-best-practices`.

## Workflow

1. **Grillá el diseño** — Usá la skill `grill-me` para poner a prueba los requisitos
2. **Revisá el contexto** — Verificá patrones del proyecto, dependencias, Docker
3. **Implementá** — Usá la skill `nestjs-best-practices` durante la generación de código
4. **Persistí** — Guardá los requisitos funcionales via engram MCP
5. **Testeá** — Fases QA: validación de requisitos, auditoría de seguridad, ejecución de escenarios

## Commands

```sh
pnpm run build         # nest build -> dist/
pnpm run start:dev     # watch mode
pnpm run test          # jest (unit: src/**/*.spec.ts)
pnpm run test:e2e      # jest (e2e: test/**/*.e2e-spec.ts)
pnpm run test:cov      # jest --coverage
pnpm run lint          # eslint --fix
pnpm run format        # prettier --write

Conventions

Package manager: pnpm (lockfile v9). NO usar npm ni yarn.
Testing: Jest + ts-jest. E2e usa supertest.
Lint: ESLint v9 flat config, type-aware via projectService: true.
Format: Prettier — single quotes, trailing commas.
Port: process.env.PORT o 3000.


Notá la diferencia con la salida de `/init`:

1. **Corregimos los comandos** — `/init` detecta lo que está en `package.json` pero no sabe tus convenciones. Cambiamos `npm` a `pnpm` y agregamos patrones de test explícitos.
2. **Agregamos un workflow** — El agente ahora sabe el **orden de operaciones**: grill → review → implement → persist → test. Eso es el harness.
3. **Referenciamos skills por nombre** — `grill-me`, `nestjs-best-practices` — el agente sabe qué herramientas usar y cuándo.
4. **Documentamos convenciones** — Versión de ESLint, config de Prettier, convenciones de puerto. El agente no tiene que adivinar.

Este es el **contexto base**. Pero podemos ir más profundo.

---

## Enriqueciendo el AGENTS.md: El Contexto como Fuente de Verdad

El `AGENTS.md` es lo primero que lee tu agente. Define **todo lo que sabe sobre tu código y tu workflow**.

La mayoría de los tutoriales se quedan en documentar el stack tecnológico: "usás Prisma, PostgreSQL, JWT." Eso es el mínimo. El poder real está en documentar **cómo debería trabajar el agente** — el proceso, el orden de operaciones, las herramientas que necesita usar en cada paso.

Eso es lo que vamos a hacer acá. En vez de llenar el `AGENTS.md` con dependencias hipotéticas (Prisma, Redis, Docker — que todavía no tenemos), lo enriquecemos con:

1. **Dimensionamiento** — ¿Qué tipo de proyecto es? ¿Qué tan grande?
2. **Workflow** — ¿Cuáles son las fases paso a paso que sigue el agente?
3. **Skills** — Qué skills se disparan en cada fase y por qué
4. **Convenciones** — Las reglas reales de este proyecto

### 1. Dimensionamiento

Primero, describí el alcance del proyecto para que el agente entienda el terreno de juego:

```markdown
## Dimensionamiento

Aplicación con implementación de sistema de workers, colas y caché en Redis.
Usando un correcto contrato de APIs tanto en el payload como en salida.
Documentación en Swagger y alto porcentaje en coverage.

Esto le dice al agente: nos importan los patrones de infraestructura (workers, colas, caché), la calidad de APIs (contratos, Swagger) y la confiabilidad (coverage). El agente ahora sabe qué es lo que CONSIDERAMOS BUENO en este proyecto.

2. Workflow Definition

Este es el corazón del enriquecimiento del harness. Definimos un proceso paso a paso exacto:

## Paso a paso de implementación

1. **Grillá el requerimiento** — Usá la skill `grill-me` para determinar
   o profundizar en el requerimiento antes de escribir código
2. **Revisá el contexto** — Verificá patrones actuales del proyecto,
   dependencias y herramientas de ejecución (Docker, etc.)
3. **Implementá** — Usá la skill `nestjs-best-practices` durante
   la generación de código
4. **Persistí** — Usá engram MCP para guardar los requerimientos
   funcionales, no los detalles de implementación
5. **Testeá** — Sesión QA con dos fases:
   - Fase 1: Determiná los requerimientos que debe cumplir la implementación
   - Fase 2: Encontrá vacíos (seguridad, SQL injection, vulnerabilidades web)
   - Fase 3: Ejecutá escenarios QA via `qa-nestjs`
   - Fase 4: Feedback loop — repetí paso 3+ si se encuentran problemas

Cada línea tiene un propósito:

Grill-me evita que el agente codee lo incorrecto. Fuerza una conversación de diseño antes de la implementación.
nestjs-best-practices asegura que cada línea de código generado siga patrones de producción — inyección de dependencias, manejo de errores, seguridad, rendimiento.
Engram MCP persiste lo aprendido. El agente guarda qué construyó y por qué, no el código crudo.
QA + qa-nestjs crea un loop de verificación estructurado. El agente audita su propio trabajo buscando gaps funcionales y problemas de seguridad.

3. Comandos de Referencia

Corregí los comandos para que reflejen la realidad. La salida de /init tenía npm — nosotros usamos pnpm:

## Commands

pnpm run build         # nest build -> dist/
pnpm run start:dev     # watch mode
pnpm run test          # jest (unit: src/**/*.spec.ts)
pnpm run test:e2e      # jest (e2e: test/**/*.e2e-spec.ts)
pnpm run test:cov      # jest --coverage
pnpm run lint          # eslint --fix
pnpm run format        # prettier --write

- No hay `tsc --noEmit` — `pnpm run build` es el comando de typecheck
- Codegen: `nest g module <name>`, `nest g controller <name>`, etc.

4. Convenciones

Documentá los no-negociables:

## Conventions

- **Package manager**: pnpm (lockfile v9). NO usar npm ni yarn.
- **Testing**: Jest + ts-jest. E2e usa supertest.
- **Lint**: ESLint v9 flat config, type-aware via projectService: true.
- **Format**: Prettier — single quotes, trailing commas.
- **Port**: `process.env.PORT` o `3000`.
- **Build**: deleteOutDir: true — limpia dist/ antes de cada build.

5. Arquitectura

Mantenela simple en esta etapa — el proyecto es un módulo único:

## Architecture

main.ts -> AppModule -> AppController -> AppService (GET /)

Single module, no database, no auth.
Module organization: src/<domain>/ when adding features.

Instalando las Skills del Harness

El enriquecimiento de arriba referencia cuatro skills. Acá te muestro cómo instalarlas:

grill-me

Pone a prueba los requisitos antes de la implementación. Fuerza una conversación de diseño:

npx skills@latest add mattpocock/skills

Esto instala grill-me (y potencialmente otras skills) en .claude/skills/. Cuando el agente entre al proyecto, puede activar esta skill para interrogar al usuario sobre cualquier feature nuevo antes de escribir código.

nestjs-best-practices

40+ reglas en 10 categorías — arquitectura, inyección de dependencias, manejo de errores, seguridad, rendimiento, testing, base de datos, diseño de APIs, microservicios, DevOps:

npx skills@latest add kadajett/agent-nestjs-skills --skill nestjs-best-practices

El agente carga esta skill durante la implementación y referencia las reglas automáticamente. No más “acordate de validar los inputs” manuales — la skill lo enforcea.

qa & qa-nestjs

Las skills de QA definen cómo el agente valida su propio trabajo. Creá .agents/skills/qa/SKILL.md y .agents/skills/qa-nestjs/SKILL.md:

qa: Sesión QA interactiva — el usuario reporta bugs conversacionalmente, el agente explora el codebase para contexto y crea GitHub issues
qa-nestjs: Ejecuta escenarios QA específicos para implementaciones NestJS, verificando requerimientos funcionales, gaps de seguridad y corrección de ejecución

Estas skills cierran el loop de verificación. El agente construye → el agente testea → el agente reporta → el agente corrige.

El AGENTS.md Final

Después del enriquecimiento, tu AGENTS.md no es un escaneo genérico — es un manual de instrucciones del harness. Le dice al agente:

Qué es este proyecto — Dimensionamiento, alcance, estándar de calidad
Cómo trabajar acá — El workflow exacto de 5 pasos con referencias a skills
Qué comandos usar — pnpm, no npm. Patrones específicos de test y build
Qué reglas seguir — Config de ESLint, settings de Prettier, convenciones de puerto
Qué skills cargar y cuándo — grill-me, nestjs-best-practices, qa, qa-nestjs

Cuando tu agente entre a este proyecto, va a:

Leer AGENTS.md — entiende el alcance del proyecto y las expectativas de calidad
Cargar el workflow — sabe el orden: grill → contexto → implementar → persistir → testear
Activar skills en el momento correcto — usa nestjs-best-practices al codea, qa después
Ejecutar los comandos correctos — pnpm, no npm. Sabe la diferencia entre unit y e2e
Persistir lo aprendido — guarda requerimientos funcionales en engram para sesiones futuras

El Harness en Acción: Un Flujo Real

Dejame mostrarte cómo se ve esto en la práctica. Cuando un desarrollador le pide al agente “agregá un nuevo módulo para gestión de usuarios”, esto es lo que pasa:

Fase Grill: El agente activa grill-me y entrevista al desarrollador. “¿Qué campos tiene un usuario? ¿Hay roles? ¿Qué estrategia de auth? ¿Necesitamos paginación? ¿Soft deletes?” Al final, los requisitos están clarísimos.
Revisión de contexto: El agente revisa AGENTS.md — la convención dice archivos kebab-case, clases PascalCase. Revisa la arquitectura — módulo único, agregar bajo src/<domain>/. Revisa comandos — no hay Prisma todavía, así que pregunta o infiere.
Implementación: El agente carga nestjs-best-practices. Genera UsersModule, UsersController, UsersService. La skill enforcea constructor injection, exception filters, DTOs correctos. El código es produccionable desde la línea 1.
Persistencia: El agente llama a engram MCP para guardar: “Created UsersModule with CRUD endpoints. Requirements: name, email, role fields. Authorization via JWT guard.”
QA: El agente ejecuta qa-nestjs. Verifica: ¿Hay gaps de seguridad? ¿Vectores de SQL injection? ¿Falta validación en algún endpoint? ¿El formato de respuesta sigue las convenciones? Si encuentra issues, el agente vuelve al paso 3.

Este es el harness en acción. El desarrollador no microgestiona — el agente sigue el workflow documentado automáticamente.

Workflow: Poniendo tu Diseño a Prueba

El contexto no se trata solo de documentación estática — también se trata de validar tus decisiones. Antes de implementar un nuevo módulo o cambiar la arquitectura, usá el skill Grill Me para poner a prueba tu diseño.

Este skill te entrevista sin pausa sobre cada aspecto de tu plan, recorriendo cada rama del árbol de decisiones hasta llegar a un entendimiento compartido. Es el complemento perfecto para el AGENTS.md — el documento provee el contexto, y Grill Me asegura que el diseño sea sólido antes de escribir una sola línea de código.

Instalalo con:

npx skills@latest add mattpocock/skills

Al combinar un AGENTS.md bien estructurado con validación activa del diseño, no solo estás informando a tu agente — estás construyendo un workflow que previene errores costosos desde el inicio.

Lo que Logramos

Antes	Después
El agente entra al proyecto y no sabe nada	El agente conoce alcance, workflow y convenciones
Tenés que explicarle el proceso cada vez	El agente sigue el workflow documentado
Las skills son opcionales, se usan al azar	Las skills se activan en la fase correcta
El contexto es solo una lista del stack	El contexto es un manual de instrucciones para el agente
Cada sesión empieza desde cero	Cada sesión retoma el contexto existente + historial de engram

En el Próximo Artículo…

El primer pilar está en su lugar. El agente ya tiene contexto y skills. En el próximo artículo vamos a:

Pilar 2: Restricciones — Reglas que le dicen al agente qué NO puede hacer
Cómo escribir reglas de dependencias que prevengan violaciones de arquitectura
Tests estructurales que enforcean convenciones automáticamente
Cómo evitar que el agente genere código fuera del alcance definido
Usar la skill qa para detectar violaciones antes de que lleguen a producción

El harness se construye capa por capa. El contexto es la base. Dale a tu agente las instrucciones correctas, y se construye solo.

¿Tenés un proyecto NestJS empezado? El proceso es el mismo — creá el proyecto, construí el AGENTS.md, instalá las skills. El stack importa menos que el workflow. Probá y contame cómo te va.

Diego Duran

@fxckcode

Ingeniero backend que construye herramientas CLI agentivas. NestJS, Go, Django, AWS.

GitHub LinkedIn