Contexto Estendido 2.0: Os agentes precisam de arquitetura, não apenas de tomar notas

Este guia é uma versão melhorada da que propus em "Contexto Estendido. Os agentes também precisam de tomar notas" e Guia: desenvolver software de qualidade assistido por agentes de IA.

Quando chegaram os editores com agentes de IA autónomos (Cursor, GitHub Copilot, Claude Code), muitos compramos a promessa: "escreve o prompt perfeito e o agente gera a feature completa de uma vez". A realidade foi outra: sem estrutura nem constraints, acabávamos a dedicar mais tempo a corrigir bugs que a escrever código.

O "vibe-coding", confiar em que o agente "apanhe a vibe" do teu projeto, funciona bem para protótipos rápidos, mas em projetos reais e complexos gera mais problemas que soluções:

• Decisões perdidas: Porque escolhemos esta arquitetura há duas semanas?
• Alucinações constantes: A IA inventa APIs, mistura frameworks, ignora constraints
• Trabalho monolítico: Impossível dividir features em tarefas rastreáveis
• Improvisação contínua: Cada sessão começa do zero

Há uns meses documentei uma solução (v1): um workflow estruturado (análise → solução → backlog → execução → progresso guardado) com quatro arquivos de contexto que convertia o vibe-coding em engenharia rastreável. Funcionou, mas havia fricção: repetir manualmente os mesmos prompts em cada sessão era doloroso.

Este guia apresenta a evolução desse sistema (v2). Aproveita o sistema de rules do Cursor para automatizar prompts e converte o workflow em protocolos reutilizáveis. Mas ao desenhá-lo emergiu um padrão universal: separar conhecimento reutilizável (rules) de memória temporária (memory). Isto vai além de poupar-te escrever os mesmos prompts: podes reutilizar o conhecimento em diferentes projetos e levar um registo ordenado de tudo o que fazes. E o padrão funciona com qualquer ferramenta de IA, não só com Cursor.

Vamos ver como construir essa arquitetura.

Problema de v1

Sistema de quatro arquivos em context/:

• 01-expert.md - Perfil do especialista
• 02-analysis.md - Análise do código
• 03-plan.md - Plano de implementação
• 04-backlog.md - Tarefas pendentes

Limitações em Projetos Reais

Conhecimento misturado: 01-expert.md combina princípios gerais (KISS, DRY) com constraints específicos do projeto (stack, versões, dependências críticas). Impossível reutilizar princípios entre projetos sem arrastar configuração irrelevante.

Duplicação entre projetos: Cada projeto replica conhecimento comum. Se trabalhas em 3 projetos WordPress, tens security: sanitize_*, nonces copiado três vezes. Atualizas uma best practice, deves sincronizar manualmente.

Sem gestão de histórico: v1 dá-te três opções, todas más:

• Sobrescrever 02-analysis.md → perdes decisões prévias
• Acumular análises no mesmo arquivo → cresce descontroladamente, impossível rastrear quando se tomou cada decisão
• Criar múltiplos arquivos (02-analysis-feature-X.md) → desordem, sem nomenclatura consistente

Em todos os casos: Porque rejeitaste a arquitetura X há duas semanas? Não há forma sistemática de recuperá-lo.

Sem modularidade: Mudar de WordPress a React requer reescrever 01-expert.md completo. Não podes manter módulos comuns (princípios, padrões) e só intercambiar o especialista técnico.

v1 tinha dois problemas fundamentais: (1) conhecimento misturado num só arquivo (01-expert.md), (2) execução manual - cada ação requeria escrever o prompt completo ("analisa este arquivo e guarda em 02-analysis.md", "lê 04-backlog.md, executa tarefas 1-3, atualiza estado"). v2 resolve ambos: separa conhecimento em rules/ modulares e automatiza execução mediante protocolos invocáveis em rules/utils/ (@analysis, @execute).

Solução: Separação Rules/Memory

A solução replica como funciona o nosso cérebro: separamos conhecimento permanente (idioma, matemáticas, habilidades) de memória episódica (o que fizemos ontem, decisões da semana passada). Mas além disso, o nosso conhecimento não é monolítico: temos módulos especializados (JavaScript, WordPress, princípios KISS) que ativamos segundo o contexto.

v2 implementa esta arquitetura dual:

1. Separação conhecimento/memória: Rules reutilizáveis vs memory temporária
2. Modularização do conhecimento: Especialistas, guidelines e protocolos executáveis

.cursor/
├── rules/          # Conhecimento reutilizável e modular
│   ├── experts/    # Papéis técnicos (WordPress, React, Python...)
│   ├── guidelines/ # Princípios e constraints (KISS, projeto-específicos)
│   └── utils/      # Protocolos executáveis (analysis, backlog, commit)
└── memory/         # Experiências temporárias
    └── YYYYMMDD-VV-descricao.md

Conceito Chave: alwaysApply

O sistema rules/memory necessita de um mecanismo de ativação: que conhecimento carrega o Cursor automaticamente vs. o que invocas sob demanda? Sem isto, terias 100 regras a competir por contexto limitado.

O flag alwaysApply resolve isto:

• alwaysApply: true → Cursor carrega-as automaticamente em cada conversação
  • Usa para: Especialistas base, guidelines críticas do projeto
  • Exemplo: wordpress-classic-themes.mdc, constraints-balneario.mdc
• alwaysApply: false → Utilizador invoca-as com @ segundo necessidade
  • Usa para: Protocolos sob demanda, ferramentas específicas
  • Exemplo: @analysis, @backlog

Rules: Conhecimento Reutilizável

Experts - Perfis de especialistas técnicos/domínio:

rules/experts/wordpress-classic-themes.mdc

---
alwaysApply: true
---
# WordPress Classic Expert
PHP + vanilla JS specialist. WordPress core APIs, theme dev.

## Stack
Backend: PHP 7.4+, WP Core APIs | Frontend: Vanilla JS, HTML5, CSS3

## Core Patterns
- Security: sanitize_*, esc_*, nonces
- Performance: transients (12h), conditional enqueue
- Translation: __(), _e() with text domain

Guidelines - Princípios de código e restrições de projeto:

rules/guidelines/constraints-balneario.mdc

---
alwaysApply: true
---
# Balneario Theme
Text domain: themefront v0.1.2
Stack: Node | SASS 1.67.0 | PHP 7.4+ | jQuery 3.x
Build: npm run watch:sass (never edit compiled CSS)

Critical: ACF PRO (18 groups), WooCommerce, WPML
Core Systems: PDF Generator (pdf-generator.php), WooCommerce integration

rules/guidelines/kiss.mdc

---
alwaysApply: true
---
# KISS Principle
- Direct solutions, avoid over-engineering
- Simple patterns, minimal dependencies
- Single responsibility per function

Rule: If you can't explain it in 2-3 sentences, it's too complex.

O princípio KISS é especialmente importante em desenvolvimento assistido por IA: é mais fácil pedir ao agente que adicione complexidade a uma solução simples, que perder tempo a analisar o que sobra na sua proposta (os LLMs tendem a gerar código mais complexo do que o necessário).

Utils - Protocolos invocáveis:

rules/utils/analysis.mdc → Analisa código/pastas e guarda em memory

---
alwaysApply: false
---
# Analysis Protocol
Trigger: @file/@folder or "analyze"
1. Acknowledge → 2. Analyze → 3. Save to .cursor/memory/YYYYMMDD-VV-*.md → 4. Confirm

rules/utils/solution.mdc → Propõe solução e guarda em memory

---
alwaysApply: false
---
# Solution Protocol (KISS)
Trigger: User requests solution
1. Acknowledge → 2. Propose simplest solution → 3. Save to memory → 4. Confirm
Principles: Simplicity > complexity, proven patterns > novel

rules/utils/backlog.mdc → Converte solução em tarefas atómicas rastreáveis

---
alwaysApply: false
---
# Backlog Protocol
Solution → atomic tasks → persistent backlog (YYYYMMDD-VV-backlog-*.md)

Format: [Phase.Task#] ⏳/🔄/✅/⚠️ Title
> What to do | Date completed | Work done

Rules: 2-4h max, sequential, testable

rules/utils/execute.mdc → Executa tarefas do backlog e atualiza estado

---
alwaysApply: false
---
# Task Execution Protocol
Load backlog → parse scope → execute → update status → stop at boundary
Input: [1.1], [2.3,2.4], Phase 2, continue

rules/utils/commit.mdc → Gera commits convencionais e atualiza backlog

---
alwaysApply: false
---
# Commit Protocol
Analyze staged → generate conventional commit → approve → execute → update backlog
Format: [JIRA-XXX] type(scope): subject (English, imperative, max 72 chars)

Memory: Registo Histórico

Os protocolos utils geram automaticamente arquivos em memory/ seguindo a nomenclatura YYYYMMDD-VV-descricao.md (VV = sequência diária: 01, 02, 03...):

memory/
├── 20250919-01-analisis-pdf-generator.md
├── 20250919-02-sistema-pdfs-emails-finalizado.md
├── 20251015-01-analisis-completo-balneario-theme.md
├── 20251015-02-solucion-facturacion-automatica-399.md
└── 20251015-03-backlog-facturacion-automatica-399.md

Vantagens: ordenação cronológica, múltiplas entradas/dia, rastreabilidade, relações visíveis.

Isto resolve o problema das três opções más de v1: a nomenclatura cronológica (YYYYMMDD-VV) acumula histórico sem descontrolo, mantém ordem sem desorganização, e preserva decisões sem sobrescrita.

Workflow no Cursor

Nota: Os comandos com @ invocam regras específicas. Por exemplo, @analysis carrega rules/utils/analysis.mdc sem necessidade de escrever o caminho completo. Isto é parte da sintaxe nativa do Cursor.

Esta secção descreve o workflow geral para desenvolvimento assistido por IA: separar conhecimento reutilizável de memória temporária, seguindo o ciclo análise → solução → backlog → execução → commit → continuar. Usamos Cursor e o seu sistema de rules como exemplo de implementação, mas o workflow é aplicável a qualquer ferramenta de IA com capacidade de injetar contexto.

A seguir verás como funciona o workflow na prática. Se depois quiseres implementá-lo nos teus projetos com Cursor, consulta o guia de Implementação e Configuração mais abaixo.

Desenvolvimento de Feature: Faturação Automática

1. Análise

@analysis checkout.php

→ Gera: 20251015-01-analisis-checkout.md

2. Solução

@solution
Implementa faturação automática WooCommerce

→ Gera: 20251015-02-solucion-facturacion.md

3. Backlog

@memory/20251015-02-solucion-facturacion
@backlog

→ Gera: 20251015-03-backlog-facturacion.md

4. Execução

@memory/20251015-03-backlog-facturacion
@execute [1.1]

→ Atualiza: [1.1] ⏳ → ✅

5. Commit

@memory/20251015-03-backlog-facturacion
@commit

→ Cria commit + atualiza backlog

6. Continuar trabalho (nova sessão)

@memory/20251015-03-backlog-facturacion
Resume trabalho

→ Carrega contexto + mostra próximas tarefas

Implementação e Configuração

1. Instalar o Sistema (5 min)

Este sistema está disponível em github.com/arinspunk/extended-context.

Duas formas de configurar:

Opção A - Contribuir ao repo partilhado (recomendado se quiseres participar na manutenção):

cd teu-projeto
git clone https://github.com/arinspunk/extended-context.git .cursor

Mantém conexão com o repo para receber atualizações e contribuir melhorias. Atualiza quando quiseres: cd .cursor && git pull

Opção B - Snapshot para o teu projeto (recomendado para trabalho diário):

git clone https://github.com/arinspunk/extended-context.git temp
cp -r temp/rules temp/memory teu-projeto/.cursor/
rm -rf temp

Cópia independente que personalizas livremente sem afetar o repo original, ideal para versionar junto com o código do teu projeto.

Migração desde v1: Usa Opção B para integrar com a tua estrutura existente.

2. Configuração Inicial (15 min)

Pré-requisitos:

• Cursor instalado e projeto aberto
• Sistema rules/memory clonado em .cursor/ (passo anterior completado)

Passo 1: Identifica o teu stack (2 min)

Revisa rules/experts/ e ativa o especialista que coincida com o teu projeto:

• WordPress → wordpress-classic-themes.mdc
• React → react-typescript.mdc (se existir)
• Backend Python → python-fastapi.mdc (se existir)

Se o teu stack não existir: copia o especialista mais próximo e adapta-o.

Passo 2: Ativa constraints do projeto (3 min)

1. Copia rules/guidelines/constraints-template.mdc a constraints-{projeto}.mdc
2. Completa:
   • Stack técnico (versões específicas)
   • Dependências críticas (bibliotecas que NÃO se podem mudar)
   • Sistemas legacy que deves respeitar
3. Muda alwaysApply: false → true

Passo 3: Ativa princípios base (1 min)

Ativa kiss.mdc mudando alwaysApply: false → true

Passo 4: Verifica carga (1 min)

Abre chat do Cursor (Cmd+L) e escreve:

Que especialista e guidelines tens ativas?

Cursor deve listar os arquivos com alwaysApply: true.

Passo 5: Primeira execução (8 min)

Prova o workflow completo com um arquivo real:

@analysis src/components/Header.tsx

Se gerar corretamente memory/YYYYMMDD-01-*.md, o sistema está operativo.

Nota para outras ferramentas: Este sistema é agnóstico ao Cursor. A separação conceptual rules/memory pode implementar-se em qualquer ferramenta capaz de injetar contexto (GitHub Copilot, Claude Code, etc.).

Uma vez configurado o sistema, o verdadeiro trabalho começa: alimentar rules com conhecimento específico do projeto e práticas habituais da equipa, enquanto memory regista o trabalho realizado com a IA (análises, propostas de solução, tarefas e progresso). Na prática, isto transforma como a IA gera código: soluções coerentes com a arquitetura do projeto e escaláveis. Além disso, documenta decisões que facilitam debug posteriores e transferência de conhecimento entre programadores.

Conclusão

O vibe-coding funciona para protótipos, mas gera mais problemas que soluções em projetos reais: decisões perdidas, alucinações constantes, trabalho impossível de rastrear. v1 resolveu isto com workflow estruturado, mas requeria repetir prompts manualmente em cada sessão.

v2 elimina essa fricção automatizando os protocolos e, ao fazê-lo, descobre um padrão universal: separar conhecimento reutilizável (rules) de memória temporária (memory). Esta separação, a mesma que faz o teu cérebro entre habilidades e experiências, converte qualquer ferramenta de IA num sistema onde o conhecimento persiste, evolui e se reutiliza sistematicamente.

Não elimina as limitações de janela de contexto, mas transforma-as num framework estruturado para construir software de forma rastreável e escalável.

Próximos Passos

1. Se usas Cursor: Clona o repo e configura o teu primeiro projeto
2. Se usas outra ferramenta: Adapta a separação rules/memory ao teu sistema
3. Partilha a tua implementação: Criaste especialistas para o teu stack? Contribui ao repo
4. Partilha resultados: Melhoraste o workflow? Documenta os teus achados para refinar coletivamente o sistema