Criar e manter uma ferramenta de agentes de pesquisa que funcione no seu próprio computador

## Rodar a ferramenta de pesquisa no computador do usuário e decidir o que ela não fará Crie um ambiente de pesquisa orientado ao uso local que, por padrão, seja executado na máquina do usuário, seja instalado por um caminho público documentado, armazene o estado durável em arquivos e no controle de versão e ofereça o ciclo completo de pesquisa em um único espaço de trabalho do projeto. Mantenha um ambiente de execução da implementação como autoridade, mesmo quando um inicializador leve ou várias interfaces o exponham. Use instruções e capacidades especializadas para orientar a pesquisa, enquanto um serviço pequeno persiste, restaura e encaminha o estado. Otimize para um núcleo bem delimitado, não para uma plataforma em expansão, e declare os objetivos excluídos sempre que uma proposta ampliar o ambiente de execução, as ferramentas públicas ou a superfície de implantação. ## Confiar nos arquivos e no comportamento atuais, não na memória ou em planos antigos Comece pelos arquivos existentes na cópia de trabalho atual, não pela memória nem por um plano antigo. Leia a visão geral do produto, o índice da documentação, a arquitetura para mantenedores, o guia de desenvolvimento, o menor conjunto de referências específicas do subsistema, a implementação e os testes pertinentes. Quando as fontes divergirem, dê preferência ao comportamento atual durante a execução e aos testes de contrato aprovados; depois, ao guia de todo o repositório; em seguida, à documentação oficial para mantenedores; por último, às notas complementares para colaboradores. Atualize a documentação incorreta na mesma alteração, em vez de preservar um caminho, uma afirmação sobre recursos ou um fluxo de trabalho desatualizados. Trate o comportamento planejado e o implementado como afirmações diferentes. Não descreva um componente como disponível até que sua implementação, configuração, integração, documentação e testes sustentem essa afirmação. ## Separar as regras para quem contribui com o código das regras para a IA dentro da ferramenta Distinga as instruções para colaboradores do repositório das instruções e capacidades que regem um agente executado dentro do produto. Um contrato de execução pode exigir uma ferramenta pública específica ou um caminho de execução restrito sem impor a mesma limitação aos mantenedores que editam o repositório. Preserve essa fronteira sempre que mudar o comportamento de uma instrução, capacidade, comando ou ferramenta. Não reinterprete um contrato de segurança interno do produto como regra de contribuição e não enfraqueça o contrato de execução apenas porque os mantenedores dispõem de ferramentas locais de desenvolvimento mais amplas. ## Manter cada projeto de pesquisa em uma pasta com histórico de versões Trate cada projeto de pesquisa como um único repositório com controle de versão e uma única raiz absoluta. Mantenha todo o conteúdo durável da pesquisa dentro dessa raiz e use ramificações ou árvores de trabalho isoladas para representar abordagens divergentes sem dividir o histórico do projeto entre locais sem relação. Mantenha um contrato explícito do espaço de trabalho para a especificação, o plano, o estado, o resumo, os artefatos, as linhas de base, os experimentos, a literatura, as transferências, o manuscrito, a memória e o estado privado de execução. Caches e registros de execução podem ficar fora do projeto, mas não podem se tornar a única cópia das evidências da pesquisa. Quando a estrutura do projeto mudar, atualize em conjunto o modelo de estrutura, os serviços de persistência, os instantâneos de estado, os consumidores da API, as interfaces de usuário, os testes e a documentação. Não migre apenas um consumidor, deixando os demais em uma estrutura obsoleta. ## Manter simples o programa de inicialização e verificar o que está rodando antes de reiniciar Mantenha o ambiente de execução oficial da pesquisa em uma única camada de implementação e faça dos inicializadores do gerenciador de pacotes adaptadores leves sobre esse ambiente e sobre quaisquer pacotes de interface pré-compilados. Os pacotes públicos de instalação devem conter os arquivos e clientes compilados necessários para iniciar; não dependa de uma compilação posterior à instalação pelo usuário final para tornar funcional o caminho compatível. Antes de depurar ou reiniciar uma instalação ativa, examine o processo em execução, a configuração efetiva, o supervisor ou inicializador existente, o executável realmente usado e o caminho inicial informado por um endpoint de integridade. Nunca deduza o caminho inicial ativo, a configuração ou o proprietário do processo apenas com base em um diretório padrão. Alinhe os manifestos dos pacotes, os metadados do projeto, a documentação pública e as expectativas sobre os pacotes distribuídos. Uma prévia do pacote ou uma simulação deve confirmar o conjunto de arquivos distribuído antes que o empacotamento seja considerado concluído. ## Manter poucas ferramentas públicas para a IA e justificar cada nova Limite a superfície pública de ferramentas incorporadas a poucas responsabilidades estáveis: memória durável, artefatos versionados e execução durável de comandos. Mantenha o comportamento do controle de versão atrás da fronteira dos artefatos e a execução do shell atrás da fronteira de execução, em vez de adicionar um novo espaço de nomes público para cada subsistema. Deixe que as instruções definam as expectativas do fluxo de trabalho e os contratos do sistema de arquivos, e que as capacidades ofereçam comportamento de execução especializado. O serviço de estado deve permanecer enxuto; evite fixar no código um grande agendador central de etapas quando os contratos de instruções e capacidades puderem expressar o fluxo de trabalho com clareza. Qualquer proposta de nova ferramenta pública deve demonstrar que nenhuma responsabilidade existente pode contê-la, definir seu modelo de persistência e permissões, atualizar todos os clientes e acrescentar testes de contrato. A mera conveniência não basta. ## Adicionar novas conexões por listas pequenas e só dá-las por concluídas quando tudo estiver pronto Use registros pequenos para executores de pesquisa, canais de comunicação, pontes de conectores, descoberta de capacidades, ferramentas locais gerenciadas e adaptadores opcionais. Prefira interfaces uniformes de registro, consulta e listagem a grandes ramificações de despacho ou condições específicas de subsistemas. Não considere uma integração implementada até que estejam presentes seu adaptador de execução, os metadados do registro, os padrões de configuração, a validação, a ligação ao serviço e à linha de comando, a documentação visível ao usuário e os testes. A ausência de uma camada significa que a integração é parcial. Mantenha os adaptadores opcionais fora do caminho central e explicite quando não estiverem presentes. Uma entrada do registro deve expor capacidades e compatibilidade sem instalar dependências silenciosamente, acessar um serviço externo ou alterar a configuração local. ## Usar o mesmo estado do projeto e a mesma conexão com o serviço (API) no navegador e no terminal Exija que as interfaces de navegador e terminal consumam a mesma API de serviço, os mesmos instantâneos de estado e o mesmo modelo de eventos. Quando uma rota da API ou um evento mudar, atualize na mesma alteração o serviço, todos os clientes, as premissas de navegação e os testes de contrato. Preserve rotas e identificadores estáveis orientados a projetos em todas as interfaces. As interfaces de usuário podem apresentar disposições diferentes, mas não podem criar semânticas de estado separadas nem ocultar uma transição que outra interface compatível precise observar. Trate um canal de comunicação de primeira classe como implementação do modelo genérico de canais e pontes. Não permita que um conector importante se torne um ambiente de execução separado, com regras próprias de persistência, tratamento de erros ou ciclo de vida. ## Definir as etapas da pesquisa, da busca à escrita, sem forçar uma linha reta Defina uma progressão oficial pequena, como descoberta, linha de base, formulação de ideias, experimentação, análise, redação e finalização. Mantenha a tomada de decisões como atividade transversal, em vez de fingir que toda atividade importante corresponde a uma única etapa linear. Auditorias de entrada, preparação de figuras, revisão e resposta a pareceres podem existir como atividades especializadas, mas não as coloque na cadeia padrão a menos que o código atual e os contratos de instrução realmente o façam. As etapas nomeadas devem corresponder aos pontos de ancoragem ativos, às transições de estado e à documentação do usuário do sistema. Mantenha o comportamento das etapas na instrução do sistema, nos contratos de instrução específicos, na montagem das instruções e nas capacidades das etapas. Evite espalhar a semântica das etapas entre manipuladores de serviço, código de interface e condições criadas caso a caso. ## Separar os guias para usuários dos documentos para desenvolvedores Mantenha os guias voltados ao usuário separados da arquitetura para mantenedores e das referências de desenvolvimento. A documentação pública deve explicar o comportamento atual; os documentos para mantenedores devem explicar contratos, pontos de extensão e requisitos de alterações coordenadas. Não coloque planos temporários, listas de verificação provisórias, caminhos privados nem notas exclusivamente internas na árvore de documentação pública. Mantenha estáveis os nomes dos documentos vinculados, remova referências a arquivos excluídos e atualize todas as traduções mantidas quando um comportamento visível ao usuário mudar. Quando uma alteração afetar apenas a manutenção interna, atualize as referências oficiais para mantenedores sem inventar um anúncio voltado ao usuário. O alcance da documentação deve acompanhar o alcance do comportamento. ## Manter senhas e caminhos pessoais fora dos arquivos compartilhados e preservar os registros da pesquisa Não registre no controle de versão caminhos absolutos específicos da estação de trabalho, credenciais, tokens, caches locais, diretórios de dependências, saídas transitórias da compilação nem caches de testes. Pacotes de interface gerados só pertencem a um pacote público quando o contrato de empacotamento os exige explicitamente. Mantenha registros duráveis de experimentos, notas de literatura, linhas de base, artefatos e manuscritos dentro da fronteira do projeto e sob controle de versão. Preserve as evidências originais antes de resumi-las e nunca substitua um resultado reproduzível por uma simples mensagem de estado da interface. Antes do lançamento, examine os arquivos públicos em busca de segredos expostos, nomes de documentos obsoletos, referências privadas e divergências em arquivos gerados. Uma execução de testes sem erros não justifica a publicação de conteúdo sensível ou não reproduzível. ## Examinar primeiro o código atual e fazer alterações pequenas Examine a implementação existente antes de propor uma nova abstração. Prefira alterações pequenas e coerentes a refatorações amplas e misturadas, use primeiro o menor conjunto pertinente de documentação e confira a proposta em relação ao código e aos testes. Quando o código e a documentação divergirem, corrija ambos em uma única alteração delimitada. Não preserve referências desatualizadas apenas porque já existiram e não reinicie um serviço de pesquisa ativo até identificar o ambiente de execução efetivo, o processo, a configuração e o caminho inicial. Separe o diagnóstico da alteração. Registre o sinal observado, o comportamento esperado, os consumidores afetados e a menor correção antes de mudar o estado compartilhado. ## Atualizar testes e documentação junto com o código alterado, sem mexer no que não tem relação Atualize todas as camadas diretamente afetadas do subsistema alterado: - estrutura do projeto ou estado durável: modelo de estrutura, serviço de persistência, instantâneos, consumidores da API e testes de estado; - instruções ou capacidades das etapas: fontes de instruções, montagem, definições de capacidades, instaladores espelhados, testes de comportamento e guias do usuário; - memória, artefatos ou execução de comandos: implementações, fronteiras públicas, testes de serviço e documentação de contratos; - executores de pesquisa: adaptador, registro, padrões de configuração, validação, ligação ao serviço e à linha de comando, guias e testes; - canais ou pontes de conectores: padrões, validação, código de canais e pontes, guias de conectores e testes de integração; - ferramentas locais gerenciadas: registro, adaptador concreto, comportamento de estado e resolução, guias para mantenedores e testes; - superfície compartilhada da API: roteador, manipuladores, cliente de navegador, cliente de terminal, navegação e testes de contrato; - empacotamento: manifestos, metadados do projeto, visão geral pública, pacotes exigidos e verificação do conteúdo do pacote. Não amplie essa matriz para subsistemas sem relação. Seu propósito é garantir completude coordenada dentro da fronteira de impacto direto, não reescrever todo o repositório. ## Testar a instalação documentada antes de dar o trabalho por concluído Execute as verificações pertinentes de unidade, integração, contrato, compilação, construção de interfaces e empacotamento para a superfície alterada. Inicie pelo caminho público documentado quando o comportamento do inicializador ou do empacotamento mudar e verifique a inicialização direta do serviço apenas como caminho de diagnóstico. Revise a diferença final em busca de edições sem relação, arquivos gerados desatualizados, documentação traduzida ausente, afirmações de recursos sem suporte e atualizações incompletas de clientes. Distinga um teste de componente bem-sucedido localmente da prova de que o caminho compatível de instalação e interface funciona. Use a cópia de trabalho real como fonte final de autoridade. Se um arquivo ou comportamento mencionado não existir mais, corrija a referência e seus consumidores em vez de preservar o erro.