Context Engineering Framework — InfoWhere

Framework para desenvolvimento de software assistido por IA, desde a ideação até código funcional.
Versão: 4.0 | Data: 25/01/2026 | Autor: Leandro Siciliano / InfoWhere SComm

🎯 Visão Geral

O Context Engineering é um framework de 5 fases que transforma ideias em código funcional através de documentação progressiva e assistência de IA.

💭 Ideação → 🏗️ Contexto Técnico → 📚 Preparação → 📋 Planeamento → ⚡ Desenvolvimento

Princípio Central: A qualidade do output da IA é diretamente proporcional à qualidade do contexto fornecido.

Nota: Para a estrutura de projeto e comandos do Claude CLI, veja o Quick Start.

📋 As 5 Fases

Fase 01 — Ideação 💭

Objetivo: Transformar ideia inicial em documento de contexto estruturado (O QUE será construído).

Entregáveis Obrigatórios:

• Problema claramente definido
• Funcionalidades principais listadas
• document_context.md completo

Entregáveis Recomendados:

• Escopo e não-objetivos definidos
• Diagrama de fluxo (flow.excalidraw)

Fase 02 — Contexto Técnico 🏗️

Objetivo: Transformar visão (O QUE) em especificação técnica (COMO será construído).

Entregáveis Obrigatórios:

• Stack tecnológica definida
• Arquitetura documentada
• ADR-001 criado
• CLAUDE.md com regras do projeto
• README.md

Entregáveis Recomendados:

• Diagrama de arquitetura
• Guidelines (coding, testing, api, git, devops)

Fase 03 — Preparação 📚

Objetivo: Preparar documentação das bibliotecas na versão exata do projeto.

Entregáveis Obrigatórios:

• Lista de libs com versões exatas
• Documentação em docs/libs/

Workflow:

1. Usar Context7 para buscar docs da lib+versão
2. Se Context7 não cobrir, usar Firecrawl para varrer site oficial
3. Gerar markdown com snippets e exemplos

Fase 04 — Planeamento 📋

Objetivo: Quebrar projeto em features e criar PRPs (Product Requirement Prompts).

Entregáveis Obrigatórios:

• Features priorizadas
• PRP por feature
• Critérios de aceitação

Estrutura de um PRP:

1. Purpose — Propósito
2. Core Principles — Princípios
3. Goal / Why / What — Objetivo
4. Success Criteria — Métricas de sucesso
5. All Needed Context — Documentação, referências
6. Known Gotchas — Problemas conhecidos
7. Implementation Blueprint — Plano de implementação
8. List of Tasks — Tarefas numeradas (TASK-1.1, TASK-1.2, ...)
9. Per-task Pseudocode — Pseudocódigo por tarefa
10. Integration Points — Pontos de integração
11. Validation Loop — L1: Syntax, L2: Unit Tests, L3: Integration

Fase 05 — Desenvolvimento ⚡

Objetivo: Executar PRPs, gerar código funcional, validar e iterar.

Entregáveis Obrigatórios:

• Código implementado
• Testes passando (85%+ cobertura)
• Code review realizado
• Feature deployável

Entregável Importante:

• state.local.md atualizado (ver seção dedicada)

⭐ state.local.md — "Onde Paramos"

Arquivo NÃO versionado que mantém o estado do trabalho entre sessões com Claude CLI.

Regras

1. Adicionar ao .gitignore
2. Atualizar ao final de CADA sessão
3. Claude CLI deve ler isso no início da próxima sessão
4. Manter conciso (< 50 linhas)

Template

# Estado Atual do Trabalho

## Feature Atual
[Nome da feature em desenvolvimento]

## Última Tarefa Completa
TASK-X.X: [descrição]

## Próxima Tarefa
TASK-X.Y: [descrição]

## Contexto Relevante
- [arquivos modificados recentemente]
- [decisões tomadas]
- [problemas encontrados]

## Blockers / Impedimentos
- [se houver]

## Notas para Próxima Sessão
- [observações importantes]

---
Atualizado em: [data/hora]

⌨️ Claude CLI Reference

Comandos Básicos

claude                    # Inicia sessão interativa (REPL)
claude "query"            # Inicia com prompt inicial
claude -c                 # Continua última conversa
claude -p "query"         # Modo print (não-interativo, scripts)
claude --resume <id>      # Resume sessão específica

Slash Commands

Atalhos

Flags Úteis

--output-format json              # Output em JSON
--output-format stream-json       # Stream JSON em tempo real
--allowedTools "Bash,Read"        # Limita ferramentas
--append-system-prompt "..."      # Adiciona ao system prompt
--dangerously-skip-permissions    # ⚠️ Pula confirmações (cuidado!)

Arquivos de Configuração

Comandos Customizados Úteis

🔌 Catálogo de MCPs para Desenvolvimento

⭐ Core / Essenciais

# Filesystem - Acesso seguro a ficheiros locais
claude mcp add filesystem -- npx @modelcontextprotocol/server-filesystem

# Git - Operações Git
claude mcp add git -- npx @modelcontextprotocol/server-git

# GitHub - PRs, Issues, Actions
claude mcp add github -- npx @modelcontextprotocol/server-github

# Fetch - Buscar conteúdo web
claude mcp add fetch -- npx @modelcontextprotocol/server-fetch

🧠 Raciocínio & Memória

# Sequential Thinking - Raciocínio estruturado passo-a-passo
claude mcp add sequential-thinking -- npx @modelcontextprotocol/server-sequential-thinking

# Memory - Knowledge graph persistente
claude mcp add memory -- npx @modelcontextprotocol/server-memory

📚 Documentação & Pesquisa

# Context7 - Docs de libs em tempo real (RECOMENDADO)
claude mcp add context7 -- npx @upstash/context7-mcp

# Firecrawl - Web scraping para docs
claude mcp add firecrawl -- npx firecrawl-mcp

# Brave Search - Pesquisa web
claude mcp add brave -- npx @anthropic/mcp-server-brave-search

🌐 Browser & Automação

# Playwright (Microsoft) - Automação cross-browser oficial
claude mcp add playwright -- npx @playwright/mcp@latest

# Playwright (EA) - Versão community com mais features
claude mcp add playwright-ea -- npx @executeautomation/playwright-mcp-server

🗄️ Bases de Dados

# PostgreSQL (oficial) - Read-only
claude mcp add postgres -- docker run mcp/postgres "$DATABASE_URL"

# PostgreSQL Full Access - Read/Write + transações
claude mcp add postgres-full -- npx mcp-postgres-full-access "$DATABASE_URL"

# DBHub - Universal (PG, MySQL, MSSQL, MariaDB)
claude mcp add dbhub -- npx @bytebase/dbhub --dsn "$DATABASE_URL"

# SQLite
claude mcp add sqlite -- npx @anthropic/mcp-server-sqlite

🐳 Containers & Kubernetes

# Docker - Gestão containers, imagens, volumes
claude mcp add docker -- npx @quantgeekdev/docker-mcp

# Kubernetes - Gestão K8s + Helm
claude mcp add kubernetes -- npx mcp-server-kubernetes

☁️ Cloud & IaC

# Terraform
claude mcp add terraform -- # Ver stakpak/mcp repo

# Pulumi
claude mcp add pulumi -- # Ver pulumi-mcp-server repo

📊 Diagramas

# Excalidraw - Diagramas de fluxo e wireframes
claude mcp add excalidraw -- npx @cmd8/excalidraw-mcp

# Mindmap - Mindmaps interativos
claude mcp add mindmap -- uvx mindmap-mcp-server

📚 Padrões Globais InfoWhere

Arquitetura por Stack

Convenções de Idioma

Convenções de Database

Convenções de Portas

🏗️ Template: CLAUDE.md

# CLAUDE.md — [Nome do Projeto]

## Projeto
[Descrição breve do projeto]

## Stack
- **Backend**: [tecnologia + versão]
- **Frontend**: [tecnologia + versão]
- **Database**: [tecnologia]
- **Infra**: [Docker, K8s, etc.]

## Arquitetura
[Breve descrição da arquitetura]

## Regras de Código

### Geral
- Código e commits em inglês
- Documentação em português
- Cobertura de testes: mínimo 85%

### Naming
- Classes: PascalCase
- Métodos/Funções: camelCase
- Constantes: UPPER_SNAKE_CASE
- Arquivos: kebab-case

### Git
- Branch principal: `main`
- Feature branches: `feature/[nome]`
- Commits: Conventional Commits (feat, fix, docs, refactor, test)

## Comandos Úteis
```bash
# Desenvolvimento
[comando para rodar em dev]

# Testes
[comando para rodar testes]

# Build
[comando para build]

Contexto Adicional

• Ver docs/technical_context.md para detalhes técnicos
• Ver state.local.md para estado atual do trabalho

---

## 📄 Template: document_context.md (Fase 01)

```markdown
# [Nome do Projeto] — Contexto de Negócio

## Problema
[Qual problema este projeto resolve?]

## Solução
[Como o projeto resolve o problema?]

## Público-Alvo
[Quem vai usar?]

## Funcionalidades Principais
1. [Funcionalidade 1]
2. [Funcionalidade 2]
3. [Funcionalidade 3]

## Escopo
### Incluído
- [O que faz parte do MVP]

### Excluído (Não-Objetivos)
- [O que NÃO faz parte do MVP]

## Requisitos Não-Funcionais
- Performance: [requisitos]
- Segurança: [requisitos]
- Escalabilidade: [requisitos]

## Riscos Identificados
| Risco | Probabilidade | Impacto | Mitigação |
|-------|---------------|---------|-----------|
| [Risco 1] | Alta/Média/Baixa | Alto/Médio/Baixo | [Como mitigar] |

## Referências
- [Links relevantes]

📄 Template: technical_context.md (Fase 02)

# [Nome do Projeto] — Contexto Técnico

## Stack Tecnológica

### Backend
- **Linguagem**: [ex: Java 21]
- **Framework**: [ex: Spring Boot 3.5]
- **Build**: [ex: Maven/Gradle]

### Frontend
- **Framework**: [ex: Vue.js 3.5]
- **Build**: [ex: Vite]
- **UI**: [ex: Bootstrap 5]

### Database
- **Principal**: [ex: PostgreSQL 16]
- **Cache**: [ex: Redis]

### Infraestrutura
- **Containers**: Docker
- **Orquestração**: [ex: Kubernetes]
- **CI/CD**: [ex: GitHub Actions]

## Arquitetura

### Padrão
[ex: Controller → Facade → Service → Repository]

### Diagrama
[Link ou referência ao diagrama]

## Bibliotecas e Versões

### Backend
| Biblioteca | Versão | Propósito |
|------------|--------|-----------|
| [nome] | [versão] | [para que serve] |

### Frontend
| Biblioteca | Versão | Propósito |
|------------|--------|-----------|
| [nome] | [versão] | [para que serve] |

## Decisões de Arquitetura
- Ver `docs/adrs/ADR-001.md`

## Integrações
[APIs externas, serviços de terceiros]

## Ambientes
| Ambiente | URL | Descrição |
|----------|-----|-----------|
| Local | localhost | Desenvolvimento |
| Staging | [url] | Testes |
| Production | [url] | Produção |

📄 Template: PRP (Fase 04)

# PRP: [Nome da Feature]

## 1. Purpose
[Por que esta feature existe?]

## 2. Core Principles
- [Princípio 1]
- [Princípio 2]

## 3. Goal / Why / What
**Why**: [Por que fazer?]
**What**: [O que será feito?]
**Goal**: [Qual o objetivo?]

## 4. Success Criteria
- [ ] [Critério 1]
- [ ] [Critério 2]
- [ ] [Critério 3]

## 5. All Needed Context
- `docs/technical_context.md`
- `docs/libs/[lib].md`
- [Outras referências]

## 6. Known Gotchas
- [Problema conhecido 1]
- [Problema conhecido 2]

## 7. Implementation Blueprint
1. [Passo 1]
2. [Passo 2]
3. [Passo 3]

## 8. List of Tasks

### TASK-1.1: [Nome da Tarefa]
**Descrição**: [O que fazer]
**Arquivos**: [Arquivos a criar/modificar]
**Critério**: [Como saber que está pronto]

### TASK-1.2: [Nome da Tarefa]
...

## 9. Per-task Pseudocode

### TASK-1.1

[Pseudocódigo]

## 10. Integration Points
- [Ponto de integração 1]
- [Ponto de integração 2]

## 11. Validation Loop
- **L1 (Syntax)**: Código compila sem erros
- **L2 (Unit)**: Testes unitários passam
- **L3 (Integration)**: Testes de integração passam

🚀 Workflow Completo

Início de Projeto Novo

# 1. Criar estrutura
mkdir -p docs/{adrs,libs,features} prps src tests .claude/{commands,agents}

# 2. Criar CLAUDE.md
claude "/init"

# 3. Criar document_context.md (Fase 01)
# Usar ChatGPT voz ou Claude para brainstorming

# 4. Criar technical_context.md (Fase 02)
claude "Leia docs/document_context.md e crie docs/technical_context.md"

# 5. Preparar docs de libs (Fase 03)
claude "Use Context7 para gerar docs das libs em docs/libs/"

# 6. Criar PRPs (Fase 04)
claude "Crie PRPs para cada feature em prps/"

# 7. Executar PRPs (Fase 05)
claude "Execute o PRP em prps/feature-001.md"

Continuação de Trabalho

# 1. Ler estado atual
claude "Leia state.local.md e continue de onde paramos"

# 2. Trabalhar nas tarefas
claude "Execute TASK-X.Y do PRP atual"

# 3. Ao finalizar sessão
claude "Atualize state.local.md com o progresso atual"

Code Review

claude "/review"

Compactar Contexto (conversas longas)

claude "/compact"

📎 Arquivos do Projeto Context Engineering

Este framework inclui os seguintes templates prontos:

• 00-voice-discussion-prompt.md — Prompt para brainstorming por voz
• CLAUDE.md — Template para projetos
• technical_context.md — Template de contexto técnico
• ADR-001.md — Template de Architecture Decision Record
• Guidelines: coding.md, testing.md, api.md, git.md, devops.md
• Stacks: java-spring.md, python.md, node.md, vue.md, angular.md, streamlit.md
• mcp.md — Guia de integração MCP

📞 Suporte

• Empresa: InfoWhere SComm
• Localização: Bruxelas, Bélgica
• Website: https://infowhere.be

Context Engineering Framework v4.0 — InfoWhere × Claude