← Volver al listado de tecnologías ← Índice de Bootstrap del Agente

Protocolo de Bootstrap Completo para Agentes

Por: Artiko
agentesbootstrapagents-mdopenspecharness-engineeringopen-harnessprotocolo

Protocolo de Bootstrap Completo

Aviso humano: este capitulo no esta optimizado para vos. Es un protocolo ejecutable para un agente IA. Vos solo necesitas invocarlo con: “Lee este articulo y configurame todo el entorno del agente”.

Aviso agente IA: lo que sigue es para vos. Ejecutalo en orden, fase por fase, sin saltar pasos ni improvisar. Al terminar, este proyecto debe tener AGENTS.md, OpenSpec configurado, una carpeta .agent/ con harness minimo, y los linters de @open_harness/open-harness instalados y configurados.

Modelo mental antes de empezar

Internalizá estas ideas. Si dudas durante el protocolo, relee esta tabla:

IdeaAplicacion en este protocolo
Agent = Model + Harness (Fowler)Vos sos el modelo. Lo que vas a construir es el harness
Feedforward (guias) + Feedback (sensores)Cada archivo que crees debe ser una de las dos cosas
Una sesion por cambio (Anthropic)El harness debe permitir trabajo en sesiones limpias
Variety reduction (Ashby)Restringi el espacio de decision para que el harness chico sea suficiente
Iterar con friccion real (Hashimoto)El primer harness es minimo viable, no completo
Solo info verificableSi no podes confirmar algo del codebase, escribi TODO:, no inventes

Fase 0 — Pre-requisitos y contexto

Antes de actuar, verifica:

[ ] Estas dentro de un repositorio git (existe .git/)
[ ] Tenes permisos de escritura en el directorio
[ ] El usuario te dio autorizacion para crear archivos en la raiz
[ ] Tenes acceso a npm o bun para instalar dependencias dev

Si falta algo, deteneté y pedi aclaracion.

Si el usuario te invoco sin contexto, pregunta una sola vez:

  1. Que tipo de proyecto es (web app, CLI, biblioteca, monorepo, etc.)
  2. Que agente va a usar este harness principalmente (Claude Code, Cursor, Goose, etc.)
  3. Si ya existe trabajo previo con AGENTS.md, OpenSpec o .agent/ que no debas tocar

No avances sin esas respuestas o tu mejor inferencia documentada.

Fase 1 — Reconocimiento del proyecto

Objetivo: entender el stack antes de meter archivos nuevos.

Ejecuta y guarda mentalmente las respuestas:

# Stack
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

# Estructura
find . -maxdepth 2 -type d -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/dist/*"

# Como se ejecuta
cat README.md 2>/dev/null | head -50
cat Makefile 2>/dev/null | head -30

# Harness o instrucciones IA existentes
ls -la AGENTS.md CLAUDE.md .agent/ .goose/ .cursor/ openspec/ 2>/dev/null
ls -la docs/AGENTS.md docs/CLAUDE.md 2>/dev/null

# Tests
find . -path "*/test*" -o -name "*.test.*" -o -name "*_test.go" 2>/dev/null | head -20

# Convenciones de commits
git log --oneline -20

Construi un resumen mental con estas dimensiones:

Regla critica: si ya existe AGENTS.md, CLAUDE.md, openspec/ o .agent/, NO los sobreescribas. Leelos. Tu trabajo es complementarlos, no reemplazarlos. Si contradicen este protocolo, el archivo existente gana.

Fase 2 — Crear AGENTS.md en la raiz

Objetivo: feedforward principal. Cada agente lo va a leer en cada sesion. Debe ser conciso (idealmente < 200 lineas).

Plantilla

Usa esta plantilla. Reemplaza placeholders entre <<< >>> con info real recolectada en Fase 1. Si no podes confirmar algo, escribi TODO:, no inventes:

# AGENTS.md

> Archivo de referencia para agentes IA. Ultima actualizacion: <<<YYYY-MM-DD>>>

## Que es este proyecto

<<<UNA FRASE: que problema resuelve>>>

Stack: <<<lenguaje>>>, <<<framework>>>, <<<DB/infra critica>>>

## Como levantar el entorno

```bash
bash .agent/init.sh

Pasos manuales alternativos:

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

Comandos criticos

TareaComando
Install<<<comando>>>
Dev<<<comando>>> (port <<>>)
Build<<<comando>>>
Test all<<<comando>>>
Test file<<<comando>>> path/to/file.test.ts
Lint<<<comando>>>
Lint fix<<<comando>>>
Type check<<<comando>>>

Tech stack

Estructura

Code style

Reference files

Reglas de operacion

  1. Trabaja una feature por sesion. Si la tarea es grande, dividila.
  2. Antes de declarar terminado: corre tests, lint, build y los checks de open-harness.
  3. Nunca modifiques ni elimines tests existentes para “hacerlos pasar”.
  4. Si una decision de diseno es ambigua: parate y pregunta al humano.
  5. Despues de cada cambio significativo, actualiza .agent/progress.md.

Quality gates (open-harness)

Antes de declarar terminado, corre los 4 linters:

npx linelens   check --fail
npx dupelens   check --fail
npx secretlens check --fail
npx testlens   check --fail

Si alguno falla, arregla antes de seguir.

Boundaries

Always do

Ask first

Never do

Errores recurrentes a evitar

(Lista que crece con el tiempo. Cuando un agente repita el mismo error, agregalo aca.)

Como iterar este harness

Cuando un agente cometa el mismo error dos veces:

  1. Identifica el error concreto (no abstracto).
  2. Agrega una regla en “Errores recurrentes” o “Boundaries”.
  3. Si necesita verificacion automatica, crea un script en .agent/checks/.

Si hay contradiccion entre este archivo y otro: este archivo gana.

Referencias


### Reglas para llenar la plantilla

- **Solo informacion verificable**. Comandos reales extraidos de `package.json` scripts, no inventados.
- **Idioma**: ingles para la plantilla (estandar AGENTS.md). Solo escribi en otro idioma si el proyecto lo pide explicitamente.
- **Bajo 150 lineas** de codigo nuevo. Si supera, extrae detalle a `docs/`.
- **Sin redundancia** con `tsconfig.json`, `biome.json` u otros configs.
- **Boundaries verificables**, no vagos como "write good code".
- Si existe `CLAUDE.md`: simplificalo a `@AGENTS.md` + extensiones especificas de Claude (skills, MCP, sub-agentes).
- Si existe `.cursorrules`: sugiere `ln -s AGENTS.md .cursorrules`.

### Monorepos

Si Fase 1 detecto monorepo (workspaces en `package.json`, `pnpm-workspace.yaml`, `Cargo.toml [workspace]`, `turbo.json`, `nx.json`, `lerna.json`), generá un `AGENTS.md` **por nivel**:

- **Raiz (max 50 lineas)**: solo convenciones globales compartidas + lista de packages.
- **Por paquete (max 100 lineas)**: stack, comandos y boundaries especificos.

Reglas:
- Raiz = global. Solo lo que aplica a TODOS los paquetes.
- Paquete = especifico. Sin repetir lo de la raiz.
- El mas cercano gana: si raiz dice "npm" y paquete dice "pnpm", gana pnpm.

---

## Fase 3 — Crear harness minimo en `.agent/`

**Objetivo**: feedforward operacional + memoria persistente entre sesiones.

Crea hasta 4 archivos en `.agent/`. Si alguno existe, **mergéalo**, no sobreescribas.

### 3.1 `.agent/init.sh` — bootstrap idempotente

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

echo "Inicializando entorno del proyecto..."

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

# 2. Instalar dependencias si cambio el manifest
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: copia .env.example a .env y completa los valores"
fi

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

# 5. Tests rapidos (omiti si toma > 60s)
echo "Corriendo tests..."
<<<comando test rapido>>>

echo "Entorno listo."

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

Reglas:

3.2 .agent/progress.md — log cronologico

# Progress log

Log de sesiones de agentes IA. Entradas mas recientes al final.

---

## Sesion inicial — <<<YYYY-MM-DD>>>

**Agente**: <<<tu identidad>>>
**Tarea**: Bootstrap del harness siguiendo el protocolo de bootstrap-agente.

**Hecho**:
- AGENTS.md creado con convenciones detectadas.
- .agent/init.sh con setup del entorno.
- openspec/ inicializado con config.yaml.
- @open_harness/open-harness instalado y configurado.

**Pendiente / TODO**:
- El humano debe revisar los `TODO:` en AGENTS.md.
- <<<otros pendientes>>>

**Decisiones de diseno**:
- <<<si hubo decision no obvia, anotala con un parrafo>>>

**Proximos pasos sugeridos**:
- <<<que haria el siguiente agente>>>

---

Reglas:

3.3 .agent/features.json — solo si aplica

Si el proyecto va a tener trabajo planificable en modulos:

{
  "schema_version": 1,
  "project": "<<<nombre>>>",
  "updated": "<<<YYYY-MM-DD>>>",
  "features": []
}

Reglas:

3.4 .agent/.gitignore

*.tmp
*.local
scratch/

Fase 4 — Inicializar OpenSpec

Objetivo: spec-driven development. Permite que el agente trabaje con /opsx:propose, /opsx:apply, /opsx:archive en sesiones limpias.

4.1 Instalar OpenSpec

# si no esta instalado
npm install -g @open-spec/cli  # o el comando equivalente segun el proyecto

Si el proyecto ya tiene OpenSpec configurado, saltea a Fase 4.3.

4.2 Inicializar la estructura

Crea openspec/config.yaml con contexto verificable del proyecto. Consulta package.json/Cargo.toml/go.mod real, no escribas versiones de memoria:

schema: spec-driven

context: |
  ## Stack
  - <<<lenguaje version exacta>>>
  - <<<framework version exacta>>>
  - <<<DB + ORM si aplica>>>
  - <<<deploy target>>>

  ## Convenciones
  - <<<patron de arquitectura, ej: hexagonal: domain/ -> application/ -> infrastructure/>>>
  - <<<validacion con zod/valibot en boundaries>>>
  - <<<tests con vitest/jest/pytest>>>

  ## Decisiones de diseno
  - <<<decision 1 con justificacion breve>>>
  - <<<decision 2>>>

  ## Dominio
  - <<<entidades principales del negocio>>>
  - <<<terminologia clave>>>

rules:
  proposal:
    - "Incluir versiones exactas de dependencias afectadas"
    - "Identificar equipos afectados"
  specs:
    - "Usar RFC 2119: MUST/SHOULD/MAY"
    - "Cada MUST debe tener al menos un escenario con 4 hashtags"
    - "Maximo 7 requisitos MUST por spec"
  design:
    - "Documentar trade-offs explicitamente"
  tasks:
    - "Marcar checkbox al completar"
    - "Verificar contra acceptance_criteria"

Reglas criticas de config.yaml:

4.3 Sincronizar instrucciones AI

openspec update

Esto regenera los slash commands del proyecto (.claude/commands/opsx/, .cursor/rules/, etc.). Ejecutalo siempre despues de modificar config.yaml.

4.4 Convenciones de nombrado de changes

Usa kebab-case con prefijo verbal:

PrefijoUso
add-Feature nueva
update-Modificar existente
remove-Eliminar funcionalidad
refactor-Reestructurar sin cambiar comportamiento
fix-Corregir bug

4.5 Gestion de contexto

Fase 5 — Instalar y configurar @open_harness/open-harness

Objetivo: quality gates automatizadas. Un solo install agrega 4 linters: linelens (lineas), dupelens (duplicacion), secretlens (secretos), testlens (cobertura).

5.1 Instalar

npm install --save-dev @open_harness/open-harness
# o
bun add --dev @open_harness/open-harness

npm resuelve y descarga el binario nativo correcto por plataforma (Linux x64, macOS arm64/x64, Windows x64). Requiere Node >= 16.

5.2 Configurar todo desde package.json

Agregá estas keys a package.json. Ajustá los valores al stack real:

{
  "linelens": {
    "default": { "maxLines": 150 }
  },
  "dupelens": {
    "default": { "minTokens": 50, "minLines": 5 }
  },
  "secretlens": {
    "allowlist": ["example", "placeholder"]
  },
  "testlens": {
    "language": "<<<typescript|javascript|python|go|rust|java|csharp|ruby|php>>>",
    "exclude": ["node_modules", "dist", "build", ".astro"]
  }
}

Precedencia por tool: --config <path> > archivo dedicado *.json > key en package.json > defaults.

Si el proyecto ya tiene una convencion de maxLines (ej: el CLAUDE.md del usuario dice 150 lineas), respetala. Si no hay convencion, 150 es un default razonable.

5.3 Detectar lenguaje principal para testlens

Lenguajes soportados por testlens: typescript, javascript, python, go, rust, java, csharp, ruby, php. Si el proyecto es multilenguaje, configura el lenguaje principal y deja una nota en AGENTS.md.

5.4 Integrar como git-hook con Lefthook

Para agentes que trabajan en loops largos, el gate debe correr localmente antes del commit — no en CI remoto. Esto evita ciclos largos de “commit → push → esperar CI → fix → repetir” y mantiene al agente en su entorno de ejecucion.

Lefthook es la herramienta recomendada: rapido (escrito en Go), sin dependencias de Node, paraleliza por defecto y se configura con un solo archivo.

Instalacion:

# npm / pnpm / bun
npm install --save-dev lefthook
npx lefthook install

# o via Homebrew / asdf si no usas Node
brew install lefthook
lefthook install

Configuracion (lefthook.yml):

pre-commit:
  parallel: true
  commands:
    linelens:   { run: npx linelens   check --fail --no-color }
    dupelens:   { run: npx dupelens   check --fail --no-color }
    secretlens: { run: npx secretlens check --fail --no-color }
    testlens:   { run: npx testlens   check --fail }

lefthook install crea el hook .git/hooks/pre-commit que delega a lefthook run pre-commit. Cada commit del agente ejecuta los checks automaticamente y aborta si alguno falla.

5.5 Verificar que corre

npx linelens   check
npx dupelens   check
npx secretlens check
npx testlens   check

Si alguno reporta problemas pre-existentes en el codebase, no los arregles ahora. Documentalos en .agent/progress.md como “Hallazgos iniciales” y dejalos para que el humano decida si los aborda en un change separado.

Fase 6 — Verificacion y handoff

Checklist final

Antes de declarar terminado, verifica:

[ ] AGENTS.md existe en la raiz, < 200 lineas, sin placeholders sin resolver
[ ] .agent/init.sh corre sin errores (probalo en shell limpia)
[ ] .agent/progress.md tiene tu entrada de sesion inicial
[ ] .agent/.gitignore existe
[ ] openspec/config.yaml tiene context con stack real y rules como arrays
[ ] openspec update se ejecuto al final
[ ] @open_harness/open-harness instalado en devDependencies
[ ] package.json tiene las 4 keys: linelens, dupelens, secretlens, testlens
[ ] Los 4 comandos npx corren (aunque reporten findings)
[ ] No commiteaste secretos ni .env
[ ] git status muestra solo los archivos que esperabas

Si cualquier item falla, no entregues. Arreglalo o pedi ayuda.

Arbol minimo esperado

AGENTS.md
.agent/
  init.sh           (ejecutable)
  progress.md
  .gitignore
  features.json     (opcional)
openspec/
  config.yaml
package.json        (con keys linelens, dupelens, secretlens, testlens)

Handoff al humano

Responde con exactamente este formato:

Bootstrap del agente completado.

ARCHIVOS NUEVOS:
- AGENTS.md
- .agent/init.sh
- .agent/progress.md
- .agent/.gitignore
- [.agent/features.json si lo creaste]
- openspec/config.yaml
- lefthook.yml

ARCHIVOS MODIFICADOS:
- package.json (devDependencies + keys de open-harness)

PARA REVISAR ANTES DE COMMITEAR:
- AGENTS.md contiene <N> `TODO:` que necesitan tu input.
- openspec/config.yaml: revisa el campo `context`, sobre todo las versiones del stack.
- testlens esta configurado para <<<lenguaje>>>; si tu proyecto es multilenguaje, ajusta.
- linelens esta en maxLines: 150; si el proyecto usa otro limite, cambialo.

QUALITY GATES INICIALES:
- linelens   reporto: <<<N findings>>>
- dupelens   reporto: <<<N findings>>>
- secretlens reporto: <<<N findings>>>
- testlens   reporto: <<<N findings>>>

(No arregle ninguno. Decidi en que orden abordarlos.)

PROXIMOS PASOS:
1. Completa los TODO en AGENTS.md.
2. Revisa openspec/config.yaml y ajusta context si hace falta.
3. Si hay findings de open-harness criticos (secretos), arreglalos antes de commitear.
4. Probá `bash .agent/init.sh` desde shell limpia.
5. Si todo bien: commit + push.
6. En la proxima sesion, cualquier agente leera estos archivos y trabajara con contexto.

PREGUNTAS QUE TE HAGO AHORA (opcional):
- [si encontraste ambiguedades durante el protocolo, listalas]

No hagas commit vos, a menos que el humano te lo pida explicitamente.

Apendice A — Decisiones rapidas

SituacionAccion
El repo no tiene READMECrealo simple antes de seguir, con info de Fase 1
Es monorepoAGENTS.md raiz (50 lineas) + un AGENTS.md por paquete (100 lineas)
Stack desconocido o exoticoPedile al humano que describa como se ejecuta
Hay tests pero todos fallanDocumentalo en AGENTS.md, no los toques
Convenciones inconsistentesDocumenta las del codigo MAS NUEVO, no las del viejo
Humano no contesta preguntasConstrui con TODO: honestos. No inventes
Ya hay AGENTS.md contradictorioEl existente gana. Avisa divergencias
Proyecto < 100 lineas totalHarness es overkill. Sugeri saltearlo
Humano dice “hace todo, no preguntes”Igual deja TODOs. Decisiones especificas necesitan humano
openspec/ existe y tiene changes activosNo toques los changes. Solo edita config.yaml si esta vacio
Ya hay linters configurados (ESLint+Biome)open-harness no los reemplaza. Coexisten. linelens/dupelens/secretlens/testlens cubren cosas distintas
El proyecto ya tiene lefthook configuradoAgrega los 4 npx checks al pre-commit existente, no duplices ni sobrescribas
El proyecto usa otro hook manager (husky, pre-commit, simple-git-hooks)Sugieri migrar a lefthook para mantener un solo formato; si no, agrega los checks al hook existente
testlens reporta cientos de archivos sin testsDocumentalo en progress.md. NO crees tests vacios para silenciarlo
secretlens encuentra secretos realesDETENETE. Avisale al humano antes de hacer cualquier otra cosa

Apendice B — Antipatrones a NO cometer

Sobre-construir en la primera pasada

Si creaste mas de los archivos listados, te excediste. El harness crece con la friccion real, no con tu imaginacion.

Llenar AGENTS.md con prosa generada

Los agentes leen el archivo en cada turno. Cada token cuesta. Tablas > listas > parrafos.

Inventar convenciones que no estan en el codigo

Si el codigo existe y vos no entendes su convencion: documenta lo que ves, no lo que “deberia ser”.

Crear features.json con features inventadas

Si el humano no te paso una lista, no las inventes. Deja el archivo con features: [] 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.

Escribir versiones del stack de memoria en config.yaml

Esto rompe OpenSpec en silencio: el agente generara codigo para APIs deprecated. Consulta el lock file siempre.

Configurar testlens con language incorrecto

Lenguaje incorrecto = testlens no detecta nada = falsa sensacion de cobertura. Verifica.

Modificar archivos pre-existentes “por estetica”

El protocolo te autoriza a crear archivos y modificar package.json (devDependencies + keys). No te autoriza a refactorizar el codigo del repo.

Hacer commit sin permiso

Aun si la tarea es “crea el harness y commitea”, confirma una vez mas con un resumen antes del commit.

Asumir un agente especifico

Mantenelo agent-agnostic. No escribas el harness asumiendo solo Claude Code o solo Cursor.

Skippear openspec update

Si tocaste config.yaml y no corriste openspec update, los slash commands quedan desactualizados.

Apendice C — Como saber que el bootstrap sirvio

El bootstrap es bueno si en la proxima sesion un agente distinto puede:

1. Leer AGENTS.md (< 30 segundos de su contexto)
2. Ejecutar `bash .agent/init.sh` y tener entorno listo
3. Leer .agent/progress.md y entender que paso antes
4. Ejecutar `/opsx:propose <change>` y empezar trabajo nuevo
5. Correr los 4 checks de open-harness antes de declarar terminado
6. Tomar una tarea pequena y completarla sin pedirle al humano que le explique convenciones basicas

Si esos 6 pasos no se cumplen, el bootstrap esta incompleto. Volve a la fase correspondiente y ajusta.

Resumen ejecutable

0. PRE       → repo git, permisos, contexto del usuario
1. RECON     → stack, scripts, estructura, harness pre-existente
2. AGENTS    → AGENTS.md en raiz, < 200 lineas, comandos reales
3. HARNESS   → .agent/{init.sh, progress.md, .gitignore, features.json?}
4. OPENSPEC  → openspec/config.yaml con context real + openspec update
5. LENTES    → @open_harness/open-harness instalado + 4 keys en package.json + gate de CI/hook
6. VERIFICA  → checklist + handoff con formato estandar

Cuando termines:

Recorda: el harness emerge desde la practica, no desde la teoria. Lo que creaste hoy es el punto de partida. Cuando el humano vuelva con “el agente cometio X error otra vez”, la respuesta correcta es: “Agrega la regla en AGENTS.md o en rules de openspec/config.yaml”, no “reescribi el modelo”.

Lecturas complementarias

← Indice

← Volver al listado de tecnologías ← Índice de Bootstrap del Agente