Lat.md: Um Gráfico de Conhecimento Baseado em Markdown para Bases de Código

O Lat.md é uma ferramenta que constrói um grafo de conhecimento para sua base de código usando arquivos markdown. Ele resolve o problema do AGENTS.md não escalar bem — conforme os projetos crescem, manter um único arquivo plano se torna impraticável, levando a decisões de design enterradas, lógica de negócios não documentada e agentes de IA alucinando contexto.

Como Funciona

Você comprime o conhecimento do domínio em um grafo de arquivos markdown interconectados armazenados em um diretório lat.md/ na raiz do seu projeto. As seções se vinculam umas às outras com [[links wiki]] como [[arquivo#Seção#Subseção]], arquivos markdown se vinculam ao código com [[src/auth.ts#validateToken]], e arquivos-fonte se vinculam de volta usando comentários como // @lat: [[section-id]] em TypeScript ou # @lat: [[section-id]] em Python. O comando lat check garante a consistência referencial.

Principais Recursos

• Codificação mais rápida para agentes: Em vez de fazer grep no código, os agentes pesquisam o grafo de conhecimento para descobrir decisões de design, restrições e contexto de domínio de forma consistente.
• Fluxo de trabalho mais rápido para humanos: Os agentes mantêm os arquivos lat; ao revisar diffs, comece com as mudanças semânticas em lat.md/ para entender o que mudou e por quê, tornando a revisão de código secundária.
• Retenção de conhecimento: Os agentes capturam contexto e raciocínio dos prompts no grafo conforme trabalham, para que sessões futuras comecem com contexto completo em vez de redescobri-lo.
• Especificações de teste com aplicação: Casos de teste podem ser descritos em seções lat.md/ marcadas com require-code-mention: true. Cada especificação deve ser referenciada por um comentário // @lat: no código de teste, e lat check sinaliza qualquer especificação sem um backlink.

Comandos CLI

• lat init: Configura agentes de codificação populares com hooks e instruções para manter o lat atualizado e correto.
• lat check: Aplica a consistência referencial; os agentes o chamam automaticamente antes de terminar o trabalho.
• lat search e lat section: Os agentes usam esses comandos para entender prompts e navegar pelo grafo em vez de fazer chamadas grep intermináveis.
• lat locate: Encontra seções por nome (exato ou aproximado).
• lat refs: Encontra o que referencia uma seção.
• lat expand: Expande [[refs]] em um prompt para agentes.
• lat mcp: Inicia o servidor MCP para integração com o editor.

Instalação e Configuração

Instale com npm install -g lat.md, depois execute lat init no seu repositório para criar um diretório lat.md/. Escreva arquivos markdown descrevendo arquitetura, lógica de negócios ou especificações de teste e vincule-os conforme necessário.

Para busca semântica (lat search), uma chave de API da OpenAI (sk-...) ou Vercel AI Gateway (vck_...) é necessária. A chave é resolvida nesta ordem: variável de ambiente LAT_LLM_KEY (valor direto), variável de ambiente LAT_LLM_KEY_FILE (caminho para um arquivo contendo a chave), variável de ambiente LAT_LLM_KEY_HELPER (comando shell que imprime a chave com um timeout de 10s) ou um arquivo de configuração salvo pelo lat.