mcp-graph v12 deixa de ser folclore: vira método AISE

“É só um task tracker com IA”

Essa foi a crítica que recebi semana passada, num grupo fechado de engenheiros que usam IA pesado no dia a dia. Olharam pro mcp-graph, viram nodes, edges, fases, e devolveram a sentença: “tá, mas isso é só um Jira esperto com hook de LLM”.

Eu entendo a leitura. De longe, qualquer coisa que tenha tasks com estado parece um tracker. O problema é que de longe nada interessante parece interessante. De perto, mcp-graph v12 é outra coisa: é a implementação local-first de duas metodologias canônicas da disciplina que está se formando agora, em 2026, sob o nome de AISE (AI Software Engineering). E isso eu não estou inventando aqui pra defender o projeto. Está na literatura, está no DORA Report 2025, e está, agora, dentro do próprio repositório, depois que decidi parar de chamar mcp-graph de “ferramenta” e começar a chamar do que ele é: uma camada de runtime.

Vamos por partes. Quero que no fim deste post você consiga responder à crítica acima em uma frase, com fonte.

O que é AISE, segundo a literatura de 2026

AISE não é um termo de marketing. É a categoria emergente que descreve a prática de entregar software via agentes de IA combinando dois pilares complementares: Agentic AI (sistemas autônomos com decisão orientada por objetivo) e Generative AI (produção de artefatos: código, texto, design).

O que mudou em 2025-26 foi o registro. Até 2024, AI em engenharia de software era basicamente “AI-assisted coding”: Copilot completando linhas, Cursor sugerindo refactors. Útil, mas marginal. A inflexão veio quando empresas grandes começaram a relatar que o gargalo deixou de ser “o agente escreve código rápido”. O gargalo virou “o sistema que cerca o agente”. É aí que o termo AISE deixa de ser sinônimo de autocomplete e vira disciplina, com metodologias próprias, métricas próprias e gates próprios.

Quem está escrevendo sobre isso em 2026: a Pragmatic Engineer numa série de previsões para o ano, o relatório 2026 Agentic Coding Trends Report da Anthropic, o time de pesquisa da Thoughtworks (Birgitta Böckeler tem material denso sobre spec-driven development), e o já mencionado DORA Report 2025, que é o instrumento mais quantitativo da turma. Tem também revisão peer-reviewed na MDPI puxando o termo “AI-Driven Innovations in Software Engineering”. A ideia está madura o bastante pra ter literatura, ainda fresca o bastante pra que pouca gente esteja consciente dela.

Dentro dessa categoria emergente, duas metodologias estão se cristalizando como pilares operacionais. São essas que importam aqui.

As duas metodologias canônicas da AISE

A primeira é Specification-Driven Development (SDD).

Escrever especificações precisas e machine-readable antes do código. Raízes em métodos formais, BDD, API design. A spec é o artefato canônico, o código é uma tradução verificável dela.

Não é nada novo conceitualmente. O que é novo é o motivo pelo qual SDD voltou a importar. Quando você tem um agente de IA escrevendo código a 200 linhas por minuto, a clareza da especificação deixa de ser higiene e vira o gargalo absoluto. Sem spec, o agente chuta. Com spec frouxa, o agente acerta o frouxo. Com spec executável, o agente tem o que reproduzir e o que validar.

A segunda é Context-Driven Engineering (CDE), às vezes também chamada de “context engineering” tout court.

Fornecer ao agente o contexto completo em que ele vai operar (intenção, constraints, decisões anteriores, código relevante) em vez de prompts soltos. Reduz a fração não-determinística do output.

CDE é o que separa “eu copiei e colei meu PRD no Claude” de “o agente abre uma sessão e já sabe quem é, o que está fazendo, qual é o limite, e onde está parado”. O nome cobre tanto o que vai pro prompt quanto o que persiste entre sessões.

Esses dois pilares aparecem juntos em quase toda literatura séria sobre AISE de 2026. SDD responde “o que construir, com que precisão”. CDE responde “em que substrato o agente opera”. Quem trata os dois em isolamento cai no antipadrão clássico: spec sem contexto vira papel, contexto sem spec vira ruído organizado.

O insight do DORA 2025 que muda o jogo

O DORA Report 2025 (resumido em detalhe pela InfoQ e dezenas de blogs de engenharia em março de 2026) trouxe a frase que mudou minha forma de explicar o mcp-graph para gente cética:

AI amplifica a qualidade do sistema de engenharia onde opera. Organizações com DevOps maduro, workflows bem definidos e capacidades de plataforma convertem ganhos de produtividade do AI em melhorias mensuráveis de entrega.

Tradução prática: 75% dos engenheiros usam IA, segundo o próprio relatório. Mas a maioria das organizações não viu nenhuma melhora mensurável de delivery. Por quê? Porque IA sozinha é um amplificador. Se o sistema é caótico, IA amplifica caos. O agente fica mais rápido, mas o cycle time não cai, porque retrabalho aumenta na mesma proporção.

A leitura inversa é o que interessa: organizações que têm capacidade de plataforma madura, com workflows bem definidos, são as que conseguem converter o ganho de produtividade do agente em ganho de entrega. A IA empilha em cima de uma estrutura que já funciona. Sem essa estrutura, a empilhada não acontece.

O mcp-graph é literalmente uma proposta de “capacidade de plataforma” para times pequenos e indivíduos. É a parte do sistema que o DORA diz ser pré-requisito.

v12: o que mudou

Antes de descer pra prova, um update factual. A versão 12.0.0 saiu em 26 de abril de 2026. Em relação à v11, o que mudou:

Bin único mcp-graph substitui a fragmentação de @mcp-graph-workflow/cli e binários de v11.
24 subcomandos consolidados (8 servidor, 16 lifecycle/ops).
CLI workspace foi dobrado dentro do bundle único dist/v11-cli.mjs no build.
Compatibilidade cross-platform (Windows, macOS, Linux) estabilizada.
Documentação completa em PT-BR.
PHASE_GATES formalizados como tabela canônica.

Não é uma releases revolucionária na superfície. O importante é que o v12 fechou as arestas que ainda deixavam o projeto parecer “experimentação acadêmica”. Hoje é um binário, com docs unificadas, com gates explícitos. É a versão em que dá pra parar de chamar de folclore.

SDD em mcp-graph: PRD vira grafo executável

Aqui começa a prova. SDD diz “spec antes do código, machine-readable”. Vou mostrar onde isso vive no repo.

O ponto de entrada é src/core/importer/prd-to-graph.ts. É um parser que pega um arquivo de PRD em Markdown, DOCX ou PDF, e cospe nodes tipados num grafo SQLite. Os tipos de node são fixos: epic, task, subtask, requirement, constraint, milestone e acceptance_criteria. Não tem free-form. AC é um tipo de node de primeira classe, não um campo solto dentro de uma task.

Roda assim:

$ mcp-graph import docs/PRD-checkout.md
✓ Parsed PRD (4.2KB, 14 sections)
✓ Created 1 epic (E-001: "Checkout flow rewrite")
✓ Created 7 tasks under E-001
✓ Created 23 subtasks
✓ Extracted 11 acceptance_criteria nodes
✓ Linked 4 constraints (LGPD, latency<200ms, idempotency, audit)
✓ Graph persisted at workflow-graph/graph.db

A diferença em relação a “colar PRD no chat” é que cada um desses nodes vira um endereço estável. A AC #7 daqui a três semanas ainda é a AC #7. Você consegue rastrear que código nasceu de qual AC. Isso é spec-driven na sua forma operacional mais simples.

A segunda peça é o enforcement. Em docs/reference/LIFECYCLE.md, a tabela PHASE_GATES define que para sair da fase IMPLEMENT e entrar em VALIDATE, o grafo precisa ter no mínimo 50% das tasks com AC testável. Não é convenção: é gate. O hook de pre-tool-use bloqueia transição inválida antes do agente sequer tentar.

A terceira peça é TDD. Em src/core/pipeline/start-task.ts, a chamada start_task checa pré-requisitos de teste antes de liberar implementação. Sem teste declarado, sem código. O teste vira a forma executável da spec. É BDD reencarnado num runtime que o agente é forçado a respeitar.

Isso é SDD aplicado, não SDD descrito num post de Medium.

CDE em mcp-graph: contexto que sobrevive a sessão

Agora o segundo pilar.

CDE diz: dê ao agente o ambiente informacional completo, não só o prompt. Mcp-graph implementa isso em três camadas:

Persistência de grafo. O SQLite em workflow-graph/graph.db sobrevive ao reload. Se você fecha o terminal hoje e abre amanhã, o agente sabe em que task estava, qual subtask falhou, qual decisão foi tomada. Não há reconstrução por prompt, porque o estado não foi perdido. Faz diferença concreta: o post-mortem mais comum de agentes em produção é “esqueceu o que estava fazendo na próxima sessão”.

RAG sobre o repositório. Em src/core/rag/ vivem 50+ indexers especializados: code-context, entity, decision, journey, knowledge linker, adaptive router, semantic cache. Não é um RAG genérico de embeddings de texto. É um RAG que sabe que código tem AST, que decisões têm rationale, que jornadas têm passos. Constraint discovery deixa de depender do agente “lembrar” que existe uma constraint num doc. Ele recupera ativamente.

Sibling context assembly. Documentado em ADR-0047. Quando o agente vai mexer numa subtask, o runtime monta um contexto contendo as subtasks-irmãs já completadas, em ordem topológica, truncadas a um budget de tokens (default 4000, configurável até 8000). Mesma tripla (epicId, subtaskId, tokenBudget) produz, sempre, o mesmo markdown. Reproduzível. Isso é o oposto do prompt-soup tradicional, em que o que vai pro contexto depende do humor do humano.

Junto, isso é Context-Driven Engineering operacional. Não é chat com memória esperta. É um substrato de informação que o agente consulta com regras.

O loop de 9 fases como spec executável

Falei em fases várias vezes. Vale explicitar o loop:

ANALYZE → DESIGN → PLAN → IMPLEMENT → VALIDATE → REVIEW → HANDOFF → DEPLOY → LISTENING

Cada transição tem um gate. Listo as mais relevantes (docs/reference/LIFECYCLE.md):

Transição	Gate (resumo)
`ANALYZE → DESIGN`	≥1 epic mapeado
`DESIGN → PLAN`	análise design-ready + ADR challenge passado
`PLAN → IMPLEMENT`	≥1 task com sprint atribuído
`IMPLEMENT → VALIDATE`	≥50% tasks done com AC testável
`VALIDATE → REVIEW`	suíte de testes verde + cobertura mínima
`REVIEW → HANDOFF`	revisão registrada com decisão

Três camadas de enforcement empilhadas garantem que o gate não é decoração:

Hook out-of-process (pre-tool-use): bloqueia ação inválida antes do MCP ser chamado.
MCP server (in-process): valida deprecation, executa handler, contabiliza tokens.
Tabela PHASE_GATES em lifecycle-phase.ts: fonte da verdade para transições.

Se você quer ver SDD num formato concreto, este loop é. A spec não é um doc parado: é um automato que recusa estados ilegais.

Prova empírica: o benchmark v11 que sustenta v12

A parte mais difícil de defender em conversas técnicas não é “isso existe”, é “isso compensa”. Aqui entra o benchmark documentado em docs/_internal/BENCHMARK-v11.md, replicado de forma independente via OpenRouter (run id db6e57871911) sob o codinome H12-faithful.

Arm	Modelo + estrutura	Pass rate	Custo USD	Wall time
A (Haiku mono baseline)	Haiku, sem grafo	60%	$0,0110	10.668 ms
B-v2 (Haiku + decomp)	Haiku com grafo + sibling context	100% parse	$0,0257	medido
C (Sonnet baseline)	Sonnet, sem grafo	80%	$0,0327	medido

Três coisas pra notar:

Primeira: Haiku sozinho tem pass rate 60%. Haiku com a estrutura do mcp-graph atinge 100% no parse gate. A estrutura compensou o modelo menor. Não foi marginal: foi 40 pontos percentuais.

Segunda: custo. O Arm B-v2 (Haiku + estrutura) custa $0,0257 por execução. O Arm C (Sonnet sozinho) custa $0,0327. A estrutura é 79% do custo do Sonnet com pass rate de parse equivalente ou superior. Você paga menos pelo modelo maior, e o que enche o gap é spec + contexto.

Terceira: o H12-faithful, rodado num provider diferente (OpenRouter) com o mesmo protocolo, replicou o resultado independente. Isso mata a hipótese mais óbvia (“ah, o resultado é só um bug da implementação do Diego”). O protocolo reproduz, então é o protocolo que está fazendo o trabalho.

Adiciono o lastro: o repositório tem 1.413 testes .test.ts validando comportamentos de cada camada, e 6 .bench.ts mantendo a régua de performance. Não é vibe.

Reposicionamento: a taxonomia AISE de mcp-graph

Junto tudo num quadrante. Cada lado do retângulo é uma das transformações que mcp-graph faz acontecer:

PRD → Spec (SDD). mcp-graph import transforma documento humano em grafo de specs executáveis com AC.
Spec → Context (CDE). Grafo + RAG + memory dão ao agente o contexto completo, reproduzível, dentro de orçamento de tokens.
Context → Code (Agentic). O agente navega o grafo, mas só pode sair de IMPLEMENT depois de TDD verde.
Code → Audit (DORA). Cada linha de código nasceu de uma AC, que nasceu de um requirement, que nasceu de um epic. Rastreabilidade ponta a ponta vira métrica de delivery natural.

Aqui mora a frase que agora está dentro do README e do glossário do projeto, e que sustenta o reposicionamento:

mcp-graph é a camada de runtime da AISE, onde Specification-Driven Development encontra Context-Driven Engineering, num substrato local-first.

Isso é defensável academicamente sem perder a voz direta. Nomeia exatamente o que o projeto é, em termos que a literatura de 2026 já usa. Deixa de competir com “task tracker” e passa a ocupar uma vaga na disciplina nova.

Vacina contra o crítico (“isso é só task tracker”)

Volto à crítica do começo. Quando alguém disser “mas isso é só um Jira com IA”, a resposta certificada é:

Não. É a implementação local-first das duas metodologias canônicas da AISE: Specification-Driven Development e Context-Driven Engineering. O grafo é a spec. O contexto é o substrato. O TDD é o gate. A memória é a continuidade. Sem essas quatro propriedades juntas, o agente não faz engenharia, faz vibe-coding caro.

E se a pessoa insistir, quatro tijolos a mais:

O package.json declara v12.0.0 com mcp-graph como bin único. Não é protótipo.
O repositório está sob CITATION.cff, ORCID 0009-0002-1117-9571, vinculado a pesquisa de mestrado em andamento na UNOPAR. Folclore não é citado em CFF.
O benchmark foi replicado independentemente via OpenRouter (H12-faithful). Folclore não passa em replicação.
A licença é AGPL v3, com trilha de licenciamento comercial separada documentada em COMMERCIAL.md. Folclore não tem dual licensing nem cláusula de copyleft de rede.

A quatro tijolos a gente para de chamar de folclore.

Para onde isso vai

A pergunta que importa em 2026 deixou de ser “qual modelo eu uso?”. Modelos vão e vêm, ficam mais baratos a cada trimestre, ganham 10 pontos percentuais e perdem outros 10 em domínio diferente. Modelo é commodity.

A pergunta que importa virou: qual é a sua camada de runtime AISE?

Quem está rodando agente em produção sem spec executável e sem contexto reproduzível está pagando o preço de não ter resposta pra essa pergunta, ainda que não saiba. O DORA Report 2025 já mostrou os números agregados: produtividade do agente sobe, entrega não. A diferença é exatamente o pedaço que SDD + CDE preenchem.

Convocação concreta. Abre o repositório do mcp-graph, pega um PRD seu (de verdade, não exemplo), e roda mcp-graph import nele. Olha o grafo nascer. Olha o GLOSSARY.md que agora tem entradas dedicadas a SDD e CDE como sub-pilares de AISE. Olha o README que agora declara qual é a “capacidade de plataforma” que ele propõe ser. E decide se você quer continuar empurrando agente sem substrato, ou se quer começar a tratar engenharia de software com IA como engenharia.

A diferença, no fim, não está no modelo. Está no labirinto que você constrói pro agente correr. Engenharia, diferente de modelos, está 100% sob o seu controle.