Código mostra o que uma equipe entregou. Raramente mostra por que aquele comportamento virou padrão, por que uma exceção foi aceita ou qual problema uma interface decidiu resolver. Enquanto o trabalho era feito apenas por pessoas que participaram das conversas, essa lacuna podia ser compensada por memória, revisão e perguntas no corredor.
Com agentes capazes de produzir interfaces e mudanças de código rapidamente, essa compensação fica mais frágil. O agente encontra componentes, nomes e exemplos no repositório. Se a razão de uma decisão ficou em uma reunião, em um comentário antigo ou na cabeça de alguém, ela não faz parte do contexto que orienta a próxima mudança.
Esse é o ponto central da experiência descrita pela Vercel: decisões de produto aceitas são tratadas como código. Elas ficam no repositório, passam por revisão e ficam disponíveis para os agentes que trabalham naquele sistema. A consequência é maior do que documentar design. É transformar julgamento de produto em uma dependência explícita da arquitetura de entrega.
O código preserva o padrão, não a intenção
Um agente pode copiar a aparência de uma tela e reutilizar o componente correto. Isso não garante que ele entenda o motivo de uma escolha. Uma mensagem curta pode ter sido adotada porque reduz uma dúvida recorrente. Um botão pode aparecer em uma posição específica porque o fluxo precisa evitar uma ação irreversível. Um estado aparentemente redundante pode existir para orientar recuperação depois de uma falha.
Sem essa explicação, o agente trata o que existe como uma coleção de exemplos. Ele generaliza a partir do caso mais próximo, mesmo quando a semelhança visual esconde uma diferença de contexto. A implementação pode compilar, passar por uma captura visual e ainda contrariar uma decisão de produto já tomada.
Isso também vale para exceções. Uma regra como “use o componente de confirmação para ações destrutivas” não é suficiente se não registra quais ações foram consideradas destrutivas, que informação o usuário precisa antes de confirmar e quando a operação pode ser desfeita. O padrão ajuda a executar; a decisão explica o limite.
Contexto versionado é parte da arquitetura
Chamar esse material de documentação pode fazer parecer que ele é complementar. Em sistemas operados por agentes, a distinção perde força. Se a ausência de uma decisão altera o resultado produzido, essa decisão participa do sistema que produz software.
Não é necessário transformar o repositório em um manual extenso. O contexto útil é curto e verificável. Para uma decisão, vale registrar:
- o problema que precisava ser resolvido;
- o comportamento escolhido e o que ficou fora do escopo;
- a razão que diferencia essa escolha de alternativas próximas;
- os sinais que permitem revisar ou aposentar a decisão.
Esse registro pode viver ao lado dos componentes, em uma pasta de decisões de produto ou em uma skill carregada pelo agente. O local importa menos do que três propriedades: precisa ser encontrado pelo fluxo de trabalho, precisa passar por revisão e precisa mudar quando o produto muda.
A Vercel descreve uma estrutura com uma skill de agente, linters e um ciclo de revisão que reúne evidências de Slack, Figma e GitHub para propor atualizações das diretrizes. O detalhe operacional pode variar entre equipes. A decisão arquitetural é a mesma: contexto de produto precisa ter um dono, uma fonte e um caminho de atualização.
O risco de congelar decisões antigas
Versionar uma decisão não significa torná-la eterna. Um repositório pode preservar padrões com tanta eficiência que passa a preservar também escolhas que perderam validade.
Por isso, cada registro precisa deixar visível seu alcance. Uma decisão pode valer apenas para uma superfície, para um tipo de usuário ou para uma restrição temporária de integração. Sem esse limite, o agente encontra uma regra verdadeira em um contexto e a aplica como lei geral.
Revisar o contexto também deve fazer parte das mudanças que o consomem. Se um novo fluxo precisa abrir uma exceção, o pull request não deveria apenas alterar a interface. Deveria indicar se a regra continua válida, se a exceção é local ou se o padrão precisa ser reescrito. A revisão deixa de perguntar apenas “o código funciona?” e passa a perguntar “a decisão que este código materializa ainda é a decisão certa?”.
O que merece virar contexto para agentes
Nem toda conversa de design precisa ser arquivada. O filtro mais prático é perguntar se a ausência daquela informação aumenta a chance de uma mudança plausível, porém errada.
Entram primeiro as decisões que afetam muitos caminhos: vocabulário do produto, estados de erro, permissões, padrões de navegação, componentes obrigatórios, critérios de acessibilidade e limites entre superfícies. Também entram as exceções que parecem contradizer uma regra comum. São justamente elas que um agente não consegue inferir com segurança a partir de um exemplo isolado.
Detalhes cosméticos e preferências sem consequência não precisam do mesmo tratamento. Se uma escolha pode ser alterada sem mudar compreensão, risco ou comportamento, um token ou componente compartilhado provavelmente já é contexto suficiente.
A decisão para a equipe
Antes de pedir que agentes produzam mais telas, a equipe deveria listar quais decisões de produto hoje só podem ser recuperadas perguntando a uma pessoa. Depois, pode classificar cada uma: padrão codificado, decisão documentada, regra automatizável ou julgamento que ainda exige revisão humana.
O objetivo não é fazer o agente participar de todas as discussões. É reduzir o espaço em que ele precisa adivinhar. Quando a decisão fica próxima do código, a equipe ganha velocidade sem transformar consistência em coincidência.
