🏗️ O Conceito de Compilação
A escolha de Karpathy pela palavra "compilador" é precisa — não metafórica. A analogia com compiladores de software não é poética: ela define propriedades técnicas específicas que o sistema deve ter.
⚙️ Software vs. Conhecimento: A Analogia Completa
🔑 Propriedades que a Analogia Garante
- •Idempotência: compilar as mesmas fontes duas vezes deve produzir o mesmo wiki (dado o mesmo CLAUDE.md)
- •Separação input/output: raw/ e wiki/ são mundos distintos — nunca misturados
- •Rastreabilidade: toda afirmação no wiki pode ser rastreada à fonte em raw/
- •Determinismo: o mesmo input + CLAUDE.md deve gerar output previsível
📁 raw/ como Código Fonte
A pasta raw/ é sagrada: nada é modificado, nada é deletado. O LLM apenas lê. Essa imutabilidade não é burocracia — é a fundação de toda a auditabilidade do sistema.
✓ O que vai em raw/
- ✓PDFs de artigos, livros e documentos
- ✓URLs salvas (conteúdo completo, não apenas link)
- ✓Transcrições de reuniões e podcasts
- ✓Notas brutas de campo ou de estudo
- ✓Exports de outras ferramentas (Notion, Roam, etc.)
✗ O que NUNCA vai em raw/
- ✗Arquivos gerados pelo LLM (esses vão em wiki/)
- ✗Versões editadas ou anotadas de documentos
- ✗Dados sensíveis ou credenciais
- ✗Arquivos temporários ou de rascunho sem valor
📊 Por que Imutabilidade Importa
Imagine descobrir que uma página wiki contém uma afirmação incorreta. Com raw/ imutável:
- 1. Você encontra o arquivo em raw/ de onde a informação veio
- 2. Verifica se a fonte original é confiável ou se o LLM interpretou mal
- 3. Se for erro de interpretação: ajusta o CLAUDE.md e recompila
- 4. Se a fonte estiver errada: adiciona nota de refutação em raw/ e recompila
Sem raw/ imutável, essa rastreabilidade desaparece — você não consegue distinguir o que veio de onde.
📖 wiki/ como Binário
wiki/ é o output do compilador: conhecimento estruturado, interligado e otimizado para consulta. Mas diferente do binário de software — que é ilegível por humanos — o wiki compilado é intencionalmente transparente.
🏗️ Estrutura Típica de wiki/
wiki/
├── conceitos/
│ ├── machine-learning.md # página de conceito
│ ├── transformer.md
│ └── attention-mechanism.md
├── entidades/
│ ├── openai.md # página de entidade/organização
│ └── karpathy-andrej.md
├── comparacoes/
│ └── rag-vs-compilacao.md # página de comparação
└── cronologias/
└── evolucao-llms.md
💡 A Grande Vantagem: Human-Readable
A decisão mais importante de design: wiki/ em Markdown puro. Isso significa que:
- •Você pode ler qualquer página no editor de texto ou Obsidian
- •Você pode editar manualmente se o LLM errou algo
- •Você pode versionar com git e ver exatamente o que mudou
- •O formato sobrevive a qualquer ferramenta — Markdown não vai morrer
📋 CLAUDE.md como Spec do Compilador
Todo compilador tem uma gramática — um conjunto formal de regras que define como transformar input em output. No LLM wiki, o CLAUDE.md é essa gramática: ele define o comportamento completo do sistema.
📋 O que um Bom CLAUDE.md Define
1. Tipos de Páginas
Quais categorias de páginas existem no wiki? Conceitos, Entidades, Comparações, Cronologias, Projetos... Cada tipo tem um template diferente que o LLM deve seguir ao compilar.
2. Regras de Nomenclatura
Como nomear arquivos? kebab-case? Com data? Por categoria? A consistência da nomenclatura é o que permite o index.md funcionar como catálogo confiável.
3. Comportamento em Ambiguidades
O que fazer quando uma fonte contradiz uma página existente? Quando um conceito já tem uma página parcial? Regras explícitas evitam decisões inconsistentes entre ingestões.
4. Nível de Detalhe por Tipo
Páginas de Entidade são mais curtas que páginas de Conceito? Cronologias incluem apenas anos ou datas precisas? Granularidade definida produz wikis consistentes.
⚠️ O Erro Mais Comum
CLAUDE.md vago ou incompleto é a causa número 1 de wikis inconsistentes. Se as regras não cobrem um caso, o LLM inventa um comportamento — e raramente é o mesmo comportamento entre ingestões. Trate CLAUDE.md como código: versionado, testado, revisado.
🔄 Compilação Incremental
A compilação incremental é o que torna o sistema eficiente em uso contínuo. Como o comando make em C — recompila apenas o que mudou, não o projeto inteiro.
🔄 Como Funciona a Compilação Incremental
💡 O Custo Constante de Ingestão
Independente do tamanho do vault (10 ou 10.000 páginas), ingerir uma nova fonte custa o mesmo: processar apenas aquela fonte + atualizar index.md. O log.md garante que o agente nunca reprocesse o que já foi compilado.
🚀 Otimizações do Compilador
Compiladores maduros têm otimizações: dead code elimination, inlining, caching. O LLM wiki tem equivalentes diretos — cada otimização segue a mesma lógica da ciência da computação.
🗜️ Compressão — Abstracts Densos
Equivalente: tree shaking / dead code elimination
Cada página wiki tem uma seção "## Abstract" de 2-3 frases — o máximo de informação no mínimo de tokens. O LLM lê abstracts na fase de Query para decidir quais páginas completas carregar. Redução de ~80% de tokens por consulta.
📑 Índices Hierárquicos — O(1) de Navegação
Equivalente: symbol tables / lookup indices
index.md aponta para sub-índices por domínio (ml-index.md, finance-index.md). A busca é sempre O(1): lê o sub-índice certo, encontra a página, carrega apenas ela. Sem varredura linear do vault.
⚡ Cache de Consultas — Respostas Pré-computadas
Equivalente: memoization / compile-time evaluation
Perguntas frequentes geram páginas de cache em wiki/cache/. "Qual o status atual do projeto X?" tem uma resposta cached, atualizada periodicamente. Consultas subsequentes custam ~200 tokens em vez de ~5.000.
✅ Resumo do Módulo 6.2
Próximo Módulo:
6.3 — Wikis Auto-Mantidos: por que humanos sempre falharam na manutenção de wikis e como LLMs resolvem o problema com custo marginal zero