Harness Bootstrap
Convierte un repositorio en uno donde cualquier sesión de agente nueva, en cualquier máquina de desarrollador, pueda responder cinco preguntas solo desde el repositorio: ¿qué es esto?, ¿cómo está organizado?, ¿cómo lo ejecuto?, ¿cómo lo verifico? y ¿dónde nos quedamos?. Luego haz que "terminado" sea algo que decida un script, no el agente.
Esta habilidad se ejecuta una vez por repositorio. Instala un contrato que el equipo confirma, y
habilidades de ciclo de vida (harness-start, harness-handoff, harness-cleanup, harness-evaluate) que
viven dentro del repositorio para que cada compañero de equipo las obtenga al clonar, sea cual sea el agente de codificación que use.
Las rutas en este archivo (scripts/, references/, assets/) son relativas al directorio que
contiene este SKILL.md. Dónde está ese directorio depende del agente y de cómo se instaló la
habilidad, así que resuélvelo desde la ubicación desde la que cargaste este archivo; nunca asumas una ruta fija
como ~/.claude/skills/.
Lee references/principles.md si necesitas el razonamiento detrás de cualquier artefacto (por ejemplo, para
explicarlo al usuario o para adaptarlo a un repositorio inusual).
El modelo que estás instalando
| Capa | Dónde | ¿Confirmado? | Propósito |
|---|---|---|---|
| Archivo de entrada | CLAUDE.md y/o AGENTS.md | sí | Mapa breve: qué, cómo ejecutar, cómo verificar, reglas estrictas, enlaces |
| Documentación | docs/ARCHITECTURE.md, PRODUCT.md, RELIABILITY.md, docs/decisions/ | sí | Conocimiento que el agente no puede inferir del código |
| Contrato | harness/ (config, reglas, lista de verificación, rúbrica, documento de calidad, plantillas, README) | sí | Mismas reglas para todos, cambiadas solo mediante PR |
| Verificación | scripts/harness/ | sí | init.sh, verify.sh, feature.py, check_architecture.py, cleanup-scan.sh |
| Ciclo de vida | .agents/skills/harness-*, reflejado para agentes que leen otra carpeta | sí | Iniciar, transferir, limpiar, evaluar |
| Adaptadores | Por agente, por ejemplo .claude/agents/, .claude/hooks/ para Claude Code | sí | Extras opcionales: subagente, hooks |
| Estado de la tarea | .harness/tasks/<TASK-ID>/ | no | Lista de características, contrato, progreso, traspaso, registros de ejecución para una tarea |
El estado de la tarea es local porque cambia en cada sesión y pertenece a la rama de una persona.
Confirmarlo causa conflictos de fusión y permite que el estado obsoleto de un desarrollador engañe al agente
de otro desarrollador. Es una caché: todo lo duradero se promueve a código, pruebas, documentación, el PR o el
rastreador de incidencias antes de que termine la tarea. harness/README.md explica esto al equipo.
Flujo de trabajo
1. Confirmar el objetivo
Ejecuta git rev-parse --show-toplevel en el directorio que el usuario quiera. Si no es un repositorio
git, detente y dilo: el aislamiento de worktree y las comprobaciones de la rama base dependen de git.
Observa si el árbol de trabajo está sucio; sugiere hacer el bootstrap en su propia rama para que pueda
revisarse como un solo PR.
2. Inventariar lo que ya existe
Mira antes de escribir. Encuentra y lee:
- Archivos de instrucciones:
AGENTS.md,CLAUDE.md,.claude/CLAUDE.md,CLAUDE.local.md,GEMINI.md,.cursorrules,.cursor/rules/,.github/copilot-instructions.md,.windsurfrules - Documentación:
README*,docs/, carpetas ADR,CONTRIBUTING* - Piezas de arnés existentes:
feature_list.json,progress.md,init.sh,Makefile,harness/,scripts/harness/,.harness/ - Configuración y habilidades del agente:
.agents/skills/,.claude/(settings.json,skills/,agents/,hooks/),.devin/,.cursor/,.github/,.worktreeinclude .gitignore
El contenido existente gana. Lo extiendes; nunca reemplazas un archivo que el equipo escribió sin preguntar.
3. Descubrir cómo se ejecuta el proyecto
Sigue references/discovery.md. El objetivo es una lista verificada de comandos para cada capa de
verificación, cada uno con el lugar donde lo encontraste (la configuración de CI es la evidencia más sólida, porque es lo que
el equipo realmente confía). También identifica las capas o módulos del código y las direcciones de
dependencia entre ellos; esas se convierten en reglas de arquitectura.
4. Preguntar solo por las lagunas
Agrupa las preguntas que no pudiste responder desde el repositorio en una sola llamada de pregunta estructurada si tu entorno la tiene, de lo contrario en un solo mensaje. Las lagunas típicas:
- Límites de arquitectura que inferiste pero de los que no estás seguro ("¿
ui/puede importardb/?") - El comando de extremo a extremo o smoke, si no existe
- Rama base y convención de nombres de ramas, si no está documentado
- Qué agentes de codificación usa el equipo (Claude Code, Codex, Cursor, Copilot, Devin, Pi, otros). Esto decide el archivo de entrada y qué adaptadores de agente instalar.
- Si el equipo usa Claude Code: si instalar sus hooks (recomendado; muestran el estado de la tarea al inicio de la sesión y bloquean las ediciones manuales del estado de la tarea antes de que ocurran)
No preguntes sobre cosas con un valor predeterminado convencional; elígelo y menciónalo en el informe final.
5. Copiar el andamio
bash <directorio de esta habilidad>/scripts/install.sh <raíz-del-repo> --agents <ids>
--agents toma los agentes del equipo del paso 4 como ids separados por comas, los mismos ids que
la CLI de npx skills usa (claude-code, codex, cursor, github-copilot, gemini-cli,
opencode, pi, devin, windsurf, kiro-cli, ...; --help los lista).
El script copia assets/project/ en el repositorio, incluidas las habilidades de ciclo de vida en
.agents/skills/, que la mayoría de los agentes leen directamente. Para los agentes que leen otra carpeta
(claude-code, devin, windsurf, kiro-cli) agrega enlaces simbólicos relativos a esas habilidades, y
para los agentes con un adaptador en assets/adapters/<id>/ copia los archivos del adaptador. Pasa --copy
para copias en lugar de enlaces simbólicos cuando el equipo tenga checkouts de Windows sin soporte de enlaces simbólicos;
init.sh luego informa sobre las copias que se desvían. El script nunca sobrescribe una ruta
existente, marca los scripts como ejecutables e imprime CREATED / LINKED / SKIPPED por ruta. Usa --dry-run
primero si el repositorio ya tiene piezas de arnés. Para cada ruta SKIPPED, lee el archivo existente y
fusiona las ideas faltantes manualmente en lugar de forzar la plantilla.
Si el script informa rutas FAILED, la zona de pruebas de tu agente probablemente protege una carpeta como
.agents/ o .claude/ (Codex hace esto con .agents/ por defecto). Vuelve a ejecutar el mismo comando con
el permiso que tu entorno ofrezca para ello, o pide al usuario que lo ejecute. Nunca reubiques las
habilidades a otra carpeta para evitarlo: los agentes descubren habilidades solo en las carpetas que leen,
por lo que las habilidades reubicadas dejan de funcionar silenciosamente.
6. Rellenar las especificidades del proyecto
Todo lo que el andamio no puede saber es tuyo para escribirlo, basado en lo que leíste en los pasos 2-4:
harness/config.sh: un comando por línea para cada capa (setup, estático, prueba, smoke, e2e), la rama base y los patrones de depuración para la pila. Deja una capa vacía solo si realmente no existe;verify.shinforma las capas obligatorias vacías como UNVERIFIED en lugar de aprobadas. Nunca llenes una capa con un comando que otra capa ya ejecuta (por ejemplo, las pruebas de integración como "e2e"): cada capa debe agregar evidencia que las otras no. Consultareferences/discovery.md.harness/architecture-rules.json: una regla por límite, siguiendoreferences/architecture-rules.md. Cada regla necesitawhyyfixescritos para un agente, porque el mensaje de error es el bucle de retroalimentación.- Documentación: crea
docs/ARCHITECTURE.md,docs/PRODUCT.md,docs/RELIABILITY.mdsolo donde el repositorio no tenga equivalente, comenzando desdeassets/docs-skeletons/. Escribe a partir del código que leíste, mantén cada uno por debajo de ~150 líneas y marca cualquier cosa que no hayas podido confirmar comoTODO(confirm): ...en lugar de adivinar. Si existen equivalentes en otro lugar, enlázalos en lugar de duplicarlos. - Registros de decisiones: el andamio agrega
docs/decisions/. Si el repositorio ya mantiene ADR en otro lugar (doc/adr/,docs/adr/), elimina la nueva carpeta y apuntaharness/README.md, las habilidades de traspaso y limpieza, y las plantillas hacia la existente. harness/quality-document.md: lista los módulos reales con una calificación inicial honesta, ounknowndonde no tengas evidencia. Nunca califiques por intuición.
7. Conectar el archivo de entrada
Inserta la sección de assets/snippets/entry-section.md en el archivo de entrada, cerca del principio o
del final (los modelos recuerdan mejor los bordes de los archivos largos que el centro). Mantén el archivo de entrada como un
enrutador: si supera las ~200 líneas, mueve los detalles a docs/ y enlázalos.
AGENTS.md es el archivo de entrada canónico: la mayoría de los agentes de codificación lo leen directamente. Otros agentes obtienen
un puntero delgado hacia él, nunca una segunda copia de las reglas, para que los archivos no se desincronicen.
| Situación | Haz esto |
|---|---|
No existen ni AGENTS.md ni CLAUDE.md | Crea AGENTS.md a partir de lo que aprendiste, más la sección. |
Solo existe AGENTS.md | Agrega la sección a AGENTS.md. |
Solo existe CLAUDE.md, el equipo usa solo Claude Code | Agrega la sección a CLAUDE.md. |
Solo existe CLAUDE.md, el equipo usa otros agentes también | Pregunta antes de moverlo: propón mover su contenido a AGENTS.md y dejar @AGENTS.md en CLAUDE.md. Si el equipo se niega, agrega la sección a CLAUDE.md y crea AGENTS.md con la sección y un enlace a CLAUDE.md. |
| Ambos existen | Agrega la sección a AGENTS.md, y asegúrate de que CLAUDE.md lo importe con @AGENTS.md. |
Luego agrega el puntero para cada agente que el equipo use que no lea AGENTS.md por defecto:
| Agente | Puntero |
|---|---|
| Claude Code | CLAUDE.md que contenga @AGENTS.md. Por defecto, Claude Code lee AGENTS.md solo cuando no existe CLAUDE.md ni CLAUDE.local.md, por lo que un repositorio con ambos descarta silenciosamente AGENTS.md sin la importación. |
| Gemini CLI | GEMINI.md que contenga @AGENTS.md, o "contextFileName": "AGENTS.md" en .gemini/settings.json. |
Cualquier agente con su propio archivo de reglas ya en el repositorio (.github/copilot-instructions.md, .cursor/rules/, .windsurfrules) | Una línea en ese archivo que diga que lea AGENTS.md, que contiene las reglas. |
Verifica el comportamiento actual de un agente del que no estés seguro en su propia documentación en lugar de adivinar; los agentes cambian qué archivos leen.
8. Fusionar la configuración
.gitignore: agrega las líneas deassets/snippets/gitignore.txtque falten.- Solo Claude Code,
.claude/settings.json: fusiona los hooks deassets/adapters/claude-code/settings-hooks.json. Lee el archivo existente, agrega a los arrays existenteshooks.SessionStart/hooks.PreToolUseen lugar de reemplazarlos, y mantén el JSON válido. Si el equipo rechazó los hooks, omite esto y elimina la carpeta.claude/hooks/que el adaptador copió. El arnés no depende de los hooks:feature.pysella el estado de la tarea y se niega a funcionar después de una edición manual, y el archivo de entrada le dice a cada agente que ejecuteinit.shal inicio de la sesión. - Solo Claude Code,
.worktreeinclude: si el proyecto necesita archivos gitignorados como.envpara ejecutarse, listalos para que cada worktree que Claude Code cree obtenga una copia. Paragit worktree addsimple, menciona esos archivos enharness/README.mdpara que la gente los copie.
9. Probarlo una vez
Ejecuta bash scripts/harness/init.sh y python3 scripts/harness/check_architecture.py e informa
el resultado real. Si algo falla por el proyecto (no por el arnés), dilo claramente y
déjalo como la primera entrada en el informe; no aflojes una regla ni elimines un comando para que esté en verde.
Luego haz la prueba de sesión nueva de references/principles.md: responde las cinco preguntas
usando solo los archivos, y corrige cualquier cosa que no puedas responder.
10. Informar
Dile al usuario, brevemente:
- Qué se creó, qué se fusionó y qué se omitió porque ya existía
- Los comandos por capa y de dónde vino cada uno
- Cada
TODO(confirm)y cada suposición que hiciste - El resultado de la inicialización/verificación, incluyendo los fallos
- Si esta habilidad misma se instaló en el repositorio (
.agents/skills/harness-bootstrap/o la carpeta de habilidades de otro agente, másskills-lock.json), dilo: el equipo no la necesita después de el bootstrap, y se puede eliminar o conservar para volver a ejecutarla más tarde. No la elimines tú mismo. - Próximo paso: revisar y confirmar el bootstrap en una rama, luego iniciar una tarea con la
habilidad
harness-start(en agentes con comandos slash,/harness-start <TASK-ID>)
No confirmes ni subas cambios a menos que el usuario lo pida.
Reglas de diseño para adaptar el andamio
- Prefiere las herramientas existentes del proyecto. Si el repositorio tiene un
Makefileconmake check, ponmake checkenconfig.shen lugar de volver a listar sus partes. - Mantén las dependencias de tiempo de ejecución en
bash,gitypython3(solo la biblioteca estándar). No agregues paquetes al proyecto para el arnés. - Los mensajes de error de cualquier script del arnés dicen qué falló, por qué y cómo solucionarlo.
- Nada destructivo en los scripts. La limpieza solo informa; los humanos o agentes actúan sobre el informe.
- Haz el arnés más pequeño cuando puedas. Un componente que no cambia el comportamiento del agente en este repositorio es sobrecarga; dilo en lugar de instalarlo por completitud.