🧩 O problema: contexto que não atravessa sessões
Sessões são isoladas por desenho: cada uma nasce sem saber o que a anterior descobriu. Projetos e instruções resolvem parte disso dentro de uma ferramenta. O que não se resolve sozinho é o contexto que atravessa ferramentas: o que você decidiu num agente e precisa valer no outro.
| O que guardar | Onde | Por quê |
|---|---|---|
| Como rodar e testar este projeto | AGENTS.md do repo | Vale para toda sessão daquela pasta |
| Mapa e riscos do repo | MAPA.md do repo | Evita releitura completa |
| Decisões que atravessam projetos | Base em arquivos | Vários agentes, vários repos |
| Preferências suas de trabalho | Base em arquivos | Estilo, formato de entrega, o que reprovar |
| Segredos, chaves, senhas | Gerenciador de segredos | Nunca em nota nem em repo |
📓 Uma base em arquivos de texto
O formato importa mais que a ferramenta. Uma nota por ideia, nome descritivo, um cabeçalho pequeno com tipo e data, links entre notas relacionadas. O Obsidian dá visualização e busca em cima disso, mas qualquer agente com acesso ao disco lê a mesma pasta.
Copie e rode
Estrutura inicial da base e o formato de uma nota
mkdir -p ~/base/{decisoes,projetos,ferramentas,pessoas,diario}
cat > ~/base/decisoes/orquestracao-modelo-barato.md <<'EOF'
---
tipo: decisao
data: 2026-09-07
projetos: [<projeto-a>, <projeto-b>]
---
# Orquestração: fronteira planeja, barato executa
Tarefas repetitivas de 10+ passos usam PLANO.md gerado pelo modelo de fronteira
e execução com modelo local. Medido em <projeto-a>: consumo de cota caiu de
25% para 11% com resultado equivalente.
Relacionado: [[cota-semanal-como-ler]], [[plano-executavel-formato]]
EOF
ls -R ~/base | head -20✓ Nota que serve a um agente
- ✓Uma decisão ou fato por arquivo
- ✓Data e projetos no cabeçalho
- ✓O porquê, não só o quê
- ✓Links para notas relacionadas
✗ Nota que atrapalha
- ✗Arquivo gigante com tudo
- ✗Sem data (o agente não sabe se ainda vale)
- ✗Só conclusão, sem contexto
- ✗Segredos e credenciais
⚠️ Nota velha vira instrução errada
Um agente lê a base como verdade. Nota sem data ou desatualizada faz ele recomendar um comando que não existe mais. Datar tudo e revisar o que envelhece é parte do custo dessa camada.
🔄 Conectar os agentes à base
Duas ligações. Na entrada: uma instrução permanente mandando consultar a base antes de decidir. Na saída: um pedido explícito de registrar o que foi decidido. A leitura pode ser por acesso direto ao disco (o agente já tem, se a pasta estiver no escopo) ou por um servidor MCP de sistema de arquivos, quando o agente roda fora da sua máquina.
Copie e rode
Instrução permanente que liga qualquer projeto à base
## Base de conhecimento
Antes de decisões de arquitetura, escolha de ferramenta ou padrão de trabalho,
consulte ~/base/ (markdown). Busque por termos do problema:
grep -ril "<termo>" ~/base/ | head -20
Se encontrar nota relevante, cite o arquivo na sua resposta e siga a decisão
registrada. Se a nota contradiz o que eu pedi agora, me avise antes de agir.
Ao fim de uma tarefa que gerou decisão nova, proponha (não crie sozinho) uma
nota em ~/base/decisoes/ no formato padrão, e me mostre o conteúdo.Copie e rode
Dar acesso à base para um agente que roda em outra pasta
# opção 1: incluir a pasta no escopo da sessão
codex --add-dir ~/base "<TAREFA>"
# opção 2: servidor MCP de sistema de arquivos limitado à base
codex mcp add base -- <COMANDO_DO_SERVIDOR_DE_ARQUIVOS> ~/base
codex mcp list✓ O agente pode fazer sozinho
- ✓Buscar e ler qualquer nota da base
- ✓Citar o arquivo que embasou a resposta
- ✓Apontar contradição entre nota e pedido atual
- ✓Redigir a proposta de nota nova
✗ Só com a sua aprovação
- ✗Criar arquivo novo na base
- ✗Editar ou apagar nota existente
- ✗Reorganizar pastas e renomear notas
- ✗Registrar como decisão algo que ainda é hipótese
💡 Propor, não escrever
Deixe o agente propor a nota e você aprovar. Base escrita automaticamente acumula duplicata e conclusão errada, e a próxima sessão lê isso como verdade.
🕸️ Visualizar e revisar a base
Ferramentas de markdown com grafo mostram notas isoladas e aglomerados. Nota órfã costuma ser uma de duas coisas: ideia que nunca se conectou a nada (candidata a poda) ou assunto novo que ainda vai crescer. A revisão olha data e uso: o que não é citado nem atualizado há meses sai ou vira arquivo morto.
Copie e rode
Encontrar notas velhas e notas órfãs para revisar
# notas não modificadas há mais de 180 dias
find ~/base -name "*.md" -mtime +180 | head -30
# notas que ninguém referencia (nenhum [[link]] aponta para elas)
cd ~/base
for f in $(find . -name "*.md"); do
n=$(basename "$f" .md)
grep -rql "\[\[$n\]\]" . >/dev/null 2>&1 || echo "orfa: $f"
done | head -30Ritmo de revisão
Semanal, 10 minutos
Notas criadas na semana: cabeçalho completo? Ligadas a alguma coisa?
Mensal, 30 minutos
Rode as duas buscas acima. Poda e religação.
Quando um agente errar
Se a recomendação errada veio de uma nota, corrija a nota na hora. É o feedback mais valioso que a base recebe.
🏗️ O sistema completo
Entrada
Base consultada e contrato escrito. Dois minutos que evitam meia hora de retrabalho.
Execução
Skill quando o método é seu, MCP quando falta capacidade, tela quando não há alternativa, plano quando o volume é grande.
Verificação
Git limpo antes, prova depois, rollback barato. Reprovar é normal e gera o critério da próxima rodada.
Registro
Decisão nova vira nota datada. Amanhã, outro agente em outro projeto começa sabendo.
| Módulo | O que entregou | Onde entra no fluxo |
|---|---|---|
| 1.1 | Loop e contrato de três linhas | Entrada |
| 1.2 | Três superfícies, sandbox, AGENTS.md | Entrada e execução |
| 1.3 | Computer use com rascunho e prova | Execução |
| 1.4 | Iteração com git e critérios de aceite | Verificação |
| 2.1 | Skills de ferramenta e de gosto | Execução |
| 2.2 | MCP e tarefas longas com marcos | Execução |
| 2.3 | Cota, esforço e orquestração | Execução |
| 2.4 | Base em arquivos | Entrada e registro |
🚀 Prática final: montar a base e fechar um ciclo
Roteiro (45 min)
Crie a base
As pastas do tópico 2 e três notas: uma decisão que você já tomou, uma preferência de trabalho, um aprendizado deste curso.
Conecte um projeto
Bloco "Base de conhecimento" no AGENTS.md do repositório em que você mais trabalha.
Escolha uma tarefa real
Algo que você faria hoje de qualquer jeito. Não invente exercício.
Rode o fluxo inteiro
Consultar base, contrato, delegar, verificar prova, git commit.
Registre
Peça ao agente a proposta de nota. Revise, corrija, salve com data.
Confirme o ciclo
Sessão nova, pergunta relacionada. A resposta deve citar a nota que você acabou de salvar.
Copie e rode
Fechar o ciclo: pedir a nota da decisão que a tarefa gerou
A tarefa terminou e foi verificada. Proponha uma nota para ~/base/decisoes/ no formato padrão (cabeçalho com tipo, data e projetos), contendo:
- a decisão em uma frase;
- o contexto: qual problema levou a ela;
- a evidência: o que foi medido ou observado;
- o que NÃO fazer, aprendido nesta tarefa;
- links para notas relacionadas que já existirem em ~/base/.
Mostre o conteúdo. Não crie o arquivo até eu aprovar.💡 A primeira volta é a mais cara
Montar base, conectar projeto e escrever a primeira nota leva quase uma hora. A segunda volta leva o tempo da tarefa mais dois minutos. É aí que o sistema começa a pagar.
🧪 Teste rápido do módulo
Três perguntas. Clique numa opção para ver a resposta.
1. Por que markdown numa pasta e não um produto de memória fechado?
2. Qual é o risco de deixar o agente escrever na base sem revisão?
3. Qual passo faz o sistema melhorar por uso?