Guía rápida en español¶
Qué hace¶
El harness gobierna una tarea de desarrollo desde la intención hasta el cierre. No reemplaza al agente, las pruebas, Git ni los analizadores: controla cuándo pueden actuar, qué evidencia deben producir y bajo qué condiciones puede avanzar la ejecución.
Instalación¶
python -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev,api]'
Preparar un repositorio¶
harness init --path ./mi-proyecto
harness inspect --path ./mi-proyecto
harness config validate --path ./mi-proyecto
El detector inicial soporta proyectos Python y Node.js. La configuración queda en .harness/project.yaml.
Definir una tarea¶
Una tarea mínima:
title: Corregir precedencia de configuración
intent: Los valores de tarea deben tener mayor prioridad que los del repositorio.
acceptanceCriteria:
- La tarea tiene la mayor prioridad.
- Los tests existentes siguen pasando.
implementation:
mode: patch
patches:
- path: src/config.py
operation: replace
content: |
# contenido esperado
Registrar la tarea:
harness task create --path ./mi-proyecto --file task.yaml
Ejecutar¶
harness run start --path ./mi-proyecto --task <task-id>
Cuando todo lo automático pasa, el comando termina con código 4: no es un error; significa que la ejecución quedó bloqueada esperando una decisión humana en DECISION.
Consultar:
harness status --path ./mi-proyecto --run <run-id>
harness findings list --path ./mi-proyecto --run <run-id>
harness evidence list --path ./mi-proyecto --run <run-id>
Aprobar el ChangeSet exacto¶
Copiar el changeSetDigest actual y ejecutar:
harness gate decide \
--path ./mi-proyecto \
--run <run-id> \
--decision APPROVE \
--change-set-digest sha256:<digest> \
--actor human.reviewer \
--rationale 'Revisé criterios, diff, tests y findings'
Después de cualquier cambio adicional, la aprobación anterior deja de ser válida automáticamente.
Cuando existen findings bloqueantes, una aprobación ordinaria no es válida. Una excepción debe utilizar APPROVE_EXCEPTION, incluir una justificación específica y queda auditada por separado.
Continuar después de una corrección¶
Cuando un test o validador falla, corregir los archivos y ejecutar:
harness run continue --path ./mi-proyecto --run <run-id>
El sistema recalcula el ChangeSet y repite las validaciones necesarias.
Trazas y retrospectiva¶
harness trace --path ./mi-proyecto --run <run-id> --format markdown --output trace.md
harness trace --path ./mi-proyecto --run <run-id> --format json --output trace.json
harness retrospect --path ./mi-proyecto --run <run-id>
La retrospectiva genera recomendaciones; nunca modifica automáticamente reglas, gates, permisos o memoria normativa.
Web local¶
harness api serve --path ./mi-proyecto --host 127.0.0.1 --port 8765
La interfaz permite observar ejecuciones y registrar decisiones vinculadas al digest. Con la sección api que escribe harness init, cada ruta exige un token bearer: el comando lo toma de HARNESS_API_TOKEN o genera uno y lo imprime una sola vez en la salida de error; el tablero lo pide una vez y lo guarda solo en la pestaña. Sin la sección no hay autenticación. En ambos casos es una interfaz local; no debe exponerse públicamente.
Límites importantes¶
El process runner local no es un sandbox fuerte. Controla autorización, argumentos, directorio, timeout, cancelación y salida, pero un proceso nativo hostil todavía puede usar los permisos del usuario del sistema operativo. Para código no confiable se requiere un adaptador basado en contenedores, VM o sandbox del sistema operativo.