DEV Community: Izaac Baptista

Skills e Hooks no Claude Code: o que são, quando usar e como criar

Izaac Baptista — Thu, 20 Aug 2026 14:30:46 +0000

Semana passada eu estava construindo skills pro meu projeto pessoal e caí numa pergunta besta que quase virou perda de tempo: "isso deveria ser uma skill ou um hook?"

Depois de errar a mão uma vez, ficou claro que são coisas bem diferentes, resolvem problemas diferentes, e confundir as duas custa caro em retrabalho. Este texto é o resumo prático que eu queria ter lido antes de começar.

O que é uma skill

Uma skill é uma pasta com um arquivo SKILL.md dentro (mais scripts ou templates opcionais). O arquivo abre com uma descrição curta, e é essa descrição que o Claude usa pra decidir se a skill é relevante pra tarefa que você pediu.

Se o pedido "casa" com a descrição, o Claude carrega o corpo inteiro do arquivo e segue o procedimento escrito ali. Se não casa, a skill nem entra no contexto, não custa token nenhum.

Isso faz da skill um tipo de conhecimento probabilístico: ela é conhecimento declarativo, o "como fazemos isso aqui", carregado sob demanda. O Claude pode seguir à risca, pode adaptar ao caso concreto, e em teoria pode até ignorar se achar que não se aplica. Por isso a especificidade da descrição importa tanto: descrição vaga significa que a skill não vai disparar quando devia, descrição específica demais significa que ela vai ficar de fora justamente quando seria útil.

Skills ficam em ~/.claude/skills/ (nível usuário) ou .claude/skills/ (nível repositório), e o Claude Code as descobre automaticamente, sem precisar registrar nada em configuração.

O que é um hook

Um hook é um script que roda em um momento fixo do ciclo de vida da sessão, por exemplo antes de uma tool ser usada (PreToolUse), depois (PostToolUse), no início da sessão, e por aí vai. Ele é configurado num JSON (.claude/settings.json), com o evento que dispara, um filtro opcional pra restringir a quais ferramentas ele se aplica, e o comando de shell que ele executa.

A diferença fundamental é que o hook roda fora do raciocínio do modelo. Ele recebe dados estruturados sobre o evento que disparou, mas não tem acesso ao histórico da conversa nem ao que o Claude está "pensando" naquele momento. Ele não decide nada, só executa a regra, sempre, sem exceção.

Isso faz do hook uma garantia determinística. Não importa se o Claude "achou" que estava tudo bem, se o gatilho aconteceu, o hook roda.

Por que a diferença importa na prática

Skill é julgamento. Ela carrega contexto e know how, mas ainda depende do Claude reconhecer a situação e decidir seguir o procedimento.

Hook é garantia. Ele não pede licença, só cumpre.

Se você usa skill pra algo que precisa ser inegociável (por exemplo, nunca fazer push sem revisão), corre o risco de o Claude, numa sessão cansada ou num contexto poluído, simplesmente não reconhecer a situação e pular a etapa. Se você usa hook pra algo que exige raciocínio (por exemplo, "como o nosso time versiona uma release"), ele não vai dar conta, porque hook não entende contexto, só executa comando.

Como criar uma skill

O mínimo é um SKILL.md com um cabeçalho de descrição e o procedimento escrito em linguagem natural, do jeito que você explicaria pra um colega novo no time. Vale a pena:

Deixar explícito o que fazer em caso de ambiguidade (no meu caso, a regra é sempre parar e perguntar, nunca decidir sozinho por conta própria).
Registrar que a skill é nova e vai ser ajustada com o uso real. Tratar o SKILL.md como algo vivo, versionado junto com o próprio código.
Testar com casos reais do dia a dia, não só com o caso feliz.

Como criar um hook

O mínimo é uma entrada no settings.json apontando pro evento (PreToolUse, PostToolUse, etc.), um matcher se você quiser restringir a determinadas ferramentas, e o comando que vai rodar. O comando pode bloquear a ação (retornando um código de saída específico) ou só avisar e deixar seguir.

Vale pensar hook como a camada de enforcement da sua operação: lint antes de commit, bloqueio de escrita fora do repositório certo, checagem de pré-condição antes de uma ação irreversível.

Dois exemplos reais do meu setup

Skill de fechamento de versão. Antes, fechar uma versão era abrir a ferramenta de kanban, achar cada card de tarefa, achar o PR linkado, mergear um por um manualmente, repetitivo e fácil de esquecer card sem PR. A skill busca tudo via MCP e confirma cada merge individualmente comigo. Qualquer ambiguidade (card sem PR, conflito, PR duplicado) para e pergunta, nunca decide sozinha.

Skill de auto-revisão de PR, com um hook na ponta. A skill roda o diff contra as regras do próprio repositório, classifica cada achado por severidade, corrige o que é mecânico sozinha, e só libera abrir PR se não houver bloqueio crítico. O detalhe interessante é que, ao final, ela grava um marcador com o SHA revisado. Um hook do Claude Code lê esse marcador antes de deixar rodar o comando de abrir PR. Se o marcador não bate com o HEAD atual, o hook bloqueia.

Ou seja: a skill decide quando o código está pronto. O hook garante que ninguém, nem eu, nem o próprio Claude, pula a etapa só porque estava com pressa.

Quando usar cada um

Pergunta simples pra decidir: isso pode ser pulado sem quebrar nada crítico, ou não pode de jeito nenhum?

Se pode ser adaptado, ignorado ou seguido de forma flexível dependendo do contexto, é skill. Se precisa acontecer sempre, sem depender de o Claude lembrar ou concordar, é hook.

Na prática, as duas camadas se complementam melhor do que competem: skill carrega o conhecimento de como fazer, hook garante que a etapa obrigatória não seja pulada.

RAG na Prática: Como Avaliar Retrieval Sem Virar "Achei Que Ficou Bom"

Izaac Baptista — Mon, 17 Aug 2026 04:10:14 +0000

No artigo anterior desta série, separei ETL, chunking e embedding como três camadas distintas de um pipeline de RAG. Mas ter as três bem implementadas não significa nada se você não consegue medir se o retrieval está funcionando.

E aqui mora um problema recorrente: a forma mais comum de "avaliar" RAG em produção ainda é abrir o chat, fazer três perguntas, olhar a resposta e dizer "ficou bom". Isso não é avaliação, é vibe check. E vibe check não escala, não é reprodutível, e não pega regressão.

Neste artigo eu quero destrinchar duas coisas: as métricas que realmente importam para retrieval, e como construir um harness de avaliação em camadas que eu uso em produção, sem depender só de "o LLM disse que tá bom".

Por que avaliar resposta final não é suficiente

Um erro comum é avaliar só a resposta final do LLM. O problema é que isso mistura dois tipos de falha completamente diferentes:

Falha de retrieval: o chunk certo nem foi recuperado. O LLM está respondendo com o contexto errado, mas ele pode ainda assim "parecer" convincente.
Falha de geração: o chunk certo foi recuperado, mas o LLM não usou bem, ignorou parte da informação, ou alucinou em cima do contexto correto.

Se você só olha a resposta final, não sabe qual das duas camadas quebrou. E sem saber isso, você fica ajustando prompt quando na verdade o problema é chunking, ou trocando de modelo de embedding quando o problema é o ETL.

Por isso, avaliação de RAG precisa ter uma camada específica para retrieval, separada da avaliação de geração.

As métricas de retrieval que importam

Antes de qualquer harness sofisticado, você precisa de um dataset de avaliação: pares de pergunta → chunks corretos esperados (ground truth), construído a partir de casos reais.

Com isso em mãos, as métricas clássicas de recuperação de informação se aplicam:

Precision@k: dos k chunks retornados, quantos são realmente relevantes. Mede ruído.
Recall@k: dos chunks relevantes que existem, quantos você conseguiu trazer dentro do top-k. Mede se você está perdendo informação.
MRR (Mean Reciprocal Rank): o quão cedo o primeiro chunk relevante aparece no ranking. Importa porque LLM dá mais peso ao que vem primeiro no contexto.
nDCG: parecido com MRR, mas considera relevância graduada (nem todo chunk relevante é igualmente útil) e pondera a posição de todos eles, não só do primeiro.

Na prática, recall@k costuma ser a métrica que mais expõe problema de chunking: se o recall está baixo, geralmente é porque a informação foi fragmentada errado antes de virar embedding, não porque o modelo de embedding é ruim.

Métrica sem contexto não decide nada sozinha. Um recall@5 de 70% pode ser ótimo para FAQ simples e péssimo para uma base jurídica onde perder um trecho muda a resposta. O threshold aceitável depende do domínio.

O harness em camadas

Métricas de retrieval resolvem uma parte do problema. Mas a resposta final do LLM também precisa ser avaliada, e aqui uma camada só de métrica não é suficiente, você não tem ground truth de texto livre pra comparar. É aqui que entra o harness em camadas, dividido em três estágios:

1. Checks determinísticos

A primeira linha de defesa, e a mais barata de rodar. Perguntas binárias e verificáveis por código, sem precisar de LLM:

A resposta contém uma citação de fonte válida?
O formato esperado foi respeitado (JSON, markdown, etc.)?
Palavras-chave obrigatórias apareceram (ex: um número de ticket, um nome de campo)?
A resposta não excedeu o limite de tokens/tamanho esperado?

Esses checks são rápidos, baratos, e pegam boa parte dos bugs óbvios antes de gastar uma chamada de LLM-as-judge.

2. LLM-as-judge

Para o que não dá pra verificar deterministicamente, correção semântica, completude, se a resposta realmente responde à pergunta, um segundo LLM avalia a resposta contra critérios explícitos (rubric), não só "essa resposta parece boa?".

Um ponto crítico aqui: o judge precisa ter acesso ao mesmo contexto recuperado, não só à pergunta e resposta. Sem isso, ele não consegue distinguir "o LLM respondeu mal" de "o LLM respondeu certo dado um contexto incompleto", que é exatamente a distinção que buscamos.

3. Calibration gate

Essa é a camada que mais gente pula, e a mais importante. LLM-as-judge sozinho tem um problema conhecido: ele pode ser inconsistente, enviesado a favor de respostas mais longas, ou simplesmente errar sistematicamente em certos tipos de pergunta.

O calibration gate é uma amostra do output do judge revisada por humano periodicamente, comparando o veredito do LLM contra o julgamento humano. Se a concordância cair abaixo de um threshold, isso é um sinal de que o judge não está confiável naquele momento — seja por mudança de prompt, mudança de modelo, ou deriva no dataset de avaliação.

Sem esse gate, é fácil cair numa armadilha perigosa: o harness reporta "95% de aprovação" e ninguém percebe que o próprio juiz está calibrado errado.

Um bug real que essa camada evita

Vale mencionar um tipo de falha que só um harness bem desenhado pega: sistemas com replanejamento automático (replanning) podem, silenciosamente, converter um bloqueio de guardrail em success: true, o sistema tenta de novo, contorna a trava de segurança, e reporta sucesso como se nada tivesse acontecido.

Sem uma camada de avaliação que audita especificamente os stop_reason e a trajetória completa da execução (não só o resultado final), esse tipo de bug passa despercebido indefinidamente. É o tipo de coisa que só aparece quando você trata avaliação como parte da arquitetura, não como um script que roda de vez em quando.

Conclusão

Avaliar RAG não é rodar uma métrica e comparar dois números. É separar onde a falha realmente aconteceu, retrieval ou geração, e construir camadas de verificação com custos e confiabilidades diferentes: determinístico primeiro (barato e binário), LLM-as-judge depois (semântico, mas falível), e um gate de calibração por cima de tudo (a garantia de que o próprio juiz ainda está confiável).

Sem isso, "meu RAG está funcionando bem" é só uma opinião. Com isso, é um número que você pode defender, e principalmente, que pega regressão antes que o usuário pegue.

Este artigo faz parte de uma série sobre implementações reais de RAG e engenharia de IA aplicada.

RAG na Prática: Por Que ETL, Chunking e Embedding Não São a Mesma Coisa

Izaac Baptista — Mon, 17 Aug 2026 03:56:48 +0000

Se você já mexeu com RAG (Retrieval-Augmented Generation), provavelmente já ouviu esses três termos sendo usados quase como sinônimos em algum momento, principalmente em conversas mais superficiais sobre o assunto. Mas eles não competem entre si. São três camadas distintas de um mesmo pipeline, e confundir suas responsabilidades é uma das causas mais comuns de RAG com recall baixo ou respostas alucinadas.

Neste artigo, vou destrinchar cada camada, mostrar onde uma termina e a outra começa, e comentar alguns trade-offs que aprendi implementando isso em produção.

O pipeline completo, de forma simples

Fonte de dados → ETL (extrai/limpa) → Chunking (divide) → Embedding (vetoriza) → Índice vetorial → Retrieval

Cada seta representa uma decisão de engenharia. Errar em qualquer uma delas degrada a qualidade final, mesmo que o LLM na ponta seja excelente.

ETL: a camada que ninguém quer fazer, mas que decide tudo

ETL (Extract, Transform, Load) é a parte "chata" do RAG, mas é onde a maior parte dos bugs de qualidade realmente nasce.

Extract: puxar conteúdo bruto de PDFs, Confluence, Jira, banco de dados, código-fonte, etc. Cada fonte tem sua própria complexidade, um PDF escaneado não é o mesmo problema que uma página HTML do Confluence cheia de macros.
Transform: limpar ruído (HTML, marcações, tabelas quebradas), normalizar encoding, remover boilerplate repetitivo, e, no meu caso, trabalhando com uma base de conhecimento técnica, decidir o que vale a pena manter versus o que é apenas ruído estrutural.
Load: persistir esse conteúdo já tratado em um storage intermediário, antes de virar embedding.

Um erro clássico aqui: tratar ETL como uma etapa "genérica" de dados, igual você faria para um data warehouse. Para RAG, a transformação precisa preservar contexto semântico, não só normalizar valores. Um texto "limpo" para BI pode já ter perdido a estrutura que o LLM precisaria para responder bem.

Chunking: a decisão mais subestimada do pipeline

Chunking é dividir o texto já tratado em pedaços menores. Existe por dois motivos:

Embeddings e LLMs têm limite de contexto.
Chunks menores e bem delimitados geram recuperação mais precisa — você quer trazer o trecho relevante, não o documento inteiro.

As estratégias mais comuns:

Tamanho fixo (ex: 512 tokens): simples, mas ignora a estrutura do conteúdo. Pode cortar uma explicação no meio.
Estrutural/semântica: respeita parágrafos, seções, headers. Geralmente performa melhor em bases técnicas (documentação, ADRs, código).
Com overlap: sobrepor uma pequena parte entre chunks vizinhos para não perder contexto na borda, muito útil quando uma ideia começa em um chunk e conclui no próximo.

Na prática, chunking ruim é silencioso: o sistema não quebra, ele só responde pior. Você pergunta algo e o retrieval traz um trecho tecnicamente relacionado, mas sem o contexto necessário para responder corretamente. É o tipo de bug que só aparece quando você já tem um harness de avaliação rodando, sem eval, passa despercebido.

Embedding: transformando texto em geometria

Só depois que o texto está limpo (ETL) e dividido (chunking) é que ele vira embedding: um vetor numérico que representa o significado semântico daquele chunk, gerado por um modelo especializado (text-embedding-3, Voyage, etc.).

Esses vetores vão para um índice vetorial, que permite busca por similaridade, é isso que possibilita, na hora do retrieval, encontrar "os pedaços de texto mais parecidos semanticamente" com a pergunta do usuário, mesmo que as palavras exatas sejam diferentes.

Um ponto importante: embedding não corrige um chunking ruim. Se o chunk já chegou fragmentado ou fora de contexto, o vetor vai representar fielmente... um pedaço de informação incompleto. Garbage in, garbage out — só que em forma de vetor.

A confusão mais comum

Muita gente trata RAG como "embedding + busca vetorial", pulando ETL e chunking como se fossem detalhes de implementação. Na prática, é o contrário: ETL e chunking são onde a maior parte do trabalho de engenharia, e da qualidade final, realmente acontece. O embedding é só a etapa que converte um bom trabalho de preparação em algo pesquisável.

Conclusão

RAG não falha por causa do modelo de embedding escolhido na maioria das vezes. Falha porque a fonte de dados foi mal extraída, o texto foi mal limpo, ou o chunking cortou informação no lugar errado. Antes de trocar de modelo de embedding ou tunar hiperparâmetros de busca, vale sempre auditar essas duas camadas anteriores primeiro.

Este artigo faz parte de uma série sobre implementações reais de RAG e engenharia de IA aplicada.

[Boost]

Izaac Baptista — Mon, 17 Aug 2026 03:48:54 +0000

Revisão de código antes do commit: agentes especializados pra cobrir o meu próprio ponto cego entre backend e frontend

Izaac Baptista — Thu, 13 Aug 2026 22:06:37 +0000

O problema que ninguém nomeia até doer

Quem revisa o próprio código fora da própria especialidade revisa pior, e isso vale mesmo quando o "time" é uma pessoa só. Num projeto pessoal com backend e frontend separados, meu background é forte em backend: anos de prática, um checklist de review que já vive na cabeça sem esforço. Frontend eu escrevo, mas não com a mesma profundidade, e é exatamente aí que a atenção de quem entende do assunto desaparece sem avisar. O código passa, os testes passam, o commit acontece, e a revisão que eu faria com rigor de especialista, se estivesse revisando backend, simplesmente não acontece com o mesmo padrão quando o arquivo é um componente Vue.

Foi esse o sintoma que apareceu ao tocar sozinho dois repositórios de stacks bem diferentes: um backend e um frontend. Não é um problema de disciplina, é estrutural. Ninguém segura na cabeça, ao mesmo tempo, o checklist de segurança de backend com a mesma profundidade que as convenções de composables de frontend, especialmente quando um dos dois lados não é a sua especialidade original.

O gatilho: um artigo, uma pergunta diferente

O ponto de partida foi um artigo sobre como um time usava IA para antecipar problemas de code review, guidelines versionadas, um ponto de entrada único para agentes, subagentes especializados e consolidação dos achados antes da entrega. A pergunta natural foi se o mesmo padrão fazia sentido sozinho, num projeto pessoal, sem um segundo revisor humano pra cobrir o lado onde minha experiência é mais rasa. Uma primeira tentativa de aplicar essa ideia foi dentro de um assistente de conhecimento pessoal baseado em RAG: ali, o "revisar antes do commit" fazia sentido para proteger invariantes específicos daquele sistema (confiança calculada de forma consistente, degradação graciosa quando dependências externas faltam, drift entre arquivos gerados e fonte). Ficou claro rapidamente que era um problema diferente do que estava doendo no dia a dia: naquele caso era revisão de conhecimento; aqui era code review real, de mudança real, em dois repositórios com stacks e riscos completamente diferentes, e, principalmente, com um nível de familiaridade minha bem desigual entre os dois lados.

Essa distinção foi o que definiu a proposta separada: agentes de review pré-commit para os dois repositórios do projeto, desacoplados do assistente de conhecimento, atacando diretamente o ponto onde a falta de especialidade em frontend deixava passar coisas que eu jamais deixaria passar em backend.

A solução: regras versionadas por domínio, não um revisor genérico

A decisão de design mais importante foi rejeitar um "revisor único genérico" e, em vez disso, versionar o conhecimento de review como está estruturalmente distribuído entre os domínios reais do sistema. Cada domínio vira um arquivo de regras curto, em prosa, revisável como qualquer outro código.

No repositório de backend:

Domínio	O que cobre
Arquitetura	Separação de camadas, responsabilidade única
Observabilidade	Log em falha, sem debug solto, sem dado sensível em log
Resiliência	Timeout em chamada externa, transação, job idempotente

No repositório de frontend:

Domínio	O que cobre
Arquitetura	Extrair componente, atomic design, lógica fora do template
Manutenibilidade	Reuso de composable/hook, simplicidade, DRY
Type safety	Tipar props/emits, nunca usar tipo genérico solto, rastrear usos até os callers
Convenções	Padrões de projeto, nomenclatura, sem log solto, sem dependência não usada
Testes	Teste unitário reflete a mudança
Segurança	Injeção de HTML/XSS, segredo em bundle, dado sensível exposto
Performance	Re-render evitável, carregamento tardio, chave estável em listas

Dos itens listados, o que se mostrou de maior valor prático foi o rastreamento de callers dentro do domínio de type safety: verificar não só se a função nova está tipada, mas se todo lugar que a chama continua consistente com a mudança. É exatamente o tipo de checagem que um humano cansado, revisando fora da própria especialidade, pula, e que gera bug em produção silenciosamente.

Cada repositório ganhou também um orquestrador, no frontend, um arquivo de skill dedicado, seguindo o mesmo padrão já usado para outras automações do repositório, complementando (não substituindo) o skill de code review genérico já existente. O orquestrador lê os arquivos de regra, aplica-os ao diff da mudança e devolve um relatório único, categorizado.

O contrato: consultivo, não bloqueante

Uma decisão deliberada, herdada da experiência anterior com o assistente de conhecimento: a v1 não trava entrega automaticamente. O papel do agente é produzir um relatório com achados categorizados por severidade, a decisão de bloquear a entrega continua sendo minha. Isso existe por dois motivos:

Calibração inicial imprevisível. Domínios como manutenibilidade (DRY, simplicidade) são inerentemente mais subjetivos do que segurança ou type safety. Sem dados reais de quantos achados desse tipo são falsos positivos, bloquear automaticamente geraria ruído e, rapidamente, eu mesmo passaria a ignorar o agente, o pior desfecho possível para uma ferramenta desse tipo.
Confiança se constrói, não se decreta. Um agente consultivo que acerta na maioria das vezes ganha o direito de, eventualmente, bloquear certas categorias de achado (por exemplo, segurança com alta confiança). Um agente bloqueante que erra uma vez perde a credibilidade inteira.

O gatilho de execução foi formalizado numa seção específica das instruções que qualquer sessão de agente lê antes de começar a trabalhar no repositório, instruindo-a a rodar o playbook antes de considerar a tarefa concluída.

Rollout em fases

Nenhum dos dois repositórios recebeu o conjunto completo de domínios de uma vez. O rollout seguiu o mesmo padrão de faseamento usado no restante do sistema de agentes internos:

Estrutura sem automação — os arquivos de regra existem e são revisáveis, mesmo antes de qualquer agente lê-los automaticamente.
Orquestrador funcional — o skill lê as regras e produz o relatório, ainda sem estar amarrado ao fluxo obrigatório.
Gatilho obrigatório — qualquer sessão de agente passa a rodar o playbook antes de finalizar.
Piloto com calibração — achados conhecidos injetados propositalmente em cada categoria, para medir taxa de falso positivo antes de considerar qualquer bloqueio automático futuro.

Os domínios mais "objetivos" (segurança, type safety, testes) foram semeados com o checklist de review que eu já aplicava de cabeça no lado onde tenho mais prática, o backend. Os mais recentes (observabilidade, resiliência) entraram com regras iniciais mais enxutas, para evoluir com uso real em vez de tentar prever tudo de antemão.

O que ficou claro depois de rodar isso de verdade

Uma vez ativo, o hook de auto-revisão passou a interceptar literalmente qualquer sessão de agente antes da entrega, inclusive sessões de trabalho em outros projetos, quando as instruções eram lidas no contexto errado. Isso expôs um ponto que a proposta original não tinha antecipado: um playbook desse tipo, referenciado de forma global demais, vaza para onde não devia. A correção não é técnica exótica, é escopo explícito: o hook precisa declarar claramente a que repositório e a que conjunto de regras ele pertence, para não disparar fora do contexto certo.

Essa é, talvez, a lição mais transferível de todo o exercício: regras versionadas e agentes especializados resolvem o problema do olhar crítico que falta, mas só se o escopo de ativação for tão bem desenhado quanto as próprias regras.

Resumindo

O problema real não era "falta de IA no code review", era perda de atenção especializada ao revisar sozinho o lado onde minha experiência é mais recente.
A solução foi desacoplar conhecimento de review em regras versionáveis por domínio, revisáveis como qualquer código.
Um orquestrador lê essas regras e produz um relatório único e categorizado, sem decidir travar a entrega, isso continua sendo humano, pelo menos nesta fase.
O gatilho fica formalizado nas instruções do agente, não em automação solta.
Rollout em fases, com piloto de calibração antes de qualquer discussão sobre bloqueio automático.

Agent OS: tratar as instruções de um agente como sistema, não como prompt

Izaac Baptista — Thu, 13 Aug 2026 22:02:17 +0000

O problema: prompt cresce, ninguém sabe mais o que está ativo

Todo assistente de IA interno começa do mesmo jeito: um arquivo de instruções que cresce a cada caso de borda descoberto. Alguém acha um comportamento errado, adiciona uma frase no prompt pedindo pra não fazer aquilo. Seis meses depois o arquivo tem duas mil linhas, ninguém sabe qual regra ainda vale, e regras novas contradizem regras antigas sem que nada avise.

O sintoma não é o agente "alucinando" — é o prompt virar uma pilha arqueológica de patches, sem precedência clara, sem forma de testar se uma mudança quebrou uma regra anterior, sem separação entre o que é sempre carregado e o que só deveria entrar em cenários específicos.

A resposta foi tratar o conjunto de instruções como um sistema versionado com schema, não como texto solto: um manifesto que declara ordem de precedência, políticas separadas por preocupação, árvore de decisão para roteamento de tarefa, checklists por tipo de entrega, e — a parte que fecha o ciclo — um validador que falha a build quando o sistema fica inconsistente.

Anatomia: carregamento progressivo, não tudo de uma vez

A decisão estrutural mais importante foi separar o que é sempre carregado do que é carregado sob demanda:

Core — poucas linhas, sempre presente: missão, ordem de instrução, princípios de operação ("inspecionar antes de assumir", "evidência é obrigatória para afirmação factual sobre o produto"). Orçamento de token explícito e pequeno.

Workflow — um por tipo de tarefa (responder pergunta de produto, investigar tecnicamente, documentar conhecimento, implementar mudança, corrigir bug, revisar mudança). Só o workflow da tarefa atual entra em contexto.

Playbook / rubrica / referência — carregado apenas quando o próprio workflow aponta pra ele. Nada entra "por garantia".

Isso resolve o problema raiz: cada peça tem um escopo de ativação declarado, então adicionar uma regra nova para o fluxo de revisão de código não infla o contexto de quem só está respondendo uma pergunta de produto.

O manifesto como fonte única de precedência

A ordem de instrução não fica implícita na posição de um parágrafo dentro de um arquivo gigante — fica explícita, em um campo de precedência: restrições rígidas primeiro, depois segurança e exigência de evidência, depois o pedido explícito do usuário, depois o workflow ativo, e só por último preferências e memória.

Essa ordem existe porque memória (contexto acumulado de sessões anteriores) é útil, mas não é fonte de verdade — o sistema trata memória explicitamente como contexto, nunca como evidência factual. Uma preferência lembrada de uma sessão passada não pode sobrescrever uma restrição de segurança da sessão atual. Sem essa hierarquia declarada, é exatamente esse tipo de conflito que fica resolvido de forma diferente a cada execução, dependendo de qual instrução "pesou mais" pro modelo daquela vez.

Roteamento por árvore de decisão, testado como código

Qual workflow carregar para uma tarefa não é decidido por um prompt tipo "identifique a intenção do usuário e escolha o fluxo apropriado" — é uma árvore de decisão explícita, com gatilhos por palavra/frase em dois idiomas, mapeando pra um workflow entre seis possíveis (responder pergunta de produto, investigação técnica, documentar, implementar, corrigir bug, revisar mudança). Roteamento de modelo e de ferramenta seguem o mesmo formato: condição → escolha, não prosa condicional.

O motivo de tratar isso como árvore e não como instrução em linguagem natural: uma árvore se testa com um benchmark de casos positivos, negativos e ambíguos. O time chegou a 95 casos cobrindo pares de confusão explícitos (por exemplo, "corrigir bug" vs "implementar mudança" — duas intenções que se parecem até alguém escrever os dois exemplos lado a lado e perceber a fronteira real) e 100% de acerto — partindo de uma base de 80 casos com quase 99%. Cada erro de roteamento encontrado nesse processo virou um caso novo no benchmark, não um ajuste de prompt sem registro.

O validador que trava build: RED também serve para arquitetura de agente

A peça que fecha o ciclo é um validador que roda contra o manifesto e falha explicitamente quando o sistema de agente fica inconsistente. Alguns exemplos do que ele pega:

Um workflow referenciando uma ferramenta que a política de segurança não permite naquele estado.
Uma transição apontando para um estado que não existe.
Um checklist ou política referenciado no manifesto que não existe no disco.
Orçamento de token excedido — o core tem um teto de ~800 tokens, cada workflow um teto de ~600, e o validador falha se qualquer um passar.
Drift entre o manifesto e os arquivos gerados a partir dele (variações de instruções específicas de cada ferramenta de IA, geradas automaticamente a partir da mesma fonte) — se alguém edita o arquivo gerado direto, sem passar pela fonte, o validador pega a divergência.
Ordem de precedência alterada de um jeito que não bate mais com a hierarquia obrigatória.

Cada uma dessas checagens nasceu de uma mutação proposital: o time pega o manifesto válido, aplica uma mutação específica (por exemplo, "remove a rubrica de objetividade"), e escreve o teste esperando a mensagem de erro exata que o validador deveria produzir. Isso é o mesmo espírito do ciclo TDD que trata código morto como "RED": aqui, o RED prova que o sistema recusa um estado inválido, não que uma feature nova funciona. Cobertura negativa cresceu de 8 para 21 casos assim, um por tipo de inconsistência que já foi imaginado — ou já aconteceu.

Confiança como campo de primeira classe, não em prosa

Uma política curta define os três níveis de confiança (alta: evidência direta valida a afirmação sem conflito crítico; média: evidência parcial ou indireta; baixa: sem evidência direta, ou resposta baseada só em memória) e uma regra que parece pequena mas evita um comportamento clássico de agente mal calibrado: confiança pode cair durante validação, nunca pode subir sem evidência mais forte. Ou seja, o modelo não pode "se convencer" de uma resposta ao longo da conversa — só pode ficar mais seguro se uma evidência nova e mais forte aparecer.

O que isso muda na prática

Nenhuma dessas peças, isoladamente, é surpreendente — árvore de decisão, checklist, orçamento de token, teste de mutação, tudo isso já existe em outros contextos de engenharia. O que muda é aplicar essa disciplina ao próprio sistema de instruções do agente, tratando-o como um artefato versionado com testes, não como um prompt que "só cresce".

O ganho concreto: quando alguém propõe uma regra nova, a pergunta não é mais "onde eu colo essa frase no prompt gigante" — é "isso é uma restrição, uma política, um workflow novo ou um caso de benchmark", e cada resposta tem um lugar certo, testável, com precedência já resolvida antes de qualquer execução real do agente.

Resumindo

Prompt monolítico que só cresce não escala — precedência fica implícita e ninguém consegue testar regressão.
A solução foi modelar o sistema de instruções com carregamento progressivo (core sempre, workflow por tarefa, playbook só sob demanda) e um manifesto único de precedência.
Roteamento de tarefa é árvore de decisão testável, não prosa — benchmark de casos positivos/negativos/ambíguos mede acerto real.
Um validador de mutação trata "isto não deveria ser um estado válido" como um teste RED, incluindo drift entre manifesto e arquivos gerados.
Confiança é campo estruturado com uma regra de uma via só: pode cair, nunca sobe sem evidência mais forte.

O que fica

O ponto comum entre um manifesto de agente e qualquer outro sistema de software não é a analogia bonita — é que os dois quebram do mesmo jeito quando ninguém trata as regras como algo testável. Um prompt que só cresce e um codebase sem teste de regressão falham pela mesma razão: mudança nova não sabe se contradiz decisão antiga até alguém descobrir em produção.

Tratar instrução de agente como sistema não é sobre desconfiar do modelo — é sobre parar de confiar na memória de quem escreveu a última frase do prompt pra saber se ela ainda é compatível com as duzentas anteriores. Um manifesto com precedência declarada e um validador que falha em mutação não deixam o agente mais inteligente; deixam o sistema em volta dele honesto sobre o que está, de fato, ativo.

Plan first, then implement: ADR, SDD e TDD como contrato de contexto antes de deixar a IA implementar

Izaac Baptista — Thu, 13 Aug 2026 21:00:31 +0000

O problema não é a IA escrever código errado, é ela decidir sem contexto suficiente

Pedir para um agente de IA "resolver a atividade X" parece simples até você lembrar como a maioria das atividades são escritas: um título, duas linhas de descrição, talvez um critério de aceite genérico. Suficiente para um humano que já conhece o sistema preencher as lacunas com contexto tácito. Insuficiente para uma IA, que vai preencher exatamente as mesmas lacunas, só que adivinhando, e sem avisar que estava adivinhando.

O sintoma não é código malformado. É decisão de design tomada silenciosamente, no meio da implementação, sem ninguém saber que ela foi tomada. Quando isso acontece, o bug não aparece no PR, aparece em produção, ou pior, nem aparece: só fica lá, dormente, até o dia em que o caminho que a IA decidiu ignorar for exatamente o caminho que um cliente real vai percorrer.

A resposta que organizou esse problema, na prática, foi inverter a ordem: gerar um ADR (Architecture Decision Record) e um SDD (Solution Design Document) junto com o agente, antes de qualquer linha de implementação, obrigando a IA a ler o código real do sistema antes de decidir qualquer coisa, e só depois disso liberar a implementação. TDD entrou como uma terceira camada, quase inevitável: se já existe uma decisão registrada (ADR) e um desenho de como implementá-la (SDD), o próximo passo natural é converter isso em testes que falham pela razão certa, antes do código que os faz passar.

O nome que ficou pra esse fluxo foi "Plan first, then implement": ADR → SDD → TDD como um contrato de contexto entre o desenvolvedor e a IA, revisável em cada etapa, antes de qualquer commit.

Por que três camadas, e não uma

Cada documento resolve uma pergunta diferente, e tentar resolver as três com um único artefato é o motivo pelo qual "documentação" costuma ser ignorada por quem já viu documentação ruim:

ADR — por quê. Uma decisão já tomada, registrada com alternativas rejeitadas e consequências assumidas. Não é um lugar para debate aberto (isso seria uma RFC); é o registro de algo que o time já decidiu, para que ninguém precise reconstruir o raciocínio depois.
SDD — como. O desenho concreto: quais arquivos mudam, qual o contrato de entrada/saída, quais consumidores existentes são afetados. É aqui que "vou fazer um fallback entre duas fontes de dados" se transforma em "estas duas classes de apresentação acessam campos fixos, então o fallback sem tradução de formato produz uma resposta quase vazia".
TDD — o quê, verificável. Os ciclos RED-GREEN que provam que a decisão do ADR e o desenho do SDD realmente se sustentam contra casos reais, incluindo os casos que só o SDD revelou.

A progressão importa: pular direto de ADR para código, sem o SDD, significa que decisões de mapeamento de dados, que não são arquiteturais o suficiente para um ADR, mas são grandes demais para ficar implícitas no código, não têm onde morar. Elas acabam vivendo na cabeça de quem implementou, exatamente o problema que o método existe para evitar.

O caso real: um fallback bidirecional entre duas APIs externas de consulta

A atividade original pedia um fallback: se a API principal de consulta a um cadastro externo falhasse, o sistema deveria tentar uma API secundária antes de desistir. Descrita assim, parece um try/catch com uma segunda chamada dentro. O ciclo ADR → SDD → TDD revelou que não era.

O que o ADR fixou: a decisão de qual API é primária, por que a ordem importa (SLA, formato de resposta, cobertura de dados), e, decisão que só apareceu numa segunda iteração do documento, que o fallback deveria disparar apenas em exceção, nunca em resposta de negócio malformada. Essa decisão existe porque as duas APIs sinalizam erro de forma assimétrica: uma sempre lança exceção, inclusive para "não encontrado"; a outra devolve sucesso HTTP com um indicador de erro no corpo da resposta. Sem essa distinção registrada explicitamente, um fallback "ingênuo" trataria uma resposta de erro de negócio da segunda API como sucesso.

O que o SDD expôs, que o ADR não tinha capturado:

Tradução de campos é pré-requisito, não etapa opcional. As classes de apresentação que consomem cada uma das duas respostas acessam nomes de campo fixos, e cada API tem seu próprio formato. Um fallback que só troca a fonte de dados, sem normalizar o formato de resposta, produz um objeto quase vazio no formato que o resto do sistema espera, o fallback "funciona" no sentido de retornar sucesso, e falha silenciosamente no sentido que importa.
Um blocker real em regra de negócio existente. Uma validação de um fluxo de baixa cadastral implementa uma regra que impede a baixa de registros ativos. Essa regra depende de um campo que, sem a tradução do item 1, simplesmente não chega, o que significa que a regra de negócio pararia de executar silenciosamente no caminho de fallback, sem nenhum erro visível.
Código morto revelado como efeito colateral. Uma verificação de um campo de status dentro do mesmo fluxo de validação nunca é verdadeira para respostas da API primária, porque essa API nunca produz esse campo. Não fazia parte do escopo da atividade, foi descoberto porque mapear os dois formatos de resposta lado a lado, exigência do SDD, expôs a inconsistência.

Nenhum desses três achados estava na atividade original. Nenhum deles seria óbvio pedindo direto "implemente o fallback" para um agente. Os três só apareceram porque o processo de escrever o SDD forçou a leitura comparada dos dois formatos de resposta e dos consumidores reais desses dados, não porque alguém foi procurar proativamente por bugs.

Os cinco ciclos de TDD, e por que o quarto é o mais interessante

Com ADR e SDD fechados, o TDD deixou de ser "escrever teste antes do código" em abstrato e virou uma lista concreta de comportamentos a provar, na ordem em que o SDD os expôs: tradução de campo, disparo de fallback só em exceção, preservação da regra de negócio de baixa, e o tratamento do código morto identificado.

O ciclo mais didático não foi o mais complexo tecnicamente, foi o que tratou o código morto. A lição ali é que RED também pode significar "isto não deveria mais existir", não só "isto ainda não existe". Um ciclo TDD tradicionalmente prova que um comportamento novo funciona; esse ciclo específico provou, com um teste que falha se a verificação morta continuar sendo alcançável para dados da API primária, que a lógica realmente nunca executa, documentando a descoberta do SDD em vez de simplesmente apagar a linha e confiar na memória de quem viu o SDD.

O que isso muda na prática

O ganho não é documentação por documentação, é o timing. Registrar a decisão de "fallback só em exceção" depois de implementar não teria evitado nada; o código já teria sido escrito assumindo outra coisa. O valor do método está inteiramente em forçar essas descobertas para antes do primeiro commit, quando ainda custa uma frase no SDD em vez de um rollback em produção.

Vale notar também que os documentos não nascem completos na primeira tentativa. A primeira versão do ADR desse caso não tinha a decisão sobre disparo por exceção, nem a tabela de mapeamento de campos, ambas apareceram numa revisão posterior, depois que checar o código real contradisse a suposição inicial. Isso não é falha do processo; é o processo funcionando: cada camada expõe algo que a anterior não tinha deixado explícito, e o documento se atualiza antes de virar código, não depois.

Um efeito colateral prático: PR, descrição de QA e critérios de aceite passam a derivar do ADR/SDD/TDD, em vez de nascerem de suposição no momento da entrega. A rastreabilidade atividade → ADR → SDD → TDD → PR fecha um ciclo que normalmente fica quebrado, em geral só a atividade e o PR existem, com tudo o que aconteceu no meio guardado apenas na cabeça de quem implementou.

Um padrão, não uma regra fixa

O mesmo fluxo se repetiu, com o mesmo formato, em atividades de escopo bem menor, como uma correção de paridade entre dois fluxos de validação de um mesmo dado cadastral, onde o "achado" não foi um blocker de negócio, mas a descoberta de que uma exclusão de categoria de cliente na validação nova era inconsistente com o comportamento já validado no fluxo legado. O tamanho do problema mudou; a disciplina de gerar os três documentos antes de tocar em produção, não.

Isso sugere que o valor do método não está atado à complexidade da tarefa, está em nunca deixar a IA (ou o próprio dev, sob pressão de prazo) decidir implicitamente algo que deveria estar registrado explicitamente antes do código existir.

O que fica

No fundo, ADR, SDD e TDD não são burocracia pra justificar processo, são a forma de transformar "confiar na IA" em algo verificável, em vez de um ato de fé. Não é sobre desconfiar do agente; é sobre não terceirizar decisões que deveriam ser explícitas para um processo que, por natureza, prefere preencher lacunas em silêncio a admitir que não sabe.

A parte contraintuitiva é que isso não deixa o trabalho mais lento, deixa mais devagar só o primeiro passo, e mais rápido tudo o que vem depois, porque o retrabalho que normalmente aparece semanas depois, disfarçado de bug em produção, já foi resolvido numa frase de documento, antes de existir código pra reescrever. Plan first, then implement não é disciplina por disciplina. É a diferença entre a IA decidir por você sem avisar, e você decidir com a IA, de olhos abertos.

Leadership that inspires starts with coherence

Izaac Baptista — Tue, 31 Mar 2026 15:52:19 +0000

We often talk about leadership as communication, motivation, or decision-making.

And yes, leadership involves all of that.

But before any of it, leadership is example.

Because teams rarely learn standards from what leaders say.

They learn them from what leaders tolerate, repeat, reinforce, and embody.

The gap between speech and example

One of the fastest ways to weaken a team is to create a gap between what is expected and what is practiced.

A leader asks for communication, but does not communicate clearly.

A leader asks for documentation, but leaves decisions undocumented.

A leader asks for discipline, but treats process as optional when it becomes inconvenient.

This is where trust starts to erode.

Not because people reject standards.

But because they notice when standards only apply downward.

Culture is shaped by repetition

In many teams, process failures are treated as isolated behavior.

A missing handoff.
A silent deployment.
An undocumented change.
A decision shared too late.

But when the same gaps keep happening without correction, they stop being exceptions.

They become culture.

Edgar Schein argued that leadership and culture are deeply tied, and that leaders create and manage culture through what they reinforce and normalize.

Because culture is not defined by the handbook.

It is defined by what the environment allows to happen repeatedly.

Leadership is not authority alone

A title can assign responsibility.

It cannot create inspiration.

What makes leadership credible is not hierarchy alone, but coherence between expectation and behavior.

If a team is expected to operate with clarity, leadership must model clarity.

If a team is expected to collaborate, leadership must model collaboration.

If a team is expected to respect process, leadership must show that process is not just a rule for others.

Without that, leadership may still function administratively.

But it stops being a reference point.

Trust is built through consistency

Simon Sinek’s view of leadership is not centered on authority, but on creating safety and trust inside the team. When people feel protected by leadership, cooperation becomes more natural.

That matters because inconsistency sends a different message.

It tells the team that process is conditional.
That clarity is optional.
That standards are flexible when power is involved.

And once that message becomes visible, credibility starts to weaken.

What strong leaders do differently

Strong leaders do not just correct visible mistakes.

They create consistency around the invisible standards that sustain execution.

They:

communicate context before urgency creates confusion
document decisions before misalignment grows
reinforce process before failure becomes routine
treat example as part of delivery, not as a soft skill

This is also what makes feedback believable.

Because standards only work when people see that they apply in every direction.

The hidden cost of inconsistent leadership

When leadership lacks coherence, the damage is not always immediate.

Sometimes deliveries still happen.
Sometimes deadlines are still met.
Sometimes the team keeps moving.

But the cost accumulates elsewhere:

preventable rework
weaker ownership
silent frustration
lower trust in process
reduced belief that feedback leads to change

Amy Edmondson’s work on psychological safety helps explain why this matters: teams perform better when people feel safe to speak up, question, and surface problems early. Inconsistent leadership weakens exactly that kind of environment.

And once people stop believing that standards matter in practice, performance becomes harder to sustain.

Because execution weakens when meaning disappears.

A more mature way to think about leadership

Instead of asking:

“Is the team following the process?”

A better question is:

“Is leadership creating an environment where the process is believable?”

That is the real test.

Not whether the process exists.

But whether leadership makes it credible enough to be followed.

Peter Drucker’s management writing consistently treated management as a discipline of responsibility and practice, not just intention. The same idea applies here: leadership is not proven by what it declares, but by what it repeatedly turns into reality.

Final thought

Leadership that inspires does not begin with charisma.

It begins with coherence.

Because teams can adapt to pressure.
They can adapt to change.
They can adapt to complexity.

What they struggle to adapt to is inconsistency from the people who are supposed to set the standard.

In the end, inspiring leadership is not about asking for better behavior.

It is about making the standard visible through example.

References / Further Reading

Culture & Leadership

Organizational Culture and Leadership — Edgar H. Schein

Trust & Safety

Why Good Leaders Make You Feel Safe — Simon Sinek (TED)
Psychological Safety and Learning Behavior in Work Teams — Amy Edmondson

Management

Management: Tasks, Responsibilities, Practices — Peter F. Drucker

A Release Is Not Ready When Development Is Done — It’s Ready When the Team Has Nothing Left to Prove

Izaac Baptista — Tue, 24 Mar 2026 22:29:47 +0000

“Development is done.”

We’ve all heard this before.

The feature is implemented.

The code is merged.

The pull request is approved.

And yet… the work is not finished.

Done is not the same as ready

In many teams, “done” is treated as a milestone.

But what does “done” actually mean?

Code written?
PR approved?
Deployed to staging?

None of these guarantee that the system behaves correctly.

Because working code is not the same as validated behavior.

The real checkpoint: validation

A release is not ready when development is done.

It’s ready when the team has nothing left to prove.

That means:

The feature behaves as expected
Edge cases are handled
Business rules are respected
The user experience makes sense

Until then, the work is still in progress.

When QA is misunderstood

Many teams see QA as a final step.

A checkpoint.

A gate.

Sometimes even a blocker.

But that’s a misunderstanding.

QA is not the problem.

QA is the feedback loop.

If issues are consistently found late in the process, it usually points to:

Missing acceptance criteria
Lack of shared understanding
Weak validation during development
Gaps between product, development, and QA

Quality is not a phase

One of the biggest mistakes teams make is treating quality as a stage.

Something that happens after development.

But quality is not something you add at the end.

It’s something you build throughout the process.

From:

refinement
to development
to review
to testing

Quality is not what QA finds at the end — it’s what developers prevent at the beginning.

What strong teams do differently

High-performing teams don’t “throw things to QA”.

They:

Involve QA early in the process
Clarify acceptance criteria before coding
Validate behavior during development
Share responsibility for quality

They don’t wait for code to be ready to start testing.

QA helps define how the system should be tested before the first line of code is written.

QA doesn’t validate alone.

Quality is owned by the team.

A more mature way to think

Instead of asking:

“Is development done?”

Start asking:

“Has this been validated end-to-end?”

Because delivery is not about code.

It’s about behavior.

Final thought

A release is not ready when development is done.

It’s ready when the team has nothing left to prove.

Because quality is not a phase.

It’s evidence.

References / Further Reading

Engineering & Quality

Continuous Delivery — Jez Humble & David Farley

Product & Collaboration

Inspired — Marty Cagan
Empowered — Marty Cagan

Engineering Management

The Manager’s Path — Camille Fournier

If Everything Is Urgent, Nothing Is Actually Important

Izaac Baptista — Tue, 24 Mar 2026 22:14:18 +0000

We hear this idea often.

And yet, many teams still operate as if everything needs to be done now.

Every request feels critical.

Every task is marked as high priority.

Every issue demands immediate attention.

But here’s the uncomfortable truth:

When everything is urgent, prioritization stops working.

Not everything should be urgent

In many teams, it’s common to hear:

“Can we prioritize this?”

“This is urgent”

“Let’s handle this as soon as possible”

But if everything is treated with urgency…

What actually defines priority?

Urgency should not be the default.

It should be intentional.

The real problem: lack of prioritization

The biggest issue is not urgency.

It’s this question:

“Do we know what truly matters right now?”

When that’s not clear:

Teams jump between tasks
Focus is constantly interrupted
Work becomes reactive instead of strategic
Important work gets delayed by “urgent” noise

As management thinker Peter Drucker emphasized:

There is nothing so useless as doing efficiently that which should not be done at all.

When urgency becomes a broken signal

There’s another layer to this.

As described by Goodhart’s Law:

“When a measure becomes a target, it ceases to be a good measure.”

When urgency becomes the default label for work:

Everything starts to look urgent
Priority signals get distorted
Teams lose the ability to distinguish what truly matters

Urgency stops being useful.

It becomes noise.

When urgency becomes a system problem

Excessive urgency is rarely about the work itself.

It usually points to:

Lack of clear priorities
Weak product or business direction
Poor backlog management
Difficulty saying “not now”

Urgency becomes a habit — not a decision.

The cost of constant urgency

Operating in a constant state of urgency leads to:

Context switching
Shallow execution
Increased stress
Lower quality deliveries

Teams stay busy…

…but meaningful progress slows down.

What high-performing teams do differently

Strong teams don’t eliminate urgency.

They protect it.

Urgency is reserved for:

Production incidents
Critical failures
Time-sensitive opportunities

Everything else is handled with clarity and prioritization.

A more mature way to think

Instead of asking:

“How fast can we do this?”

Start asking:

“Is this truly urgent — or just important?”

Because those are not the same.

Final thought

Urgency should be rare.

If everything is urgent, your team is not fast.

It’s reactive.

And reactive teams don’t scale.

References / Further Reading

Management

The Effective Executive — Peter Drucker
Management: Tasks, Responsibilities, Practices — Peter Drucker

Product & Prioritization

Inspired — Marty Cagan
Empowered — Marty Cagan

Economics & Systems Thinking

Goodhart’s Law — Charles Goodhart

Communication Is Important — But It’s Not the Most Important Thing in Engineering Teams

Izaac Baptista — Tue, 24 Mar 2026 21:56:17 +0000

Communication Is Important — But It’s Not the Most Important Thing in Engineering Teams

“Communication is key.”

We hear this all the time.

And yes — communication matters.

But here’s the uncomfortable truth:

Too much communication is often a sign of broken processes.

Not everything should depend on talking

In many teams, people say:

“Let’s align on this”
“We should discuss this”
“Can we jump on a quick call?”

But why does everything need alignment?

Why do we need constant clarification?

As product leader Marty Cagan often emphasizes, strong teams are empowered by clear context and autonomy — not constant coordination.

If people need to ask at every step, something deeper is missing.

The real problem: lack of clarity

The biggest issue is not communication.

It’s this question:

“Where does my responsibility start and end?”

When that’s not clear:

People overstep
Or worse — no one takes ownership
Decisions get delayed
Meetings multiply

This connects directly with a classic idea from Melvin Conway:

Systems mirror the communication structure of organizations.

If your system is full of dependencies, your team will rely on constant communication just to function.

When communication becomes a crutch

Without strong processes and culture:

Communication turns into dependency
Teams rely on conversations instead of structure
Knowledge stays in people’s heads, not in the system

Engineering leader Camille Fournier highlights this well:

Teams that depend too much on synchronous communication usually lack strong documentation and clear processes.

The deeper issue: unclear thinking

There’s another layer here.

As Sam Altman has pointed out:

Unclear communication is often a symptom of unclear thinking.

If the system, the problem, or the goal isn’t well understood, no amount of communication will fix it.

What actually makes a team agile

Agility is not:

More meetings
Faster replies
Constant alignment

Even decades ago, management thinker Peter Drucker argued that meetings are often a symptom of poor structure.

Real agility comes from:

Clear responsibilities
Well-defined processes
Autonomy with boundaries
Shared understanding of how work flows

Communication supports this.

It does not replace it.

A more mature way to think

Instead of asking:

“Did we communicate enough?”

Start asking:

“Was this supposed to require communication at all?”

Final thought

Great teams don’t communicate more.

They communicate better and less — because the system already does most of the work.

And without structure, no amount of communication will make a team truly agile.

References / Further Reading

Product & Empowered Teams

Inspired — Marty Cagan
Empowered — Marty Cagan

Engineering Management

The Manager’s Path — Camille Fournier

Organizational Design

Conway’s Law — Melvin Conway

Management

The Effective Executive — Peter Drucker
Management: Tasks, Responsibilities, Practices — Peter Drucker

Thinking & Clarity

Talks and interviews — Sam Altman

Trajetória Ascendente: Desenvolvedor Trainee Júnior a Pleno

Izaac Baptista — Mon, 18 Mar 2024 12:42:18 +0000

A carreira de desenvolvedor, desde o estágio trainee júnior até o nível pleno, é uma jornada repleta de desafios e conquistas. No estágio inicial, os profissionais enfrentam o desafio de assimilar uma ampla gama de conceitos teóricos enquanto mergulham nas nuances da programação. A constância no aprendizado é fundamental nesse estágio, exigindo uma dedicação contínua para absorver novas tecnologias, linguagens e práticas de desenvolvimento.

A resiliência emerge como uma habilidade-chave à medida que os desenvolvedores trainees enfrentam obstáculos e bugs que fazem parte do processo de aprendizado prático. A teoria, adquirida nos estudos iniciais, encontra sua aplicação real, e a resolução de problemas práticos requer a habilidade de colocar a 'mão no código'. Esse equilíbrio entre teoria e prática é essencial, e a resiliência desempenha um papel crucial ao lidar com os inevitáveis desafios enfrentados ao longo do caminho.

Além dos aspectos técnicos, a comunicação eficaz e a capacidade de trabalho em equipe tornam-se cada vez mais relevantes à medida que os desenvolvedores progridem em suas carreiras. Compartilhar conhecimento, colaborar em projetos e compreender as necessidades do cliente são habilidades que elevam o desenvolvedor de trainee a júnior e, eventualmente, a pleno.

O mentorado desempenha um papel crucial nessa trajetória ascendente. Desenvolvedores mais experientes fornecem orientação valiosa, acelerando o crescimento e proporcionando insights que não são encontrados apenas nos livros. A troca de experiências encurta a curva de aprendizado e inspira confiança para enfrentar desafios cada vez mais complexos.

Da mesma forma, na carreira de desenvolvedor, a busca constante pelo conhecimento, aliada à aplicação prática e à resiliência diante dos desafios, molda um profissional apto a enfrentar as complexidades do desenvolvimento de software e a alcançar o nível pleno com sucesso.

Immanuel Kant, filósofo iluminista, acreditava que a educação é a chave para a liberdade. Nesse contexto, sua célebre frase 'O homem é aquilo que a educação faz dele' destaca a importância do aprendizado contínuo na formação de um indivíduo.

Referências:

Hunt. (1999). O Programador Pragmático: Sua Jornada rumo à Maestria.
Cavalcanti. (2018). Caminho para o Sucesso: Estratégias para uma Carreira Sólida em Desenvolvimento de Software.
McConnell. (2004). Código Completo: Um Guia Prático da Construção de Software.

Blog Codigo Simples