Hoofy

Seu companheiro de desenvolvimento com IA. Um servidor MCP que dá à sua IA memória persistente, especificações estruturadas e gerenciamento adaptativo de mudanças — para que ela construa o que você realmente deseja.

GitHub

Experimente este MCPPatrocinado

Documentação

Hoofy

O assistente de codificação com IA que lembra do contexto e reduz alucinações de especificação.
Um servidor MCP que dá à sua IA memória persistente, especificações estruturadas,
e gerenciamento adaptativo de mudanças — para que ela construa o que você realmente quer.

Post do Blog · Guia de Fluxo de Trabalho · Referência de Ferramentas · Fundamentos de Pesquisa ·

Comece Aqui (TL;DR)

Se o README parecer avassalador, use esta seção primeiro.

Hoofy é um servidor MCP que dá à sua IA memória persistente + fluxo de trabalho orientado por especificações.
Ele previne os modos clássicos de falha de IA: esquecer contexto, alucinar requisitos e pular o planejamento.
Funciona com Claude Code, Cursor, VS Code Copilot, OpenCode, Gemini CLI (e qualquer ferramenta compatível com MCP).
Você pode usá-lo para novos projetos, mudanças em andamento ou projetos existentes sem especificações.
Instale, conecte o MCP e comece com uma pequena mudança.

Início Rápido em 60 Segundos

Instale o Hoofy: brew install HendryAvila/hoofy/hoofy (ou use o script de instalação abaixo).
Conecte o MCP: claude mcp add --scope user hoofy hoofy serve (ou use a configuração MCP do seu editor).
Peça à sua IA para implementar uma mudança — o Hoofy orienta o planejamento + memória automaticamente.

O que é o Hoofy? — Companheiro de Desenvolvimento de IA para MCP

O Hoofy resolve três problemas recorrentes de desenvolvimento com IA: perda de memória entre sessões, implementações alucinadas e fluxos de trabalho não estruturados. É um único servidor MCP (Model Context Protocol) escrito em Go — um binário, zero dependências externas de runtime.

Escolha seu caminho

Novo projeto → execute o pipeline completo do projeto (sdd_init_project →... → sdd_validate)
Projeto existente, adicionando/corrigindo algo → comece com sdd_change
Projeto existente sem especificações ainda → sdd_reverse_engineer + sdd_bootstrap
Só precisa de contexto/revisão rapidamente → sdd_suggest_context, sdd_review, sdd_audit

Sistemas principais (de relance)

Sistema	O que faz	Ferramentas
Memória	Contexto persistente entre sessões usando SQLite + busca em texto completo FTS5.	`mem_*` ferramentas
Pipeline de Mudanças	Fluxo adaptativo para trabalho em andamento baseado no tipo × tamanho da mudança (12 variantes).	`sdd_change*`, `sdd_adr`
Pipeline de Projeto	Fluxo completo de especificação para projetos novos com Clarity Gate (9 etapas).	`sdd_*` ferramentas de projeto
Bootstrap	Engenharia reversa de bases de código existentes em requisitos, regras e artefatos de design.	`sdd_reverse_engineer`, `sdd_bootstrap`

Principais recursos (mais importantes)

Pipeline de princípios primeiro — defina os inegociáveis antes dos requisitos.
Clarity Gate — bloqueia especificações vagas antes do início da implementação.
Verificação de contexto em cada mudança — detecta conflitos cedo.
Revisão/auditoria ciente de especificações — compare o código com requisitos e regras.
Memória persistente + grafo de conhecimento — decisões e correções permanecem pesquisáveis.
Instruções quentes/frias — instruções principais leves + guias sob demanda. Veja os detalhes completos dos recursos
Project Charter — A antiga etapa de "proposta" agora é um charter com contexto de domínio, partes interessadas, visão, limites, critérios de sucesso, sistemas existentes e restrições.
Auditoria Spec-vs-Code — sdd_audit compara especificações com o código-fonte para detectar implementações ausentes e desvios.
Instruções de Agente Geradas Automaticamente — sdd_init_project injeta instruções SDD em CLAUDE.md/AGENTS.md (idempotente).
Armazenamento ADR Unificado — ADRs são sempre gravados em docs/adrs/NNN-slug.md.
Revisão de Código Ciente de Especificações — sdd_review gera uma lista de verificação vinculada a FR/NFR/regras de negócio/ADRs.
Sugestão de Contexto Ad-Hoc — sdd_suggest_context recomenda o que ler antes da implementação.
Bootstrap de Projeto Existente — sdd_reverse_engineer + sdd_bootstrap criam artefatos ausentes para bases de código legadas.
Grafo de Conhecimento — relacione observações com arestas tipadas (depends_on, caused_by, implements, etc.).
Ferramentas Facade-First — pontos de entrada unificados de memória: mem_save e mem_session.
Etapa de Regras de Negócio — extração BRG + DDD antes do Clarity Gate.
Exploração Pré-pipeline — sdd_explore captura objetivos/restrições/incógnitas antes do trabalho formal do pipeline.
Atribuições em Ondas — ondas de dependência de tarefas para planejamento de execução 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 que Hoofy?

Assistentes de codificação com IA são poderosos, mas esquecidos e excessivamente confiantes. Estudos mostram que desenvolvedores experientes são 19% mais lentos com IA não estruturada (METR 2025), e a adoção de IA sem estrutura causa 7,2% de instabilidade na entrega (DORA 2025). O Hoofy resolve isso fazendo sua IA lembrar do contexto, seguir especificações e validar o entendimento antes de codificar.

Como funciona o fluxo

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

Guia completo de fluxo de trabalho com exemplos passo a passo · Referência completa de ferramentas

Início Rápido

1. Instale o binário

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 / Source

# 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. Conecte à sua ferramenta de IA

Servidor MCP vs Plugin — qual é a diferença?

O servidor MCP é o próprio Hoofy — o binário que você acabou de instalar. Ele fornece memória, pipeline de mudanças, pipeline de projeto, bootstrap e ferramentas independentes através do MCP e funciona com qualquer ferramenta de IA compatível com MCP.

O Plugin é um aprimoramento exclusivo do Claude Code que adiciona capacidades adicionais sobre o servidor MCP:

Componente O que faz
Agente Uma personalidade personalizada (Hoofy, o arquiteto-cavalo) que ensina através de conceitos, não despejos de código. Impõe disciplina SDD — a IA não pulará especificações.
Habilidades Conjuntos de instruções carregáveis para domínios específicos (React 19, Next.js 15, TypeScript, Tailwind 4, Django DRF, Playwright, etc.). O agente detecta automaticamente o contexto e carrega a habilidade certa antes de escrever código.
Hooks Automação de ciclo de vida — hooks PreToolCall e PostToolCall que acionam operações de memória automaticamente (por exemplo, salvar contexto da sessão, capturar descobertas após o uso de ferramentas).

O plugin é opcional — você obtém toda a funcionalidade do Hoofy apenas com o servidor MCP. O plugin apenas torna a experiência mais suave no Claude Code.

Componente	O que faz
Agente	Uma personalidade personalizada (Hoofy, o arquiteto-cavalo) que ensina através de conceitos, não despejos de código. Impõe disciplina SDD — a IA não pulará especificações.
Habilidades	Conjuntos de instruções carregáveis para domínios específicos (React 19, Next.js 15, TypeScript, Tailwind 4, Django DRF, Playwright, etc.). O agente detecta automaticamente o contexto e carrega a habilidade certa antes de escrever código.
Hooks	Automação de ciclo de vida — hooks `PreToolCall` e `PostToolCall` que acionam operações de memória automaticamente (por exemplo, salvar contexto da sessão, capturar descobertas após o uso de ferramentas).

Claude Code

Servidor MCP — um comando, pronto:

claude mcp add --scope user hoofy hoofy serve

Plugin (opcional, apenas Claude Code) — adiciona agente + habilidades + hooks sobre o servidor MCP:

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

Cursor

Adicione à sua configuração MCP:

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

VS Code Copilot

Adicione a .vscode/mcp.json:

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

OpenCode

Adicione a ~/.config/opencode/opencode.json dentro da chave "mcp":

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

Gemini CLI

Adicione à sua configuração MCP:

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

3. Use-o

Apenas converse com sua IA. As instruções integradas do Hoofy dizem à IA quando e como usar cada sistema.

4. Atualize

hoofy update

Verifica automaticamente na inicialização, atualiza quando você disser.

O Hoofy já inclui instruções integradas do servidor, mas um pequeno bloco de política no seu arquivo de instruções do agente reforça o fluxo de trabalho.

Nota: sdd_init_project gera isso automaticamente nos arquivos do agente. Adicione manualmente apenas se você executar o Hoofy no modo somente MCP.

Coloque isso no seu arquivo de instruções específico da ferramenta:

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\`

Melhores Práticas

1. Especificações antes do código — sempre

A IA tentará pular direto para a codificação. Não deixe. Para qualquer trabalho não trivial:

Novo projeto? → sdd_init_project e percorra o pipeline completo de 9 etapas
Nova funcionalidade? → sdd_change(type: "feature", size: "medium") no mínimo
Correção de bug? → Até sdd_change(type: "fix", size: "small") dá a você verificação de contexto → descrever → tarefas → verificar

As etapas mais baratas (verificação de contexto + descrever + tarefas + verificar) levam menos de 2 minutos e economizam horas de depuração de código alucinado.

2. Explore antes de planejar

Antes de entrar em um pipeline, use sdd_explore para capturar o contexto da sua discussão — objetivos, restrições, preferências técnicas, incógnitas, decisões. Ele salva contexto estruturado na memória para que o pipeline comece com clareza, não com suposições. Chame-o várias vezes conforme seu pensamento evolui — ele faz upsert, nunca duplica.

3. Bootstrap de projetos existentes

Trabalhando em um projeto que nunca passou por SDD? Não pule as especificações — faça bootstrap delas. Execute sdd_reverse_engineer para escanear a base de código, depois sdd_bootstrap para gerar os artefatos ausentes. Isso leva menos de um minuto e significa que o pipeline de mudanças funciona com contexto completo em vez de voar às cegas. Mudanças médias/grandes são bloqueadas sem especificações — e isso é intencional.

4. Dimensione corretamente suas mudanças

Não use um pipeline grande para uma correção de uma linha. Não use um pipeline pequeno para um novo sistema de autenticação.

Se a mudança...	Provavelmente é...
Toca 1-2 arquivos, correção clara	pequena (4 etapas — verificação de contexto + descrever + tarefas + verificar)
Precisa de requisitos ou pensamento de design	média (5 etapas)
Afeta arquitetura, múltiplos sistemas	grande (6-7 etapas)

5. Deixe a memória trabalhar para você

Você não precisa dizer à IA para usar memória — as instruções integradas do Hoofy cuidam disso. Mas você obterá melhores resultados se:

Comece as sessões cumprimentando a IA — isso aciona mem_context para carregar o histórico recente
Mencione decisões passadas — "lembra quando escolhemos SQLite?" aciona mem_search
Confirme os resumos da sessão — a IA os escreve no final da sessão, revise-os para precisão

6. Conecte conhecimento com relações

O grafo de conhecimento do Hoofy permite conectar observações relacionadas com arestas tipadas e direcionais — transformando memórias planas em uma web navegável. A IA cria relações automaticamente quando reconhece conexões. Você também pode pedir para relacionar observações manualmente. Use mem_get(id=..., depth=...) para explorar o grafo completo em torno de qualquer observação.

7. Use chaves de tópico para conhecimento em evolução

Quando uma decisão pode mudar (esquema de banco de dados, design de API, arquitetura), use topic_key em mem_save. Isso atualiza a observação existente em vez de criar duplicatas. Uma observação por tópico, sempre atual.

8. Uma mudança de cada vez

O Hoofy impõe uma mudança ativa por vez. Isso não é uma limitação — é um recurso. O aumento de escopo acontece quando você tenta fazer três coisas ao mesmo tempo. Termine uma mudança, verifique-a e depois comece a próxima.

9. Confie no Clarity Gate

Quando o Clarity Gate fizer perguntas, não passe por elas apressadamente. Cada pergunta que ele faz representa uma ambiguidade que teria se tornado um bug, uma alucinação ou um momento de "não era isso que eu queria". Dois minutos respondendo perguntas economizam duas horas depurando implementações erradas.

10. O Hoofy é o arquiteto, o modo Plano é o empreiteiro

Se sua ferramenta de IA tem um modo de plano/implementação, use-o depois que as especificações do Hoofy estiverem prontas. O Hoofy responde QUEM e O QUÊ. O modo Plano responde COMO.

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

A Pesquisa por Trás do SDD

O pipeline de especificações do Hoofy não é construído em opiniões. É construído em pesquisa. Cada recurso mapeia para uma recomendação específica da Anthropic Engineering ou pesquisa da indústria — veja o documento completo de fundamentos de pesquisa para o mapeamento completo.

Anthropic Engineering:

Construindo Agentes Eficazes — design de ACI, padrões de ferramentas, arquitetura orquestrador-trabalhador
Engenharia de Contexto Eficaz — memória persistente, divulgação progressiva, contexto como recurso finito
Escrevendo Ferramentas Eficazes — namespacing de ferramentas, design de resposta, eficiência de tokens
Sistema de Pesquisa Multiagente — resumos de sessão, saída de sistema de arquivos, consciência de orçamento de tokens
Estruturas para Agentes de Longa Duração — rastreamento de progresso, entrega incremental, JSON sobre Markdown para estado
Melhores Práticas do Claude Code — varredura de CLAUDE.md, fluxos de trabalho estruturados

Pesquisa da Indústria:

METR 2025: Desenvolvedores experientes foram 19% mais lentos com IA apesar de se sentirem 20% mais rápidos — o uso não estruturado de IA introduz sobrecarga de depuração e falsa confiança.
DORA 2025: aumento de 7,2% na instabilidade de entrega para cada 25% de adoção de IA — sem sistemas e práticas fundamentais.
McKinsey 2025: Os melhores desempenhos veem ganhos de produtividade de 16-30% apenas com especificação e comunicação estruturadas.
IEEE 720574: Corrigir um erro de requisito em produção custa 10-100x mais do que corrigi-lo durante os requisitos — pior com código gerado por IA.
Codified Context (Lulla 2026): infraestrutura AGENTS.md associada a 29% menos tempo de execução e 17% menos consumo de tokens. Constituições compactas (~660 linhas) com recuperação sob demanda superam instruções monolíticas. A arquitetura de instruções quentes/frias do Hoofy implementa esse padrão.
IREB & IEEE 29148: Elicitação estruturada, rastreabilidade, detecção de ambiguidade — o Clarity Gate do Hoofy implementa esses frameworks.
Business Rules Group: O Manifesto de Regras de Negócio — regras como cidadãos de primeira classe. Hoofy usa a taxonomia BRG.
EARS: Modelos de frases baseados em pesquisa que eliminam a ambiguidade de requisitos.
DDD Ubiquitous Language: Linguagem compartilhada elimina erros de tradução — glossário de regras de negócio do Hoofy.
Harness Engineering (OpenAI 2026): O embrulho estruturado de IA melhora a qualidade da saída ao restringir o contexto, impor fluxos de trabalho e tornar o estado explícito. O redesenho de identidade do Hoofy v1.0 foi diretamente inspirado pela filosofia deste artigo de "o usuário traz conteúdo, a IA complementa/organiza/valida."

Estrutura vence velocidade.

Contribuindo

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 contribuição

Mais dimensões de clareza (mobile, API, pipeline de dados)
Mais tipos de mudança além de correção/recurso/refatoração/melhoria
Melhorias e personalização de modelos
Transporte HTTP transmitível para implantação remota
Exportação para Jira, Linear, GitHub Issues
i18n para especificações não-inglesas

Agradecimentos

O sistema de memória do Hoofy é inspirado no Engram do Gentleman Programming — o servidor MCP de memória persistente original que provou que assistentes de IA precisam de contexto de longo prazo para serem verdadeiramente úteis. Engram lançou a base; Hoofy construiu em cima dela.

Licença

MIT

Pare de dar prompts. Comece a especificar.
Construído com cuidado pela comunidade Hoofy.