Guia: desenvolver software de qualidade assistido por agentes de IA

Esta guia é uma versão melhorada da proposta inicialmente apresentada em "Contexto estendido. Os agentes também precisam de tomar notas".

O seu propósito é implementar uma estratégia que nos permite desenvolver projetos complexos assistidos por agentes sem perder a coerência e qualidade do código gerado.

A sua redação está orientada para o uso com ferramentas como Cursor ou GitHub Copilot, mas pode ser adaptada de forma simples a muitas outras.

Estrutura do Sistema de Contexto

Para implementar esta estratégia, criamos uma pasta context/ na raiz do projeto com a seguinte estrutura:

context/
├── 01-expert.md      # Definição de especialista sintético
├── 02-analysis.md    # Análise do código existente (vazio)
├── 03-plan.md        # Plano mestre de desenvolvimento (vazio)
└── 04-backlog.md     # Tarefas desglosadas e o seu estado (vazio)

Passo 1: Definição do Especialista Sintético

O primeiro passo consiste em definir um "especialista sintético": um papel específico com competências e restrições claras que guiará o agente de IA durante todo o desenvolvimento.

Prompt para o agente:

Lê o ficheiro `context/01-expert.md` para entenderes o teu papel no projeto.

Não geres código até receberes requisitos específicos.

Exemplo de conteúdo para context/01-expert.md:

# SUDO: Age como um Especialista Sénior em Desenvolvimento Frontend especializado em HTML5, CSS3/SCSS e JavaScript ES6+.

## PAPEL
Desenvolvedor Frontend Sénior (10+ anos) especialista em HTML5 semântico, CSS3/SCSS avançado com metodologias BEM e ITCSS, e JavaScript ES6+ moderno, com foco em arquitetura de componentes, desempenho e acessibilidade.

## COMPETÊNCIAS_TÉCNICAS

- HTML5 semântico e acessibilidade (ARIA, WCAG 2.1)
- CSS3 avançado (Grid, Flexbox, animações, propriedades personalizadas)
- SCSS/Sass com arquitetura ITCSS (Triângulo Invertido CSS)
- Metodologia BEM estrita (Bloco__Elemento--Modificador)
- JavaScript ES6+ (async/await, módulos, destructuring, classes)
- Gestão de estado e arquitetura de componentes
- Otimização de desempenho web (Core Web Vitals)
- Testes unitários e de integração
- Ferramentas de construção modernas (Vite, Webpack)

## PRINCÍPIOS_DE_TRABALHO

- Código limpo e mantível seguindo princípios SOLID
- Documentação clara e concisa
- Abordagem mobile-first e responsiva
- Melhoria progressiva
- Semântica antes da apresentação

## RESTRIÇÕES

- Evitar jQuery e bibliotecas legacy exceto requerimento específico
- Manter compatibilidade com navegadores modernos (últimas 2 versões)
- Priorizar soluções nativas sobre dependências externas
- Não gerar código até receber requisitos específicos

⚠️ Importante: A última restrição ("Não gerar código até receber requisitos específicos") é fundamental, os modelos são muito proativos 😅

Passo 2: Análise do Código do Projeto

Este passo só é necessário para projetos existentes. Se estás a começar um projeto do zero, podes omiti-lo.

Agora pedimos ao agente que analise o código do projeto e guarde a sua análise em context/02-analysis.md

Prompt para o agente:

Analisa em profundidade o código atual do projeto. Exclui a pasta `context/` da análise.

Guarda o resultado da análise em `context/02-analysis.md` com a seguinte estrutura:
- Resumo executivo
- Arquitetura atual
- Tecnologias utilizadas
- Padrões identificados
- Áreas de melhoria potencial
- Dependências críticas

Ao terminar, espera instruções adicionais sem realizar nenhuma ação.

⚠️ Importante: Não duvides em iterar com o agente se não estiveres satisfeito com a sua primeira análise.

Passo 3: Criação do Plano Mestre

Uma vez analisado o código, explicamos ao agente o que queremos desenvolver e pedimos-lhe que defina um plano mestre que deve ser guardado em context/03-plan.md

O plano mestre é o documento fundamental que guiará todo o desenvolvimento. Toma o tempo necessário para definir claramente os requisitos e objetivos.

Prompt para o agente:

Baseando-te nos seguintes requisitos, cria um plano mestre detalhado para o desenvolvimento:

[REQUISITOS DO PROJETO]

Preciso criar um serviço REST que processe imagens em lotes. O serviço deve:

- Receber múltiplas imagens numa única pedição
- Redimensionar imagens segundo parâmetros configuráveis
- Comprimir e otimizar para web
- Devolver imagens processadas em formato WebP
- Implementar cache para otimizar recursos
- Fornecer endpoints para consultar estado de processamento

Considerações técnicas:

- Usar Bun pelo seu desempenho em operações intensivas
- Avaliar compatibilidade com bibliotecas de processamento de imagens
- Implementar processamento assíncrono para lotes grandes
- Incluir validação robusta de entrada

[FIM DE REQUISITOS]

Cria um plano mestre estruturado e guarda-o em `context/03-plan.md`.

Ao terminar, espera instruções adicionais.

⚠️ Importante: Continua a dialogar com o agente se vires que ao plano falta ou sobra algo.

Passo 4: Criação do Backlog Detalhado

Neste ponto pedimos ao agente que transforme o plano mestre em tarefas executáveis, o mais pequenas e específicas possível. Tarefas mais granulares resultam em código de maior qualidade.

Prompt para o agente:

Divide o plano mestre em tarefas atómicas seguindo estes critérios:

- Descrição detalhada de requisitos técnicos
- Dependências claramente identificadas

Guarda a lista em `context/04-backlog.md` com esta estrutura:

# Backlog de Tarefas - [Nome do Projeto]

## Resumo do Projeto
[Breve descrição e implementação do plano em `context/03-plan.md`]

## Estado de Tarefas

### FASE 1: [TÍTULO DE FASE]

- **1.1** ⏳ [título de tarefa]
  - **Descrição detalhada**:
  - **Dependências**:
  - **Data**: 
  - **Trabalho realizado**: 

- **1.2** ⏳ [título de tarefa]
  - **Descrição detalhada**:
  - **Dependências**:
  - **Data**: 
  - **Trabalho realizado**:

### FASE 2: [TÍTULO DE FASE]
[Continua com o mesmo formato...]

## Legenda de Estados
- ⏳ Pendente
- 🔄 Em progresso
- ✅ Completada
- ⚠️ Bloqueada

## Notas e Dependências
[Informação adicional relevante]

## Acompanhamento do Progresso
- Tarefas totais: 0
- Tarefas completadas: 0
- Progresso: 0%

Ao terminar, espera instruções adicionais

⚠️ Importante: É necessário indicar ao LLM a estrutura de backlog que queremos, se não torna-se criativo 😬

Passo 5: Execução de Tarefas

Com o backlog definido, procedemos a executar tarefas de forma sistemática.

Prompt para executar uma tarefa:

Executa a tarefa 1.1 do backlog (`context/04-backlog.md`) seguindo estritamente a sua descrição.

Contexto adicional disponível em:
- `context/02-analysis.md` (se existir)
- `context/03-plan.md`

Requisitos de execução:
- Usar ferramentas do agente para criar ficheiros e pastas (não a terminal)
- Seguir convenções estabelecidas no prompt inicial
- Documentar código segundo padrões definidos
- Não realizar ações fora do âmbito da tarefa

Ao completar:
1. Atualizar estado da tarefa em `context/04-backlog.md`:
   - Mudar estado para ✅
   - Adicionar data de finalização
   - Descrever trabalho realizado
   - Atualizar Acompanhamento do Progresso
2. Esperar instruções adicionais sem executar mais tarefas

⚠️ Importante: É necessário pedir ao LLM que não faça nada mais do que indicado na tarefa para evitar que se extralimite.

Passo 6: Reinício da Janela de Contexto

Para manter a qualidade e coerência, é necessário reiniciar periodicamente a janela de contexto.

É evidente que devemos reiniciar a janela de contexto quando notarmos que o agente começa a "perder o norte". Mas a abordagem ótima é não chegar nunca a este ponto e abrir um chat novo:

• Cada 4-6 tarefas completadas
• Ao mudar de fase (o backlog do nosso exemplo está estruturado em fases que se dividem em tarefas).

Prompt para reiniciar:

Instruções iniciais:

1. Lê `context/01-expert.md` para entenderes o teu papel neste projeto
2. Lê `context/02-analysis.md` para conheceres o estado atual do código
3. Lê `context/03-plan.md` para entenderes os objetivos
4. Lê `context/04-backlog.md` para veres o progresso e tarefas pendentes

Fornece um breve resumo de:

- O teu papel e competências
- Estado atual do projeto
- Próximas tarefas a executar

Ao terminar, espera instruções adicionais.

🔧 Automação com Atalhos

Tanto o GitHub Copilot como o Cursor permitem criar atalhos personalizados para prompts frequentes:

GitHub Copilot

• Instructions
• Prompts

Cursor

• Rules

Benefícios do Sistema

Esta estratégia de gestão de contexto transforma a limitação da janela de contexto de um obstáculo numa oportunidade para trabalhar de forma mais estruturada e eficiente. Os principais benefícios incluem:

• Continuidade: Manter o progresso sem perder informação crítica
• Qualidade consistente: O agente mantém o mesmo nível de detalhe e precisão
• Rastreabilidade: Registo completo de decisões e evolução do projeto
• Melhor colaboração: Facilita o trabalho em equipa e a incorporação de novos membros

Conclusão

Ao implementar este sistema, não só evitas as limitações técnicas dos LLM mas também estabeleces uma metodologia de desenvolvimento mais profissional e escalável para projetos assistidos por IA.

---

Perguntas ou sugestões? Partilha a tua experiência implementando esta estratégia e ajuda a melhorar a guia para a comunidade.