Product Traceability: 4 Ficheiros que Dão Memória ao Teu AI Agent (e Cortam Custos)
Se usas Claude Code, Cursor ou Copilot, já passaste por isto: passas os primeiros minutos de cada sessão a reexplicar o projeto, a arquitetura, os requisitos. O agente faz ls, find, grep, lê os mesmos ficheiros outra vez, erra, tenta de novo. Ao fim de 5 minutos, finalmente começa a produzir código útil.
O Vlad Mysla, criador do LocalFlow, fartou-se deste ciclo. Durante três meses a trabalhar em dez projetos, apercebeu-se de que o problema real não são os tokens que gastas, mas o contexto que perdes entre sessões. Ele criou uma skill para Claude Code que resolve isto. Chama-se Product Traceability.
O que é que ela faz? Mantém quatro ficheiros de texto sincronizados com o estado real do projeto. Sempre que o código muda, a skill atualiza os ficheiros automaticamente. E o resultado, segundo os dados dele, é uma redução de 30 a 45% nos custos de input tokens.
Neste post vais perceber:
- Como a skill funciona e porque é que ela resolve o problema do contexto perdido
- Os números reais de redução de custos e aumento de produtividade
- Como instalar e começar a usar no teu próximo projeto
- A minha opinião sobre a abordagem e as limitações que tens de ter em conta
O Problema de Contexto
Sessões de AI coding têm um custo escondido. Não está no preço por token, está no tempo que o agente perde a redescobrir o que já sabia.
Num projeto médio, o agente faz uma série de comandos de exploração: ls para perceber a estrutura, cat para ler ficheiros, grep para encontrar funções. Se o projeto for complexo, erra à primeira e tenta outra query. Isto gasta 1 a 5 minutos no início de cada sessão.
Quando fechas o terminal e abres uma sessão nova no dia seguinte, voltas à estaca zero. O agente não se lembra de nada. E estás a pagar por cada requisição que ele faz para se reorientar.
O Vlad escreveu isto no artigo original:
The expensive part is not just paying for tokens. The expensive part is making high-cost agents repeatedly rediscover context your repo could have remembered for free.
A Solução: 4 Ficheiros
A skill Product Traceability é open-source. Funciona exclusivamente com Claude Code (o CLI da Anthropic) e assenta em três hooks:
- SessionStart: cria os ficheiros de trace se não existirem
- UserPromptSubmit: injeta a regra de traceability no turno atual
- Stop: se o código mudou mas os trace files não, recusa parar e pede ao Claude para atualizar
A skill mantém quatro ficheiros:
| Ficheiro | O que contém |
|---|---|
| requirements.md | PRD atualizado: o que a aplicação faz agora, não o que estava no documento inicial |
| change.log | Histórico cronológico de alterações, no formato Keep a Changelog |
| decisions.md | Decisões tomadas e o raciocínio por trás delas |
| traceability-matrix.md | Mapa que liga requisitos, prompts, implementação, decisões e testes |
A ideia não é complicada. É literalmente manter um changelog e um registo de decisões como já deves fazer em projetos de equipa, mas automatizado para o teu AI agent ler antes de começar a trabalhar.
Os Números
O Vlad fez uma análise retrospetiva com base nos logs de sessões reais do Claude Code em 10 projetos. Não é um A/B test controlado, por isso vale o que vale. Mas os números são interessantes.
Custos
A skill aumenta a taxa de prompt caching de 5% para 40%. Isto traduz-se em 30 a 45% de poupança em input-token costs. Para uma startup com duas equipas (cerca de 10 developers) a usar Claude Opus, estamos a falar de 10 000 dólares por ano de poupança.
Produtividade
| Métrica | Com traceability | Sem traceability | Diferença |
|---|---|---|---|
| Sessões produtivas | 92% | 64% | +44% |
| Sessões que falham | 8% | 36% | -78% |
| Passos de exploração pré-edit | -30% | baseline | -30% |
| Cache hit rate | ~40% | ~5% | +700% |
| Menções a decisões/requisitos | 287 | 8 | 35x mais |
A taxa de falha caiu de 36% para 8%. A diferença é grande. Mesmo que o impacto real seja metade do reportado, continua a ser relevante. Sessões com menos erros de contexto significam menos frustração e menos tempo perdido.
Outras conclusões
- Profundidade de sessão 6x maior (o agente não precisa de reiniciar tanto)
- Transcrições 77% maiores por sessão
- Decisões re-litigadas passaram de frequentes para raras
Como Instalar
Um comando, funciona em macOS e Linux:
E está feito.
O Que Acho disto
Gosto da abordagem. O mercado tem startups a receber milhões para resolver o problema da "agentic memory" com plataformas complexas. O Vlad resolveu com quatro ficheiros de texto e uns hooks. É uma daquelas soluções que parece óbvia depois de ler.
Há limites, claro. A análise é retrospetiva, não controlada. Os números podem estar inflacionados. E a skill depende de três hooks específicos do Claude Code. Se usas Cursor ou Copilot, não funciona diretamente. Mas a ideia é adaptável a qualquer ferramenta.
A cena mais importante aqui: não precisas de uma plataforma cara para resolver o problema de contexto. Precisas de disciplina para manter o registo do que estás a fazer. A skill automatiza essa disciplina.
Para Concluir
Se usas AI agents para coding e sentes que passas mais tempo a dar contexto do que a codar, vale a pena experimentar. São quatro ficheiros, um clone do repo e um comando para instalar. Se não resultar, desinstalas em 10 segundos.
Comentários (0)
Nenhum comentário ainda. Seja o primeiro!
Deixar comentário