CommunityProgramación y desarrollogithub.com

harness-bootstrap

Instala un arnés completo y listo para el equipo en cualquier repositorio git: archivo de entrada (CLAUDE.md / AGENTS.md), documentación de arquitectura y fiabilidad, scripts de verificación, reglas de arquitectura ejecutables, lista de tareas por característica, archivos de transferencia de sesión y progreso locales (gitignorados), lista de verificación de estado limpio, un evaluador independiente y comprobaciones de integridad que lo refuerzan todo. Funciona con cualquier agente de codificación (Claude Code, Codex, Cursor, Copilot, Devin, Pi y otros). Úsalo cada vez que alguien quiera 'configurar un arnés', hacer que un repositorio esté listo para el agente, evitar que los agentes olviden el contexto entre sesiones, evitar que los agentes afirmen 'terminado' antes de que las cosas funcionen, organizar traspasos entre desarrolladores o worktrees, o crear archivos AGENTS.md / CLAUDE.md / feature_list.json / init.sh / session-handoff para un proyecto, incluso si nunca dicen la palabra 'arnés'.

¿Qué es harness-bootstrap?

Harness Bootstrap es una habilidad para agentes de IA diseñada para transformar cualquier repositorio git en un entorno donde los agentes de codificación puedan trabajar de manera consistente y confiable. Su propósito principal es instalar un 'contrato' completo —que incluye un archivo de entrada (AGENTS.md/CLAUDE.md), documentación de arquitectura, reglas de verificación, scripts de inicialización y un sistema de seguimiento de tareas— que todos los miembros del equipo y los agentes sigan. Esto resuelve problemas comunes como la pérdida de contexto entre sesiones, la falsa sensación de 'tarea completada' y la dificultad de las transferencias entre desarrolladores o worktrees. La habilidad es compatible con todos los principales agentes de codificación: Claude Code, Codex, Cursor, GitHub Copilot, Devin, Gemini CLI, Pi, Windsurf y Kiro CLI. Funciona analizando el repositorio existente (archivos de instrucciones, documentación, configuraciones de CI) para adaptar el arnés al proyecto sin sobrescribir nada que el equipo ya haya creado. Luego, copia una estructura de archivos que incluye scripts de verificación (`init.sh`, `verify.sh`, `feature.py`, `check_architecture.py`), reglas de arquitectura ejecutables y archivos de ciclo de vida (`harness-start`, `harness-handoff`, `harness-cleanup`, `harness-evaluate`). El resultado es un repositorio donde cualquier agente nuevo, en cualquier máquina, puede responder desde los archivos: qué es esto, cómo está organizado, cómo ejecutarlo, cómo verificarlo y dónde nos quedamos. 'Terminado' lo decide un script, no un agente. La habilidad se usa una vez por repositorio y todo lo instalado se confirma en el control de versiones para que todos los miembros del equipo lo obtengan al clonar.

Compatible con✓Claude Code✓Codex CLI✓Cursor✓Gemini CLI✓OpenCode✓Windsurf
npx skills add https://github.com/Gabriel-Valin/harness-bootstrap/tree/HEAD

Installed? Explore more Programación y desarrollo skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

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

CapaDónde¿Confirmado?Propósito
Archivo de entradaCLAUDE.md y/o AGENTS.mdsíMapa breve: qué, cómo ejecutar, cómo verificar, reglas estrictas, enlaces
Documentacióndocs/ARCHITECTURE.md, PRODUCT.md, RELIABILITY.md, docs/decisions/síConocimiento que el agente no puede inferir del código
Contratoharness/ (config, reglas, lista de verificación, rúbrica, documento de calidad, plantillas, README)síMismas reglas para todos, cambiadas solo mediante PR
Verificaciónscripts/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 carpetasíIniciar, transferir, limpiar, evaluar
AdaptadoresPor agente, por ejemplo .claude/agents/, .claude/hooks/ para Claude CodesíExtras opcionales: subagente, hooks
Estado de la tarea.harness/tasks/<TASK-ID>/noLista 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 importar db/?")
  • 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:

  1. 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.sh informa 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. Consulta references/discovery.md.
  2. harness/architecture-rules.json: una regla por límite, siguiendo references/architecture-rules.md. Cada regla necesita why y fix escritos para un agente, porque el mensaje de error es el bucle de retroalimentación.
  3. Documentación: crea docs/ARCHITECTURE.md, docs/PRODUCT.md, docs/RELIABILITY.md solo donde el repositorio no tenga equivalente, comenzando desde assets/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 como TODO(confirm): ... en lugar de adivinar. Si existen equivalentes en otro lugar, enlázalos en lugar de duplicarlos.
  4. 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 apunta harness/README.md, las habilidades de traspaso y limpieza, y las plantillas hacia la existente.
  5. harness/quality-document.md: lista los módulos reales con una calificación inicial honesta, o unknown donde 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ónHaz esto
No existen ni AGENTS.md ni CLAUDE.mdCrea AGENTS.md a partir de lo que aprendiste, más la sección.
Solo existe AGENTS.mdAgrega la sección a AGENTS.md.
Solo existe CLAUDE.md, el equipo usa solo Claude CodeAgrega la sección a CLAUDE.md.
Solo existe CLAUDE.md, el equipo usa otros agentes tambiénPregunta 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 existenAgrega 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:

AgentePuntero
Claude CodeCLAUDE.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 CLIGEMINI.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 de assets/snippets/gitignore.txt que falten.
  • Solo Claude Code, .claude/settings.json: fusiona los hooks de assets/adapters/claude-code/settings-hooks.json. Lee el archivo existente, agrega a los arrays existentes hooks.SessionStart / hooks.PreToolUse en 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.py sella 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 ejecute init.sh al inicio de la sesión.
  • Solo Claude Code, .worktreeinclude: si el proyecto necesita archivos gitignorados como .env para ejecutarse, listalos para que cada worktree que Claude Code cree obtenga una copia. Para git worktree add simple, menciona esos archivos en harness/README.md para 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ás skills-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 Makefile con make check, pon make check en config.sh en lugar de volver a listar sus partes.
  • Mantén las dependencias de tiempo de ejecución en bash, git y python3 (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.

Skills relacionados