CommitCycle Insights, em português

A instrução que você escreve uma vez, não a cada sessão

Tue, 18 Aug 2026 00:00:00 GMT

Existe um momento, a cada poucos dias, em que você digita a mesma correção de novo. Use o nosso componente de botão. Não adicione uma dependência para isso. As datas neste projeto são sempre ISO. Você disse isso na terça, a sessão terminou e o conhecimento terminou com ela.

Uma skill é aquela instrução, escrita uma vez só, num arquivo que o agente pega sozinho quando ela passa a ser relevante.

Esse é o conceito inteiro, e o resto desta página é a mecânica, o julgamento sobre o que cabe dentro de uma e a depuração — porque a falha típica não é escrever uma skill ruim, é escrever uma skill boa que nunca carrega.

O que é uma skill no disco

Uma pasta com um arquivo markdown dentro:

.claude/skills/
  cc-brand/
    SKILL.md
    references/
      token-reference.md
      motion-and-craft.md
      cc-tokens.css
    assets/
      AppShell.vue

O SKILL.md abre com um frontmatter que carrega duas coisas que importam:

---
name: cc-brand
description: Implements UI in the CC design system for Vue. Use this WHENEVER
  building, styling, theming or reviewing any Vue interface, component, page,
  dashboard or form for CommitCycle — and whenever the user mentions CC UI, the
  brand blue (#693DFF), Plus Jakarta Sans, shadcn-vue, or "make this on-brand".
---

# CC Design System Implementor

Everything the agent should know, in ordinary markdown.

Nada além disso é necessário. Sem etapa de build, sem registro, sem arquivo de configuração. A pasta existe, logo a skill existe.

Por que não colocar isso no prompt?

Porque você precisa lembrar, toda vez, e você não vai. Mais precisamente: as vezes em que você esquece não são aleatórias. São as vezes em que você estava indo rápido, que são as vezes em que o agente tinha menos contexto, que é exatamente quando a convenção mais importava.

Por que não colocar isso no AGENTS.md?

Esta é a pergunta de verdade, e a resposta é o projeto inteiro do recurso.

O AGENTS.md (ou CLAUDE.md) é sempre carregado. Todo turno, toda sessão, toda task, seja relevante ou não. Isso o torna perfeito para fatos que são sempre verdadeiros — a stack, os comandos, o layout de pastas, as coisas que nunca se deve fazer — e significa que cada linha que você acrescenta custa contexto em trabalhos que não têm nada a ver com ela. Um AGENTS.md de 900 linhas é um imposto sobre cada pedido.

Uma skill é carregada só quando casa. O que está sempre em contexto é o nome e a description dela: umas duas linhas. O corpo é lido só quando o agente decide que o trabalho pede aquilo.

Isso se chama progressive disclosure, e funciona em três níveis:

Nível	O que carrega	Quando
1	Nome + description	Sempre. Custa quase nada
2	O corpo do SKILL.md	Quando a description casa com a task
3	Os arquivos que acompanham a pasta	Quando o corpo aponta para eles e a task precisa

É por isso que uma skill pode ser enorme — um design system completo, um checklist de conformidade, a superfície inteira de uma API — sem deixar mais lento um pedido sobre outra coisa. Você está carregando uma biblioteca, não um bilhete.

O que vai onde

O julgamento que faz tudo isso funcionar:

Coloque em	Quando	Exemplo
O prompt	Verdadeiro só para esta task	“Use azul no cabeçalho desta página”
AGENTS.md	Sempre verdadeiro, sempre relevante, curto	“A stack é Astro + Tailwind. Nunca edite arquivos em `dist/`”
Uma skill	Verdadeiro numa situação específica, longo demais para o AGENTS.md	Seu design system completo, suas convenções de API, sua voz ao escrever
Um servidor MCP	O agente precisa alcançar algo	Seu banco de dados, seu rastreador de issues, sua analytics

O erro comum é colocar conteúdo do tamanho de um design system no AGENTS.md, onde ele é carregado a cada pedido, inclusive nos que são sobre um script de build. O outro erro comum é colocar a stack do projeto numa skill, onde ela pode não carregar no momento em que é necessária.

A description é o gatilho inteiro

Se você levar uma coisa só desta página: a description não é documentação, é a regra de casamento. Ela é a única parte da sua skill que o agente vê antes de decidir se lê o resto.

Então escreva com as palavras que uma pessoa digita de verdade. Não:

Diretrizes de implementação de marca e padrões de componentes.

Isso não casa com nada. Quem pede “faz isso parecer o nosso app” não usou nenhuma dessas palavras. Em vez disso:

Use isto sempre que estiver construindo, estilizando, tematizando ou revisando qualquer interface, página, dashboard, formulário ou componente de [produto] — e sempre que o usuário mencionar [a cor da marca], [a fonte], [a biblioteca de componentes] ou “deixa on-brand”. Recorra a isto mesmo quando o pedido for só “faz uma página de configurações” ou “estiliza este card”.

Concretamente, uma description que dispara de forma confiável nomeia:

Os verbos — construir, estilizar, revisar, migrar, redigir
Os substantivos — os artefatos aos quais ela se aplica
As strings literais — nomes de produto, códigos hex, nomes de fonte, nomes de biblioteca
As formulações informais — “deixa on-brand”, “do jeito de sempre”, “igual às outras páginas”
Quando usar mesmo quando não parece que se aplica — esta linha faz um trabalho surpreendente

Ser inclusivo demais custa um pouco de contexto quando dispara sem necessidade. Ser inclusivo de menos custa a skill inteira, em silêncio, para sempre. Incline-se para disparar.

Onde as skills ficam

Dois lugares, e a escolha importa mais do que parece.

.claude/skills/ dentro do projeto. É commitado junto com o repositório, então está na sua outra máquina, em toda sessão futura e para qualquer pessoa que clone. Tudo que descreve este produto pertence aqui.

~/.claude/skills/ na sua pasta pessoal. Disponível em todo projeto que você toca, invisível para todo mundo. Isso é para o seu jeito de trabalhar: como você gosta que os commits sejam escritos, como você quer os documentos estruturados.

O padrão deve ser o projeto. Uma skill que vive só no seu notebook está a uma máquina de distância de não existir, e é a razão pela qual um projeto “só funciona direito quando é você que roda”.

Como sei que ela disparou?

Pergunte. Quais skills você usou para isso? é uma pergunta razoável e recebe uma resposta direta. Quais skills você tem disponíveis? lista todas, que é a primeira verificação depois de instalar uma.

A verificação forte é comportamental: abra uma sessão nova, formule um pedido do jeito que um usuário real formularia — não do jeito que a documentação da própria skill formula — e veja se a saída segue as regras sem você mencioná-las. Esse é o único teste que importa, porque essa é a condição real de uso.

Por que minha skill não dispara?

Sintoma	Quase sempre	Correção
Nunca carrega	A description não contém as palavras que estão sendo digitadas	Reescreva a description com formulações reais e nomes literais
Carrega, e aí a saída ignora	O SKILL.md é longo demais ou as regras estão enterradas em prosa	Corte. Comece pelas regras. Mova o detalhe para `references/`
Carrega em tudo	A description é ampla demais	Adicione o limite: para que ela não serve
Funciona para você, não para um colega	Está em `~/.claude/skills/`, não no projeto	Mova para o repositório e faça o commit
Contradita por outras instruções	O AGENTS.md diz outra coisa	Decida qual vence e diga isso explicitamente nos dois

Repare que quatro dos cinco são problemas de description ou de localização. O conteúdo raramente é o que está errado.

Mantendo o SKILL.md curto

Uma vez carregado, o corpo é lido inteiro — então o tamanho custa alguma coisa, e a boa estrutura é um arquivo de instruções curto que aponta para o detalhe.

SKILL.md               as regras, a ordem de decisão, o que vence num conflito
references/             o material longo: tabelas de tokens, superfícies de API, exemplos
assets/                 coisas para copiar: componentes, folhas de estilo, modelos
scripts/                coisas para rodar

A skill cc-brand do exemplo acima tem exatamente esse formato: o SKILL.md declara a prioridade de camadas e a regra de conflito em algumas centenas de palavras, e a referência de tokens, a orientação de movimento e os componentes de shell prontos ficam em arquivos para os quais ele aponta. O agente abre a referência da barra lateral quando está construindo uma barra lateral, e nunca em outra hora.

Duas coisas pertencem ao SKILL.md e não a um arquivo de referência: a ordem de precedência (quando duas regras colidem, qual vence) e o que não fazer. As duas são curtas e as duas são o que o agente erra quando elas faltam.

Skills, MCP, subagents, slash commands

Quatro coisas que se confundem, em eixos genuinamente diferentes:

	O que é	Quem dispara
Skill	Instruções carregadas por relevância	O agente, ao casar a description
Servidor MCP	Tools que alcançam sistemas externos	O agente, quando precisa da tool
Subagent	Uma janela de contexto separada para trabalho delegado	O agente, ou você
Slash command	Um prompt salvo que você invoca pelo nome	Você, explicitamente

Skills e MCP são complementos, não alternativas. O servidor MCP dá ao agente uma conexão com o seu banco de dados; a skill conta a ele as suas convenções de schema e quais tabelas nunca são escritas diretamente. Ferramentas sem instruções é a configuração que a maior parte das pessoas tem, e é por isso que o agente consegue alcançar tudo e ainda assim fazer a coisa errada com aquilo.

Instalando uma que alguém te deu

Coloque a pasta em .claude/skills/ (projeto) ou ~/.claude/skills/ (pessoal).
Abra uma sessão nova — uma já aberta já montou a lista dela.
Pergunte quais skills você tem disponíveis e confira se a sua aparece pelo nome.
Dê a ela um pedido realista e veja se as regras se aplicam sem serem mencionadas.

Se o passo 3 falhar, a pasta está no lugar errado ou o SKILL.md está com o nome errado. Se o passo 4 falhar, é a description.

A que vale instalar no primeiro dia é uma skill de design. Se você tem uma ideia mas ainda nenhuma marca e nenhuma opinião visual, o startpow.com deixa você escolher o que gosta, exportar e baixar o resultado como skill. Você solta a pasta lá dentro e, daí em diante, cada tela que o agente construir chega nas suas cores, na sua tipografia e no seu espaçamento sem você descrever tudo de novo — que é, mais ou menos, a diferença entre um produto e uma demo, por uns dez minutos de trabalho.

Quantas skills são demais?

Existe um orçamento real, e não é o que as pessoas temem. Os corpos são de graça até carregarem, então uma pasta com quarenta skills não deixa nada mais lento. O que não é de graça são as descriptions, que estão todas em contexto, o tempo todo.

Quarenta descriptions vagas são piores que cinco afiadas por uma segunda razão também: quanto mais elas se sobrepõem, menos confiável é que a certa vença. Duas skills que cobrem “estilo” de forma igualmente plausível significam um cara ou coroa a cada pedido de UI.

O formato prático é um punhado de skills com fronteiras limpas, cada uma das quais você conseguiria descrever numa frase sem usar a palavra “e”. Quando você não consegue, aquilo são duas skills.

Uma skill é instrução que você concorda em executar

Vale dizer com todas as letras, porque skills circulam como se fossem modelos de estilo, e não são.

Uma skill é um conjunto de instruções que um agente vai seguir, com as suas permissões, no seu repositório. Uma skill baixada pode dizer a um agente para instalar um pacote, para mandar um arquivo para algum lugar, para tratar uma regra como mais importante que as que você escreveu. É a mesma decisão de confiança de rodar um script que alguém te mandou, e o fato de ser markdown em vez de código faz aquilo parecer menor do que é.

Então: leia o SKILL.md antes de instalar, olhe o que mais tem na pasta e tenha mais cuidado com skills que trazem scripts do que com skills que trazem documentação. Um design system de uma ferramenta que você escolheu é uma proposta muito diferente de uma skill colada num fio de fórum.

O mesmo vale ao contrário quando você publica uma: quem instala a sua está te estendendo essa confiança.

Levando isso para um time

Três caminhos, em ordem crescente de cerimônia:

Faça o commit delas no repositório. .claude/skills/ está no repo, então clonar traz tudo. Isso cobre a maior parte dos casos e não precisa de infraestrutura nenhuma.
Distribua num plugin. Um plugin pode carregar skills junto com comandos e servidores MCP, instalado pelo nome e atualizado de forma central. É o certo quando vários repositórios precisam das mesmas convenções.
Mande a pasta. Serve uma vez, é ingerenciável na quarta pessoa, porque agora não há resposta para “qual versão você tem?”.

A falha a evitar é aquela em que a skill existe só na pasta pessoal de uma pessoa. O projeto passa a se comportar de forma diferente dependendo de quem está no volante, e ninguém consegue ver por quê.

O jeito mais rápido de escrever sua primeira skill

Não comece de uma página em branco. Páginas em branco produzem regras genéricas, e regras genéricas são as que o modelo já segue.

Em vez disso: trabalhe normalmente e preste atenção no que você corrige. Na terceira vez que você disser a mesma coisa — a terceira vez que apontar o formato de data, ou o componente, ou que aqui a gente não usa aquela biblioteca — diga:

Transforme o que você acabou de aprender numa skill. Escreva a description para que ela dispare sempre que alguém pedir qualquer coisa nesta área, inclusive nas formulações informais. Mantenha o SKILL.md curto e coloque o detalhe longo num arquivo de referência.

Suas correções já são exatamente o conteúdo de que uma skill precisa. São específicas, são reais e são as que de fato estavam sendo erradas — o que é um ponto de partida muito melhor do que qualquer coisa que você pensaria em escrever de antemão.

Truques que fazem diferença de verdade

Mostre, não só conte. Um exemplo trabalhado da sua convenção rende mais que três parágrafos descrevendo-a. Modelos são extremamente bons em reconhecer padrões a partir de um exemplo, e meramente obedientes ao seguir uma regra.
Uma skill por assunto. Uma única skill de “nossos padrões” cobrindo design, testes e deploy dispara em tudo e não se aplica bem a nada. Divida.
Diga qual vence. Toda skill que contém mais de uma fonte de orientação precisa de uma frase dizendo qual tem precedência num conflito. Sem ela, o modelo escolhe, e escolhe diferente a cada vez.
Escreva as regras negativas. Não introduza uma segunda biblioteca de componentes. Não adicione dependências para algo que a biblioteca padrão já faz. Restrições negativas são seguidas de forma mais confiável que as positivas e quase sempre são o que você de fato queria.
Versione junto com o código que ela descreve. Uma skill de design no repositório muda no mesmo commit que os tokens que ela documenta. Uma skill de design no seu notebook desvia em quinze dias e depois ensina, com toda a confiança, as cores do mês passado.
Teste com uma sessão fria e uma formulação preguiçosa. “faz a página de configurações” é como o pedido vai chegar de verdade. Se a skill precisa da versão bem formulada para disparar, ela não funciona.
Deixe as skills velhas morrerem. Uma skill que descreve uma convenção que você abandonou é pior que nenhuma skill: é uma instrução confiante e sempre disponível para fazer a coisa errada.

Se você não está no Claude Code

Skills como pastas são um recurso do Claude Code. Outras ferramentas agênticas leem um único arquivo de instruções sempre carregado, e a convenção quase universal é AGENTS.md na raiz do repositório.

O conteúdo se transfere direto. O que não se transfere é o carregamento seletivo — tudo naquele arquivo é pago a cada pedido — então a disciplina é outra: limite ao que é sempre verdadeiro, coloque o material longo em documentação comum e aponte para ela a partir do arquivo em vez de colar tudo dentro.

De um jeito ou de outro, o movimento de fundo é o mesmo, e é o hábito de maior alavancagem no desenvolvimento com agentes: na segunda vez que você explicar alguma coisa, escreva isso onde o agente vai encontrar. O resto da configuração em volta disso — o repositório, o modelo, o host, a stack, as salvaguardas — são seis decisões.

GitHub para quem não escreve o código

Tue, 18 Aug 2026 00:00:00 GMT

Se você nunca usou o GitHub, ignore como ele costuma ser descrito. Não é uma rede social para programadores, você não está ali para ler o código de ninguém, e os quadradinhos verdes não são um placar que você precisa preencher.

É um sistema de salvamento com histórico, hospedado em algum lugar que não é o seu notebook. É isso.

Para um vibe coder, ele ganha o lugar dele por um motivo específico. Em algum momento — não talvez, em algum momento — uma sessão vai reescrever algo que já funcionava. Vai refatorar um arquivo de que você gostava, apagar uma função que decidiu que não era usada, ou corrigir um bug introduzindo dois em silêncio. Sem commits, aquele trabalho se foi e sua única recuperação é descrever tudo de novo, de memória, para um modelo que esqueceu a conversa. Com commits, a recuperação é uma frase.

Este guia é tudo de que você precisa para isso, e nada de que você não precisa.

Git e GitHub não são a mesma coisa

Vale dez segundos, porque misturar os dois é o que deixa todo o resto confuso.

Git é um programa no seu computador. Ele registra versões de uma pasta. Funciona sem internet, sem conta e sem site, e é o que faz todo o trabalho de fato.

GitHub é um site que guarda uma cópia de um repositório Git e acrescenta o que um site pode acrescentar: uma página para navegar nele, um lugar para outras pessoas, automação que roda quando você envia.

Então quando o seu agente “commita”, isso é o Git, local, instantâneo. Quando ele faz “push”, isso é a cópia viajando para o GitHub. É por isso que você consegue trabalhar num avião e por isso que um commit não é um backup até ter sido enviado.

As alternativas — GitLab, Bitbucket, Codeberg — são o mesmo Git por baixo com outro site por cima. Nada neste guia muda se você escolher uma delas.

As sete palavras que cobrem quase tudo

Elas ficam em inglês porque é assim que você vai vê-las no GitHub e no terminal:

Palavra	O que de fato é
Repository (“repo”)	A pasta do seu projeto, mais toda versão que ela já foi
Commit	Um ponto de salvamento com um bilhete anexado
Branch	Uma cópia do projeto onde você pode quebrar coisas com segurança
Push / pull	Mandar seus commits para o GitHub / trazer os dos outros
Clone	Baixar um repositório inteiro, histórico incluído
Pull request (“PR”)	“Aqui está uma mudança, dê uma olhada antes que ela entre”
Merge	Dobrar os commits de um branch dentro de outro

Mais duas que você vai ver e pode quase sempre ignorar: origin é o apelido padrão para “a cópia que está no GitHub”, e main é o nome padrão do branch principal.

Preciso aprender comandos de Git?

Não, e esta é a parte que ninguém conta para quem está começando. Você precisa de três frases para dizer ao seu agente, e ele roda os comandos.

Faz o commit disso com uma mensagem clara.
O que mudou desde o último commit?
Desfaz tudo desde o último commit.

Essa é a interface inteira do seu primeiro mês. O que você precisa mesmo é entender o que essas três coisas significam, que é para isso que serve o resto desta página — porque a falha típica não é digitar o comando errado, é pedir o tipo errado de desfazer.

Se você prefere botões a frases, o GitHub Desktop é gratuito, mostra os arquivos alterados como um diff visual e transforma commit e push em dois cliques. Muita gente que publica produtos reais nunca usa o terminal para o Git.

Onde seu código fica enquanto você trabalha

As mensagens do Git falam de arquivos “staged”, “tracked” e “untracked”, e nada disso faz sentido até você saber que existem três lugares onde uma mudança pode estar:

Lugar	O que significa	Como ela sai dali
Diretório de trabalho	Você (ou o agente) editou o arquivo. Nada foi registrado	`git add`
Área de staging	Marcado como parte do próximo commit, mas ainda não salvo	`git commit`
Já em um commit	Registrado no histórico de forma permanente	`git push` manda para o GitHub

A área de staging é a parte que parece inútil no começo. O propósito dela é escolher: doze arquivos mudaram, quatro pertencem a este commit, então você marca esses quatro. Como vibe coder você vai commitar quase sempre tudo de uma vez — mas precisa saber que o staging existe, senão “changes not staged for commit” é uma mensagem de erro sobre nada.

git status é o comando de “onde eu estou”, e é o que vale a pena você mesmo saber ler. Ele diz em qual branch você está, o que mudou, o que está em staging e se você está à frente ou atrás do GitHub. Quando algo está confuso, é a primeira coisa a olhar, e é completamente seguro: não muda nada.

O primeiro arquivo que importa: .gitignore

Antes do seu primeiro push, antes de qualquer outra coisa: o .gitignore é uma lista de arquivos que o Git nunca deve registrar.

No mínimo, ele contém:

.env
.env.local
node_modules/
.DS_Store
dist/

O .env é o que importa. É ali que ficam suas API keys, e aquela única linha é o que impede que elas sejam publicadas na primeira vez que você enviar. Repositórios públicos são varridos continuamente por gente procurando exatamente isso, e uma chave vazada é encontrada em minutos, não em dias.

Peça isso explicitamente na configuração inicial — adicione um .gitignore apropriado para esta stack e garanta que o .env está nele — e depois confira com seus próprios olhos que o .env está listado. É uma verificação de trinta segundos que evita o erro caro mais comum de quem começa.

Deixe o repositório privado por padrão. Público é uma decisão deliberada de publicar, e é muito mais fácil tornar público depois um repositório privado do que despublicar alguma coisa, inclusive tudo que está no histórico dela.

Como leio um diff sem ler código?

Um diff é o que mudou, mostrado linha por linha. Linhas verdes com + foram adicionadas, linhas vermelhas com - foram removidas, linhas cinzas são contexto sem alteração. Você não precisa entender o código para tirar valor real dali:

Qual é o tamanho? Doze linhas alteradas para um pedido pequeno é normal. Quatrocentas é um sinal para parar e perguntar o que mais ele fez.
Quais arquivos? Se você pediu uma mudança de cor e um arquivo com auth, migration ou schema no nome está na lista, esse é o momento de perguntar por quê.
Alguma coisa apagada que você não pediu para apagar? Blocos longos de vermelho merecem uma pergunta.

Essa é a habilidade inteira, e é a maior parte do que uma revisão de código entrega num projeto solo. Me mostra o diff e explica em português claro o que a mudança de cada arquivo faz é um bom hábito antes de cada commit.

O que faz uma mensagem de commit valer a pena?

O único trabalho dela é ajudar o você do futuro a achar um momento no tempo. “Update” e “fixes” falham nisso; seis delas em sequência são indistinguíveis.

Escreva qual é o estado, não o que você fez: tela de login funciona, validação ainda não feita. Seis semanas depois, essa mensagem é o que permite dizer “volta para quando o login funcionava” e significar algo preciso.

Faça o commit quando algo funciona, não no fim do dia. O fim do dia é um ponto de salvamento para oito horas de decisões. Todo estado que funciona é um lugar ao qual você pode voltar.

Quando eu de fato preciso de um branch?

Como vibe coder solo, menos vezes do que os tutoriais dão a entender. Você precisa de um quando está prestes a tentar algo de que pode se arrepender: uma refatoração grande, uma troca arriscada de dependência, um experimento do qual você só está meio convencido.

O motivo é que o desfazer fica de graça. Você está no experiment, dá errado, você volta para o main e apaga o branch. Nada para desatar, nada para reverter, nenhuma discussão com o agente sobre o que ele mudou.

No momento em que mais alguém toca no repositório, isso deixa de ser opcional e passa a ser um branch por pedaço de trabalho — que é onde o vibe coding fica genuinamente mais difícil, e um problema diferente deste.

Como eu desfaço alguma coisa?

A seção mais importante desta página. Existem quatro tipos de desfazer, e pedir o errado é como as pessoas perdem trabalho tentando salvá-lo.

1. Você tem mudanças sem commit e quer elas fora.

git restore .

Tudo desde o último commit desaparece. Este é o do dia a dia: a sessão deu errado, nada valia a pena guardar, recomeça do último estado bom.

2. Você commitou, mas não enviou, e quer o commit fora.

git reset --soft HEAD~1   # desfaz o commit, mantém as mudanças
git reset --hard HEAD~1   # desfaz o commit e as mudanças

--soft é para “commit certo, mensagem errada, momento errado”. --hard é para “aquela direção inteira estava errada”.

3. Você já enviou, e outras pessoas (ou um deploy) têm aquilo.

git revert <commit>

Isso faz um commit novo que desfaz o antigo. É o seguro, porque acrescenta ao histórico em vez de reescrevê-lo, e nada do que outra pessoa já tem discorda do que você tem.

4. Você acha que perdeu algo para sempre.

git reflog

O Git mantém um registro privado de cada posição em que o seu branch esteve por cerca de noventa dias, incluindo commits que você “apagou” e branches que removeu. Quase nada some de verdade. Este é o que se busca depois de um --hard do qual você se arrependeu ou de um force-push que comeu a sua tarde — e vale saber que ele existe justamente porque o momento em que você precisa dele é o momento em que você está em pânico.

O que é um conflito de merge, e quem resolve?

Dois branches mudaram as mesmas linhas. O Git não vai adivinhar qual versão vence, então marca o trecho em disputa no arquivo com <<<<<<< e >>>>>>> e para.

Nada está quebrado e nada foi perdido. As duas versões estão ali; alguém tem que escolher.

Agentes são bons nisso, com uma condição: conte para eles para que cada mudança servia. A decisão é sobre intenção, não sintaxe — este lado é a lógica nova de preços, aquele lado é a correção do bug de ontem, mantenha os dois comportamentos recebe uma resolução correta. “Resolve o conflito” recebe um cara ou coroa.

O que acontece se eu commitar uma API key?

Rotacione. Agora. Vá até o serviço, revogue a chave, emita uma nova.

Apagar o arquivo num commit posterior não faz nada, porque a chave continua ali no histórico, onde qualquer um consegue ler. Num repositório público, presuma que ela foi varrida em minutos: isso é automatizado em escala.

O GitHub ajuda em dois pontos, e vale ligar os dois. O secret scanning percebe formatos de chave conhecidos no seu repositório e avisa você. A push protection vai além e bloqueia o envio antes de o segredo chegar a aterrissar. Nenhum dos dois cobre todo formato, então o .gitignore continua sendo a defesa de verdade.

Limpar a chave do histórico depois é possível e chato. Também é secundário: uma vez rotacionada a chave, a que está no histórico é uma string morta.

O que mais é o GitHub, além de armazenamento?

Coisas que você vai encontrar, em uma linha cada:

Issues — uma lista de pendências anexada ao projeto. Serve para anotações solo, embora um board de verdade seja melhor assim que o trabalho ganha forma.
Actions — automação que roda no push. É assim que os testes rodam e que os deploys disparam. Você vai encontrar na primeira vez que conectar um host.
Releases e tags — um nome fixado a um commit específico. v1-launch é um marcador dizendo esta versão estava boa, e não custa nada.
Pages — hospedagem estática gratuita direto de um repositório. Serve para uma landing, não para nada com backend.
Fork — sua própria cópia do repositório de outra pessoa. Relevante quando você quer mudar o projeto open source de alguém.
Dependabot — abre pull requests quando uma dependência tem uma correção de segurança. Gratuito, vale deixar ligado.
Codespaces — um ambiente de desenvolvimento completo no navegador. Útil quando você quer trabalhar de uma máquina que não tem nada instalado.

Coisas que vão te confundir exatamente uma vez

Cada uma delas produz um momento de alarme genuíno, e cada uma é inofensiva depois que você viu uma vez.

“You are in ‘detached HEAD’ state.” Você olhou um commit antigo e agora está em cima dele em vez de em um branch. Commits feitos aqui não pertencem a nada e são fáceis de perder. git switch main traz você de volta. Nada está quebrado.

Seu repositório contém outro repositório. Um agente rodou git init dentro de uma pasta que já estava em um repo, normalmente enquanto montava alguma coisa. O GitHub então mostra uma pasta que você não consegue abrir e que não contém nada. A correção é apagar a pasta .git interna — e a pista é um commit que adiciona um diretório mas nenhum dos arquivos dentro dele.

Um arquivo é grande demais para enviar. O GitHub rejeita arquivos individuais acima de 100 MB, e um vídeo, um dump de banco de dados ou um node_modules que escapou do .gitignore vão bater nisso. A armadilha é que remover o arquivo não conserta o envio, porque ele continua no histórico — o commit que o adicionou precisa ser desfeito. É bem mais fácil prevenir: confira o .gitignore antes do primeiro push.

Suas duas máquinas discordam. Você commitou no notebook, enviou, e depois commitou no desktop sem dar pull. O Git vai recusar o segundo envio. git pull primeiro, resolva o que ele perguntar, e então envie. O hábito que evita isso por completo é dar pull no começo de uma sessão, não no fim.

O agente commitou como outra pessoa. Commits carregam o nome e o e-mail da sua configuração local do Git, que numa máquina nova pode estar em branco ou errada. Vale configurar uma vez, ou o seu histórico fica assinado por “unknown”.

Truques que se pagam sozinhos

Faça o commit antes de cada sessão com o agente, não depois. O commit não é um registro do que você fez, é o ponto de salvamento que você está prestes a arriscar. Dez segundos, e ele converte todo desastre em git restore .
Peça o diff antes de aceitar. Me mostra o que você mudou e por quê pega o extra prestativo que você não queria, que é a falha mais comum a sobreviver até produção.
Um branch por experimento, e apagar é o desfazer. Mais barato que qualquer revert.
git stash quando o agente reclamar de árvore suja. Ele guarda no bolso o seu trabalho sem commit; git stash pop devolve. Melhor que commitar lixo para se destravar.
--force-with-lease, nunca --force puro. Os dois reescrevem o que está no GitHub. O primeiro recusa se outra pessoa enviou nesse meio-tempo; o segundo sobrescreve sem perguntar.
Proteja a main assim que algo real estiver nela. A proteção de branch do GitHub pode exigir um pull request antes do merge, o que torna “o agente enviou direto para a main às 2 da manhã” estruturalmente impossível em vez de meramente desencorajado.
Marque com tag a versão que funcionou. Antes de uma mudança grande, v-works não custa nada e é trivialmente encontrável, ao contrário de um hash de commit que você nunca vai reconhecer.
Faça squash no merge. Catorze commits de “wip”, “fix”, “agora vai” viram uma entrada com significado, e o seu histórico continua legível por um humano — e pelo próximo agente que o ler.
Lembre que o reflog existe antes de precisar dele. No momento em que você precisar, não vai estar em estado de descobri-lo.

O que fazer no primeiro dia

Crie a conta. Deixe o primeiro repositório privado.
Coloque o .gitignore no lugar com o .env nele, e confira com seus próprios olhos.
Peça ao agente para fazer o primeiro commit e enviar. Olhe o repositório no GitHub e veja seus arquivos ali.
E então, toda vez que algo funcionar: faz o commit disso com uma mensagem clara.

Essa é a prática inteira. Todo o resto desta página está aqui para o dia em que algo der errado — e o motivo para ler agora é que o dia em que algo dá errado é um péssimo dia para estar aprendendo de qual tipo de desfazer você precisa.

O resto da configuração em que isto se encaixa — o modelo, o host, a stack, as salvaguardas — são seis decisões, e o controle de versão é a que todas as outras presumem que você já tem.

Seis decisões antes do seu primeiro prompt, e por que cada uma está ali

Tue, 18 Aug 2026 00:00:00 GMT

Ninguém quer gastar uma tarde com setup. O impulso é abrir um chat e começar a descrever a coisa, e para um protótipo esse é o instinto certo — a primeira semana tem um post próprio e quase todo conselho de lá é vá mais rápido.

Este é o outro post. Ele é para o momento em que você decide que a coisa ainda vai existir mês que vem, e são seis decisões. Cada uma leva minutos. Cada uma fecha um jeito específico de a segunda semana dar errado, e a razão para tomá-las juntas é que as seis são baratas agora e caras depois.

Nenhuma delas é sobre qual modelo é o melhor.

1. GitHub, que é um botão de desfazer com quem você conversa

Se você nunca usou, ignore como costumam descrever. GitHub não é uma rede social para programadores e você não está lá para ler o código de ninguém. É um sistema de save com histórico, hospedado em algum lugar que não é o seu notebook.

Cinco palavras cobrem quase tudo que você precisa:

Repositório — a pasta do seu projeto, mais todas as versões que ela já teve.
Commit — um ponto de save com um bilhete junto. “Tela de login funciona” é um commit.
Branch — uma cópia do projeto onde você pode quebrar coisas sem quebrar o original.
Push / pull — sincronizar entre a cópia da sua máquina e a cópia no GitHub.
Pull request — “aqui está uma mudança, olhe antes de ela entrar”. Sozinho você não vai precisar disso; vai precisar no dia em que outra pessoa tocar no projeto.

E aqui está por que quem faz vibe coding se importa especificamente. Em algum momento — não “talvez” — uma sessão vai reescrever algo que já funcionava. Vai refatorar um arquivo de que você gostava, ou apagar uma função que ela decidiu que não era usada, ou consertar um bug introduzindo dois. Sem commits, esse trabalho se foi e a sua única recuperação é descrever tudo de novo de memória. Com commits, a recuperação é uma frase.

O que traz a parte que ninguém conta para iniciantes: você não precisa aprender Git. Você precisa aprender três frases para dizer ao seu agente.

Faça commit disso com uma mensagem clara.
O que mudou desde o último commit?
Desfaça tudo desde o último commit.

Essa é a interface inteira no primeiro mês. O agente roda os comandos.

Configure assim e pare de pensar nisso: crie a conta, deixe o repositório privado por padrão, e antes de qualquer coisa garanta que .env está no .gitignore. Aquela única linha é o que impede as suas chaves de API de serem publicadas na primeira vez que você fizer push. Chaves vazam de repositórios de iniciantes o tempo todo, e são varridas em minutos.

Depois um hábito, que é a coisa de maior retorno deste post inteiro: quando algo funcionar, faça commit. Não no fim do dia. No momento em que funciona.

Isso basta para começar. O resto — ler um diff sem ler código, os quatro tipos diferentes de desfazer e quando cada um se aplica, o que fazer no dia em que você commitar uma chave de API — está no guia completo.

2. Um modelo, e isso importa menos do que você pensa

Claude Code, Codex, ou um modelo de pesos abertos que você mesmo roda. O enquadramento honesto: essa é a decisão que você pode reverter de graça. O repositório é portátil, os seus prompts são portáteis, e nada do que você constrói fica preso à ferramenta que escreveu.

O que de fato separa essas opções não são notas de benchmark, é se a ferramenta mora dentro do seu projeto:

	O que é	Onde encaixa
Claude Code	CLI agêntica no seu terminal, lê e escreve seus arquivos, roda comandos	Construir funcionalidades inteiras através de muitos arquivos
Codex	O equivalente agêntico da OpenAI, terminal e nuvem	O mesmo trabalho, outro estilo da casa
Pesos abertos (via Ollama, LM Studio, e um cliente como Aider ou Cline)	Modelos rodando na sua máquina ou no seu próprio servidor	Privacidade, controle de custo, sem fatura por token

A recomendação: escolha uma ferramenta agêntica paga e fique nela por um mês. Não porque as outras sejam piores, mas porque a habilidade que você está construindo é saber o que pedir e como perceber que a resposta está errada, e essa habilidade transfere devagar enquanto você ainda troca de ferramenta toda semana.

Sobre open source, sendo direto: é real, é mais barato, é privado, e é o primeiro passo errado. Você vai gastar a primeira semana com setup em vez de com a coisa que queria construir, e trabalhos agênticos longos — muitos arquivos, muitos passos, segurar o plano o caminho todo — são exatamente onde a distância ainda é maior. Volte a isso no mês dois, quando você souber o que está comparando.

E seja qual for a escolha, a alavanca não está no modelo. Está no que o modelo consegue ver sobre o seu projeto, que são as decisões 4, 5 e 6.

3. Um host, e uma conta só se você conseguir

Você vai precisar de algum lugar para colocar. As duas respostas óbvias são Cloudflare e Vercel, e a pergunta que decide não é desempenho.

É quantas contas você quer segurar.

Cloudflare é o tudo-em-um: hospedagem, um banco de dados (D1), armazenamento de arquivos (R2), chave-valor, o próprio domínio, DNS, roteamento de e-mail — um login, uma fatura, um lugar onde as coisas estão erradas quando estão erradas. Para quem está começando, essa consolidação vale mais do que qualquer recurso individual. O preço é um runtime que não é exatamente Node, então um punhado de pacotes do npm não vai rodar lá, e você descobre no deploy e não na instalação.

Vercel te dá o deploy mais suave que existe se você está em Next.js. A troca é que as peças de dados vêm de parceiros do marketplace, então o banco de dados é o painel de outra pessoa, o armazenamento é mais outro, e você vai acabar reconectando três serviços num domingo à noite tentando lembrar qual deles tem a credencial que falhou.

Escolha Cloudflare a menos que você tenha um motivo específico para estar em Next.js.

E compre o domínio no primeiro dia, do mesmo provedor. Custa uns dez euros, leva quatro minutos, e muda como você trata o projeto. Uma coisa com domínio é uma coisa que existe.

4. Uma stack — escolhida por você, e por escrito

A tentação é deixar isso para o modelo. Não deixe, e o motivo não é que a escolha dele seria ruim.

É que o modelo escolhe por conversa. A sessão de segunda escolhe Next.js. A de quarta, sem memória da segunda, escolhe Vite e React Router. A de sexta adiciona uma biblioteca de componentes que duplica a que você já tem. Nada dá erro quando isso acontece — você simplesmente termina com um projeto que são três projetos usando um sobretudo, e cada sessão futura precisa adivinhar em qual convenção está.

Então: React + Tailwind, e diga ao modelo para usar shadcn/ui.

Por que essa combinação específica, se existem várias outras perfeitamente boas:

É a combinação mais bem documentada nos dados de treino de qualquer modelo. Você está escolhendo a região do mapa onde o modelo é mais preciso e menos inventivo, e isso vale mais do que qualquer vantagem técnica no primeiro dia.
O Tailwind mantém o estilo na marcação, então quando você diz “deixe esse card mais compacto”, o agente muda uma linha no arquivo que você está olhando em vez de caçar uma folha de estilo.
Os componentes do shadcn são copiados para o seu repositório, não instalados como dependência. Essa é a parte subestimada. Quando você pede uma mudança num botão, o agente edita o seu botão. Com uma biblioteca de componentes tradicional, ele tem que brigar com a API da biblioteca, e normalmente perde envolvendo tudo em três camadas de bobagem.

Uma exceção, e é comum. Se o que você constrói é quase todo conteúdo — um site, uma landing page, um blog, um conjunto de documentação, com uma pequena área administrativa junto — use Astro no lugar. Ele envia quase nenhum JavaScript por padrão, as páginas ficam rápidas sem você fazer nada, e escala até virar uma aplicação de verdade quando você precisar. Este site é Astro.

Skills: como você para de se repetir

Uma skill é uma pasta com um arquivo SKILL.md dentro que o seu agente lê só quando é relevante. Essa última parte é o ponto inteiro: são instruções disponíveis sem estar no caminho.

A anatomia é pequena. Um arquivo em .claude/skills/<nome>/SKILL.md, começando com:

---
name: my-design-system
description: Use ao construir ou reestilizar qualquer UI deste projeto —
  cores, tipografia, espaçamento, padrões de componentes.
---

Tudo o que o agente deveria saber, em markdown comum.

A linha description é a importante, porque é contra ela que o agente compara para decidir se carrega a skill. Descrição vaga, skill que nunca dispara.

Dois lugares para colocá-las: .claude/skills/ dentro do seu projeto, o que significa que vai commitada no GitHub e continua lá amanhã e na sua outra máquina, ou ~/.claude/skills/, para coisas que você quer em todo projeto que tocar. Prefira a do projeto — uma skill que descreve este produto pertence a este produto.

Para instalar uma que alguém te deu: solte a pasta lá, abra uma sessão nova, e pergunte quais skills você tem disponíveis. Se não listar, a descrição é a primeira coisa a checar.

Esse é o formato. Por que a descrição é a única parte que sempre carrega, o que vai numa skill contra o que vai no AGENTS.md, e o jeito mais rápido de escrever a sua primeira — o guia completo.

(Skills são um recurso do Claude Code. Se você foi de Codex, a alavanca equivalente é o arquivo AGENTS.md descrito na seção extra — mesma ideia, com carregamento menos seletivo.)

A de design vale a pena no primeiro dia. Se você tem uma ideia mas nenhuma marca, nenhuma cor e nenhuma opinião visual ainda, vá em startpow.com, escolha o que você gostar, exporte, e escolha o download de skill. Solte em .claude/skills/. A partir desse momento toda tela que o agente construir chega nas suas cores, com a sua tipografia e o seu espaçamento, sem você descrever de novo — o que é a diferença entre um produto e uma demo, e custa uns dez minutos.

5. Algo que lembre, para amanhã não ser uma reconstrução

Esta é a falha de que essa decisão trata, e vale a pena ser preciso porque a versão popular está errada.

O modelo não é malicioso. Ele é prestativo e rápido, em lugares onde errar sai caro. O banco de dados não é derrubado por uma IA rebelde; ele é derrubado porque uma migração estava quebrada, derrubar a tabela era o caminho mais curto para um teste passando, e ninguém foi consultado. O auth não é reescrito num ato de sabotagem; ele é reescrito porque um teste estava falhando e a checagem de auth era o que fazia falhar.

Duas camadas de defesa, e a primeira é de graça:

Os hábitos. Um banco de desenvolvimento que não é o banco de produção. Credenciais de produção que o agente nunca segura. Um commit antes de começar qualquer coisa. E a instrução que quase ninguém dá — o que ele não pode tocar. Modelos são prestativos; vão fazer com prazer uma coisa útil que você não queria.

As ferramentas. É isso que o CommitCycle é: o trabalho começa como uma task com um escopo declarado, o agente ganha acesso preso àquela única task e a um único branch e isso expira sozinho, os paths que de fato doeriam carregam um owner que precisa dizer sim, e cada task fecha com um registro do que foi declarado contra o que foi tocado.

Agora o limite honesto, que é também a frase mais importante daqui: isso não remove a possibilidade. A responsabilidade final é sempre da pessoa que aprova o que o agente pede. O agente executa; você consente. O que a ferramenta remove é a classe de acidente em que ninguém podia dizer não, porque ninguém foi consultado — e essa classe é a maioria deles.

Se você quiser: /plugin marketplace add pow-paulinho/commitcycle-plugin e depois /plugin install commitcycle@commitcycle, no Claude Code, ou npm i -g commitcycle para a CLI. O board hospedado é só por convite enquanto isso é pequeno.

6. E agora? Comece pelo formato, não pela tela

Você tem as seis peças. O instinto é mandar construa a home para mim, e é o primeiro passo errado — não porque a home não importe, mas porque ela é consequência de decisões que você ainda não tomou.

A primeira pergunta útil é: isso precisa de contas? Quase tudo se organiza em quatro superfícies a partir daí.

Superfície	O que é	Você precisa?
Parte pública	Tudo que é visível sem fazer login	Quase sempre
Auth	Cadastro, login, recuperar senha, verificar e-mail	Só se existir um “seu” alguma coisa
O produto	O que as pessoas veem depois de fazer login	Se tem auth, então sim
Admin	Onde você vê usuários, pagamentos, problemas	Sim, e todo mundo esquece até a segunda semana

Se a resposta honesta for “quase toda parte pública, admin pequeno”, construa em Astro e não adicione um sistema de autenticação que você vai manter para um usuário só. Se for “quase todo produto”, o auth e o modelo de dados são a primeira coisa, porque todo o resto pendura neles.

Os prompts

Primeiro, o que não escreve código. Esse é o prompt de maior valor do processo inteiro e é o que a maioria pula:

Quero construir: [descreva em três ou quatro frases, incluindo para
quem é e pelo que pagam, se pagam algo].

Não escreva código ainda. Me entreviste — me faça as perguntas que
você precisa que eu responda para planejar isso direito, em lotes.

Quando tiver o suficiente, me devolva:
1. As telas, agrupadas em público / auth / produto / admin
2. O modelo de dados, como lista de entidades e como se relacionam
3. Qualquer serviço de terceiros que isso precise e por quê
4. O que você construiria primeiro, e o que deixaria
   deliberadamente para depois

Você está fazendo o modelo produzir uma pergunta, e revisar uma pergunta é muito mais barato do que revisar trezentas linhas de uma resposta construída sobre uma suposição que você nunca viu.

Segundo, a fundação. Faça o deploy da coisa vazia no primeiro dia — “colocar no ar” nunca deveria virar um projeto próprio mais tarde:

Monte o esqueleto do projeto:
- [Astro | React + Vite], TypeScript, Tailwind, shadcn/ui
- Destino de deploy: Cloudflare
- Um repositório Git com um primeiro commit, enviado ao GitHub

Deixe uma página vazia com deploy feito e me dê a URL no ar antes de
adicionar qualquer funcionalidade.

Depois escreva AGENTS.md na raiz registrando: a stack e as versões, a
estrutura de pastas, as convenções de nomes, os comandos para rodar e
buildar, e qualquer coisa que você nunca deve fazer neste projeto.

Não adicione autenticação, banco de dados nem nenhuma dependência
além do acima ainda.

Terceiro, as superfícies que precisam de um sistema atrás:

Construa cadastro e login: criar conta, entrar, sair, recuperação de
senha, verificação de e-mail.

Use [o provedor de auth que você escolheu] em vez de fazer na mão.
As telas usam nossos componentes existentes — não introduza uma
segunda biblioteca de componentes.

Me dê também a menor página de admin que liste usuários, porque eu
preciso conseguir ver se isso funciona.

NÃO toque: pagamentos, as páginas de marketing, nada abaixo de [path].
Se você esbarrar numa decisão que eu não tomei — preços, duração da
sessão, o que acontece com contas não verificadas depois de uma
semana — pare e pergunte em vez de escolher.

Repare nas duas linhas que quase ninguém escreve: o que ele não pode tocar, e pare e pergunte em vez de escolher. Essas duas linhas evitam mais retrabalho do que qualquer quantidade de refinamento em prompt engineering.

Quarto, quando funcionar, deixe com a sua cara: instale a skill de design e peça para reestilizar uma tela com ela. Confira essa. Depois deixe rodar no resto.

7. Histórias de usuário, que é onde isso fica real

Se você consegue narrar o que uma pessoa faz, você consegue construir. Pegue a frase do próprio usuário:

Alguém vê um anúncio, cai no site, cria uma conta, assina um plano, paga com cartão, e a assinatura dele libera o acesso.

Leia de novo devagar, porque essa frase única é uma especificação. Ela contém:

Uma landing page para onde o anúncio aponta, que não é a home
Cadastro, e portanto verificação, e portanto e-mail que chega de verdade
Provavelmente onboarding, porque uma conta nova e vazia é onde as pessoas vão embora
Um provedor de pagamento — Stripe, na prática — e um checkout
Um webhook, porque o pagamento dá certo nos servidores da Stripe e o seu app tem que descobrir
Entitlement: algum estado que diga que essa conta agora é assinante
Feature gating guiado por esse estado, em todo lugar onde importa
O caminho de falha: cartão recusado, pagamento que deu certo mas webhook que não chegou, assinatura cancelada no meio do mês
Uma visão de admin, para que quando alguém te escrever dizendo que pagou e nada liberou, você consiga olhar

Uma frase, nove itens de trabalho, e os três últimos são os que são descobertos em produção, por um cliente, se ninguém escreveu.

Isso também é trabalho que o modelo faz bem — entregue a história e pergunte o que ela implica, e ele vai produzir uma lista muito parecida com a de cima. O que ele não consegue é lembrar da lista na terça que vem. É para isso que serve um board: cada item vira uma task com um escopo, uma task vira um branch, e o branch fecha com um registro do que realmente mudou.

Isso soa chato. É, um pouco. E no interesse de não vender demais: três prompts realmente conseguem te dar algo que roda e parece bom, e a emoção de ver funcionando é real e vale a pena ter. Vá lá e tenha.

Mas a coisa que ainda está de pé no mês três, que você consegue entregar para outra pessoa, que você consegue mudar sem prender a respiração — essa foi construída por alguém que escreveu o que ela deveria fazer. Consistência é sem glamour e é a diferença inteira.

Faixa bônus

Coisas pequenas, na ordem aproximada de quanto arrependimento elas evitam:

AGENTS.md na raiz do repositório. O arquivo de maior retorno que você vai escrever. Stack, convenções, comandos, e a lista de coisas para nunca fazer. Toda ferramenta agêntica lê. O nosso guarda ali o mapa de zones e escreve a task ativa num CLAUDE.local.md ignorado pelo git, que é limpo na entrega, mas um escrito à mão já é a maior parte do valor.
Dois bancos de dados desde o primeiro minuto. Desenvolvimento e produção, nunca as mesmas credenciais, e o agente só segura o de desenvolvimento. Essa é a defesa específica contra o desastre específico.
Segredos nunca no repositório. .env no .gitignore, valores reais no cofre de segredos do seu host. Rotacione qualquer coisa que chegou a ser commitada — apagar o arquivo não remove do histórico.
Deploys de preview por branch. Tanto Cloudflare quanto Vercel te dão uma URL por branch de graça. Ver a mudança numa URL real antes de ir ao ar vale mais do que qualquer quantidade de teste local.
Deixe o agente ver o que ele construiu. Capturas de tela, ou uma ferramenta de navegador que ele possa dirigir. Um agente construindo UI sem nunca olhar está trabalhando às cegas, e dá para perceber.
Rastreamento de erros, mais exatamente um número de analytics que você olha de verdade. Mais do que um e você não vai olhar nenhum.
Termos e política de privacidade antes de cobrar um cartão. A Stripe vai pedir um site funcionando com os dois antes de ativar a conta, e descobrir isso no dia do lançamento é um dia ruim.
Conheça a sua restauração, não só o seu backup. Um backup não testado é uma crença, não um backup.
Um arquivo de decisões. Três linhas por decisão: o quê, por quê, o que você rejeitou. Seis semanas depois é a única coisa entre você e relitigar tudo com um modelo que não estava lá.
Espere o modelo custar mais do que a hospedagem. Essa proporção está certa e não é sinal de que você está fazendo errado.

O setup inteiro acima é uma tarde. O que ele compra é que a segunda semana seja uma continuação em vez de um projeto de arqueologia — e se você quer os hábitos que vão em cima disso, esse é o post da primeira semana.

Vibe coding, e a primeira semana que não termina em bagunça

Fri, 14 Aug 2026 00:00:00 GMT

Vibe coding é construir descrevendo o que você quer e aceitando o que o modelo escreve sem ler tudo. O termo é do Andrej Karpathy, e o que distingue não é a IA ter escrito o código — isso hoje é comum — mas que ninguém revisou linha por linha.

Isso é uma troca, não um erro. Se é uma boa troca depende inteiramente de uma pergunta: por quanto tempo esse código precisa viver?

Onde o vibe coding funciona de verdade?

Protótipos que você pretende apagar. O custo de errar é jogar fora, que era o que você ia fazer de qualquer jeito.

Scripts e ferramentas de uso único. Uma coisa que reformata um CSV, popula um banco de dados, faz scraping de uma página uma vez só. Se produz a saída certa, acabou; ninguém vai manter aquilo.

Aprender o formato de algo desconhecido. Conseguir um exemplo funcionando de uma biblioteca que você nunca usou é mais rápido assim do que ler a documentação antes, e você pode ler a documentação depois com uma coisa concreta na frente.

Qualquer coisa em que o feedback seja imediato e total. Se funciona, funciona, e você descobre em dez segundos.

O fio comum é que errar é barato e óbvio. Essa é a condição. Não o tamanho do projeto, nem a linguagem, nem se é “de verdade” — só se um erro aparece na hora e custa pouco.

Quando ele para de funcionar?

No momento em que o código sobrevive à sessão que o produziu.

Isso não é um julgamento moral. É aritmética: você comprou velocidade pulando o entendimento, e a conta chega quando alguém precisa mudar código que ninguém entendeu quando foi escrito. Se ninguém nunca mudar, a conta nunca chega e a velocidade saiu de graça. Esse é um desfecho real e acontece muito.

O que faz dar errado é não saber em qual dos dois casos você está. Quase toda experiência ruim começa como um protótipo que virou crítico em silêncio, sem ninguém decidir nada.

Como sei em qual caso estou?

Três perguntas, e elas são sobre a situação mais do que sobre o código:

Pergunta	Vibe coding vale quando	Deixa de valer quando
Com que rapidez descubro que errei?	Em segundos. Você roda e vê	Em semanas, por um cliente
Quanto custa errar?	Você apaga e começa de novo	Dinheiro, dados ou a confiança de alguém
Quem mais depende disso?	Ninguém	Qualquer pessoa que não seja você

As três apontando para o mesmo lado é o caso para o qual isso foi feito. As três apontando para o outro lado e você não está fazendo vibe coding, está apostando com passos a mais.

O útil é que isso se decide por peça de trabalho, não por projeto. A mesma tarde comporta um script descartável que você nunca lê e uma mudança de permissões que você lê duas vezes. Tratar um repositório inteiro como um ajuste único é o que produz os dois erros comuns: ler tudo num protótipo, e não ler nada na parte que morde.

O que eu nunca deveria fazer com vibe coding?

Uma lista curta, e o motivo é o mesmo em todos os itens:

Autenticação e permissões. Errar aqui não lança erro. Deixa a pessoa errada entrar em silêncio, e você descobre por outra pessoa.
Dinheiro. Preços, cobranças, estornos, moeda. Um off-by-one num laço é um bug; um off-by-one em centavos é um chargeback e um e-mail que você não quer escrever.
Qualquer coisa que apague. Exclusões em cascata principalmente. O teste dessa categoria é se existe um desfazer.
Migrações de banco de dados. Rodam uma vez, contra dados reais, e a falha é descoberta depois que os dados já se foram.
Tudo que lida com dados pessoais dos outros. Errar aqui vem com um regulador junto.

Repare no que não é o critério: dificuldade. Alguns desses são código fácil. A propriedade que compartilham é que errar não se anuncia sozinho — que é exatamente a suposição sobre a qual o vibe coding roda.

Isso não é “escreva você mesmo”. É “leia esse aqui”. Deixe o modelo escrever, depois leia de verdade o que ele escreveu, e peça que explique as partes que você não conseguir acompanhar. A leitura é todo o custo, e nessas cinco vale a pena pagar.

A primeira semana

Mantenha as sessões curtas, e termine cada uma em algo que funciona. Esse é o hábito de maior retorno e não tem nada a ver com a IA. Uma sessão longa acumula decisões que ninguém escreveu, e quando enfim algo está errado não existe ponto para voltar. Sessões curtas com um commit que funciona no fim te dão um lugar para onde voltar.

Leia as partes caras. Não tudo — isso derrubaria o propósito. Leia qualquer coisa que toque dinheiro, autenticação, exclusão de dados, ou código em que outra pessoa também trabalha. O resto, passe o olho. A habilidade construída aqui é triage, e é uma habilidade real: saber onde errar sai caro é a maior parte do que engenheiros seniores sabem.

Diga o que ele não pode fazer. Quase todo mundo descreve o que quer e para por aí. A instrução que mais economiza tempo é a que exclui coisas — não toque no módulo de auth, não adicione dependências, não mude o schema do banco. Modelos são prestativos e vão fazer com prazer uma coisa útil que você não queria.

Rode antes de acreditar. Código gerado que parece certo e não roda é a falha isolada mais comum, e a mais barata de pegar.

Perceba quando o protótipo deixou de ser protótipo. Costuma existir um momento específico: outra pessoa abre, ou vai para a frente de um usuário, ou você faz deploy. Esse é o momento em que a troca muda, e a resposta honesta é voltar e ler direito.

Como é uma boa sessão, do começo ao fim

Concretamente, porque “mantenha as sessões curtas” é um conselho com o qual você concorda e mesmo assim não aplica:

Comece de um commit. Não de um repositório arrumado — de um com commit. Esse é o ponto de save, e leva dez segundos.
Diga o objetivo e o limite na mesma mensagem. O que você quer, e o que está fora de alcance. A segunda metade é a que as pessoas pulam.
Deixe trabalhar sem interromper. Corrigir o rumo no meio do voo produz uma mudança que é metade de um plano e metade de outro, o que é mais difícil de ler do que qualquer um dos dois.
Leia o diff, não a base de código. Quantos arquivos, quais arquivos, e se apagou algo que você não pediu para apagar.
Rode. Antes de acreditar em qualquer parte.
Faça commit, ou jogue a sessão inteira fora. Os dois são desfechos aceitáveis. O que não é aceitável é carregar um estado meio pronto para a próxima sessão.

Cerca de uma hora é onde isso costuma cair para a maioria, e o número importa menos que o formato: a sessão é a unidade que você pode jogar fora. Assim que uma sessão está longa a ponto de descartá-la ser impensável, você perdeu a propriedade que tornava toda a abordagem segura — e isso acontece de forma gradual, que é justamente por que vale a pena ficar de olho.

As perguntas que as pessoas realmente fazem

“Eu ainda sou um desenvolvedor de verdade fazendo isso?”

A pergunta por baixo é se você está construindo uma habilidade ou fugindo de uma. Está construindo uma — triage, especificação, saber onde o risco mora — e não é a mesma habilidade de escrever a sintaxe você mesmo. As duas são reais. Nenhuma se basta sozinha.

“Como impeço que ele invente bibliotecas que não existem?”

Rode o código. Imports alucinados falham na hora, o que faz dessa a classe de erro menos perigosa. Preocupe-se mais com os que rodam.

“Ele reescreveu algo que eu não pedi para tocar.”

Muito comum, e a correção normal é dizer o que está fora de alcance antes de começar. Num repositório em que outras pessoas trabalham, isso deixa de ser um incômodo e vira o problema de verdade — o que tem um post próprio.

“Devo fazer commit de código que não li?”

Em algo descartável, sim. Em algo compartilhado, você está entregando aos seus colegas um diff sobre o qual não consegue responder perguntas, e isso é um problema social antes de ser técnico.

“É assim que times profissionais trabalham agora?”

Em parte, e honestamente a resposta ainda está se movendo. O que está claro é que a restrição saiu de com que rapidez isso pode ser escrito para com quanta confiança isso pode ser mudado depois, e os times que vão bem são os que tratam isso como o eixo do desenho.

Para onde isso está indo, e o que a gente faz a respeito

Tudo acima funciona para uma pessoa sozinha na própria máquina. As falhas interessantes começam quando o repositório é compartilhado — quando o código gerado é localmente razoável e globalmente errado porque o modelo não conseguia ver uma convenção que mora na cabeça de alguém.

Esse é o problema em que o CommitCycle trabalha: cada agente ganha um grant preso a uma task e a um branch que expira sozinho, os paths que doeriam carregam um owner, e cada task fecha com um registro do que declarou contra o que tocou.

Sendo direto sobre onde isso está: o plugin instala hoje o enforcement, e o pacote commitcycle no npm instala a CLI — o processo sem o muro. O board hospedado é só por convite enquanto isso é pequeno. E nada disso é o que você precisa na sua primeira semana de vibe coding — na primeira semana você precisa de sessões curtas e do hábito de ler as partes caras.

Na semana seguinte, quando você já tiver decidido que a coisa vai existir além da sexta, a pergunta sai de hábitos e vai para setup: o que ter no lugar antes do primeiro prompt, e por que cada peça está ali.

O que quebra quando o vibe coding chega num repositório compartilhado

Fri, 14 Aug 2026 00:00:00 GMT

Tudo sobre vibe coding muda quando o repositório tem outras pessoas dentro. Não porque o código fique pior, mas porque o jeito como ele falha deixa de ser visível.

Na sua própria máquina, um erro aparece como algo que não funciona. Num repositório compartilhado, a falha característica é código que funciona, se lê como razoável, passa na revisão e mesmo assim está errado — porque quebrou uma regra que nunca foi escrita em nenhum lugar que o modelo pudesse ler.

O formato disso

Pede-se a um agente que adicione um campo a um formulário. Ele adiciona, com competência. Ele também adiciona uma migração de banco de dados, porque é isso que adicionar um campo geralmente exige.

A migração está boa. O problema é que este time aplica migrações à mão, numa ordem específica, depois de uma revisão da pessoa que é owner do schema — uma convenção que existe por causa de um incidente de dezoito meses atrás, é conhecida por quatro pessoas, e não está escrita em lugar nenhum.

Nada naquele diff parece errado. Essa é a falha. Não é código ruim; é código localmente razoável e globalmente errado, e a distância entre essas duas coisas é exatamente a distância entre o que está no repositório e o que está na cabeça de alguém.

Por que a revisão não pega isso?

A revisão lê o diff e pergunta se ele é bom. Essa classe de problema é invisível para essa pergunta, porque o diff é bom. O defeito mora na relação entre a mudança e um pedaço de contexto que não está na tela.

Quem revisa só pega se por acaso carregar a convenção e por acaso lembrar dela enquanto lê. Isso funciona, às vezes, quando quem revisa é uma das quatro pessoas. Para de funcionar no momento em que o volume sobe — e o volume subir é o ponto inteiro de usar agentes.

Então o conselho de sempre, revise código gerado por IA com mais cuidado, está meio certo e não escala. Revisão cuidadosa linha por linha de tudo remove o motivo de gerar em primeiro lugar.

Qual é a falha que custa mais?

Dois agentes, ao mesmo tempo, no mesmo repositório.

Cada um está correto isoladamente. Cada um passa nos próprios testes. Um refatora um helper de que o outro depende; ou os dois tocam a mesma configuração de direções opostas; ou um move um arquivo em que o outro está escrevendo. Nada dá erro. Os dois branches estão verdes.

A perda aparece dias depois como uma mudança que foi feita e depois não estava mais lá, e ninguém consegue dizer quando ela parou de existir. É cara justamente porque não existe um momento de falha para apontar — você está reconstruindo um negativo a partir do histórico do git.

Isso não é hipotético e não é raro. É a consequência comum de rodar mais de um agente num repositório, o que hoje é uma terça-feira normal.

Como sei que isso já está acontecendo?

Não chega como um incidente, e essa é a dificuldade. Chega como um conjunto de fatos pequenos que cada um tem uma explicação individual plausível:

Trabalho que foi feito e depois não estava lá. Alguém lembra de ter escrito. O git diz que existiu. Ninguém consegue nomear o commit que removeu.
O mesmo bug corrigido duas vezes, com três semanas de diferença, por duas pessoas que cada uma achou que era a primeira.
Uma convenção reexplicada em três sessões separadas, porque cada sessão começou sem memória da anterior e ninguém escreveu no meio.
Um pull request que toca arquivos que ninguém esperava, onde os arquivos a mais são todos individualmente defensáveis.
“Quem mudou isso?” respondido por uma mensagem de commit que diz refactor e um autor que não estava lendo com atenção.

Qualquer uma dessas sozinha é uma semana ruim comum. Todas juntas são a falha, e o motivo de ela ficar sem nome por tanto tempo é que não existe erro para procurar. Você está procurando a ausência de uma coisa, e ausências não acionam ninguém.

E se as outras pessoas forem os meus próprios agentes?

A inversão que pega mais gente de surpresa: você não precisa de um time para ter um problema de repositório compartilhado. Dois terminais bastam.

Um repositório não sabe que duas sessões pertencem ao mesmo humano. Toda propriedade que torna isso difícil num time está presente quando você está sozinho — escritas concorrentes nos mesmos arquivos, nenhuma memória compartilhada entre as sessões, convenções que existem só na sua cabeça — e uma propriedade é estritamente pior. Num time, o trabalho do segundo agente é pelo menos lido por uma pessoa diferente. Quando os dois são seus, você aprova os dois, rápido, na mesma tarde, e não existe um segundo leitor em lugar nenhum do circuito.

É por isso que “sou desenvolvedor solo, isso não se aplica a mim” normalmente já está errado no momento em que alguém diz. O limiar não é o número de pessoas. É o número de coisas escrevendo no repositório ao mesmo tempo.

AGENTS.md e CLAUDE.md resolvem isso?

A resposta padrão é um CLAUDE.md ou um AGENTS.md com as suas convenções dentro. Escreva um. Ajuda de verdade, e é a coisa mais barata desta lista.

Ele também apodrece, pela mesma razão que toda documentação apodrece: é uma foto do que alguém lembrava no dia em que escreveu, e nada força a revisitá-lo quando a coisa que ele descreve muda. Seis meses depois é uma mistura de verdadeiro, vencido e aspiracional, e um agente lendo não consegue dizer qual linha é qual. Uma pessoa recém-contratada também não.

Um arquivo de contexto é necessário e não é suficiente, e o vão entre essas duas coisas é onde está o trabalho interessante.

O que ajuda de verdade?

Nomeie os paths onde errar sai caro. Não tudo — a maior parte de um repositório é genuinamente segura para mudar, e tratar tudo como perigoso significa que nada é. Uma lista curta dos paths que doeriam vale mais do que uma exaustiva, porque uma lista curta é lida.

Dê a cada um deles um owner. Não por burocracia: para que “isso deveria mudar?” tenha a quem perguntar. Uma regra sem owner é uma regra contornada no primeiro inconveniente, por humanos tanto quanto por agentes.

Defina o escopo do trabalho antes de ele começar, não depois. O que isso deve fazer, o que não pode tocar, quais áreas toca. Escrito antes de o código existir, isso é uma especificação. Escrito depois, é uma desculpa.

Torne possível ver o que uma peça de trabalho de fato tocou, contra o que ela disse que tocaria. Essa diferença é onde estão as surpresas, e é uma pergunta que o git consegue responder se alguém fizer.

Nada disso precisa de um produto. Precisa que a lista exista em algum lugar que tanto as pessoas quanto os agentes consigam ler.

O que eu posso fazer na segunda-feira, sem comprar nada?

Em ordem, porque fazer as duas primeiras é a maior parte do valor:

Escreva os cinco paths onde errar sai caro. Cinco, não cinquenta — o ponto é que a lista seja lida. Migrações, auth, o código de pagamentos, a configuração compartilhada, os que forem os seus.
Coloque um nome ao lado de cada um. Para que “isso deveria mudar?” tenha para onde ir. Não precisa ser um owner formal; precisa ser uma pessoa.
Comece toda peça de trabalho dizendo o que ela não pode tocar. Uma linha, antes de o código existir. Essa é a frase de maior rendimento do desenvolvimento agêntico e não custa nada.
Uma vez por semana, olhe o que de fato mudou contra o que você achava que estava sendo trabalhado. Não uma revisão do código: uma comparação de duas listas. O vão é onde as surpresas moram, e uma vez por semana basta para pegá-las enquanto ainda estão baratas.

Nada disso é um produto e nada disso precisa de permissão. Se acabar importando para você, a próxima pergunta é o que impõe isso quando todo mundo está ocupado — que é onde o resto disso fica interessante.

Onde o CommitCycle entra

Essa lista é a coisa sobre a qual a gente constrói. As zones são os paths que doeriam, cada uma com um owner e um risk level. Uma task declara o que toca antes de começar, e mover um muro exige uma aprovação com um motivo. Cada agente ganha um grant preso a uma task e a um branch que expira sozinho, então duas sessões em worktrees próprios não conseguem se autorizar mutuamente em silêncio — dividindo um mesmo diretório elas ainda conseguem, e é por isso que o worktree é a instrução, não uma preferência. Cada task fecha com um registro do que declarou contra o que tocou.

Onde isso de fato está, em bom português: o enforcement se instala hoje como plugin do Claude Code; o pacote commitcycle no npm coloca cycle no seu PATH e não carrega hook, então ele te dá o processo sem o muro. O board hospedado é só por convite enquanto isso é pequeno. O modelo de zones é agnóstico de agente, mas o ponto de enforcement precisa de um pequeno adaptador por harness, e hoje só o do Claude Code foi visto negando numa instalação real.

E o limite honesto que vale repetir: negar uma chamada de ferramenta em voo não é o que torna isso diferente. Vários fornecedores entregam isso e o Claude Code inclui de graça. A parte que é nossa é o grant preso a uma única task, atribuído a um owner, e que expira sozinho — e o registro depois que diz o que realmente aconteceu.

Se você é uma pessoa só num protótipo, nada disso é problema seu ainda, e o post dos primeiros passos é o mais útil — ou o do setup, se o protótipo começou a parecer que vai sobreviver ao mês.

O que tirar do Obsidian, e o que deixar nele

Fri, 14 Aug 2026 00:00:00 GMT

O post anterior argumentou que um vault do Obsidian não pode ser a base de conhecimento dos seus agentes de IA: ele é privado de uma máquina, suas afirmações não têm procedência e nada marca uma nota como vencida.

Concordam com esse argumento e depois não agem, porque “mova o seu conhecimento” não é uma coisa que alguém consiga começar numa terça-feira. Este post é a metade prática. O que sai de fato, o que fica, e como o substituto se parece depois de estar rodando.

A linha, aplicada por nota

Se errar sobre esta nota levaria outra pessoa a errar junto, ela passou do ponto de um vault pessoal.

Por nota, não por vault. Essa distinção é o ponto inteiro, e é por isso que o trabalho é menor do que parece. A maior parte de um vault é pensamento — conexões pela metade, restos de reunião, coisas que você escreveu para descobrir o que pensava. Nada disso sai. O que sai é a minoria sobre a qual outras pessoas, ou um agente, agiriam.

Na prática isso tem sido menos de um quinto das notas em todos os casos que acompanhei. O resto fica exatamente onde está.

O que sai?

Convenções. “A gente faz migrations em duas etapas.” “Os handlers devolvem o erro, não fazem log dele.” Qualquer coisa formulada como a gente faz X é uma afirmação sobre o time, e uma afirmação sobre o time pertence a onde o time consegue ver e corrigir.

Decisões, com os motivos. Não só o que foi escolhido, mas o que foi descartado e por quê. Esta é a categoria de maior valor e a que mais se perde, porque o raciocínio mora na cabeça de alguém e o vault registra só a conclusão. Um agente que recebe a conclusão sem o motivo vai desfazê-la alegremente na primeira vez em que a conclusão for inconveniente.

Qualquer coisa sobre a qual um agente agiria. Se uma nota mudaria o que é escrito quando um agente a lê, ela é operacional, não pessoal. É a categoria mais nova e aquela para a qual os vaults nunca foram projetados.

Os limites. “A gente deliberadamente não faz X, e eis o porquê.” Ninguém escreve isso e todo mundo redescobre pelo caminho caro.

O que fica?

Todo o resto, e isso não é prêmio de consolação.

Ideias pela metade. Notas que têm permissão de estar erradas. A conexão que você ainda não fez. Notas de leitura, restos de reunião, aquilo que você escreveu às 2 da manhã e que fazia sentido às 2 da manhã. O Obsidian é melhor em tudo isso do que qualquer coisa pela qual você o trocaria, e é melhor porque não tem revisão, nem aprovação, nem plateia — exatamente as propriedades que o desqualificam para a outra categoria.

Um vault que guarda só isso é um vault fazendo o seu trabalho.

E as notas que são metade pensamento, metade convenção?

O caso desconfortável de sempre, e o que trava as pessoas, porque a linha parece limpa até você encontrar uma nota real de duas mil palavras remoendo um assunto com uma decisão de verdade enterrada no fim.

Divida, e é mais fácil do que parece. O pensamento fica no vault. A afirmação sai, sozinha, como uma frase. Linke de volta, se quiser.

O que você não pode fazer é mover a coisa inteira. Uma nota que é oitenta por cento tateio e vinte por cento decisão, sentada no repositório, ensina a um agente que as convenções do seu time são provisórias — e um agente que acha que uma regra é provisória vai negociar com ela na primeira vez em que a regra for inconveniente. Deixar a coisa inteira no vault tem a falha oposta: os vinte por cento de que as outras pessoas precisam ficam invisíveis, indistinguíveis da divagação ao redor.

O teste para saber se uma nota está pronta: você consegue extrair uma frase que comece com “a gente faz” ou “a gente não faz”? Se não, ainda não há nada para mover, e a nota continua fazendo o seu trabalho onde está.

Onde as notas que saem devem morar?

No repositório que elas descrevem. Não num wiki, não numa segunda ferramenta: no repo, revisadas no mesmo pull request que o código de que falam.

Essa colocação é o que faz o trabalho. Uma nota no repo é lida no momento em que alguém muda a coisa que ela descreve, porque ela está no diff. Uma nota num wiki é lida quando alguém vai procurar, que é o modo de falha que você está deixando para trás.

Isso também significa que a nota é revisada como código. Alguém aprova. Alguém responde por ela. Dois engenheiros não conseguem manter duas versões contraditórias sem que uma delas apareça num diff.

Como é uma nota depois de sair?

O formato importa menos do que quatro propriedades, e cada uma responde a um jeito pelo qual a versão do vault falhava:

Uma afirmação por nota. “A gente faz migrations em duas etapas” é uma nota. “Notas sobre o nosso backend” é uma pasta usando o nome de uma nota, e nada lá dentro pode ser confirmado, contradito ou arquivado de forma independente.
Ela diz de onde veio. A decisão, o incidente, o pull request. Uma afirmação que você não consegue rastrear é uma afirmação que você não consegue pesar, e mover uma afirmação irrastreável para o repositório realoca o problema em vez de resolvê-lo.
Ela diz o que foi descartado. A conclusão sem o raciocínio é desfeita na primeira vez em que a conclusão for inconveniente — normalmente por um agente, alegremente, num diff que parece uma simplificação.
No presente, e específica o bastante para poder estar errada. “Cuidado com migrations” não é uma nota, é um estado de espírito. Ninguém consegue agir sobre ela e ninguém jamais conseguirá provar que ela venceu.

E curta. A razão pela qual páginas de wiki não são lidas é que elas têm duas mil palavras quando a afirmação é uma linha, e uma nota que ninguém lê é uma nota que não existe — que é o mesmo desfecho de deixá-la no vault, depois de mais trabalho.

O que isto não resolve?

Mover notas para o repo resolve descoberta e revisão. Não resolve o apodrecimento, e qualquer post que dissesse o contrário estaria vendendo alguma coisa para você.

Uma nota num repositório vence exatamente na mesma velocidade que uma nota num vault. O que muda o apodrecimento não é o lugar, é um gatilho — algo que force o conhecimento a ser escrito enquanto a pessoa ainda lembra o porquê, e algo que permita tirar uma nota errada por um mecanismo, e não pela memória de alguém.

Essas são as duas propriedades a procurar no que quer que você use, e são as duas sobre as quais o CommitCycle constrói: o conhecimento é alimentado no fechamento de uma unidade de trabalho, uma linha por vez, enquanto o motivo ainda está fresco; e archived é um estado real, que é o que permite ao conjunto encolher em vez de só ficar mais confiante.

Como eu começo sem uma migração?

Não migre. Migrações de conhecimento falham pela mesma razão que migrações de qualquer coisa falham — o esforço vem na frente e o retorno fica difuso.

Em vez disso: na próxima vez que você escrever uma nota da qual outras pessoas dependeriam, escreva no repo em vez de no vault. Depois a seguinte. O vault para de crescer na categoria que dói, e o conjunto que importa começa a se acumular no lugar onde é revisado. Nada é movido e nada é perdido.

Para as notas cujos leitores são agentes e não pessoas, o destino tem um formato: uma skill é uma pasta no repositório que é carregada quando fica relevante e ignorada quando não fica, que é a coisa mais próxima de uma nota de vault que um agente consegue de fato usar.

Depois de algumas semanas, o que continuar no vault e continuar sustentando peso é uma lista curta, e a essa altura você vai saber exatamente quais notas estão nela.

Como eu sei que está funcionando?

Quatro sinais, mais ou menos na ordem em que aparecem:

Você para de reexplicar a mesma coisa a cada sessão nova. Este chega primeiro e é o mais imediatamente satisfatório.
Alguém corrige uma nota durante um code review. Isso é a colocação dando retorno: significa que a nota foi lida no momento em que a coisa que ela descreve estava sendo mudada, que é a razão inteira de ela ter ido para o repositório.
Um agente cita uma delas de volta para você — propondo algo e nomeando a nota de onde aquilo veio, em vez de propor algo plausível.
Alguém arquiva uma. Este é o sinal de verdade, e é o que demora mais. Um conjunto que só cresceu está sendo acumulado, não mantido, e vai acabar exatamente onde o vault estava: mais confiante a cada mês e menos exato.

O contrassinal é o espelho desse último. Se as notas do repositório crescem e nada nunca foi removido, você reconstruiu o vault com cerimônia extra, e o vencimento está a caminho.

Onde o CommitCycle está de verdade

Vale dizer com clareza, porque o ponto deste post é uma linha que você pode aplicar com ou sem a gente: o enforcement se instala hoje como plugin, e o pacote commitcycle do npm instala a CLI ao lado dele. O board hospedado é só por convite enquanto isto é pequeno.

Então pegue a linha e use. Não custa nada, se aplica às ferramentas que você já tem, e o argumento por baixo dela está no post anterior se você quiser conferir o raciocínio antes de confiar na conclusão.

Seu vault do Obsidian não pode ser a base de conhecimento dos seus agentes de IA

Mon, 10 Aug 2026 00:00:00 GMT

Um vault do Obsidian falha como base de conhecimento para agentes de IA por três razões estruturais: ele é privado de uma máquina, suas afirmações não trazem citações, e nada avisa quando uma nota deixou de ser verdade. Agentes leem o que recebem e não têm como distinguir uma nota atual de outra que venceu três sprints atrás — então a resposta confiante e errada e a certa chegam com a mesma cara.

Isto não é uma crítica ao Obsidian. Ele é muito bom no trabalho para o qual foi feito, que é uma pessoa pensando. A falha é um erro de categoria: uma ferramenta pessoal de pensamento sendo cobrada como fonte de verdade compartilhada.

Agentes conseguem ler um vault do Obsidian?

Conseguem, e vale esclarecer isso primeiro porque é onde a conversa costuma começar. Um vault é uma pasta de markdown puro. Qualquer agente com acesso a arquivos lê sem cerimônia, e existem servidores MCP que ligam um deles numa tarde.

O acesso nunca foi o problema. Ler e confiar são operações diferentes, e um vault não carrega nenhum sinal que as separe. Uma nota escrita semana passada e uma nota que deixou de ser verdade em 2024 são o mesmo tipo de objeto, na mesma pasta, com a mesma autoridade. Quem lê o próprio vault desconta automaticamente — ah, essa é velha — usando conhecimento que não está em lugar nenhum do arquivo. Um agente não tem com o que descontar.

Então a metade fácil é resolvida, a metade difícil passa despercebida, e o arranjo parece estar funcionando até o momento em que ele age com toda a confiança sobre algo que já tinha vencido.

As três falhas, na ordem do que custam

1. É privado, então o conhecimento é por pessoa

Um vault mora num notebook. Sincronize e você tem uma pasta compartilhada, não conhecimento compartilhado — porque o vault não tem noção de revisão. Ninguém aprova uma nota. Ninguém responde por ela. Dois engenheiros mantêm dois vaults, cada um certo sobre coisas diferentes, e o agente fica com o vault de quem estiver operando.

O sintoma é fácil de reconhecer: a mesma pergunta recebe duas respostas dependendo de quem perguntou ao agente.

2. As afirmações não têm procedência

Uma nota diz “a gente faz migrations em duas etapas.” Isso é uma decisão que alguém tomou, a observação de um incidente, ou algo em que um colega acreditava em 2024? A nota não diz, e depois de alguns meses ninguém lembra.

Para um leitor humano isso é atrito. Para um agente é fatal, porque ele não consegue pesar uma afirmação que não consegue rastrear. Ele vai seguir uma nota vencida exatamente com a mesma confiança com que segue uma correta.

3. Nada marca uma nota como vencida

Esta é a que faz mais estrago em silêncio. Um vault não tem estado de morte. As notas se acumulam, e o único mecanismo para tirar uma errada é alguém lembrar que ela está errada — o que falha com regularidade, porque quem sabe que a nota está vencida não é quem está lendo.

O resultado é um corpo de notas que cresce monotonicamente mais confiante e menos exato.

O que a documentação para agentes precisa ser?

Cada propriedade abaixo existe por causa de um jeito específico pelo qual os vaults falham:

Propriedade	A falha que ela responde
Mora no repositório	Revisada como código, não sincronizada como uma pasta
Cita uma decisão, uma task ou um arquivo	Uma afirmação que você não rastreia é uma que você não pesa
Escrita quando o trabalho fecha	Não “quando alguém lembrar”, que é nunca
Tem um estado de arquivada	Uma nota errada precisa poder sair por algo que não seja memória
Carregada pelo que a task declara	Cinquenta notas não são contexto, são ruído

Essa última linha é a que a maioria das ferramentas ignora. Entregar uma base de conhecimento inteira a um agente não é engenharia de contexto; é um prompt maior. O que uma task precisa é do subconjunto relevante para aquela task, escolhido por algo que a própria task declarou.

Por que não dar o vault inteiro para o agente?

O movimento óbvio, e ele falha de três jeitos específicos:

Volume não é contexto. Quatrocentas notas num prompt significam que as três relevantes ficam diluídas entre trezentas e noventa e sete que não são. Isso é um prompt maior, não um embasamento melhor, e custa exatidão em vez de comprá-la.

Nada diz quais notas valem aqui. Os links de um vault codificam associação — isto me lembrou daquilo — não aplicabilidade à task que está na sua frente. São relações diferentes, e só uma delas serve para escolher.

Contradições não têm desempate. Duas notas discordam sobre como se faz deploy. Nada no vault registra qual venceu, porque a vencedora foi decidida numa conversa. O agente resolve escolhendo a que mais se parece com o prompt, e relata o resultado com a mesma confiança nos dois casos.

O desfecho é pior do que um arquivo curto e curado teria sido: uma resposta bem escrita, aparentemente bem fundamentada, e errada.

RAG sobre o vault resolve?

Em parte, e vale ser preciso sobre qual parte, porque é a correção mais proposta.

A recuperação resolve a seleção. Isso é genuíno: transforma “o agente leu quatrocentas notas” em “o agente leu as quatro mais próximas”, que é uma melhora de verdade e o incômodo que mais se sente.

Ela não toca em procedência nem em validade, e na validade pende levemente para o lado errado. A recuperação traz o que está textualmente mais perto da pergunta, e uma nota vencida escrita com segurança — “a gente faz migrations em duas etapas” — costuma ser a coisa mais próxima de uma pergunta sobre migrations. A nota correta pode ser mais nova, mais cheia de ressalvas e escrita menos parecida com a pergunta. Embeddings não têm opinião sobre datas nem sobre verdade; eles ordenam por similaridade.

Então RAG promove o problema de o agente leu tudo e não sabia o que estava valendo para o agente leu as quatro coisas mais relevantes e não sabia o que estava valendo. Melhor, e não a correção.

E o Notion, o Confluence ou um wiki?

Eles respondem a uma das três falhas com clareza e deixam as outras duas mais ou menos onde estavam.

Compartilhado: sim. Este é o ganho real, e não é pouco — um corpo de notas, muitos leitores, acabou o “a mesma pergunta recebe duas respostas dependendo de qual vault o agente leu”.

Procedência: não. Uma página de wiki raramente diz de qual decisão veio ou qual incidente a produziu, pela mesma razão que uma nota de vault não diz: quem escreveu sabia, então anotar parecia redundante.

Validade: discutivelmente pior. As notas ruins de um vault pelo menos estão enterradas. As de um wiki estão indexadas, são buscáveis e linkadas de outras quatro páginas, então a escala torna uma afirmação vencida mais fácil de achar, não menos, e nada na ferramenta a arquiva. O mecanismo para tirar uma página errada continua sendo alguém lembrar.

E uma falha que o wiki acrescenta: ele não fica onde o código muda. Uma nota no repositório está na sua frente, no diff, no momento em que você altera a coisa que ela descreve. Uma nota num wiki é lida quando alguém vai procurar — que é justamente o comportamento que você estava tentando corrigir.

Como o CommitCycle faz

O CommitCycle chama isso de playbooks — arquivos de conhecimento por topic e por projeto que moram no seu repositório. Quatro propriedades, cada uma respondendo a uma linha da tabela acima:

Eles citam. Toda afirmação aponta para uma decisão, uma task ou um arquivo. Um lint aponta a afirmação que não traz citação nenhuma — ele avisa, não bloqueia — e quando o cycle seed redige playbooks, uma afirmação que cita um arquivo que não está no repositório é descartada, e um playbook que fica sem nada citado nem chega a ser criado.
São alimentados no fechamento do trabalho, um item por vez, enquanto a pessoa ainda lembra o porquê. Não numa retro, não quando alguém lembrar.
São carregados pelos topics que a task declarou, então uma task sobre o banco de dados não carrega as convenções do frontend.
Podem ser arquivados. archived é um estado real, e é isso que permite que o conjunto encolha.

E uma passada adversarial — cycle challenge — foi feita para propor as práticas que o repositório visivelmente não tem, cada uma com uma fonte nomeada. Como o cycle seed, ela precisa de um modelo configurado no board, e ainda não rodou contra um modelo de verdade. Você pode recusar, e a sua recusa fica registrada com os motivos. “A gente se desvia disso de propósito, e eis o porquê” também é conhecimento, e é do tipo que os vaults nunca capturam porque ninguém escreve o que decidiu não fazer.

A parte honesta

Aqui existe uma objeção real e ela merece resposta direta: “se você gerar um playbook a partir do meu repositório legado, isso não vai só codificar a minha bagunça?”

Vai. Por design, só descrever codifica a bagunça — com recibos. É por isso que o challenger existe: ele foi feito para propor o que falta no repo em vez de apenas descrever o que existe, e uma pessoa aceita ou recusa cada proposta. Não há aceitação automática, e um teste mantém esse caminho fechado.

O que isto não substitui

Fique com o vault. Isto não é uma migração.

O Obsidian continua melhor do que qualquer coisa aqui para pensar — para ideias pela metade, para conexões que você ainda não fez, para notas que são suas e têm permissão de estar erradas. O que sai dele é o subconjunto do qual outros leitores dependem para ser verdade. Esse subconjunto sempre foi a parte que doía quando vencia, e nunca foi a parte que o Obsidian foi projetado para segurar.

Uma linha útil de traçar: se errar sobre esta nota levaria outra pessoa a errar junto, ela não pertence a um vault pessoal.

Para onde isso vai, no caso das notas que um agente deve ler, é uma skill no repositório — o mesmo markdown, mas versionado com o código que ele descreve e carregado só quando a task pede.

Onde o CommitCycle está de verdade

O CommitCycle conduz o próprio desenvolvimento — o board, o gate, os audit records e os playbooks descritos acima estão em uso hoje no repositório dele. A metade de enforcement se instala como plugin do Claude Code; o pacote commitcycle no npm coloca a CLI cycle no seu PATH, sem o hook. O board hospedado é só por convite enquanto isto é pequeno. A Phase 0 está medida e publicada com os seus limites.

Então este post não está pedindo que você migre nada hoje. Ele faz um argumento que você pode avaliar pelo mérito, e se ele se sustentar, a waitlist é o próximo passo honesto. Se o argumento estiver errado, isso vale mais para nós do que um cadastro.

O resto do produto está documentado por completo: o bloco de contexto AGENTS.md, as zones e o audit record.