contexto-baseado-em-filesystem

Engenharia de Contexto Baseada em Filesystem

Use o sistema de arquivos como a principal camada de overflow para o contexto do agente, porque as janelas de contexto são limitadas enquanto as tarefas geralmente requerem mais informações do que cabem em uma única janela. Arquivos permitem que os agentes armazenem, recuperem e atualizem uma quantidade efetivamente ilimitada de contexto através de uma única interface.

Prefira a descoberta dinâmica de contexto -- puxando contexto relevante sob demanda -- em vez da inclusão estática, porque o contexto estático consome tokens independentemente da relevância e ocupa espaço que poderia ser usado para informações específicas da tarefa.

Quando Ativar

Ative esta skill quando:

• Saídas de ferramentas estão inchando a janela de contexto
• Agentes precisam persistir estado em trajetórias longas
• Subagentes precisam compartilhar informações sem passar mensagens diretamente
• Tarefas exigem mais contexto do que cabe na janela
• Construindo agentes que aprendem e atualizam suas próprias instruções
• Implementando scratch pads para resultados intermediários
• Saídas de terminal ou logs precisam estar acessíveis aos agentes

Não ative esta skill para trabalhos adjacentes de outras skills:

• Memória semântica entre sessões, rastreamento de entidades ou grafos de conhecimento temporal: memory-systems.
• Sumarização de conversas, compactação ou redação de handoff durável: context-compression.
• Táticas de eficiência de tokens que não exigem armazenamento em arquivos: context-optimization.
• Topologia de multi-agentes ou design de protocolo de handoff: multi-agent-patterns.
• Edições de modelo que removem conteúdo da janela ativa: self-managed-context.

Conceitos Principais

Diagnostique falhas de contexto com base nestes quatro modos, porque cada um requer um remédio diferente do filesystem:

1. Contexto ausente -- a informação necessária está ausente do contexto total disponível. Corrija persistindo saídas de ferramentas e resultados intermediários em arquivos para que nada seja perdido.
2. Contexto sub-recuperado -- o conteúdo recuperado não encapsula o que o agente precisa. Corrija estruturando arquivos para recuperação direcionada (formatos amigáveis para grep, cabeçalhos de seção claros).
3. Contexto super-recuperado -- o conteúdo recuperado excede em muito o necessário, desperdiçando tokens e degradando a atenção. Corrija offloading de conteúdo em massa para arquivos e retornando referências compactas.
4. Contexto enterrado -- informações específicas estão escondidas em muitos arquivos. Corrija combinando glob e grep para busca estrutural junto com busca semântica para consultas conceituais.

Use o sistema de arquivos como a camada persistente que aborda todos os quatro: escreva uma vez, armazene de forma durável, recupere seletivamente.

Tópicos Detalhados

O Trade-off entre Contexto Estático e Dinâmico

Trate o contexto estático (instruções do sistema, definições de ferramentas, regras críticas) como um imóvel caro -- ele consome tokens a cada turno, independentemente da relevância. À medida que os agentes acumulam capacidades, o contexto estático cresce e ocupa espaço da informação dinâmica.

Use a descoberta dinâmica de contexto: inclua apenas ponteiros estáticos mínimos (nomes, descrições de uma linha, caminhos de arquivos) e carregue o conteúdo completo com ferramentas de busca quando relevante. Isso é mais eficiente em termos de tokens e geralmente melhora a qualidade das respostas, reduzindo informações contraditórias ou irrelevantes na janela.

Aceite o trade-off: a descoberta dinâmica exige que o modelo reconheça quando precisa de mais contexto. Os modelos de fronteira atuais lidam bem com isso, mas modelos menos capazes podem falhar em acionar os carregamentos. Em caso de dúvida, erre para incluir restrições críticas de segurança ou correção estaticamente.

Padrão 1: Filesystem como Scratch Pad

Redirecione saídas grandes de ferramentas para arquivos em vez de retorná-las diretamente ao contexto, porque uma única pesquisa na web ou consulta ao banco de dados pode despejar milhares de tokens no histórico da mensagem, onde persistem por toda a conversa.

Escreva a saída em um arquivo scratch, extraia um resumo compacto e retorne uma referência ao arquivo. O agente então usa recuperação direcionada (grep para padrões, leitura com intervalos de linhas) para acessar apenas o que precisa.

def handle_tool_output(output: str, threshold: int = 2000) -> str:
    if len(output) < threshold:
        return output

    file_path = f"scratch/{tool_name}_{timestamp}.txt"
    write_file(file_path, output)

    key_summary = extract_summary(output, max_tokens=200)
    return f"[Saída gravada em {file_path}. Resumo: {key_summary}]"

Use grep para pesquisar o arquivo descarregado e read_file com intervalos de linhas para recuperar seções direcionadas, porque isso preserva a saída completa para referência futura, mantendo apenas ~100 tokens no contexto ativo.

Padrão 2: Persistência de Planos

Escreva planos no sistema de arquivos porque tarefas de longo horizonte perdem coerência quando os planos saem da atenção ou são resumidos. O agente relê seu plano a qualquer momento, restaurando a consciência do objetivo e do progresso.

Armazene planos em formato estruturado para que sejam legíveis por humanos e analisáveis por máquina:

# scratch/current_plan.yaml
objective: "Refatorar módulo de autenticação"
status: em_andamento
steps:
  - id: 1
    description: "Auditar endpoints de autenticação atuais"
    status: concluído
  - id: 2
    description: "Projetar novo fluxo de validação de token"
    status: em_andamento
  - id: 3
    description: "Implementar e testar alterações"
    status: pendente

Releia o plano no início de cada turno ou após qualquer atualização de contexto para se reorientar, porque isso funciona como "manipulando a atenção através da recitação."

Padrão 3: Comunicação entre Subagentes via Filesystem

Roteie as descobertas dos subagentes através do sistema de arquivos em vez de passagem de mensagens, porque cadeias de mensagens multi-hop degradam a informação através da sumarização a cada salto ("jogo de telefone").

Faça com que cada subagente escreva diretamente em seu próprio diretório de trabalho. O coordenador lê esses arquivos diretamente, preservando a fidelidade total:

workspace/
  agents/
    research_agent/
      findings.md
      sources.jsonl
    code_agent/
      changes.md
      test_results.txt
  coordinator/
    synthesis.md

Imponha isolamento de diretório por agente para evitar conflitos de escrita e manter a propriedade clara de cada artefato de saída.

Padrão 4: Carregamento Dinâmico de Skills

Armazene skills como arquivos e inclua apenas nomes de skills com breves descrições no contexto estático, porque colocar todas as instruções no prompt do sistema desperdiça tokens e pode confundir o modelo com orientações contraditórias.

Skills disponíveis (carregue com read_file quando relevante):
- database-optimization: Ajuste de consultas e estratégias de indexação
- api-design: Melhores práticas de REST/GraphQL
- testing-strategies: Padrões de teste unitário, integração e e2e

Carregue o arquivo completo da skill (por exemplo, skills/database-optimization/SKILL.md) apenas quando a tarefa atual exigir. Isso converte o custo de token estático O(n) em O(1) por tarefa.

Padrão 5: Persistência de Terminal e Logs

Persista a saída do terminal em arquivos automaticamente e use grep para recuperação seletiva, porque a saída do terminal de processos de longa duração se acumula rapidamente e a cópia manual é propensa a erros.

terminals/
  1.txt    # Saída da sessão de terminal 1
  2.txt    # Saída da sessão de terminal 2

Consulte com grep direcionado (grep -A 5 "error" terminals/1.txt) em vez de carregar históricos completos de terminal no contexto.

Padrão 6: Aprendizado Através de Automodificação

Faça com que os agentes escrevam preferências e padrões aprendidos em seus próprios arquivos de instrução, para que sessões subsequentes carreguem esse contexto automaticamente, em vez de exigir atualizações manuais no prompt do sistema.

def remember_preference(key: str, value: str):
    preferences_file = "agent/user_preferences.yaml"
    prefs = load_yaml(preferences_file)
    prefs[key] = value
    write_yaml(preferences_file, prefs)

Proteja este padrão com validação, porque a automodificação pode acumular instruções incorretas ou contraditórias ao longo do tempo. Trate-o como experimental -- revise as preferências persistidas periodicamente.

Técnicas de Busca no Filesystem

Combine ls/list_dir, glob, grep e read_file com intervalos de linhas para descoberta de contexto, porque os modelos são especificamente treinados em travessia de filesystem e essa combinação geralmente supera a busca semântica para conteúdo técnico onde os padrões estruturais são claros.

• ls / list_dir: Descobrir estrutura de diretórios
• glob: Encontrar arquivos correspondentes a padrões (por exemplo, **/*.py)
• grep: Pesquisar conteúdo de arquivos, retorna linhas correspondentes com contexto
• read_file com intervalos: Ler seções específicas sem carregar arquivos inteiros

Use a busca no filesystem para consultas estruturais e de correspondência exata, e busca semântica para consultas conceituais. Combine ambas para uma descoberta abrangente.

Orientação Prática

Quando Usar Contexto de Filesystem

Aplique padrões de filesystem quando a situação corresponder a estes critérios, porque eles adicionam sobrecarga de E/S que só é justificada pela economia de tokens ou necessidades de persistência:

Use quando:

• Saídas de ferramentas excedem ~2000 tokens
• Tarefas abrangem vários turnos de conversa
• Vários agentes precisam de estado compartilhado
• Skills ou instruções excedem o tamanho confortável do prompt do sistema
• Logs ou saída de terminal precisam de consulta seletiva

Evite quando:

• Tarefas são concluídas em turnos únicos (sobrecarga não justificada)
• O contexto cabe confortavelmente na janela (nenhum problema a resolver)
• A latência é crítica (E/S de arquivo adiciona atraso mensurável)
• O modelo não tem capacidades de ferramentas de filesystem

Organização de Arquivos

Estruture arquivos para descoberta pelo agente, porque os agentes navegam listando e lendo nomes de diretórios:

project/
  scratch/           # Arquivos de trabalho temporários
    tool_outputs/    # Grandes resultados de ferramentas
    plans/           # Planos ativos e listas de verificação
  memory/            # Informações persistentes aprendidas
    preferences.yaml # Preferências do usuário
    patterns.md      # Padrões aprendidos
  skills/            # Definições de skills carregáveis
  agents/            # Espaços de trabalho de subagentes

Use convenções de nomenclatura consistentes e inclua timestamps ou IDs em arquivos scratch para desambiguação.

Para loops de pesquisa autônomos, armazene evidências brutas recuperadas na execução que as consumiu, por exemplo researcher/runs/<run-id>/sources/evidence/raw/. Não deixe despejos de pesquisa brutos na raiz do repositório; artefatos no nível da raiz tornam-se difíceis de auditar e fáceis de citar sem procedência.

Contabilidade de Tokens

Meça de onde os tokens se originam antes e depois de aplicar padrões de filesystem, porque otimizar sem medir leva a esforço desperdiçado:

• Acompanhe a proporção de contexto estático vs dinâmico
• Monitore os tamanhos das saídas das ferramentas antes e depois do offloading
• Meça com que frequência o contexto carregado dinamicamente é realmente usado

Exemplos

Exemplo 1: Offloading de Saída de Ferramenta

Entrada: Pesquisa na web retorna 8000 tokens
Antes: 8000 tokens adicionados ao histórico da mensagem
Depois:
  - Escrever em scratch/search_results_001.txt
  - Retornar: "[Resultados em scratch/search_results_001.txt. Descoberta principal: Limite de taxa da API é 1000 req/min]"
  - Agente usa grep no arquivo quando precisa de detalhes específicos
Resultado: ~100 tokens no contexto, 8000 tokens acessíveis sob demanda

Exemplo 2: Carregamento Dinâmico de Skill

Entrada: Usuário pergunta sobre indexação de banco de dados
Contexto estático: "database-optimization: Ajuste de consultas e indexação"
Ação do agente: read_file("skills/database-optimization/SKILL.md")
Resultado: Skill completa carregada apenas quando relevante

Exemplo 3: Histórico de Chat como Referência de Arquivo

Gatilho: Limite da janela de contexto atingido, sumarização necessária
Ação:
  1. Escrever histórico completo em history/session_001.txt
  2. Gerar resumo para nova janela de contexto
  3. Incluir referência: "Histórico completo em history/session_001.txt"
Resultado: Agente pode pesquisar o arquivo de histórico para recuperar detalhes perdidos na sumarização

Diretrizes

1. Escreva saídas grandes em arquivos; retorne resumos e referências ao contexto
2. Armazene planos e estado em arquivos estruturados para releitura
3. Use espaços de trabalho de arquivos de subagentes em vez de cadeias de mensagens
4. Carregue skills dinamicamente em vez de colocar tudo no prompt do sistema
5. Persista saída de terminal e logs como arquivos pesquisáveis
6. Combine grep/glob com busca semântica para descoberta abrangente
7. Organize arquivos para descoberta pelo agente com nomenclatura clara
8. Meça a economia de tokens para validar que os padrões de filesystem são eficazes
9. Implemente limpeza de arquivos scratch para evitar crescimento infinito
10. Proteja padrões de automodificação com validação
11. Mantenha evidências brutas próximas à execução, avaliação e proposta que as usou

Armadilhas

1. Crescimento infinito do diretório scratch: Agentes criam arquivos temporários sem limpeza, eventualmente consumindo disco e tornando as listagens de diretório ruidosas. Implemente uma política de retenção (baseada em idade ou contagem) e execute a limpeza nos limites da sessão.
2. Condições de corrida no acesso a arquivos por múltiplos agentes: Gravações simultâneas no mesmo arquivo corrompem o estado silenciosamente. Imponha isolamento de diretório por agente ou use arquivos somente para anexar com entradas prefixadas pelo agente.
3. Referências de arquivo obsoletas após movimentações/renomeações: Agentes mantêm caminhos de turnos anteriores que não existem mais após refatorações ou reorganização de arquivos. Sempre verifique a existência do arquivo antes de ler um caminho em cache; redescubra com glob se a verificação falhar.
4. Falsos positivos em padrões glob: Padrões excessivamente amplos (por exemplo, **/*) puxam arquivos irrelevantes para o contexto, desperdiçando tokens e confundindo o modelo. Escopo globs para diretórios e extensões específicas.
5. Suposições de tamanho de arquivo: Ler um arquivo sem verificar o tamanho pode despejar 100K+ tokens no contexto em uma única chamada de ferramenta. Verifique o tamanho do arquivo antes de ler; use leituras com intervalo de linhas para arquivos grandes.
6. Falta de verificação de existência de arquivo: Agentes assumem que arquivos existem de turnos anteriores, mas eles podem ter sido excluídos ou movidos. Sempre proteja leituras com verificações de existência e trate erros de arquivo ausente com elegância.
7. Deriva de formato do scratch pad: Scratch pads não estruturados tornam-se impossíveis de analisar após muitas gravações porque as convenções de formato se desgastam com anexos sucessivos. Defina e imponha um esquema (YAML, JSON ou markdown estruturado) desde a primeira gravação.
8. Caminhos absolutos codificados: Quebram quando os repositórios são verificados em locais diferentes ou quando executados em contêineres. Use caminhos relativos a partir da raiz do projeto ou resolva caminhos dinamicamente.

Integração

Esta skill é proprietária do armazenamento de contexto baseado em arquivos

... [truncado para tradução]