Se você trabalha com agentes de IA para desenvolvimento — Claude Code, Cursor, Windsurf, Kimi — provavelmente já viveu essa cena.

Você está no meio de um projeto. O agente está entendendo a arquitetura, seguindo os padrões, tomando boas decisões. Aí algo interrompe a sessão. Você fecha a janela, acaba o crédito, troca de modelo, ou simplesmente retoma o projeto no dia seguinte.

Nova sessão. Contexto zero.

O agente não sabe o que estava sendo construído. Começa a sugerir padrões que você já descartou. Faz perguntas que você respondeu duas sessões atrás. Ignora decisões arquiteturais que levaram horas para definir. Você gasta 20 minutos re-explicando o projeto antes de conseguir trabalhar de novo.

Quem usa agentes de IA com frequência sabe que isso não é exceção — é rotina.

O problema real: agentes de IA são stateless por natureza

Diferente de um colega de equipe que lembra do que vocês discutiram ontem, agentes de IA não têm memória persistente entre sessões. Cada janela nova é uma tela em branco.

Isso não é um bug — é uma característica do modelo. Mas sem estrutura para compensar isso, o resultado prático é que você perde ritmo, retrabalha contexto constantemente e nunca consegue o melhor do agente porque ele nunca está totalmente orientado.

Algumas pessoas tentam resolver isso com prompts enormes no início de cada sessão. Funciona, mas é manual, cansativo e fácil de esquecer alguma coisa importante. Outros simplesmente aceitam o retrabalho como parte do processo.

O Squidy resolve isso de forma sistemática.

O que é o Squidy

Squidy é um CLI open source em Python que gera uma estrutura completa de governança para projetos desenvolvidos com agentes de IA.

A ideia central é simples: em vez de depender de prompts ad hoc no começo de cada sessão, você dá ao agente um conjunto de documentos persistentes — um "ritual" — que ele lê no boot e que mantém o contexto completo do projeto entre todas as sessões.

Você executa um comando, responde algumas perguntas sobre o projeto em linguagem natural, e o Squidy gera tudo automaticamente.

pipx install squidy
squidy init

Um agente de IA conduz uma entrevista sobre o seu projeto:

🤖 Agent: Hi! Tell me about the project you want to configure.
   You: It's an SEO analytics web app built with Supabase on the 
        backend and Next.js on the frontend, integrating with the 
        DataForSEO API.

🤖 Agent: What primary problem does this app solve for its users?
   You: It helps users stop juggling spreadsheets and external tools 
        by centralizing DataForSEO data in one place.

🤖 Agent: Are there specific architectural patterns you've implemented?
   You: Modular structure, all external API calls server-side, RLS 
        in Supabase for data isolation, organized by feature.

✓ Sufficient context collected
✅ Setup completed!

Cinco perguntas. Dez arquivos gerados. Agente pronto para trabalhar.

O que o Squidy gera

A estrutura criada cobre todos os aspectos que um agente precisa para manter contexto e trabalhar com consistência:

meu-projeto/
├─ readme-agent.md        # Instruções de boot — o agente lê isso primeiro
├─ .squidy/
│  └─ AGENT.md            # Carregado automaticamente pelo Claude, Cursor e outros
├─ doc/
│  ├─ constituicao.md     # Princípios, proibições e Definition of Done
│  ├─ oraculo.md          # Registros de Decisões Arquiteturais (ADRs)
│  ├─ kanban.md           # Board de tarefas com IDs sequenciais e critérios de aceite
│  ├─ emergencia.md       # Registro de bloqueios críticos
│  ├─ contexto-sessao.md  # Estado atual: feito, pendente, próximos passos
│  ├─ politicas.md        # Convenções de código, nomenclatura e estilo
│  └─ indice-diario.md    # Índice consolidado de todas as entradas do diário
└─ diario/
   └─ 2026-02.md          # Log diário: o que foi feito, por que, e qual resultado

Cada arquivo tem um papel específico no ciclo de desenvolvimento:

constituicao.md define o que o agente deve e nunca deve fazer. É o documento mais importante — sem ele, o agente tem liberdade demais e começa a tomar decisões que você não autorizou.

oraculo.md registra decisões arquiteturais com contexto completo: qual era o problema, qual decisão foi tomada, por que, e quais são as consequências. Isso é o que impede o agente de "sugerir de volta" uma alternativa que você já avaliou e descartou.

kanban.md é o board de tarefas com IDs sequenciais e critérios de aceite. O agente sabe exatamente o que está em andamento, o que está pendente e o que já foi entregue.

contexto-sessao.md é atualizado ao final de cada sessão com o estado atual do projeto. Na sessão seguinte, o agente lê esse arquivo primeiro e retoma exatamente de onde parou — sem perguntas, sem re-explicações.

diario/ é o log de desenvolvimento. Cada sessão gera uma entrada com o que foi feito, por que foi feito dessa forma, e qual foi o resultado. Isso cria rastreabilidade real: se algo quebra semanas depois, você consegue reconstruir o raciocínio que levou àquela decisão.

Por que isso funciona melhor do que prompts ad hoc

Existe uma diferença importante entre engenharia de prompt e engenharia de contexto.

Engenharia de prompt é sobre construir a mensagem certa para uma interação específica. Engenharia de contexto é sobre construir a estrutura persistente que torna cada interação informada, consistente e rastreável.

Prompt é uma conversa. Contexto é um sistema.

Os documentos gerados pelo Squidy não são prompts — são a memória viva do projeto. Eles crescem junto com o desenvolvimento. O oraculo.md acumula ADRs conforme decisões arquiteturais são tomadas. O diario/ constrói um histórico de cada sessão. O contexto-sessao.md é atualizado continuamente para que a próxima sessão comece do ponto certo.

O agente não está apenas seguindo instruções. Ele está operando dentro de uma realidade completa do projeto.

Os resultados práticos

Quem adota esse fluxo de trabalho reporta resultados consistentes:

Zero perda de contexto entre sessões. O agente retoma em segundos, já sabendo o estado completo do projeto.

Muito menos alucinação fora do escopo. Quando o agente tem uma constituição definindo o que pode e não pode fazer, e um oráculo explicando por que decisões foram tomadas, ele para de inventar alternativas.

Menor consumo de tokens. Sem gastar os primeiros 10% de cada sessão re-explicando o projeto.

Rastreabilidade total. Cada decisão tem registro. Cada sessão tem entrada no diário. O projeto tem histórico real.

Entregas melhores. O agente trabalha com ritmo, segue o kanban, respeita as políticas e não deriva do objetivo principal.

A filosofia por trás do projeto

As melhores equipes de software não dependem de indivíduos lembrando de tudo. Elas constroem sistemas — documentação, ADRs, retrospectivas, boards — que tornam o conhecimento coletivo explícito e persistente.

Agentes de IA são poderosos, mas são stateless. Sem estrutura para compensar isso, cada sessão começa do zero. O Squidy aplica a mesma disciplina que faz boas equipes de software funcionarem ao fluxo de desenvolvimento assistido por IA.

O segredo da qualidade está em executar um processo bem estruturado — mesmo aquelas etapas que parecem desnecessárias. Isso vale tanto para times humanos quanto para agentes de IA.

Como começar

# Instalar
pipx install squidy

# Inicializar o projeto
squidy init

# Orientar o agente
"Acesse readme-agent.md e siga o ritual"

Requer Python 3.9+ e uma chave de API da OpenAI ou Anthropic.

Funciona com Claude Code, Cursor, Windsurf, Kimi e qualquer agente de codificação baseado em LLM. Os documentos gerados são Markdown puro — sem dependências de runtime, sem servidor, sem banco de dados. Funciona em qualquer repositório git.

🌐 squidy.run
🐙 github.com/seomarc/squidyrun
📦 pypi.org/project/squidy
📖 docs.squidy.run

É open source, licença MIT. Se você já sofreu com perda de contexto em projetos com agentes de IA, vale muito a pena testar. E se tiver feedback, issue ou PR — o projeto está aberto para contribuições.