desenvolvimento-de-projetos

Metodologia de Desenvolvimento de Projetos

Este skill abrange os princípios para identificar tarefas adequadas ao processamento com LLM, projetar arquiteturas de projeto eficazes e iterar rapidamente usando desenvolvimento assistido por agente. A metodologia se aplica tanto na construção de um pipeline de processamento em lote, um sistema de pesquisa multi-agente ou uma aplicação de agente interativa.

A unidade de trabalho para este skill é o projeto inteiro ou um pipeline multi-estágio. O design de ferramentas individuais (descrições, esquemas, mensagens de erro) pertence ao tool-design. O roteamento de ativação por skill pertence ao skill correspondente mais o índice do corpus. Este skill é dono das perguntas em nível de projeto: você deve construir isso com um LLM? Qual formato o pipeline deve ter? Quanto custa? Como deve ser iterado?

Quando Ativar

Ative este skill quando a unidade de trabalho for um projeto inteiro ou pipeline:

• Decidir se um LLM é a primitiva certa para uma tarefa (task-model fit antes de qualquer código).
• Definir a forma de um pipeline multi-estágio em lote ou agente (adquirir / preparar / processar / analisar / renderizar).
• Estimar tokens, custo em dólar e cronogramas para um projeto pesado em LLM.
• Escolher entre agente único e multi-agente no nível do projeto.
• Estruturar iteração assistida por agente (onde o agente ajuda a construir o próprio projeto).
• Projetar saída estruturada no nível do contrato do pipeline (formato de handoff entre estágios).

Não ative este skill para trabalhos adjacentes de outros skills:

• Descrição, esquema, nome, formato de resposta, mensagem de erro por ferramenta: tool-design.
• Táticas de eficiência de tokens por trajetória (mascaramento, particionamento, cache): context-optimization.
• Decidir dividir o trabalho entre sub-agentes no nível da topologia do agente: multi-agent-patterns.
• Projetar o loop de controle autônomo (métricas bloqueadas, portas de novidade, limites de aprovação humana): harness-engineering.

Conceitos Centrais

Reconhecimento de Task-Model Fit

Avalie o task-model fit antes de escrever qualquer código, porque construir automação em uma tarefa fundamentalmente incompatível desperdiça dias de esforço. Execute cada tarefa proposta por meio destas duas tabelas para decidir prosseguir ou parar.

Prosseguir quando a tarefa tiver estas características:

Característica	Justificativa
Síntese entre fontes	LLMs combinam informações de múltiplas entradas melhor que alternativas baseadas em regras
Julgamento subjetivo com rubricas	Classificação, avaliação e categorização com critérios mapeiam naturalmente para raciocínio de linguagem
Saída em linguagem natural	Quando o objetivo é texto legível por humanos, LLMs o entregam nativamente
Tolerância a erros	Falhas individuais não quebram o sistema geral, então o não-determinismo do LLM é aceitável
Processamento em lote	Nenhum estado conversacional é necessário entre itens, mantendo o contexto limpo
Conhecimento de domínio no treinamento	O modelo já tem contexto relevante, reduzindo a sobrecarga de engenharia de prompt

Parar quando a tarefa tiver estas características:

Característica	Justificativa
Cálculo preciso	Matemática, contagem e algoritmos exatos são não confiáveis em modelos de linguagem
Requisitos de tempo real	A latência do LLM é muito alta para respostas em sub-segundos
Requisitos de precisão perfeita	Risco de alucinação torna 100% de precisão impossível
Dependência de dados proprietários	O modelo não tem o contexto necessário e não pode adquiri-lo apenas com prompts
Dependências sequenciais	Cada etapa depende fortemente do resultado anterior, amplificando erros
Requisitos de saída determinística	A mesma entrada deve produzir saída idêntica, o que LLMs não podem garantir

A Etapa de Protótipo Manual

Sempre valide o task-model fit com um teste manual antes de investir em automação. Copie uma entrada representativa na interface do modelo, avalie a qualidade da saída e use o resultado para responder estas perguntas:

• O modelo tem o conhecimento necessário para esta tarefa?
• O modelo consegue produzir saída no formato necessário?
• Qual nível de qualidade deve ser esperado em escala?
• Existem modos de falha óbvios a serem tratados?

Faça isso porque um protótipo manual falho prevê um sistema automatizado falho, enquanto um bem-sucedido fornece tanto uma linha de base de qualidade quanto um template de design de prompt. O teste leva minutos e evita horas de desenvolvimento desperdiçado.

Arquitetura de Pipeline

Estruture projetos com LLM como pipelines em estágios porque a separação de estágios determinísticos e não-determinísticos permite iteração rápida e controle de custos. Projete cada estágio para ser:

• Discreto: Limites claros entre estágios para que cada um possa ser depurado independentemente
• Idempotente: Re-executar produz o mesmo resultado, evitando trabalho duplicado
• Cacheável: Resultados intermediários persistem em disco, evitando recomputação cara
• Independente: Cada estágio pode ser executado separadamente, permitindo re-execução seletiva

Use esta estrutura de pipeline canônica:

adquirir -> preparar -> processar -> analisar -> renderizar

1. Adquirir: Buscar dados brutos de fontes (APIs, arquivos, bancos de dados)
2. Preparar: Transformar dados no formato de prompt
3. Processar: Executar chamadas LLM (a etapa cara e não-determinística)
4. Analisar: Extrair dados estruturados das saídas do LLM
5. Renderizar: Gerar saídas finais (relatórios, arquivos, visualizações)

Os estágios 1, 2, 4 e 5 são determinísticos. O estágio 3 é não-determinístico e caro. Mantenha essa separação porque permite reexecutar a etapa cara do LLM apenas quando necessário, enquanto itera rapidamente na análise e renderização.

Sistema de Arquivos como Máquina de Estado

Use o sistema de arquivos para rastrear o estado do pipeline em vez de bancos de dados ou estruturas em memória, porque a existência de arquivos fornece idempotência natural e depuração legível por humanos.

dados/{id}/
  raw.json         # estágio de adquirir completo
  prompt.md        # estágio de preparar completo
  response.md      # estágio de processar completo
  parsed.json      # estágio de analisar completo

Verifique se um item precisa ser processado verificando se o arquivo de saída existe. Reexecute um estágio excluindo seu arquivo de saída e os arquivos downstream. Depure lendo os arquivos intermediários diretamente. Esse padrão funciona porque cada diretório é independente, permitindo paralelização simples e cache trivial.

Design de Saída Estruturada

Projete prompts para saídas estruturadas e analisáveis porque o design do prompt determina diretamente a confiabilidade da análise. Inclua estes elementos em cada prompt estruturado:

1. Marcadores de seção: Cabeçalhos ou prefixos explícitos que os parsers possam reconhecer
2. Exemplos de formato: Mostre exatamente como a saída deve ser
3. Divulgação de justificativa: Afirme "Eu analisarei isso programaticamente" para que o modelo priorize a conformidade com o formato
4. Valores restritos: Opções enumeradas, faixas de pontuação e formatos fixos

Construa parsers que lidem graciosamente com variações na saída do LLM, porque LLMs não seguem instruções perfeitamente. Use padrões regex flexíveis o suficiente para variações menores de formatação, forneça padrões sensatos quando seções estiverem faltando e registre falhas de análise para revisão em vez de travar.

Desenvolvimento Assistido por Agente

Use modelos com capacidade de agente para acelerar o desenvolvimento através de iteração rápida: descreva o objetivo e as restrições do projeto, deixe o agente gerar a implementação inicial, teste e itere sobre falhas específicas, depois refine prompts e arquitetura com base nos resultados.

Adote estas práticas porque mantêm a saída do agente focada e de alta qualidade:

• Forneça requisitos claros e específicos desde o início para reduzir ciclos de revisão
• Divida grandes projetos em componentes discretos para que cada um possa ser validado independentemente
• Teste cada componente antes de passar para o próximo para capturar falhas cedo
• Mantenha o agente focado em uma tarefa de cada vez para evitar degradação do contexto

Estimativa de Custo e Escala

Estime os custos de processamento com LLM antes de começar, porque os custos de tokens se acumulam rapidamente em escala e a descoberta tardia de estouros de orçamento força retrabalho caro. Use esta fórmula:

Custo total = (itens x tokens_por_item x preco_por_token) + sobrecarga_de_API

Para processamento em lote, estime tokens de entrada por item (prompt + contexto), estime tokens de saída por item (comprimento típico da resposta), multiplique pela contagem de itens e adicione 20-30% de margem para retentativas e falhas.

Acompanhe os custos reais durante o desenvolvimento. Se os custos excederem significativamente as estimativas, reduza o comprimento do contexto através de truncamento, use modelos menores para itens mais simples, armazene em cache e reutilize resultados parciais ou adicione processamento paralelo para reduzir o tempo real.

Tópicos Detalhados

Escolhendo Arquitetura de Agente Único vs. Multi-Agente

Por padrão, use pipelines de agente único para processamento em lote com itens independentes, porque são mais simples de gerenciar, mais baratos de executar e mais fáceis de depurar. Escale para arquiteturas multi-agente apenas quando uma destas condições se aplicar:

• Exploração paralela de diferentes aspectos é necessária
• A tarefa excede a capacidade de uma única janela de contexto
• Sub-agentes especializados melhoram demonstrativamente a qualidade em benchmarks

Escolha multi-agente para isolamento de contexto, não para antropomorfização de papéis. Sub-agentes recebem janelas de contexto novas para subtarefas focadas, o que evita degradação de contexto em tarefas de longa duração.

Consulte o skill multi-agent-patterns para orientação detalhada de arquitetura.

Redução Arquitetural

Comece com arquitetura mínima e adicione complexidade apenas quando evidências de produção provarem que é necessário, porque estruturas superdimensionadas geralmente restringem em vez de habilitar o desempenho do modelo.

O estudo de caso d0 da Vercel relata sucesso melhorado após reduzir muitas ferramentas especializadas a duas primitivas: execução de comandos e SQL (claim-project-development-vercel-d0-reduction). O padrão de agente do sistema de arquivos usa utilitários Unix padrão em vez de ferramentas de exploração personalizadas.

Reduza quando:

• A camada de dados é bem documentada e consistentemente estruturada
• O modelo tem capacidade de raciocínio suficiente
• Ferramentas especializadas estão restringindo em vez de habilitar
• Mais tempo é gasto mantendo estruturas do que melhorando resultados

Adicione complexidade quando:

• Os dados subjacentes são confusos, inconsistentes ou mal documentados
• O domínio requer conhecimento especializado que o modelo não possui
• Restrições de segurança exigem limitar as capacidades do agente
• As operações são verdadeiramente complexas e se beneficiam de fluxos de trabalho estruturados

Consulte o skill tool-design para orientação detalhada de arquitetura de ferramentas.

Iteração e Refatoração

Planeje várias iterações arquiteturais desde o início, porque sistemas de agente de produção em escala sempre exigem refatoração. A Manus refatorou sua estrutura de agente cinco vezes desde o lançamento. The Bitter Lesson sugere que estruturas adicionadas para limitações atuais do modelo se tornam restrições à medida que os modelos melhoram.

Construa para mudança seguindo estas práticas:

• Mantenha a arquitetura simples e sem opinião para que a refatoração seja barata
• Teste entre gerações de modelos para verificar se a estrutura não está limitando o desempenho
• Projete sistemas que se beneficiem de melhorias no modelo, em vez de bloquear limitações

Orientação Prática

Template de Planejamento de Projeto

Siga este template em ordem, porque cada etapa valida suposições antes que a próxima etapa invista esforço.

1. Análise da Tarefa

   • Defina a entrada e a saída desejada explicitamente
   • Classifique: síntese, geração, classificação ou análise
   • Defina uma taxa de erro aceitável com base no impacto comercial
   • Estime o valor por conclusão bem-sucedida para justificar os custos

2. Validação Manual

   • Teste um exemplo representativo com o modelo alvo
   • Avalie a qualidade e o formato da saída em relação aos requisitos
   • Identifique modos de falha que precisam de endurecimento do parser ou revisão do prompt
   • Estime tokens por item para projeção de custo

3. Seleção de Arquitetura

   • Escolha pipeline único vs. multi-agente com base nos critérios acima
   • Identifique ferramentas e fontes de dados necessárias
   • Projete estratégia de armazenamento e cache usando estado do sistema de arquivos
   • Planeje abordagem de paralelização para o estágio de processamento

4. Estimativa de Custo

   • Calcule itens x tokens x preço com uma margem de 20-30%
   • Estime o tempo de desenvolvimento para cada estágio do pipeline
   • Identifique requisitos de infraestrutura (chaves de API, armazenamento, computação)
   • Projete custos operacionais contínuos para execuções de produção

5. Plano de Desenvolvimento

   • Implemente estágio por estágio, testando cada um antes de prosseguir
   • Defina uma estratégia de teste por estágio com saídas esperadas
   • Defina marcos de iteração vinculados a métricas de qualidade
   • Planeje a abordagem de implantação com capacidade de rollback

Exemplos

Exemplo 1: Pipeline de Análise em Lote (Karpathy's HN Time Capsule)

Tarefa: Analisar 930 discussões do HN de 10 anos atrás com classificação retrospectiva.

Arquitetura:

• Pipeline de 5 estágios: buscar -> prompt -> analisar -> parse -> renderizar
• Estado do sistema de arquivos: dados/{data}/{item_id}/ com arquivos de saída de cada estágio
• Saída estruturada: 6 seções com requisitos de formato explícitos
• Execução paralela: 15 workers para chamadas LLM

Resultados: Custo total de $58, ~1 hora de execução, saída HTML estática.

Exemplo 2: Redução Arquitetural (Vercel d0)

Tarefa: Agente Texto-para-SQL para análises internas.

Antes: muitas ferramentas especializadas com menor sucesso medido e maior tempo médio de execução.

Depois: duas ferramentas (bash + SQL) com maior sucesso medido e menor tempo médio de execução (claim-project-development-vercel-d0-reduction).

Insight chave: A camada semântica já era boa documentação. Claude só precisava de acesso para ler arquivos diretamente.

Veja Estudos de Caso para análise detalhada.

Diretrizes

1. Valide o task-model fit com prototipagem manual antes de construir automação
2. Estruture pipelines como estágios discretos, idempotentes e armazenáveis em cache
3. Use o sistema de arquivos para gerenciamento de estado e depuração
4. Projete prompts para saídas estruturadas e analisáveis com exemplos de formato explícitos
5. Comece com arquitetura mínima; adicione complexidade apenas quando comprovadamente necessária
6. Estime custos cedo e acompanhe durante todo o desenvolvimento
7. Construa parsers robustos que...

... [truncado para tradução]