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	Qué hace
`git pull --rebase origin main`	Asegura que el repo esté actualizado antes de empezar
`hot-cache-sync.ps1`	Descarga el contexto “caliente” del proyecto (STATE.md, docs recientes)
`Get-Date`	Inyecta la hora local de Madrid para que Claude no use la hora UTC incorrecta
`sync-hook-wrapper.ps1`	Sincroniza el repositorio `claude-method` con las últimas guías y herramientas

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

Tipo	Para qué
`user`	Quién es el usuario: rol, expertise, preferencias
`feedback`	Correcciones y directrices sobre cómo trabajar
`project`	Estado de iniciativas en curso, objetivos, restricciones
`reference`	Punteros a recursos externos (URLs, dashboards, tickets)

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

Skill	Qué hace
`/code-review`	Revisa el diff del branch actual buscando bugs y mejoras
`/simplify`	Aplica las correcciones del code-review automáticamente
`/verify`	Lanza la app y verifica que un cambio funciona
`/run`	Arranca el proyecto y hace screenshot/observación
`/security-review`	Auditoría de seguridad del código

Skills de la wiki (Supercontexto)

Skill	Qué hace
`/wiki-promote`	Promueve un draft a active
`/wiki-review-drafts`	Revisa todos los drafts pendientes
`/wiki-delete`	Archiva/elimina una página
`/bib-archive-last-answer`	Guarda la última respuesta de bib_ask como concept_page

Skills de diseño UI

Skill	Qué hace
`/design-make-a-prototype`	Construye un prototipo interactivo
`/design-polish-pass`	Revisión de calidad de un diseño (accesibilidad + jerarquía + slop)
`/design-generate-variations`	Produce 3+ variaciones de un componente o pantalla
`/design-wireframe`	Genera wireframes de baja fidelidad

Los agentes especializados

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

Agente	Para qué	Cuándo usarlo
`design-collaborator`	Diseño UI/frontend con criterio de calidad	Cualquier trabajo visual no trivial
`general-purpose`	Investigación compleja, búsquedas multi-archivo	Cuando no hay agente más específico
`Plan`	Diseñar estrategias de implementación	Antes de feat/refactor grandes
`Explore`	Búsqueda en abanico por muchos archivos	Para localizar código sin leerlo todo

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