Hoofy

Tu compañero de desarrollo de IA. Un servidor MCP que le brinda a tu IA memoria persistente, especificaciones estructuradas y gestión adaptativa de cambios, para que construya lo que realmente deseas.

GitHub

Prueba este MCPPatrocinado

Documentación

Hoofy

El asistente de codificación con IA que recuerda el contexto y reduce las alucinaciones en las especificaciones.
Un servidor MCP que le da a tu IA memoria persistente, especificaciones estructuradas
y gestión de cambios adaptativa — para que construya lo que realmente quieres.

Entrada de blog · Guía de flujo de trabajo · Referencia de herramientas · Fundamentos de investigación ·

Empieza aquí (TL;DR)

Si el README te resultó abrumador, usa esta sección primero.

Hoofy es un servidor MCP que le da a tu IA memoria persistente + flujo de trabajo basado en especificaciones.
Previene los fallos clásicos de la IA: olvidar el contexto, alucinar requisitos y saltarse la planificación.
Funciona con Claude Code, Cursor, VS Code Copilot, OpenCode, Gemini CLI (y cualquier herramienta compatible con MCP).
Puedes usarlo para proyectos nuevos, cambios en curso o proyectos existentes sin especificaciones.
Instala, conecta MCP y empieza con un cambio pequeño.

Inicio rápido en 60 segundos

Instala Hoofy: brew install HendryAvila/hoofy/hoofy (o usa el script de instalación de abajo).
Conecta MCP: claude mcp add --scope user hoofy hoofy serve (o usa la configuración MCP de tu editor).
Pide a tu IA que implemente un cambio — Hoofy guía la planificación y la memoria automáticamente.

¿Qué es Hoofy? — Compañero de desarrollo con IA para MCP

Hoofy resuelve tres problemas recurrentes en el desarrollo con IA: pérdida de memoria entre sesiones, implementaciones alucinadas y flujos de trabajo no estructurados. Es un único servidor MCP (Model Context Protocol) escrito en Go — un solo binario, cero dependencias externas de ejecución.

Elige tu camino

Proyecto nuevo → ejecuta el pipeline completo de proyecto (sdd_init_project →... → sdd_validate)
Proyecto existente, añadiendo o arreglando algo → empieza con sdd_change
Proyecto existente sin especificaciones aún → sdd_reverse_engineer + sdd_bootstrap
Solo necesitas contexto/revisión rápidamente → sdd_suggest_context, sdd_review, sdd_audit

Sistemas principales (de un vistazo)

Sistema	Qué hace	Herramientas
Memoria	Contexto persistente entre sesiones usando SQLite + búsqueda de texto completo FTS5.	Herramientas `mem_*`
Pipeline de cambios	Flujo adaptativo para trabajo en curso según tipo de cambio × tamaño (12 variantes).	`sdd_change*`, `sdd_adr`
Pipeline de proyecto	Flujo completo de especificación greenfield con Clarity Gate (9 etapas).	Herramientas de proyecto `sdd_*`
Bootstrap	Ingeniería inversa de codebases existentes en requisitos, reglas y artefactos de diseño.	`sdd_reverse_engineer`, `sdd_bootstrap`

Características clave (las más importantes)

Pipeline basado en principios primero — define lo no negociable antes que los requisitos.
Clarity Gate — bloquea especificaciones vagas antes de que comience la implementación.
Verificación de contexto en cada cambio — detecta conflictos temprano.
Revisión/auditoría consciente de especificaciones — compara el código contra requisitos y reglas.
Memoria persistente + grafo de conocimiento — las decisiones y correcciones permanecen buscables.
Instrucciones calientes/frías — instrucciones principales ligeras + guías bajo demanda. Ver detalles completos de características
Project Charter — La antigua etapa de "propuesta" ahora es un charter con contexto de dominio, interesados, visión, límites, criterios de éxito, sistemas existentes y restricciones.
Auditoría Spec-vs-Code — sdd_audit compara especificaciones contra código fuente para detectar implementaciones faltantes y desviaciones.
Instrucciones de agente auto-generadas — sdd_init_project inyecta instrucciones SDD en CLAUDE.md/AGENTS.md (idempotente).
Almacenamiento ADR unificado — Los ADR siempre se escriben en docs/adrs/NNN-slug.md.
Revisión de código consciente de especificaciones — sdd_review genera una lista de verificación vinculada a FR/NFR/reglas de negocio/ADRs.
Sugerencia de contexto ad-hoc — sdd_suggest_context recomienda qué leer antes de la implementación.
Bootstrap de proyectos existentes — sdd_reverse_engineer + sdd_bootstrap crean artefactos faltantes para codebases heredadas.
Grafo de conocimiento — relaciona observaciones con aristas tipadas (depends_on, caused_by, implements, etc.).
Herramientas facade-first — puntos de entrada de memoria unificados: mem_save y mem_session.
Etapa de reglas de negocio — Extracción BRG + DDD antes del Clarity Gate.
Exploración previa al pipeline — sdd_explore captura objetivos/restricciones/incógnitas antes del trabajo formal del pipeline.
Asignaciones por oleadas — oleadas de dependencia de tareas para planificación de ejecución paralela.

Decision: "Switched to JWT"  →(caused_by)→  Discovery: "Session storage doesn't scale"
    ↑(implements)                               ↑(relates_to)
Bugfix: "Fixed token expiry"              Pattern: "Retry with backoff"

¿Por qué Hoofy?

Los asistentes de codificación con IA son potentes pero olvidadizos y demasiado confiados. Los estudios muestran que los desarrolladores experimentados son 19% más lentos con IA no estructurada (METR 2025), y la adopción de IA sin estructura causa 7.2% de inestabilidad en la entrega (DORA 2025). Hoofy arregla esto haciendo que tu IA recuerde contexto, siga especificaciones y valide la comprensión antes de codificar.

Cómo fluye

flowchart TB
    explore["sdd_explore\n(goals, constraints, unknowns)"]

    subgraph project ["New Project (greenfield)"]
        direction LR
        P1[Init] --> P1b[Principles] --> P2[Charter] --> P3[Requirements] --> P3b["Business\nRules"]
        P3b --> P4{Clarity Gate}
        P4 -->|Ambiguous| P3
        P4 -->|Clear| P5[Design] --> P6[Tasks] --> P7[Validate]
    end

    subgraph bootstrap ["Existing Project (no specs)"]
        direction LR
        B1["sdd_reverse_engineer\n(scan codebase)"] --> B2["AI analyzes\nreport"] --> B3["sdd_bootstrap\n(write artifacts)"]
    end

    subgraph change ["Existing Project (changes)"]
        direction LR
        C1["sdd_change\n(type × size)"] --> C1b["Context\nCheck"]
        C1b --> C2["Opening Stage\n(describe/charter/scope)"]
        C2 --> C3["Spec + Design\n(if needed)"]
        C3 --> C4[Tasks] --> C5[Verify]
    end

    subgraph memory ["Memory (always active)"]
        direction LR
        M1["mem_session(action=start)"] --> M2["Work + mem_save"]
        M2 --> M3["Connect with Relations"]
        M3 --> M4["mem_session(action=end, summary)"]
    end

    explore -.->|"captures context before"| project
    explore -.->|"captures context before"| change
    bootstrap -.->|"enables"| change

    style explore fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style P4 fill:#f59e0b,stroke:#d97706,color:#000
    style P1b fill:#e879f9,stroke:#c026d3,color:#000
    style P3b fill:#e879f9,stroke:#c026d3,color:#000
    style C1b fill:#e879f9,stroke:#c026d3,color:#000
    style B1 fill:#06b6d4,stroke:#0891b2,color:#fff
    style B3 fill:#06b6d4,stroke:#0891b2,color:#fff
    style P7 fill:#10b981,stroke:#059669,color:#fff
    style C5 fill:#10b981,stroke:#059669,color:#fff

Guía completa del flujo de trabajo con ejemplos paso a paso · Referencia completa de herramientas

Inicio rápido

1. Instala el binario

macOS (Homebrew)

brew install HendryAvila/hoofy/hoofy

macOS / Linux (script)

curl -sSL https://raw.githubusercontent.com/HendryAvila/Hoofy/main/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/HendryAvila/Hoofy/main/install.ps1 | iex

Go / Fuente

# Go install (requires Go 1.25+)
go install github.com/HendryAvila/Hoofy/cmd/hoofy@latest

# Or build from source
git clone https://github.com/HendryAvila/Hoofy.git
cd Hoofy
make build

2. Conéctalo a tu herramienta de IA

Servidor MCP vs Plugin — ¿cuál es la diferencia?

El servidor MCP es Hoofy en sí — el binario que acabas de instalar. Proporciona memoria, pipeline de cambios, pipeline de proyecto, bootstrap y herramientas independientes a través de MCP y funciona con cualquier herramienta de IA compatible con MCP.

El Plugin es una mejora solo para Claude Code que añade capacidades adicionales sobre el servidor MCP:

Componente Qué hace
Agente Una personalidad personalizada (Hoofy el arquitecto caballo) que enseña a través de conceptos, no de volcados de código. Aplica disciplina SDD — la IA no se saltará las especificaciones.
Habilidades Conjuntos de instrucciones cargables para dominios específicos (React 19, Next.js 15, TypeScript, Tailwind 4, Django DRF, Playwright, etc.). El agente detecta el contexto automáticamente y carga la habilidad correcta antes de escribir código.
Hooks Automatización del ciclo de vida — hooks PreToolCall y PostToolCall que activan operaciones de memoria automáticamente (por ejemplo, guardar contexto de sesión, capturar descubrimientos después del uso de herramientas).

El plugin es opcional — obtienes toda la funcionalidad de Hoofy solo con el servidor MCP. El plugin solo hace la experiencia más fluida en Claude Code.

Componente	Qué hace
Agente	Una personalidad personalizada (Hoofy el arquitecto caballo) que enseña a través de conceptos, no de volcados de código. Aplica disciplina SDD — la IA no se saltará las especificaciones.
Habilidades	Conjuntos de instrucciones cargables para dominios específicos (React 19, Next.js 15, TypeScript, Tailwind 4, Django DRF, Playwright, etc.). El agente detecta el contexto automáticamente y carga la habilidad correcta antes de escribir código.
Hooks	Automatización del ciclo de vida — hooks `PreToolCall` y `PostToolCall` que activan operaciones de memoria automáticamente (por ejemplo, guardar contexto de sesión, capturar descubrimientos después del uso de herramientas).

Claude Code

Servidor MCP — un comando, listo:

claude mcp add --scope user hoofy hoofy serve

Plugin (opcional, solo Claude Code) — añade agente + habilidades + hooks sobre el servidor MCP:

/plugin marketplace add HendryAvila/hoofy-plugins
/plugin install hoofy@hoofy-plugins

Cursor

Añade a tu configuración MCP:

{
  "mcpServers": {
    "hoofy": {
      "command": "hoofy",
      "args": ["serve"]
    }
  }
}

VS Code Copilot

Añade a .vscode/mcp.json:

{
  "servers": {
    "hoofy": {
      "type": "stdio",
      "command": "hoofy",
      "args": ["serve"]
    }
  }
}

OpenCode

Añade a ~/.config/opencode/opencode.json dentro de la clave "mcp":

{
  "mcp": {
    "hoofy": {
      "type": "local",
      "command": ["hoofy", "serve"],
      "enabled": true
    }
  }
}

Gemini CLI

Añade a tu configuración MCP:

{
  "mcpServers": {
    "hoofy": {
      "command": "hoofy",
      "args": ["serve"]
    }
  }
}

3. Úsalo

Solo habla con tu IA. Las instrucciones integradas de Hoofy le dicen a la IA cuándo y cómo usar cada sistema.

4. Actualiza

hoofy update

Comprueba automáticamente al inicio, actualiza cuando tú lo digas.

Hoofy ya incluye instrucciones de servidor integradas, pero un bloque de política corto en tu archivo de instrucciones de agente refuerza el flujo de trabajo.

Nota: sdd_init_project genera esto automáticamente en los archivos de agente. Añádelo manualmente solo si ejecutas Hoofy en modo solo MCP.

Pon esto en tu archivo de instrucciones específico de la herramienta:

Claude Code: CLAUDE.md
Cursor: .cursor/rules/hoofy.md
OpenCode: AGENTS.md
VS Code Copilot: .github/copilot-instructions.md
Gemini CLI: GEMINI.md

## Hoofy — Spec-Driven Development

Before coding any non-trivial change, use Hoofy specs first.
- New projects: \`sdd_init_project\` -> full pipeline
- Existing projects without specs: \`sdd_reverse_engineer\` -> \`sdd_bootstrap\`
- Ongoing work: \`sdd_change\` (size/type adaptive)
- Ad-hoc sessions: \`sdd_suggest_context\`
- Reviews: \`sdd_review\`
- Spec/code drift checks: \`sdd_audit\`
- Memory: \`mem_save\`, \`mem_session\`

Mejores prácticas

1. Especificaciones antes que código — siempre

La IA intentará saltar directamente a codificar. No lo permitas. Para cualquier trabajo no trivial:

¿Proyecto nuevo? → sdd_init_project y recorre el pipeline completo de 9 etapas
¿Nueva funcionalidad? → sdd_change(type: "feature", size: "medium") como mínimo
¿Corrección de errores? → Incluso sdd_change(type: "fix", size: "small") te da verificación de contexto → describir → tareas → verificar

Las etapas más baratas (verificación de contexto + describir + tareas + verificar) toman menos de 2 minutos y ahorran horas de depuración de código alucinado.

2. Explora antes de planificar

Antes de saltar a un pipeline, usa sdd_explore para capturar contexto de tu discusión — objetivos, restricciones, preferencias técnicas, incógnitas, decisiones. Guarda contexto estructurado en memoria para que el pipeline comience con claridad, no con suposiciones. Llámalo varias veces mientras tu pensamiento evoluciona — hace upsert, nunca duplica.

3. Bootstrap de proyectos existentes

¿Trabajando en un proyecto que nunca pasó por SDD? No te saltes las especificaciones — haz bootstrap. Ejecuta sdd_reverse_engineer para escanear el codebase, luego sdd_bootstrap para generar los artefactos faltantes. Esto toma menos de un minuto y significa que el pipeline de cambios funciona con contexto completo en lugar de a ciegas. Los cambios medianos/grandes están bloqueados sin especificaciones — y eso es intencional.

4. Dimensiona tus cambios correctamente

No uses un pipeline grande para un arreglo de una línea. No uses un pipeline pequeño para un nuevo sistema de autenticación.

Si el cambio...	Probablemente es...
Toca 1-2 archivos, arreglo claro	pequeño (4 etapas — verificación de contexto + describir + tareas + verificar)
Necesita requisitos o pensamiento de diseño	mediano (5 etapas)
Afecta arquitectura, múltiples sistemas	grande (6-7 etapas)

5. Deja que la memoria trabaje por ti

No necesitas decirle a la IA que use la memoria — las instrucciones integradas de Hoofy lo manejan. Pero obtendrás mejores resultados si:

Empiezas las sesiones saludando a la IA — activa mem_context para cargar el historial reciente
Mencionas decisiones pasadas — "recuerda cuando elegimos SQLite" activa mem_search
Confirmas los resúmenes de sesión — la IA los escribe al final de la sesión, revísalos para verificar su precisión

6. Conecta conocimiento con relaciones

El grafo de conocimiento de Hoofy te permite conectar observaciones relacionadas con aristas tipadas y direccionales — convirtiendo memorias planas en una red navegable. La IA crea relaciones automáticamente cuando reconoce conexiones. También puedes pedirle que relacione observaciones manualmente. Usa mem_get(id=..., depth=...) para explorar el grafo completo alrededor de cualquier observación.

7. Usa claves de tema para conocimiento en evolución

Cuando una decisión pueda cambiar (esquema de base de datos, diseño de API, arquitectura), usa topic_key en mem_save. Esto actualiza la observación existente en lugar de crear duplicados. Una observación por tema, siempre actual.

8. Un cambio a la vez

Hoofy aplica un cambio activo a la vez. Esto no es una limitación — es una característica. La expansión del alcance ocurre cuando intentas hacer tres cosas a la vez. Termina un cambio, verifícalo, luego empieza el siguiente.

9. Confía en el Clarity Gate

Cuando el Clarity Gate haga preguntas, no las apresures. Cada pregunta que hace representa una ambigüedad que se habría convertido en un error, una alucinación o un momento de "no es lo que quería decir". Dos minutos respondiendo preguntas ahorran dos horas depurando implementaciones incorrectas.

10. Hoofy es el arquitecto, el modo Plan es el contratista

Si tu herramienta de IA tiene un modo plan/implementación, úsalo después de que las especificaciones de Hoofy estén listas. Hoofy responde QUIÉN y QUÉ. El modo Plan responde CÓMO.

Hoofy (Requirements Layer)  →  "WHAT are we building? For WHO?"
Plan Mode (Implementation)  →  "HOW do we build it? Which files?"

La investigación detrás de SDD

El pipeline de especificaciones de Hoofy no se basa en opiniones. Se basa en investigación. Cada característica se mapea a una recomendación específica de Anthropic Engineering o investigación de la industria — consulta el documento completo de fundamentos de investigación para el mapeo completo.

Anthropic Engineering:

Construyendo Agentes Efectivos — Diseño de ACI, patrones de herramientas, arquitectura orquestador-trabajador
Ingeniería de Contexto Efectiva — Memoria persistente, divulgación progresiva, contexto como recurso finito
Escribiendo Herramientas Efectivas — Espacios de nombres de herramientas, diseño de respuestas, eficiencia de tokens
Sistema de Investigación Multi-Agente — Resúmenes de sesión, salida del sistema de archivos, conciencia del presupuesto de tokens
Arneses de Agentes de Larga Duración — Seguimiento de progreso, entrega incremental, JSON sobre Markdown para estado
Mejores Prácticas de Claude Code — Escaneo de CLAUDE.md, flujos de trabajo estructurados

Investigación de la Industria:

METR 2025: Desarrolladores experimentados fueron 19% más lentos con IA a pesar de sentirse 20% más rápidos — el uso no estructurado de IA introduce sobrecarga de depuración y falsa confianza.
DORA 2025: Aumento del 7.2% en inestabilidad de entrega por cada 25% de adopción de IA — sin sistemas y prácticas fundamentales.
McKinsey 2025: Los mejores desempeños ven ganancias de productividad del 16-30% solo con especificación y comunicación estructuradas.
IEEE 720574: Corregir un error de requisitos en producción cuesta 10-100x más que corregirlo durante los requisitos — peor con código generado por IA.
Contexto Codificado (Lulla 2026): Infraestructura AGENTS.md asociada con 29% menos tiempo de ejecución y 17% menos consumo de tokens. Las constituciones compactas (~660 líneas) con recuperación bajo demanda superan a las instrucciones monolíticas. La arquitectura de instrucciones calientes/frías de Hoofy implementa este patrón.
IREB e IEEE 29148: Elicitación estructurada, trazabilidad, detección de ambigüedad — la Puerta de Claridad de Hoofy implementa estos marcos.
Business Rules Group: El Manifiesto de Reglas de Negocio — reglas como ciudadanos de primera clase. Hoofy usa la taxonomía BRG.
EARS: Plantillas de oraciones respaldadas por investigación que eliminan la ambigüedad de requisitos.
Lenguaje Ubicuo de DDD: Lenguaje compartido elimina errores de traducción — el glosario de reglas de negocio de Hoofy.
Ingeniería de Arneses (OpenAI 2026): Envoltura estructurada de IA mejora la calidad de salida al restringir el contexto, hacer cumplir flujos de trabajo y hacer explícito el estado. El rediseño de identidad de Hoofy v1.0 fue directamente inspirado por la filosofía de este artículo de "el usuario aporta contenido, la IA complementa/organiza/valida."

La estructura supera a la velocidad.

Contribuyendo

git clone https://github.com/HendryAvila/Hoofy.git
cd Hoofy
make build        # Build binary
make test         # Tests with race detector
make lint         # golangci-lint
./bin/hoofy serve # Run the MCP server

Áreas para contribuir

Más dimensiones de claridad (móvil, API, canalización de datos)
Más tipos de cambios más allá de corrección/característica/refactorización/mejora
Mejoras y personalización de plantillas
Transporte HTTP transmisible para despliegue remoto
Exportación a Jira, Linear, GitHub Issues
i18n para especificaciones no inglesas

Agradecimientos

El sistema de memoria de Hoofy está inspirado en Engram de Gentleman Programming — el servidor MCP original de memoria persistente que demostró que los asistentes de IA necesitan contexto a largo plazo para ser realmente útiles. Engram sentó las bases; Hoofy se construyó sobre ellas.

Licencia

MIT

Deja de pedir. Empieza a especificar.
Construido con cuidado por la comunidad de Hoofy.