El Harness de Claude Code: configuración del equipo

Parte de la colección [[concept—workspace—supercontexto-00-vision]]. Cubre: qué es el harness, hooks SessionStart/Stop, pre-commit hook, permisos pre-aprobados, memorias persistentes, skills y agentes especializados.

¿Qué es el harness?

El harness es la capa de configuración que envuelve a Claude Code y hace que el agente se comporte de forma consistente y correcta para el equipo de Esferic Labs. No es Claude en sí — es el conjunto de reglas, automatismos y contexto que rodea a Claude para que trabaje bien en nuestro proyecto.

El harness se configura en dos archivos settings.json:

• ~/.claude/settings.json — configuración global del usuario (aplica a todos los proyectos)
• C:\dev\CreaRack-Pro\.claude\settings.json y .claude\settings.local.json — configuración específica del proyecto

graph TD
    subgraph HARNESS["🔧 Harness de Claude Code"]
        H1["📋 CLAUDE.md\n(instrucciones del proyecto)"]
        H2["🔗 Hooks\n(automatismos al arrancar/parar)"]
        H3["🔑 Permisos\n(allowlist de comandos)"]
        H4["🧠 Memorias\n(contexto persistente entre sesiones)"]
        H5["🛠️ Skills\n(capacidades especializadas)"]
        H6["🤖 Agentes\n(subagentes especializados)"]
    end

    H1 --> CLAUDE["Claude Code\n(el agente en sí)"]
    H2 --> CLAUDE
    H3 --> CLAUDE
    H4 --> CLAUDE
    H5 --> CLAUDE
    H6 --> CLAUDE

El CLAUDE.md: instrucciones del proyecto

CLAUDE.md es el documento más importante del harness. Claude Code lo lee al inicio de cada sesión y define:

• El rol del agente (arquitecto de software + sysadmin senior)
• Las 26 Reglas de Oro que rigen todo el comportamiento
• El stack tecnológico del proyecto
• Los comandos y URLs más usados
• La estructura del proyecto
• El equipo y sus roles

Las reglas más críticas son:

• Regla 0 — Consultar la Biblioteca antes de cualquier tarea
• Regla 1 — Responder siempre en español
• Regla 3 — Actualizar docs en cada commit
• Regla 16 — Nunca [skip ci]
• Regla 20 — Flujo híbrido push directo / PR según el tipo de cambio

Los hooks: lo que pasa al arrancar y parar sesión

Hook SessionStart (al abrir Claude Code)

Cada vez que Edu, Dani o Txell abren Claude Code en el proyecto CreaRack-Pro, se ejecutan automáticamente 4 comandos:

sequenceDiagram
    participant CC as Claude Code
    participant Git as Git
    participant HCS as hot-cache-sync.ps1
    participant TZ as Timezone hook
    participant SM as sync-method.ps1

    Note over CC: Usuario abre Claude Code
    CC->>Git: git pull --rebase origin main
    Git-->>CC: ✅ repo actualizado
    CC->>HCS: hot-cache-sync.ps1
    HCS-->>CC: 🔥 project_hot_cache.md (contexto del proyecto)
    CC->>TZ: Get-Date Europe/Madrid
    TZ-->>CC: [Local time] 2026-05-27 13:00:00 +02:00 (CEST)
    CC->>SM: sync-hook-wrapper.ps1
    SM-->>CC: ✅ claude-method sincronizado

Hook Stop (al cerrar sesión)

Cuando Claude termina de responder, se ejecuta un script que comprueba si hay que recordar actualizar el WORKLOG:

# Lógica simplificada del hook Stop
si hoy ya mostré el recordatorio → no hacer nada
si hay 3+ commits propios hoy en los dos repos → mostrar recordatorio WORKLOG

El recordatorio dice: “REMINDER: hoy hay N commits (CreaRack-Pro: X, workspace: Y). Actualiza WORKLOG.md en CreaRackSL-workspace antes de cerrar.”

El pre-commit hook: guardián de la Biblioteca

Antes de cada git commit, el script claude-method/harness/bib_report_check.py (el hook lo ejecuta desde ahí; desde el 05-08-2026 no hay copias por repo) verifica que Claude Code haya llamado a bib_report_change para cada archivo Python modificado en los últimos 10 minutos.

git commit -m "feat: nuevo endpoint"
    ↓
[pre-commit] Verificando bib_report_change...
    ↓ Si OK: commit procede
    ↓ Si NO: ❌ BLOCKED: archivo monitoring/views.py modificado sin bib_report_change
    ↓ Bypass: BIB_SKIP=1 git commit (queda en el registro del Pulse)

Si el MCP del workspace está caído, el hook degrada con un warning y deja pasar el commit. No rompe el flujo productivo por un problema de infraestructura.

Los permisos pre-aprobados (allowlist)

Para que Claude Code no interrumpa el flujo de trabajo con prompts de confirmación en cada comando, la allowlist pre-aprueba los más frecuentes:

Permisos globales (~/.claude/settings.json)

• Read, Write, Edit, Glob, Grep — operaciones de ficheros sin restricción
• Bash(*), PowerShell(*) — cualquier comando de terminal
• WebFetch, WebSearch — búsquedas web
• Skill(*) — ejecución de skills sin confirmación
• mcp__crearack-workspace__* — todas las herramientas del MCP del workspace
• mcp__context7__* — todas las herramientas del MCP de Context7 (docs de librerías)

Permisos denegados (protecciones)

• git reset --hard * — protege contra pérdida de trabajo
• git checkout -- * — protege contra descarte de cambios
• git clean -f* — protege contra borrado de archivos sin trackear
• git branch -D* — protege contra borrado de ramas

Modo por defecto

• settings.json global: modo default (pide confirmación para lo no listado)
• settings.local.json del proyecto: modo acceptEdits (acepta ediciones automáticamente — más fluido)

Las memorias persistentes

Claude Code tiene un sistema de memorias persistentes en ~/.claude/projects/C--dev-CreaRack-Pro/memory/. Son archivos .md con frontmatter estructurado que persisten entre sesiones.

Tipos de memoria

Ejemplos de memorias activas

• feedback_crearack_ui_english_native.md — toda la UI de CreaRack en inglés, NO español
• feedback_no_model_changes_without_consent.md — no cambiar modelos IA sin consultar
• project_work_on_online_not_public.md — el equipo prueba en PROD, no en local
• reference_vpn_netbird.md — configuración de la VPN NetBird del equipo

El índice MEMORY.md contiene una línea por memoria para que Claude sepa qué hay disponible sin leer todos los archivos.

Los skills: capacidades especializadas

Los skills son “rutinas” que Claude puede ejecutar con un comando /skill-name. Los más relevantes:

Skills de gestión del proyecto

Skills de la wiki (Supercontexto)

Skills de diseño UI

Los agentes especializados

Además de skills, hay agentes especializados que se pueden lanzar para tareas complejas:

Regla del equipo: usar siempre el agente más específico disponible. general-purpose es el último recurso, no el primero.

El context7 MCP: docs de librerías siempre actualizadas

El MCP de Context7 da a Claude acceso a documentación actualizada de cualquier librería, sin depender del conocimiento de entrenamiento (que puede estar desactualizado):

# Claude Code consulta automáticamente cuando detecta una librería
mcp__context7__resolve-library-id("django ninja")
  → "/vitalik-buterin/django-ninja"
mcp__context7__query-docs("/vitalik-buterin/django-ninja", "¿cómo se definen routers?")
  → Documentación actualizada de la versión actual

Esto significa que cuando Edu pregunta “¿cómo configuro HTMX con Alpine.js?”, Claude consulta la documentación real en vez de inventarse una respuesta desactualizada.

Véase también

• [[concept—workspace—supercontexto-00-vision]] — Visión general del sistema completo
• [[concept—workspace—supercontexto-01-biblioteca]] — La Biblioteca que el harness usa
• [[concept—workspace—supercontexto-05-crons]] — Automatismos que complementan el harness