O que é context engineering e por que ela é o pilar do GSD que resolve o Claude Code perdido no projeto

Fala aí, beleza? Sabe aquela sessão do Claude Code que começa afiada, entende o projeto, faz tudo certinho, e uma hora vira outra pessoa?

Ele começa a repetir, esquece decisão que vocês já tinham fechado dez minutos antes, reescreve arquivo que já estava pronto e funcionando

A reação padrão é culpar o modelo, trocar pra um mais forte, xingar a Anthropic

Mas na maioria das vezes o problema não é o modelo, é o CONTEXTO. E existe um nome pra disciplina que ataca isso: context engineering

Neste post eu quero te explicar o conceito antes de você sair configurando qualquer coisa, e depois mostrar um caso concreto de como isso vira arquitetura de verdade, usando o GSD Core como exemplo

E lá no fim eu te mostro uma sessão real minha, com um plugin de context mode rodando dentro do Claude Code, pra você ver o princípio funcionando fora do papel

Context rot: por que a qualidade cai quando a janela enche

A intuição de todo mundo é que quanto mais informação a IA tiver, melhor ela responde

Só que não é bem assim

A pesquisa Context Rot, publicada por Kelly Hong, Anton Troynikov e Jeff Huber, da Chroma, avaliou 18 modelos de ponta e mostrou uma coisa desconfortável: a confiabilidade cai de forma relevante conforme o input cresce

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 116 aulas
• 4 projetos
• 9h 23min

Conhecer formação

E olha que não estamos falando de raciocínio complicado

A queda aparece até em tarefas simples, tipo recuperar um trecho e copiar texto

Ou seja: encher a janela não é neutro, é um custo. Cada coisa que entra no contexto disputa espaço e atenção com o que realmente importa pra tarefa

Agora traz isso pro seu dia a dia numa base grande

Você abre a sessão, o agente lê uns 20 arquivos pra entender a estrutura, roda testes, imprime log gigante, pesquisa dependência, cola stack trace inteira

A decisão de arquitetura que você tomou lá no começo continua tecnicamente na janela, só que agora ela está soterrada embaixo de megabytes de ruído

Esse é o context rot: a degradação de qualidade que se ACUMULA conforme a janela enche

E não é uma teoria minha, é o problema central que o open-gsd/gsd-core declara resolver. O projeto nomeia o context rot como o inimigo e organiza tudo em cima disso

Prompt engineering x context engineering: qual é a diferença na prática

Muita gente usa os dois termos como sinônimo, e não são

A Anthropic trata context engineering como a evolução natural do prompt engineering: o conjunto de estratégias pra curar e manter o conjunto ótimo de tokens durante a inferência, incluindo tudo que chega ao contexto FORA do prompt

Essa última parte é a chave, se liga

O resultado da ferramenta que o agente rodou, o arquivo que ele leu sozinho, o histórico da conversa, o log de erro: nada disso você digitou, e tudo isso ocupa a janela

Um jeito fácil de sentir a diferença: se você conhece a diferença entre escrever uma boa query e desenhar o schema do banco, é mais ou menos isso

A query bem escrita resolve a pergunta de agora

O schema decide se o sistema aguenta o ano inteiro

E olha, isso não anula o prompt bem escrito, beleza? Dar informação certa continua valendo muito, tanto que dar contexto de negócio pra sua skill é justamente decidir o que entra na janela. Context engineering só amplia a régua: agora você responde também pelo que a ferramenta despejou lá dentro sem te pedir licença

Claude Code perdido no projeto: sintoma, causa e o que a disciplina propõe

Vamos aterrissar isso na cena real

Os sintomas que você já viu:

• respostas que ignoram uma decisão que vocês fecharam na mesma sessão
• código pronto sendo refeito do zero, às vezes num padrão diferente do resto do projeto
• o agente perdendo o fio em base grande, tipo abrindo de novo arquivo que ele já tinha lido
• respostas mais genéricas conforme a sessão avança, como se ele tivesse ficado mais burro

A causa:

Raramente é o modelo que piorou. É a janela que virou depósito

Se a confiabilidade cai conforme o input cresce, uma sessão de duas horas com log, arquivo e pesquisa acumulados é exatamente o cenário de pior desempenho

E tem um detalhe cruel: quando a janela estoura, a compactação decide sozinha o que guardar

Nem sempre o que sobrevive é o que importava pra você

O que a disciplina propõe:

O princípio é simples de enunciar e chato de aplicar: manter a sessão principal ENXUTA e empurrar leitura pesada pra fora dela

O trabalho continua acontecendo, mas o lixo do trabalho não fica morando na sua janela

Como prevenir no braço, sem instalar nada:

• recorte escopo antes de pedir. Uma tarefa por vez, com fronteira clara
• trabalhe por fase (entender, planejar, executar, verificar) em vez de misturar tudo numa conversa só
• não deixe a sessão virar depósito: quando o assunto muda de verdade, abrir sessão nova custa menos que arrastar duas horas de ruído
• escreva as decisões em arquivo, não na conversa. O que está no disco você reinjeta quando quiser; o que está na conversa some na compactação

Esses hábitos já resolvem uma boa parte, e ainda combinam bem com escolher o modelo certo pra cada tarefa, porque sessão enxuta muda o que você precisa de potência

Como o GSD Core transforma context engineering em arquitetura

Agora a parte massa: o que acontece quando alguém leva esse princípio a sério a ponto de virar estrutura de projeto

O GSD Core declara três pilares: meta-prompting, context engineering e spec-driven development. Context engineering é o segundo da lista, e não é enfeite de README

A estratégia de contexto declarada é essa: pesquisa, planejamento e execução pesados rodam em SUBAGENTES de contexto novo, enquanto a sessão principal fica enxuta

Ou seja, quem lê 40 arquivos pra entender o módulo não é a sua sessão

O orquestrador não toca no código:

Esse é o detalhe que mais me chamou atenção no desenho

No GSD Core a sessão principal funciona como orquestrador e NÃO toca arquivos-fonte

Ela dispara agentes, coleta os resultados, atualiza o estado compartilhado e roteia pro próximo passo

É como o tech lead que coordena a squad: ele sabe o que cada um está fazendo, sabe o que já foi decidido, mas não é ele que fica com 30 abas de código aberto na cabeça

Uma fase por vez:

Cada milestone repete o mesmo loop de cinco passos, uma fase por vez: Discuss, Plan, Execute, Verify e Ship

Parece burocracia, mas é consequência direta do princípio

Se misturar discussão, plano e execução na mesma janela, tudo vira uma sopa só e a compactação escolhe o que salvar

Separando por fase, cada etapa carrega só o que ela precisa

O estado mora no disco, não na conversa:

Todo o estado do GSD Core vive na pasta .planning/ na raiz do projeto, em Markdown e JSON legíveis, sem banco de dados e sem servidor

Isso é ouro, e por dois motivos

Primeiro: o que está em arquivo não morre na compactação. Você pode reabrir a sessão amanhã que a decisão continua lá

Segundo: é Markdown, você LÊ. Dá pra abrir, conferir e corrigir na unha se o agente entendeu errado, sem depender de nenhuma caixa preta

Sacou por que eu disse que o desenho é consequência do princípio? Cada escolha aí (subagente, orquestrador que não edita, fase separada, estado em arquivo) existe pra manter a janela principal limpa 😀

O que apareceu na prática ao isolar contexto numa sessão real

Eu não quero ficar só no conceito, então deixa eu contar o que eu vi quando testei isso na prática

No vídeo eu mostro um plugin de context mode rodando dentro do Claude Code, num projeto que eu já tinha pronto, com os prompts planejados antes

Foram três pedidos pesados em sequência: uma análise completa do projeto (estrutura de pastas, dependências, como a autenticação funciona, comunicação entre frontend e backend e vulnerabilidades de segurança), depois aplicar as três correções de segurança mais críticas e extrair a validação dos controllers pra um middleware reutilizável, e por fim uma funcionalidade nova de estatísticas com endpoint e uma seção visual com barra de progresso

Tipo de tarefa que normalmente enche a janela em minutos, né?

Depois dos três prompts eu rodei o comando de status do plugin, e os números que ele reportou na MINHA sessão foram esses:

• 84 KB de dados processados
• cerca de 40 KB que ficaram na sandbox, sem entrar no contexto (aviso de honestidade: na hora de falar eu cito 40k tanto pro que ficou de fora quanto pro que entrou, então essa fala ficou ambígua e eu prefiro registrar assim em vez de arredondar a história pro lado bonito)
• 50% de redução no tráfego de tokens, segundo o próprio status

E tem a parte subjetiva, que pra mim foi a mais sentida: o contexto passou a durar bem mais antes de compactar. Antes eu via poucas dezenas de minutos de trabalho contínuo, depois passou de uma hora

Deixa MUITO claro o que isso é e o que não é

Isso é observação de UMA sessão, num projeto específico, com prompts meus. Não é benchmark, não é média, não é promessa de que vai dar o mesmo número na sua máquina

O que me interessa aqui é o princípio confirmando na prática: quando o dado pesado não entra inteiro na janela, a sessão respira e dura mais

No vídeo você vê isso acontecendo ao vivo na tela: os prompts rodando, o plugin agindo sozinho durante a execução (sem eu chamar nada manualmente) e o status no final com a conta do que ficou fora do contexto

Quando context engineering vale o esforço (e quando é exagero)

Seja honesto com o seu caso, porque disciplina tem custo

Vale muito a pena quando:

• a base é grande e o agente precisa entender relação entre várias partes pra não quebrar nada
• é refatoração longa, daquelas que atravessam dezenas de arquivos com o mesmo padrão
• o projeto é multi-fase e cada fase depende de decisão tomada na anterior
• o trabalho atravessa VÁRIAS sessões, e amanhã você precisa que o agente lembre por que fizeram daquele jeito

É aqui que separar fases, empurrar leitura pesada pra subagente e guardar estado em arquivo devolve o investimento

É exagero quando:

• é script curto, coisa de um arquivo e vinte linhas
• é ajuste pontual, corrigir um bug óbvio, renomear função
• é tarefa que cabe inteira numa conversa de cinco minutos

Montar orquestrador, milestone e pasta de planejamento pra trocar uma cor de botão é usar PC da Nasa pra abrir bloco de notas haha

E não é só coisa de Claude Code:

Detalhe importante pra quem não usa só um agente: o GSD Core roda sobre vários agentes de código. Claude Code, Codex, Antigravity CLI, Kimi CLI, Copilot e Cursor estão entre os citados

A forma dos comandos muda conforme o runtime

No Claude Code os comandos entram com hífen, tipo /gsd-nome-do-comando

No Gemini CLI a forma é com dois-pontos, /gsd:nome-do-comando

Parece bobagem, mas é exatamente o tipo de coisa que faz o cara achar que a instalação quebrou quando na verdade ele só digitou a sintaxe do outro runtime

Por onde começar depois de entender o conceito

Se você chegou até aqui, a parte difícil já foi: o conceito vem ANTES da configuração

Context engineering não é truque de prompt nem fórmula mágica, é decidir o que ocupa a janela e o que fica de fora. Tudo o resto (subagente, fase, pasta de estado) é implementação desse princípio

Se quiser experimentar o desenho na prática, a instalação global no Claude Code é essa:

npx @opengsd/gsd-core@latest --claude --global

Trocando --global por --local, ele escreve na pasta .claude/ na raiz do projeto, que é o caminho pra testar num repo só antes de adotar pra tudo

Depois de instalado, o comando pra começar é:

/gsd-new-project

Uma linha de estado do projeto pra você não instalar o pacote errado, porque essa história teve reviravolta

O repositório original gsd-build/get-shit-done, publicado por TÂCHES, foi arquivado pelo dono em 26/06/2026 e está somente-leitura. O mantenedor ficou incontatável desde 01/04/2026, as contas sociais associadas foram apagadas e um token $GSD ligado ao projeto foi publicamente associado a um rug pull entre 21 e 22 de maio de 2026

Em 22/05/2026 o contribuidor de longa data Tom Boucher (trek-e) criou a organização open-gsd no GitHub e publicou o get-shit-done-redux como espelho bit-perfeito do original, preservando branches, tags e a licença MIT e removendo o material ligado a criptomoeda. O fork passou por auditoria interna de segurança e por revisão independente da empresa RokketSec, que não encontrou evidência de código malicioso no código-base

Hoje o repositório mantido é open-gsd/gsd-core, com 7.558 estrelas e 518 forks, e o pacote npm passou a se chamar @opengsd/gsd-core. Os pacotes @opengsd/get-shit-done-redux e @opengsd/gsd-sdk serão depreciados

E fica o aviso, porque isso ainda pega gente: o pacote antigo get-shit-done-cc continua registrando download no npm mesmo com o repositório original arquivado, foram 41.372 downloads entre 2 e 31 de julho de 2026

Tome cuidado na hora de copiar comando de tutorial velho, beleza?

Começa entendendo o porquê, aplica o hábito simples de manter a sessão enxuta, e só depois vai pra ferramenta

Nessa ordem, funciona muito melhor =)

até o próximo post!