Proyecto existente¶
El flujo es el mismo que en Proyecto nuevo. Lo que cambia es el punto de partida: historia, convenciones, dependencias que no instalaste tú y, a veces, un estado base que ya está roto. La guía en inglés Brownfield reproduce un caso real sobre pallets/itsdangerous 2.2.0.
Pasos¶
- Entra al repositorio y comprueba el estado del árbol.
git status --short
Lo mejor es un árbol limpio. Si hay cambios sin confirmar, forman parte del estado base y quedan fuera del ChangeSet, pero la ejecución registra un hallazgo environment.dirty-tree de severidad LOW que dice cuántos cambios había. (Con environment.dirtyTree: block en la configuración, la ejecución se detiene.)
- Inicializa el harness.
harness init
En un repositorio de Git, init agrega .harness/ a .git/info/exclude, un archivo que Git lee como un .gitignore pero que no forma parte del árbol. Tu árbol no queda sucio por el harness y no hay nada que confirmar por esto. Si prefieres que la entrada vaya en el .gitignore del proyecto, usa harness init --ignore-file gitignore (ese cambio sí hay que confirmarlo). Si .harness/project.yaml ya existe, init se niega a sobrescribirlo salvo con --force.
- Revisa lo que detectó, sin riesgo: son comandos de solo lectura.
harness inspect
harness doctor --path .
harness config validate
harness project show
doctor comprueba Python, Git, la configuración, los validadores que el proyecto ejecutará, el commit base y si .harness/ está ignorado por Git. Cada punto que no pasa trae su remedio.
-
Instala las dependencias de prueba del proyecto en el entorno donde corre el harness. Los validadores ejecutan los comandos del proyecto (
python -m pytest,npm test) con el intérprete o las herramientas delPATH. Contoolchain.interpreter: auto(lo que escribeinit), los validadores de Python usan el.venvovenvdel proyecto,uv run --no-syncopoetry run. Una dependencia que falta no se detecta de antemano: las pruebas fallan al recolectarse y la ejecución sale con código 6, aunque el estado base falle igual, porque no se ejecutó ninguna prueba (ver más abajo). Los proyectos con comandos distintos declaran sus propios validadores entoolchain.validators(ver la referencia de configuración). -
Crea la tarea y ejecútala, igual que en un proyecto nuevo. Para un cambio en código existente declara en
metadata.ownedPathslos directorios que el agente puede modificar: el ChangeSet solo contiene esas rutas.
harness task create --file task.yaml
harness run start --task <taskId>
Qué hace el harness con el código que ya existe¶
- Con
architecture.mode: agent(lo que escribeinit), la fase de descubrimiento hace una consulta de solo lectura al agente para estudiar la arquitectura del proyecto y la guarda en.harness/architecture.mdy.harness/architecture.json. Las siguientes ejecuciones la reutilizan sin otra consulta. Con el proveedorsimulatedel archivo solo dice «Simulated survey: no layering was inferred»; con un agente real describe los patrones y las reglas de capas. Ver Ingeniería inversa y Arquitecturas. - Los archivos que
.gitignoreexcluye nunca se leen ni se guardan. Conworkspace.snapshot: git,baseline: manifestysnapshotCache: true(lo que escribeinit), repositorios de miles de archivos no se vuelven lentos en cada ejecución. - La detección respeta tus convenciones: lee los archivos marcadores (
pyproject.toml,package.json, ...) sin modificarlos. Si usas un gestor de paquetes distinto de npm en un proyecto Node.js, trata esos resultados con cuidado, porque el perfil siempre ejecutanpm.
Si el estado base ya está roto¶
Con verification.differential (lo escribe harness init), un validador obligatorio que falla también se ejecuta sobre el estado base: un fallo que el estado base comparte queda como PREEXISTING_ERROR y no bloquea; uno nuevo queda como INTRODUCED_ERROR y bloquea. Una ejecución de pruebas que no ejecutó ninguna prueba (por ejemplo, pytest detenido por un error de recolección porque falta una dependencia de pruebas) no es comparable y sigue bloqueando (issue 190 del repositorio). La evidencia muestra qué archivos fallaron. Si la ejecución falla, hay dos salidas:
- Corrige lo que falla (en el caso de
itsdangerous, instalafreezegun) y vuelve a ejecutar la tarea conharness run start. Congovernance.stopTheLine: restore(lo que escribeinit), los cambios de la ejecución fallida quedan en cuarentena y el árbol vuelve al estado base, así queharness run continueverificaría un ChangeSet vacío. Si la nueva ejecución pasa, basta unAPPROVEnormal. - Cierra con
APPROVE_EXCEPTIONy una justificación escrita; queda auditada aparte.
Trabajar sin tocar tu árbol¶
Si quieres seguir editando mientras el harness trabaja, o ejecutar varias tareas a la vez, usa el aislamiento por worktree: harness run start --task <taskId> --isolate worktree. Está explicado, con sus límites, en Trabajo simultáneo.