🎮 Tutorial Interactivo: De 45% a 80% en 10 Minutos

Objetivo: Obtener el score base de tu proyecto y entender qué subsistemas necesitan atención.

Ejecuta el scanner en la raíz de tu proyecto para obtener un diagnóstico completo en formato JSON:

harness scan . --json

{
  "score": 45,
  "grade": "NEEDS_IMPROVEMENT",
  "subsystems": [
    { "id": "instructions", "score": 60, "weight": 0.25 },
    { "id": "state", "score": 40, "weight": 0.20 },
    { "id": "verification", "score": 10, "weight": 0.20 },
    { "id": "scope", "score": 50, "weight": 0.15 },
    { "id": "lifecycle", "score": 55, "weight": 0.10 },
    { "id": "skills", "score": 30, "weight": 0.10 }
  ]
}

Revisa los scores por subsistema. Los más bajos suelen ser Verification (falta de tests) e Instructions (falta de docs estructuradas). Anota tu score base: lo compararás al final.

Objetivo: Crear stubs automáticos para todos los archivos de harness que faltan en tu proyecto.

El comando harness fix . analiza tu repo y genera archivos de scaffolding con contenido mínimo viable:

harness fix .

✅ AGENTS.md creado
✅ ROADMAP.md creado
✅ TASK.md creado
✅ docs/vision.md creado
✅ scripts/verify.sh creado
✅ tests/ creado
⚠️  Revisa los stubs generados y reemplázalos con contenido real.

Importante: harness fix . no cubre los siguientes archivos — debes crearlos manualmente si aplican a tu proyecto:

• SOUL.md — identidad y filosofía del proyecto
• TOOLS.md — stack y herramientas permitidas
• USER.md — perfil del usuario objetivo
• MEMORY.md — convenciones de memoria y estado
• BOOTSTRAP.md — instrucciones de setup inicial
• RULES.md — reglas de negocio y constraints
• .gitignore — exclusiones de version control
• LICENSE — licencia del proyecto

Objetivo: Transformar los stubs genéricos en documentación viva que refleje la identidad real de tu proyecto.

Abre cada archivo generado y reescríbelo con contenido específico. No dejes placeholders. Algunos ejemplos:

• SOUL.md: "Este proyecto es un motor de backtesting cuantitativo. Su razón de ser es permitir a traders individuales validar estrategias sin código."
• AGENTS.md: Define quién es el agente, qué puede hacer y qué no debe hacer nunca.
• ROADMAP.md: Lista milestones reales con fechas o versiones objetivo.
• docs/vision.md: Describe el north star del proyecto en 3 párrafos máximo.

Regla de oro: si un archivo tiene más del 30% de texto genérico o placeholders ("TODO", "FIXME", "[NOMBRE]"), el harness score no subirá.

Objetivo: Medir el impacto de la documentación y los stubs generados.

Vuelve a ejecutar el scanner y compara los scores:

harness scan . --json

{
  "score": 62,
  "grade": "FAIR",
  "subsystems": [
    { "id": "instructions", "score": 85, "weight": 0.25 },
    { "id": "state", "score": 70, "weight": 0.20 },
    { "id": "verification", "score": 15, "weight": 0.20 },
    { "id": "scope", "score": 65, "weight": 0.15 },
    { "id": "lifecycle", "score": 60, "weight": 0.10 },
    { "id": "skills", "score": 45, "weight": 0.10 }
  ]
}

Lo más probable es que Instructions y Scope hayan subido drásticamente. Sin embargo, Verification seguirá bajo hasta que agregues tests.

Objetivo: Cerrar el gap de Verification creando al menos 2 archivos de test.

Crea el directorio tests/ y al menos 2 archivos de test con casos reales:

mkdir tests
touch tests/test_core.py
touch tests/test_validation.py

Escribe al menos un test que pase y uno que valide un error. Ejemplo mínimo:

# tests/test_core.py
def test_something_real():
    assert True  # reemplaza con una prueba real de tu dominio

# tests/test_validation.py
def test_invalid_input_raises():
    with pytest.raises(ValueError):
        process_input(None)

Luego re-escanea para ver el salto en Verification:

harness scan . --json

{
  "score": 78,
  "grade": "GOOD",
  "subsystems": [
    { "id": "instructions", "score": 85, "weight": 0.25 },
    { "id": "state", "score": 70, "weight": 0.20 },
    { "id": "verification", "score": 80, "weight": 0.20 },
    { "id": "scope", "score": 75, "weight": 0.15 },
    { "id": "lifecycle", "score": 70, "weight": 0.10 },
    { "id": "skills", "score": 55, "weight": 0.10 }
  ]
}

Con solo 2 archivos de test bien escritos, el subsistema de Verification puede saltar de ~15% a ~80%.

Objetivo: Alcanzar 80%+ de harness score y planificar mejoras continuas.

Con los 5 pasos anteriores, tu score debería estar en el rango 75–85%. Si aún no llegas a 80%, revisa estos ajustes rápidos:

• Skills: Si usas skills o recetas, asegúrate de que cada una tenga un SKILL.md con frontmatter.
• Lifecycle: Agrega un scripts/init.sh o scripts/verify.sh ejecutable.
• State: Crea progress.md o session-handoff.md con estado actual del proyecto.
• Scope: Define un Definition of Done explícito en AGENTS.md o TASK.md.

Cuando alcances 80% o más, ejecuta una última vez:

harness scan . --json | jq '.score'

Y celebra. Tu proyecto ahora tiene un harness que cualquier agente puede entender y usar de manera confiable.