O que introspect faz?
Transforme o que aconteceu em seus threads de codificação de IA em mudanças que fazem seus agentes trabalharem melhor para você — para que sua configuração se acumule em vez de reiniciar a cada sessão.
É agnóstico a agentes. Ele lê seus threads do Claude Code, OpenAI Codex e Cursor, encontra as poucas coisas que valem a pena mudar e — com sua aprovação — as escreve de volta na configuração do agente que realmente guia as sessões futuras. O Claude Code já vem com /insights, que lê seus últimos 30 dias e mostra um relatório. Essa é a metade de ler, exclusiva do Claude. O Introspect é a metade de escrever, em todos os agentes que você usa. Youssef colocou bem no thread de onde isso veio: consertar o sistema uma vez para que você não precise consertar a saída mil vezes.
A ideia central que faz isso funcionar: padrões, não táticas
A falha de "o que eu poderia ter feito melhor?" é que ela traz à tona táticas — uma bandeira melhor para um comando, uma abordagem mais esperta para um bug. Isso não se acumula. Desaparece amanhã.
O que se acumula é um hábito que você mantém repetindo: a mesma correção que você dá em três threads diferentes, a mesma preferência que você reitera toda semana, o mesmo erro que o agente comete toda vez que toca na sua configuração de teste. Então toda a habilidade é enviesada para recorrência:
Uma mudança candidata só merece seu lugar quando aparece mais de uma vez, ainda não está escrita em algum lugar e teria plausivelmente mudado o resultado. Todo o resto é ruído — registre, não aja.
Esta também é a resposta honesta para os dois medos que as pessoas levantaram naquele thread:
- "Tenho medo de acumular decisões ruins / meu fluxo de trabalho ficar estúpido." → Nada é escrito sem que você veja o diff exato e aprove. Toda mudança aplicada é registrada e reversível. Em caso de dúvida, proponha menos coisas.
- "Isso só atualiza a habilidade todos os dias para sempre — isso algum dia converge?" → Deve convergir. Se uma regra já existe, você fortalece ou mescla; não adiciona uma segunda. Um dia tranquilo produz um conjunto de mudanças vazio, e isso é um sucesso, não um fracasso.
O pipeline
Coletar → Extrair → Diff vs. configuração existente → Propor conjunto de mudanças → Aprovar → Aplicar + Registrar
(script) (você) (você, lê configuração atual) (você, com evidência) (usuário) (você, reversivelmente)
1. Coletar — execute o script, não reanalise nada manualmente
scripts/collect_threads.py lê o armazenamento de threads de cada agente (JSONL do Claude, arquivos de rollout do Codex, SQLite do Cursor), filtra para uma janela, oculta segredos e emite UM resumo comum: por sessão ele marca qual agente era, os prompts digitados pelo humano, as ferramentas usadas, onde as ferramentas erraram e sinais leves de "atrito" (prompts que parecem correções, ferramentas chamadas muitas vezes seguidas).
python3 scripts/collect_threads.py --days 1 # hoje, todo agente instalado (auto)
python3 scripts/collect_threads.py --agent all --days 7 # última semana, força todos os três
python3 scripts/collect_threads.py --agent codex --format md
python3 scripts/collect_threads.py --since 2026-07-01 --until 2026-07-05 --format json
python3 scripts/collect_threads.py --project ~/dev/myproject # um projeto
python3 scripts/collect_threads.py --selftest # teste de sanidade para todos os três parsers
--agent padrão é auto (detecta quais agentes estão instalados). Use --format md quando for ler você mesmo; --format json para pós-processamento. O script nunca decide nada — ele fornece material bruto limpo e normalizado para que você use seu julgamento no que importa, não em analisar três formatos de transcrição diferentes.
2. Extrair — leia o resumo e extraia três tipos de coisa
Leia o resumo como se você fosse o chefe de gabinete do usuário revisando o dia em todas as suas ferramentas. As preferências do usuário vêm primeiro — esta habilidade é principalmente sobre aprender como eles gostam de trabalhar, não sobre policiar o comportamento padrão do agente. Separe:
- Preferências duráveis (o principal evento) — o usuário corrigindo um padrão ou reafirmando como gosta das coisas ("não, use pnpm", "pare de adicionar comentários", "sempre corte um branch do development primeiro", "não toque na worktree"). Uma preferência que aparece EM AMBOS os seus threads do Claude e do Codex é um sinal especialmente forte — é sobre você, não sobre a ferramenta.
- Lacunas de configuração que fizeram o agente repetir trabalho — onde o agente redescobriu ou ficou preso em múltiplas sessões porque algo não estava escrito: reaprender um comando de build, reencontrar um arquivo que sempre está no mesmo lugar, perder um contexto de projeto. A correção é escrever a coisa faltante na configuração do usuário — NÃO adicionar uma regra repreendendo o agente. Se uma repetição é apenas comportamento genérico do agente sem correção específica do usuário (ex: "leia um arquivo antes de editá-lo"), isso não é uma regra, é ruído; deixe de fora.
- Fluxos de trabalho reutilizáveis — uma coisa de várias etapas que o usuário executou mais de uma vez que merece ser uma habilidade ou um comando para ser uma única etapa na próxima vez.
Para cada candidato, anote a evidência: qual agente, quais sessões, quantas vezes, uma citação curta. Sem evidência de recorrência → é uma tática, não um padrão → descarte.
3. Diff contra a configuração existente — a etapa anti-inchaço / convergência
Antes de propor qualquer coisa, leia o que já está lá para o(s) agente(s) relevante(s), para que você fortaleça o sistema em vez de inchá-lo. references/routing.md tem os locais e formatos exatos de leitura/escrita para cada agente; a versão resumida:
| Agente | Configuração existente para ler (e depois escrever) |
|---|---|
| Claude | ~/.claude/CLAUDE.md (global), ./CLAUDE.md, memória por projeto ~/.claude/projects/<dir>/memory/, ~/.claude/skills/, ~/.claude/commands/ |
| Codex | ~/.codex/AGENTS.md (global), <repo>/AGENTS.md (projeto), skills em ~/.agents/skills/ |
| Cursor | .cursor/rules/*.mdc (projeto), .cursorrules legado, AGENTS.md |
Para cada candidato pergunte: Isso já está coberto? Se sim → descarte, ou proponha uma pequena edição que aprimore a regra existente. Nunca adicione uma segunda regra que diga quase a mesma coisa. Se dois candidatos se sobrepõem, mescle-os. Prefira editar a adicionar.
Dica entre agentes: AGENTS.md é lido pelo Codex e Cursor, e muitas pessoas criam um symlink para CLAUDE.md. Se uma preferência é genuinamente universal, prefira escrevê-la onde todos os agentes a veem (um AGENTS.md, ou um symlink CLAUDE.md↔AGENTS.md) em vez de duplicá-la três vezes. Sempre resolva symlinks antes de escrever para saber qual arquivo você está realmente editando.
4. Propor um conjunto de mudanças — diffs concretos com evidência, limitado
Apresente um conjunto de mudanças: uma lista ordenada e escaneável onde cada item tem o agente + arquivo alvo, a edição exata (um diff ou um antes/depois claramente marcado), a evidência e uma confiança. Use o formato em references/changeset-format.md. Duas regras mantêm a sanidade:
- Limite. Apresente no máximo ~5 mudanças por execução, com maior confiança primeiro. Qualquer outra coisa vai para uma seção de "backlog" — anotado, não aplicado. Uma enxurrada de edições é como os fluxos de trabalho ficam estúpidos.
- Classifique por recorrência × impacto. Uma preferência declarada três vezes que evitará uma correção a cada sessão supera uma esperteza pontual toda vez.
Sempre salve o conjunto de mudanças em um relatório datado mesmo que nada seja aplicado, para que haja um registro para consultar depois (isso responde à pergunta do thread "você salva as saídas em algum lugar, ou apenas lê e segue?"). Escreva para ~/.introspect/reports/YYYY-MM-DD.md.
5. Aprovar — a barreira
Mostre o conjunto de mudanças e deixe o usuário escolher o que aplicar: tudo, alguns ou nenhum. Padrão para propor-e-aprovar — não edite a configuração de nenhum agente sem um sim explícito. Use AskUserQuestion (seleção múltipla) para permitir que eles escolham itens quando houver vários. Se o usuário pediu explicitamente por uma execução não supervisionada/agendada, veja "Execuções não supervisionadas" abaixo.
6. Aplicar + registrar — reversivelmente
Para cada item aprovado, escreva na superfície correta (formatos completos em references/routing.md):
- Claude — CLAUDE.md: anexe sob a seção
##correta ou edite a regra no lugar; mantenha o estilo da casa (curto, imperativo, explica por quê). - Claude — memória: crie/anexe um arquivo de nó e adicione uma linha de índice ao
MEMORY.md; corresponda às convençõesfeedback_*/project_*/reference_*e links cruzados[[wikilink]]. - Claude — skill/comando: crie/edite
~/.claude/skills/<nome>/SKILL.mdou~/.claude/commands/<nome>.md. Se várias sessões reescreveram o mesmo script auxiliar, agrupe. - Codex — AGENTS.md: anexe dentro de um bloco gerenciado (
<!-- introspect:begin --> … <!-- end -->) para que reexecuções sejam idempotentes; mantenha compacto (Codex trunca AGENTS.md em ~32 KiB). Prefira oAGENTS.mdna raiz do projeto (o aplicativo Desktop não carrega confiavelmente o global). - Cursor — .cursor/rules/*.mdc: escreva um arquivo de regra com frontmatter YAML (
alwaysApply: truepara preferências sempre ativas, oudescription:+alwaysApply: false). NÃO tente escrever as "Memórias" em nuvem do Cursor; use arquivos de regra. Não escreva nostate.vscdbativo enquanto o Cursor estiver em execução.
Em seguida, adicione uma linha ao ledger em ~/.introspect/ledger.jsonl — um objeto JSON por mudança aplicada: {date, agent, target_file, kind, summary, evidence, sessions, undo_hint}. O ledger permite que você (a) mostre como a configuração se acumulou ao longo do tempo e (b) desfaça uma mudança depois. Antes de editar um arquivo existente, anote seu estado anterior em undo_hint (ou mantenha um .bak).
Modelo de segurança (leia isto — é a razão pela qual é seguro executar diariamente)
- Propor, não impor. Barreira de aprovação ativada por padrão. O usuário vê cada diff.
- Limiar de recorrência. Não proponha a partir de uma única ocorrência. Hábitos, não táticas.
- Convergir, não agitar. Fortaleça/mescle regras existentes em vez de adicionar quase duplicatas. Uma execução que não muda nada é perfeitamente aceitável e esperada em um dia tranquilo.
- Limitar o raio de explosão. Máximo de ~5 mudanças por execução; o restante vai para o backlog.
- Regras são sobre o usuário, não sobre o agente. Capture como o usuário quer trabalhar. Não crie regras que apenas reafirmam a competência base do agente (como "leia antes de editar") — isso é inchaço. Um sinal de "o agente travou / repetiu-se" merece uma mudança apenas quando anotar uma parte da configuração do usuário evitaria a repetição.
- Nunca armazene segredos. O coletor oculta formas comuns de chave/token, mas fique alerta: nunca copie uma chave de API, senha, valor de
.envou token para uma regra ou relatório. Se você vir um, deixe-o de fora e (se parecer ativo) sinalize para o usuário. - Reversível. Tudo aplicado está no ledger com uma dica de desfazer.
- Superfície certa, escopo certo. Preferências para todo o usuário → arquivo global para aquele agente. Fatos específicos do projeto → configuração daquele projeto. Não coloque trivialidades de projeto em um arquivo global.
Gatilhos — três maneiras de executar
- Por demanda. "revise meus threads", "execute introspect", "o que eu continuei repetindo esta semana no Claude e Codex", "transforme as correções de hoje em regras". Janela padrão: hoje.
- Diário / agendado (nativo do harness). Registre a execução através do agendador nativo do harness — a skill
scheduleou a ferramenta de rotinaCronCreate— não um cron do SO, launchd ou um loop de shell. A execução nativa roda a rotina dentro do harness com as mesmas ferramentas e permissões, e o usuário a gerencia com/schedule. Um bom padrão é uma vez por dia à noite sobre a janela daquele dia. - A cada N sessões / por atrito (opcional). Algumas pessoas (veja buildooor no thread de origem) preferem acionar isso quando algo deu errado ou a cada ~10 sessões em vez de por um relógio. Conecte como um hook
Stopque conta invocações e cutuca após N. Ofereça; nunca instale um hook sem aprovação.
Execuções não supervisionadas
Se invocado por uma agenda/rotina sem humano presente, não aplique silenciosamente mudanças na configuração de nenhum agente. Em vez disso: execute o pipeline, escreva o relatório datado com o conjunto de mudanças proposto para ~/.introspect/reports/ e apresente um breve resumo (via notificação da rotina) para que o usuário possa aprovar na próxima sessão interativa. A única categoria segura para auto-aplicar não supervisionada é um novo nó de memória do Claude que não duplica nada — e mesmo assim, registre. Mantenha o acúmulo sob controle humano; esse é o ponto.
Referências
references/routing.md— fontes de leitura por agente + superfícies de escrita + formatos exatos em disco (CLAUDE.md, memória, AGENTS.md, .cursor/rules/*.mdc) e os esquemas de transcrição que o coletor usa.references/changeset-format.md— os modelos de conjunto de mudanças + relatório + ledger.scripts/collect_threads.py— o coletor multiagente (execute--selftestpara verificar).
Repetindo o loop central, porque é a coisa toda: coletar os threads de todos os agentes → encontrar os padrões recorrentes (não táticas únicas) → verificar se já não estão escritos → propor um pequeno conjunto de mudanças limitado com evidência → aplicar apenas o que foi aprovado na configuração do agente certo → registrar reversivelmente.