Quem trabalha com desenvolvimento assistido por IA já sabe: agentes de IA como Claude Code, Cursor e Windsurf são ferramentas poderosas — mas têm um problema estrutural que compromete a produtividade de qualquer projeto.
Eles não lembram de nada entre sessões.
O Squidy é um framework open source em Python criado para resolver exatamente isso. Neste artigo, você vai entender como ele funciona, por que ele é eficaz e como aplicá-lo no seu fluxo de desenvolvimento.
🧩 O problema que ninguém fala sobre agentes de IA
Toda vez que você abre uma nova sessão com um agente de IA, ele começa do zero. Não importa o quanto você trabalhou na sessão anterior — o contexto, as decisões arquiteturais, as regras do projeto, o que foi feito e o que está pendente: tudo some.
Na prática, isso significa:
- Re-explicar o projeto a cada nova sessão
- O agente sugerindo padrões que você já descartou
- Decisões arquiteturais sendo ignoradas ou contraditas
- Tempo perdido em “aquecimento” antes de conseguir trabalhar de verdade
- Alucinações fora do escopo do projeto
Isso não é um bug — é uma característica fundamental dos modelos de linguagem. LLMs são stateless por natureza. Cada janela de contexto é independente.
O problema não é o agente. É a falta de estrutura para compensar essa limitação.
A solução não é usar prompts maiores. É construir um sistema de contexto persistente que o agente acessa no início de cada sessão. É exatamente isso que o Squidy faz.
🧠 O que é Engenharia de Contexto?
Você provavelmente já conhece engenharia de prompt — a prática de formular instruções claras e bem estruturadas para obter boas respostas de uma IA.
Engenharia de contexto é o próximo nível.
| Engenharia de Prompt | Engenharia de Contexto | |
|---|---|---|
| Foco | A mensagem individual | A estrutura persistente |
| Escopo | Uma interação | Todas as sessões do projeto |
| Resultado | Boa resposta pontual | Consistência ao longo do tempo |
| Analogia | Dar uma instrução | Fazer um onboarding completo |
Enquanto a engenharia de prompt foca em o que você diz, a engenharia de contexto foca em o ambiente em que o agente opera. Não é sobre o prompt de hoje — é sobre o sistema que garante que todos os prompts futuros já comecem com o contexto certo.
O Squidy é, na prática, um framework de engenharia de contexto para projetos de desenvolvimento.
🦑 O que é o Squidy?
O Squidy é um CLI open source em Python que automatiza a criação da estrutura de governança de um projeto de desenvolvimento.
Ao inicializar um novo projeto, o Squidy conduz uma entrevista em linguagem natural sobre o que você está construindo. Com base nas suas respostas, ele gera automaticamente 10 arquivos Markdown — o “ritual” do projeto — que qualquer agente de IA lê no boot da sessão para retomar o trabalho com contexto completo.
Em resumo: o Squidy cria a memória persistente do seu projeto.
- ✅ Open source (MIT)
- ✅ Python 3.9+
- ✅ Funciona com OpenAI e Anthropic
- ✅ Agnóstico de ferramenta — Claude Code, Cursor, Windsurf, Kimi e outros
- ✅ Zero dependências de runtime — Markdown puro, funciona em qualquer repositório git
⚙️ Como o Squidy funciona na prática
O fluxo começa com um único comando:
pipx install squidy
squidy init
A partir daí, um agente de IA conduz uma conversa sobre o seu projeto:
🤖 Agent: Tell me about the project you want to configure.
You: It's an SEO analytics web app built with Supabase and Next.js 14,
integrating with the DataForSEO API.
🤖 Agent: What primary problem does this app solve for its users?
You: It centralizes DataForSEO data in one place — no more juggling
spreadsheets and raw API responses.
🤖 Agent: Are there specific architectural decisions you've already made?
You: Modular structure, all external API calls server-side, RLS in
Supabase for data isolation, organized by feature.
✓ Sufficient context collected
✅ Setup completed! Files generated at: /home/user/meu-projeto
Cinco perguntas. Dez arquivos. Agente pronto para trabalhar.
Depois disso, basta orientar o seu agente:
"Acesse readme-agent.md e siga o ritual"
O agente lê os arquivos, absorve o contexto completo do projeto e começa a trabalhar com total orientação — sem perguntas repetidas, sem sugestões desalinhadas.
📁 Os 10 arquivos do ritual
Cada arquivo tem um papel específico no ciclo de desenvolvimento:
readme-agent.md
Instruções de boot. É o primeiro arquivo que o agente lê antes de qualquer ação. Define como o ritual funciona e qual a sequência de leitura dos demais documentos.
AGENT.md
Carregado automaticamente pelo Claude Code, Cursor e outros agentes que reconhecem esse padrão de arquivo. Contém um resumo executivo do projeto para orientação rápida.
constituicao.md
O documento mais importante do ritual. Define os princípios do projeto, as proibições (o que o agente nunca deve fazer) e o Definition of Done. Sem ele, o agente tem liberdade demais e começa a tomar decisões que você não autorizou.
oraculo.md
Registro de Decisões Arquiteturais (ADRs) com contexto completo: qual era o problema, qual decisão foi tomada, por que, e quais são as consequências. Isso impede que o agente “sugira de volta” alternativas que você já avaliou e descartou.
kanban.md
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 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 e retoma exatamente de onde parou.
politicas.md
Convenções de código, padrões de nomenclatura e guia de estilo do projeto. Garante consistência mesmo quando diferentes agentes ou modelos são usados em momentos distintos.
emergencia.md
Registro de bloqueios críticos que impedem o progresso. Mantém visibilidade sobre impedimentos sem poluir os outros documentos.
diario/
Log de desenvolvimento organizado por mês. Cada sessão gera uma entrada com o que foi feito, por que foi feito dessa forma, e qual foi o resultado. Cria rastreabilidade real — se algo quebrar semanas depois, você consegue reconstruir o raciocínio que levou àquela decisão.
indice-diario.md
Índice consolidado de todas as entradas do diário, com referências cruzadas para navegação rápida.
🔌 Compatibilidade: onde o Squidy funciona
O Squidy gera Markdown puro — sem dependências de runtime, sem servidor, sem banco de dados. Funciona em qualquer repositório git e é compatível com qualquer agente de IA que aceite arquivos de contexto:
| Ferramenta | Integração |
|---|---|
| Claude Code | Lê AGENT.md automaticamente no boot |
| Cursor | Carrega AGENT.md como contexto de projeto |
| Windsurf | Compatível via instruções manuais |
| Kimi Code | Compatível via instruções manuais |
| GitHub Copilot | Compatível via instruções manuais |
| Qualquer LLM | Funciona com qualquer agente que aceite arquivos de contexto |
Dica: Para Claude Code e Cursor, o arquivo
AGENT.mdé carregado automaticamente. Para outros agentes, basta incluir a instrução “Leia o readme-agent.md e siga o ritual” no início da sessão.
📊 Resultados práticos
Quem adota o fluxo de trabalho com Squidy reporta mudanças concretas no dia a dia:
⚡ Sessões que começam em segundos O agente não precisa ser re-orientado. Ele lê o ritual e já sabe exatamente onde o projeto está e o que precisa ser feito.
🎯 Zero alucinação fora do escopo Com uma constituição clara e ADRs documentados, o agente para de inventar alternativas e trabalha dentro dos limites definidos.
💰 Menor consumo de tokens Sem repetir contexto a cada sessão, o uso de tokens cai. Menos custo para quem usa APIs pagas, mais velocidade para todos.
📋 Rastreabilidade total Cada decisão tem um registro no oráculo. Cada sessão tem uma entrada no diário. O projeto tem histórico real — algo que a maioria dos projetos solo simplesmente não tem.
🚀 Entregas melhores O agente trabalha com ritmo. Segue o kanban. Respeita as políticas. Não deriva do objetivo principal.
🚀 Como instalar e usar
Pré-requisitos:
- Python 3.9+
- pipx instalado
- Chave de API da OpenAI ou Anthropic
Instalação:
pipx install squidy
Inicializar um projeto:
cd meu-projeto
squidy init
Orientar o agente:
"Acesse readme-agent.md e siga o ritual"
A partir daí, o agente está pronto para trabalhar com contexto completo em qualquer sessão futura.
✅ Conclusão
Agentes de IA transformaram o desenvolvimento de software. Mas sem estrutura para compensar sua natureza stateless, o potencial deles nunca é totalmente aproveitado.
O Squidy resolve isso de forma elegante — não substituindo o agente, mas preparando o terreno para que ele trabalhe melhor, com mais consistência e sem perder o fio da meada.
Em resumo:
- Para quem usa agentes de IA no desenvolvimento → O Squidy é quase obrigatório
- Para projetos com múltiplas sessões → Elimina o retrabalho de re-orientação
- Para times que usam IA → Garante que todos os agentes trabalhem com o mesmo contexto
- Para projetos solo → Cria a disciplina de documentação que projetos maiores já têm por necessidade
O segredo da qualidade está em executar um processo bem estruturado — mesmo aquelas etapas que parecem desnecessárias. Isso vale tanto para equipes humanas quanto para agentes de IA.
🌐 Site: squidy.run 🐙 GitHub: github.com/seomarc/squidyrun 📦 PyPI: pypi.org/project/squidy 📖 Docs: docs.squidy.run