solution-architecture-mcp-toolkit

Este repositório nasceu de uma pergunta que ouço há anos em revisão de arquitetura: "o agente já escreveu, por que eu ainda preciso decidir?" A resposta é que um agente escreve rápido, mas não assina. Quem responde pela decisão em auditoria, no incidente ou na renovação de contrato é uma pessoa — e essa pessoa precisa de um registro que diga o que foi decidido, em qual contexto e com quais alternativas descartadas.

O toolkit encoda essa disciplina em ferramentas reutilizáveis: Architecture Decision Records, checklists do AWS Well-Architected, prompts e templates de threat modeling, fluxos de revisão de custo e risco, e um desenho de ferramentas compatível com MCP (Model Context Protocol) para assistentes de arquitetura. A ideia não é substituir o trabalho do arquiteto por chat genérico — é dar ao agente uma interface estreita e previsível, onde cada saída já nasce no formato que a governança exige.

O que está no repositório: um pacote Python instalável que expõe o comando sa-toolkit, uma suíte de testes em pytest, um frontend estático em HTML/CSS/JavaScript publicado na Vercel em mcp-toolkit.moretes.com, documentação em docs/architecture.md e um OPERATIONS.md com GitFlow, segredos da Vercel e o pipeline de segurança. O código de aplicação é Python; HTML aparece como linguagem principal porque o frontend pesa mais em bytes, não em lógica.

A CLI é a única porta: sa-toolkit é um entry point Python instalado pelo pip install -e .. Cada subcomando — adr, well-architected — recebe argumentos explícitos e devolve texto pronto para ir ao repositório. Não há estado, não há banco, não há chamada de rede; o que entra pelos flags é tudo que a ferramenta sabe.

Templates são a fonte de verdade: ADR, checklist e threat model vivem como templates no pacote. A CLI preenche campos, não inventa seções. Isso importa por uma razão prática: quando o formato do ADR muda — um campo novo de compliance, por exemplo — muda num lugar só, e todo agente que usa a ferramenta passa a produzir o formato novo sem retreinar nada.

Desenho MCP em cima da mesma lógica: a proposta de ferramenta compatível com MCP expõe as mesmas operações da CLI com contrato de entrada e saída definido. O agente não recebe "escreva um ADR" como instrução livre; recebe uma tool com parâmetros nomeados. A diferença aparece na revisão: saída estruturada é comparável entre projetos, saída de chat não.

Testes guardam o contrato: pytest -q cobre CLI e templates. Sem isso, um template editado com erro de formatação chegaria ao agente e viraria ADR quebrado em silêncio — e ADR quebrado é pior que ADR ausente, porque parece que existe.

Frontend desacoplado: o site em frontend/ é HTML/CSS/JS sem framework, com npm ci, lint e build como único ciclo. Não compartilha código com o pacote Python; é documentação e portfólio, publicado na Vercel pela integração Git.

Depois de anos revisando desenhos de sistemas financeiros, o defeito que mais vi não foi decisão errada — foi decisão sem registro. O sistema entra em produção, o time muda, e dois anos depois ninguém sabe por que a fila é FIFO ou por que o banco é multi-região. O custo dessa amnésia não é o de escrever o ADR que faltou; é o de refazer a análise inteira sob pressão de incidente.

Agentes de IA pioram ou resolvem isso, dependendo de como entram. Entram como chat livre, e o resultado é prosa convincente que ninguém consegue comparar com o projeto anterior. Entram como ferramenta com contrato, e cada saída já traz título, contexto, decisão e consequências no mesmo lugar de sempre.

Traceabilidade: ADR gerado pela CLI vai para o git ao lado do código. O git blame responde quem decidiu e quando.

Revisão de segurança: threat model no template padrão é comparável entre projetos; o revisor sabe onde procurar a mitigação que falta.

Custo como manutenção: o fluxo de revisão de custo pergunta o que a escolha custa por ano de operação — não o que custa no mês do lançamento.

A lição por trás do repositório: ferramenta estreita produz artefato auditável; chat largo produz texto que parece artefato.