Hoofy

Hoofy

El asistente de codificación con IA que recuerda el contexto y reduce las alucinaciones de 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.

Publicación de Blog · Guía de Flujo de Trabajo · Referencia de Herramientas · Fundamentos de Investigación ·

---

Comienza 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 modos de fallo 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 comienza con un cambio pequeño.

Inicio rápido en 60 segundos

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

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

Hoofy resuelve tres problemas recurrentes del 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 en tiempo de ejecución.

Elige tu camino

• Proyecto nuevo → ejecuta el pipeline completo del proyecto (sdd_init_project → ... → sdd_validate)
• Proyecto existente, agregando/arreglando algo → comienza 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.	mem_* tools
Pipeline de cambios	Flujo adaptativo para trabajo en curso basado en 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).	sdd_* project tools
Bootstrap	Ingeniería inversa de bases de código existentes en requisitos, reglas y artefactos de diseño.	sdd_reverse_engineer, sdd_bootstrap

Características clave (las más importantes)

• Pipeline de principios primero — define lo no negociable antes de 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 con los requisitos y reglas.
• Memoria persistente + grafo de conocimiento — las decisiones y correcciones permanecen buscables.
• Instrucciones calientes/frías — instrucciones centrales ligeras + guías bajo demanda. Ver detalles completos de las 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 las especificaciones con el 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 bases de código 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 de 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 dependencias 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 un 19% más lentos con IA no estructurada (METR 2025), y la adopción de IA sin estructura causa un 7,2% de inestabilidad en la entrega (DORA 2025). Hoofy soluciona esto haciendo que tu IA recuerde el 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. Conecta 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 exclusiva de 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 con volcados de código. Aplica la 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 automáticamente el contexto 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 que la experiencia sea más fluida en Claude Code.

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

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

Verifica automáticamente al inicio, actualiza cuando lo digas.

5. Refuerza el comportamiento (recomendado)

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 — Desarrollo basado en especificaciones

Antes de codificar cualquier cambio no trivial, usa primero las especificaciones de Hoofy.

• Proyectos nuevos: sdd_init_project -> pipeline completo
• Proyectos existentes sin especificaciones: sdd_reverse_engineer -> sdd_bootstrap
• Trabajo en curso: sdd_change (adaptativo por tamaño/tipo)
• Sesiones ad-hoc: sdd_suggest_context
• Revisiones: sdd_review
• Verificaciones de desviación especificación/código: sdd_audit
• Memoria: mem_save, mem_session

---

Mejores prácticas

1. Especificaciones antes del código — siempre

La IA intentará saltar directamente a la codificación. No lo permitas. Para cualquier trabajo no trivial:

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

Las etapas más baratas (verificación de contexto + describe + tareas + verifica) 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 el contexto de tu discusión — objetivos, restricciones, preferencias técnicas, incógnitas, decisiones. Guarda contexto estructurado en la memoria para que el pipeline comience con claridad, no con suposiciones. Llámalo varias veces a medida que 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: ponlas en marcha. Ejecuta sdd_reverse_engineer para escanear el código base, 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. Ajusta el tamaño de tus cambios

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 + descripción + tareas + verificación)
Requiere requisitos o pensamiento de diseño	mediano (5 etapas)
Afecta arquitectura, múltiples sistemas	grande (6-7 etapas)

5. Deja que la memoria trabaje para ti

No necesitas decirle a la IA que use memoria: las instrucciones integradas de Hoofy se encargan de ello. Pero obtendrás mejores resultados si:

• Comienza las sesiones saludando a la IA — esto activa mem_context para cargar el historial reciente
• Menciona decisiones pasadas — "¿recuerdas cuando elegimos SQLite?" activa mem_search
• Confirma 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 el conocimiento con relaciones

El grafo de conocimiento de Hoofy te permite conectar observaciones relacionadas con aristas tipadas y direccionales, convirtiendo recuerdos planos 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 impone un cambio activo a la vez. Esto no es una limitación, es una característica. El alcance se descontrola cuando intentas hacer tres cosas a la vez. Termina un cambio, verifícalo y luego comienza el siguiente.

9. Confía en el Clarity Gate

Cuando el Clarity Gate haga preguntas, no las pases por alto. 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 de 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 asigna a una recomendación específica de Anthropic Engineering o de la investigación de la industria; consulta el documento completo de fundamentos de investigación para ver el mapeo completo.

Anthropic Engineering:

• Building Effective Agents — diseño de ACI, patrones de herramientas, arquitectura orquestador-trabajador
• Effective Context Engineering — memoria persistente, divulgación progresiva, contexto como recurso finito
• Writing Effective Tools — espacios de nombres de herramientas, diseño de respuestas, eficiencia de tokens
• Multi-Agent Research System — resúmenes de sesión, salida del sistema de archivos, conciencia del presupuesto de tokens
• Long-Running Agent Harnesses — seguimiento de progreso, entrega incremental, JSON sobre Markdown para el estado
• Claude Code Best Practices — escaneo de CLAUDE.md, flujos de trabajo estructurados

Investigación de la industria:

• METR 2025: Los desarrolladores experimentados fueron un 19% más lentos con IA a pesar de sentirse un 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 la 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-100 veces más que corregirlo durante los requisitos, peor con código generado por IA.
• Codified Context (Lulla 2026): La infraestructura de AGENTS.md se asocia con un 29% menos de tiempo de ejecución y un 17% menos de 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 & IEEE 29148: Elicitación estructurada, trazabilidad, detección de ambigüedad: el Clarity Gate 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 los requisitos.
• DDD Ubiquitous Language: El lenguaje ubicuo compartido elimina errores de traducción: el glosario de reglas de negocio de Hoofy.
• Harness Engineering (OpenAI 2026): El envoltorio estructurado de la IA mejora la calidad de la salida al restringir el contexto, hacer cumplir los flujos de trabajo y hacer explícito el estado. El rediseño de identidad de Hoofy v1.0 se inspiró directamente en la filosofía de este artículo de "el usuario aporta contenido, la IA complementa/organiza/valida".

La estructura supera a la velocidad.

---

Contribuciones

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, pipeline 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
• Exportar 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 de memoria persistente original 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.