100 Dicas para Construir um Agente de IA Pessoal: Do Protótipo na Nuvem à Produção

Um desenvolvedor passou seis semanas construindo um agente de IA pessoal do zero — não um wrapper de chatbot, mas um assistente persistente que gerencia tarefas, acompanha negócios, lê e-mails, analisa dados de negócios e proativamente levanta itens perdidos. O projeto começou na nuvem (Claude Projects com arquivos de memória compartilhados, janelas de contexto amplas, habilidades personalizadas) e depois migrou para o Claude Code dentro do VS Code, que liberou acesso a arquivos locais, rastreamento git, hooks de shell e tarefas headless agendadas. A migração forçou a resolução de problemas que eles nem sabiam que existiam. Essas 100 dicas são o resultado destilado, com o uso máximo do Claude 20x passando de 100% desenvolvimento / 0% mundo real inicialmente para 20% / 80% após seis semanas.

Fundação e Identidade (1–8)

• Escreva uma Constituição, não um prompt de sistema. Um prompt de sistema lista comandos; uma Constituição explica regras. Quando o agente encontra um caso extremo que nenhuma regra cobre, ele raciocina a partir da Constituição em vez de adivinhar. Isso separa agentes que degradam graciosamente daqueles que alucinam com confiança.
• Dê ao seu agente um nome, voz e papel. Exemplo: "Sempre em primeira pessoa. Direto. Dados antes de emoção. Sem palavras de preenchimento. Sem resumos finais." Isso elimina centenas de microdecisões por sessão e cria consistência para auditoria.
• Separe regras rígidas de diretrizes comportamentais. Regras rígidas em uma seção dedicada — nunca substituídas. Diretrizes comportamentais se adaptam. Misturá-las torna ambas sem sentido.
• Defina profundamente seu principal. Quem o agente serve? O que os frustra? Como eles decidem? Exemplo: "Decide com dados, não com instinto. Quer alternativas com pontuação, não uma única recomendação. Odeia respostas vagas."
• Construa um Mapa de Capacidades e um Mapa de Componentes separadamente. Mapa de Capacidades: o que o agente pode fazer (habilidades, integrações, automações). Mapa de Componentes: como é construído (arquivos, conexões). Conflitá-los cria um documento inútil após o terceiro mês.
• Defina o que o agente NÃO é. "Não é um resumidor. Não é uma máquina de sim. Não é um mecanismo de busca. Não espera ser perguntado." Definições negativas previnem o desvio para a utilidade genérica.
• Construa um modelo mental PENSAR vs. FAZER. Quando incerto → PENSAR (analisar, rascunhar, preparar). Quando claro → FAZER (executar, escrever, despachar). Nunca congelar. Padrão para ação no nível mais baixo de risco, apresente o resultado.
• Versionar seu arquivo de identidade no git. git blame na configuração ajuda a depurar regressões comportamentais que remontam a edições específicas.

Sistema de Memória (9–18)

• Use arquivos markdown simples para memória — não um banco de dados. Legíveis, pesquisáveis, rastreáveis por git, diretamente carregáveis pelo agente. Nenhuma camada de infraestrutura.
• Separe a memória por domínio, não por data. Arquivos como entities_people.md, entities_companies.md, entities_deals.md, hypotheses.md, task_queue.md. Um arquivo = um domínio. Dumps cronológicos tornam-se impossíveis de pesquisar após a segunda semana.
• Construa um arquivo de índice MEMORY.md. Índice único listando cada arquivo de memória com uma descrição de uma linha. O agente carrega o índice primeiro, puxa arquivos específicos sob demanda. Mantém o uso da janela de contexto previsível.
• Distinguir "cache" de "fonte da verdade" — explicitamente. Marque cada arquivo de cache com o timestamp last_sync:. Por exemplo, o deals.md local é um cache do CRM; o CRM é a SSOT.