Curso 3: Desenvolvimento Agêntico | Rodrigo Pinto

Encontro 2

Engenharia de Contexto
A arte de alimentar o context window

3 horasContext EngineeringCLAUDE.md + Skills

Instrutor: Rodrigo Pinto

Slide título. Esperar todos entrarem (10 min acomodação). Hoje é o encontro mais importante de fundamentação: Context Engineering é o que separa uso amador de uso profissional de agentes.

Recap Encontro 1

O que vimos até aqui

Claude Code

CLI, instalação, primeiros comandos

CLAUDE.md

Arquivo de contexto do projeto

Memory + Permissões

Persistência entre sessões

Hoje: maximizar o contexto que o agente recebe

Min 10-25. Recap rápido do E1. Perguntar: "Quem criou o CLAUDE.md no projeto de vocês?" Transição: "Vocês deram o primeiro passo. Hoje vamos aprofundar."

Por que o agente
esquece tudo
a cada sessão?

Você já teve que repetir a mesma instrução 10 vezes?

O problema não é o modelo. É o CONTEXTO.

Criar identificação. A maioria já passou por isso. O agente "esquece" porque o context window não foi alimentado corretamente. Transição para o conceito formal.

Agenda do Encontro 2

3 Ciclos de Hoje

Ciclo 1 — Context Engineering: O Conceito

25 min — Definições, 6 componentes, evolução

Ciclo 2 — CLAUDE.md Hierárquico + Memory Files

30 min — Global, project, folder-level, exercício

Ciclo 3 — Skills Customizadas

30 min — Anatomia, instalação, criação, exercício

Intervalo de 20 min entre Ciclo 2 e Ciclo 3

Mostrar a estrutura do encontro. Cada ciclo tem teoria curta + prática. Intervalo no meio.
Ciclo 1 — 30 min

Context Engineering

O Conceito

Min 25. Iniciar Ciclo 1. "Antes de meter a mão na massa, precisamos entender o conceito que muda tudo."

Definição #1

"The delicate art and science of filling the context window with just the right information for the next step."

— Andrej Karpathy, 2025

Ex-diretor de IA da Tesla, co-fundador da OpenAI

Citação do Karpathy. Enfatizar "delicate art AND science" - não é só arte, não é só ciência. E "just the right information" - não é TODA informação, é a CERTA. E "for the next step" - contexto muda a cada passo.

Definição #2

"The art of providing all the context for the task to be plausibly solvable by the LLM."

— Tobi Lutke, 2025

CEO do Shopify

Notem: "plausibly solvable" — o contexto precisa tornar a tarefa plausivelmente resolvível

Citação do Lutke (CEO Shopify). Ele mandou memo interno dizendo que IA é obrigatória antes de contratar. "Plausibly solvable" é chave: se o contexto não é suficiente, a tarefa não é resolvível pelo LLM.

Evolução

De Prompt Engineering para Context Engineering

Prompt Engineering

Curso 1 — O que vocês já sabem

  • Foco: escrever um bom prompt
  • 1 mensagem → 1 resposta
  • Persona, formato, contexto inline
  • Humano dirige cada interação

Context Engineering

Curso 3 — O que vamos dominar

  • Foco: alimentar o context window
  • Sistema completo → múltiplas interações
  • System prompts, tools, RAG, memory
  • Agente opera com autonomia
Comparação visual. "Prompt Engineering é como escrever uma boa carta. Context Engineering é como montar o escritório inteiro onde o agente vai trabalhar." Nos Cursos 1 e 2 vocês aprenderam PE. Agora vamos além.

Analogia: Novo Funcionário

Sem contexto

"Faz ai o relatório"

Sem manual, sem exemplos, sem histórico

Resultado: lixo

Com contexto

"Aqui está o manual, os exemplos anteriores, as regras do setor, e o que espero"

Onboarding completo

Resultado: excelente

O agente é um funcionário brilhante mas com amnésia total a cada sessão.

Analogia poderosa. "Imaginem contratar alguém genial mas que todo dia acorda sem memória. O que vocês fariam? Dariam um manual completo. É exatamente isso que vamos fazer."

Os Pilares

6 Componentes de Context Engineering

1

System Prompts

Instruções persistentes

2

Tools / MCP

Ferramentas disponíveis

3

RAG

Recuperação de informação

4

Memory

Memória entre sessões

5

State

Estado atual da tarefa

6

Structured Data

Dados estruturados

Os 6 componentes. Revelar um a um. "Prompt Engineering só cuida do item 1. Context Engineering cuida de TODOS os 6." Esses componentes trabalham juntos para dar ao agente tudo que ele precisa.

Mapeamento Prático

Como Claude Code implementa cada componente

CLAUDE.md

→ System Prompts + Structured Data

Memory files

→ Memory + State

Skills (SKILL.md)

→ Tools + Structured Data

MCP Servers

→ Tools + RAG

Cada ferramenta do Claude Code alimenta componentes específicos do context window

Mapeamento concreto. "Não é abstrato. Cada coisa que vocês configuram no Claude Code preenche partes específicas do context window." MCP será tema do Encontro 5.

Visualizando

O Context Window é um balde

Capacidade: 200K tokens (Claude) — parece muito, mas...

Desafio: Não é só caber. E colocar a informação certa na ordem certa.

Erro comum: Jogar tudo la dentro → agente se perde

Solução: Curadoria — "just the right information" (Karpathy)

Context Engineering = curadoria inteligente do balde

"O context window tem limite. Mesmo 200K tokens enchem rápido com projetos grandes. Por isso a CURADORIA é fundamental. Não é jogar tudo, é selecionar o que importa para o próximo passo."

Resumo: Ciclo 1

1. Context Engineering ≠ Prompt Engineering

2. 6 componentes: system prompts, tools, RAG, memory, state, structured data

3. Claude Code implementa via CLAUDE.md, memory, skills, MCP

4. Curadoria > quantidade — "just the right information"

Agora vamos para a prática: como estruturar o contexto no repositório

Transição para Ciclo 2. "Entenderam o conceito. Agora vamos implementar."
Ciclo 2 — 30 min

CLAUDE.md Hierárquico

+ Memory Files

Min 55. Ciclo 2. "Agora vamos construir a espinha dorsal do contexto: o sistema hierárquico de CLAUDE.md."

Hierarquia

3 Níveis de CLAUDE.md

1

Global — ~/.claude/CLAUDE.md

Preferências pessoais: idioma, estilo de código, convenções que se aplicam a TODOS os projetos

2

Projeto — ./CLAUDE.md (raiz do repo)

Regras do projeto: stack, arquitetura, padrões, deploy, convenções do time

3

Pasta — ./subpasta/CLAUDE.md

Contexto específico: regras daquele módulo, API endpoints, formato de dados

3 níveis. "Pensem como cascata: o global se aplica sempre, o de projeto adiciona regras específicas, e o de pasta refina ainda mais. O Claude lê TODOS os níveis relevantes."

Como a Cascata Funciona

# Quando você abre Claude Code em ./meu-projeto/api/
# O agente lê automaticamente:

1. ~/.claude/CLAUDE.md        # Global (suas preferências)
2. ./CLAUDE.md                # Projeto (regras do repo)
3. ./api/CLAUDE.md            # Pasta (regras da API)

# Resultado: contexto COMPLETO e RELEVANTE
# Sem você precisar repetir nada!

O Claude combina automaticamente todos os níveis aplicáveis

"É automático. Você não precisa dizer 'leia o CLAUDE.md'. Ele já lê. Por isso é tão poderoso: você configura UMA VEZ e funciona em todas as sessões."

Nível1

CLAUDE.md Global — Exemplo

# ~/.claude/CLAUDE.md

## Preferências Gerais
- Idioma: Português brasileiro
- Sem acentos em nomes de arquivo
- Comentários em português
- Tom: direto, prático, sem enrolação

## Estilo de Codigo
- TypeScript quando possível
- Testes com Vitest
- ESLint + Prettier
- Commits em português, formato convencional

Isso se aplica a TODOS os seus projetos, automaticamente

"Configurem isso UMA VEZ. Nunca mais precisam dizer ao Claude 'responda em português' ou 'use TypeScript'. Ele já sabe."

Nível2

CLAUDE.md de Projeto — Exemplo

# ./CLAUDE.md (raiz do repositório)

## Visão Geral
App de gestão de tarefas para servidores públicos.
Stack: Next.js 14 + Supabase + Tailwind

## Arquitetura
- /app — rotas e pages (App Router)
- /lib — lógica de negócio
- /components — componentes React reutilizáveis

## Regras Críticas
- NUNCA expor chaves de API no client-side
- Toda query ao Supabase usa RLS
- Deploy via Vercel — branch main = produção
"Aqui vai tudo que é específico do projeto. Vocês viram isso no E1, mas agora entendem o PORQUE: é o system prompt do agente para este projeto."

Nível3

CLAUDE.md de Pasta — Exemplo

# ./api/CLAUDE.md

## Contexto desta pasta
API routes do Next.js. Cada arquivo = 1 endpoint.

## Padrões obrigatórios
- Validar input com Zod
- Retornar erros no formato { error: string, code: number }
- Logar toda requisição com timestamp
- Rate limiting: max 100 req/min por IP

## Endpoints existentes
- GET /api/tasks — lista tarefas do usuário
- POST /api/tasks — cria nova tarefa
- PATCH /api/tasks/[id] — atualiza tarefa
"Nível 3 é para contexto super específico. Quando o agente trabalha na pasta /api/, ele sabe exatamente os padrões E os endpoints que já existem. Não vai criar duplicatas."

Persistência

Memory Files — Memória entre Sessões

O que são?

  • Arquivos que o Claude cria/atualiza automaticamente
  • Persistem entre sessões (não se perdem)
  • Guardam decisões, progresso, contexto
  • Ficam em ~/.claude/

Quando usar?

  • Decisões de arquitetura importantes
  • Progresso de tarefas longas
  • Padrões descobertos durante o trabalho
  • Bugs resolvidos (para não repetir)

Memory = o "caderno de notas" do agente entre sessões

"Lembram da analogia do funcionário com amnésia? Memory files são o caderno de notas que ele consulta todo dia de manhã. Decisões tomadas, erros cometidos, progresso feito."

Comparação

CLAUDE.md vs Memory Files

AspectoCLAUDE.mdMemory Files
Quem escreve?Você (humano)O agente (automático)
Quando muda?Raramente (setup)A cada sessão relevante
ConteúdoRegras, padrões, estruturaDecisões, progresso, aprendizados
Versionado (git)?SimNão (local)
Compartilhado?Com o timePessoal

Usem ambos juntos — são complementares

"CLAUDE.md é a constituição do projeto. Memory files são o diário de bordo. Os dois juntos dão ao agente contexto completo: regras E histórico."
Exercício Prático — 15 min

Crie um sistema hierárquico

1. Escolham um projeto real (ou criem um fictício)

2. Criem o CLAUDE.md da raiz com: visão geral, stack, estrutura de pastas, regras críticas

3. Criem pelo menos 1 CLAUDE.md de subpasta com regras específicas

4. Testem: abram Claude Code na subpasta e verifiquem se ele "sabe" as regras

15 min prática. Circular e ajudar. Perguntar: "O que vocês colocaram no CLAUDE.md? Que regras são críticas?" Se alguém terminar rápido, sugerir adicionar CLAUDE.md em mais subpastas.

Intervalo

20 minutos

Voltem prontos para criar skills customizadas

Min 85-105. Intervalo de 20 min.
Ciclo 3 — 30 min

Skills Customizadas

Ensine novas habilidades ao agente

Min 105. Ciclo 3. "Vocês configuraram o contexto. Agora vamos dar HABILIDADES ao agente."

Conceito

O que sãoSkills?

Definição

Skills sãoreceitas reutilizáveis que ensinam o Claude a executar tarefas específicas de forma consistente.

Cada skill é um arquivo SKILL.md com instruções detalhadas.

Analogia

Pensem em skills como manuais de procedimento:

  • "Como fazer deploy" → skill de deploy
  • "Como criar componente" → skill de componente
  • "Como rodar testes" → skill de testes
"Imaginem que vocês tem um estagiário. Ao invés de explicar o procedimento toda vez, vocês escrevem um manual. Skills são exatamente isso: manuais que o agente consulta automaticamente."

Anatomia

Estrutura de uma Skill

# .claude/skills/criar-componente.md

## Description
Cria um componente React seguindo os padrões do projeto.
Use quando o usuário pedir para criar um novo componente.

## Instructions
1. Criar arquivo em /components/[NomeComponente]/
2. Usar TypeScript com interface de Props
3. Estilizar com Tailwind (nunca CSS inline)
4. Criar arquivo de teste: [NomeComponente].test.tsx
5. Exportar no index.ts da pasta components/

## Examples
- "crie um componente de card de tarefa"
- "novo componente: botão de ação"
"3 seções: Description (quando usar), Instructions (como fazer), Examples (gatilhos). O Description é crucial porque o Claude usa para decidir QUANDO aplicar a skill."

Localização

Onde ficam as Skills?

1

Skills do Projeto

.claude/skills/*.md — versionadas no git, compartilhadas com o time

2

Skills Pessoais

~/.claude/skills/*.md — suas skills pessoais, todos os projetos

3

Skills da Comunidade

Repositórios open source, marketplaces — instalar e adaptar

"Skills de projeto vão no git. Skills pessoais ficam locais. E há um ecossistema crescente de skills da comunidade que vocês podem instalar e adaptar."

Descoberta

Como Encontrar e Instalar Skills

Encontrar

  • Comando: /skills no Claude Code
  • GitHub: buscar "claude-code skills"
  • Pedir ao Claude: "que skills existem para [tarefa]?"
  • Comunidade: forums, Discord, blogs

Instalar

  • Copiar o SKILL.md para .claude/skills/
  • Ou usar /install-skill [url]
  • Revisar e adaptar ao seu projeto
  • Testar com um caso real
"Não reinventem a roda. Muitas skills já existem. Encontrem, instalem, adaptem. Mas SEMPRE revisem antes de usar - entendam o que a skill faz."

Criação

Criando sua Própria Skill

Passo 1: Identifique uma tarefa que você repete com frequência

Passo 2: Escreva as instruções como se explicasse para alguém novo

Passo 3: Estruture em Description + Instructions + Examples

Passo 4: Salve em .claude/skills/nome-da-skill.md

Passo 5: Teste com /skill nome-da-skill ou linguagem natural

Passo 6: Itere — refine as instruções com base nos resultados

Dica: Peça ao próprio Claude para ajudar a escrever a skill!

"A melhor forma de criar uma skill: faça a tarefa uma vez com o Claude, depois peça para ele transformar o processo em uma skill. Ele é ótimo nisso."

Exemplo Completo

Skill: Criar Apresentação HTML

# .claude/skills/criar-apresentacao.md

## Description
Cria apresentações HTML com slides interativos.
Trigger: quando pedirem para criar apresentação, slides, ou deck.

## Instructions
1. Ler o template base em /apresentacoes/template.html
2. Criar ~30 slides seguindo a estrutura: título, abertura, 3 ciclos, recap, fechamento
3. Usar classes CSS do template: .glass, .grad-teal, .fragment, .anim
4. Incluir speaker notes em cada slide (div.notes)
5. Adicionar imagens Pexels como background em slides-chave
6. Atualizar contador total no JavaScript

## Examples
- "crie apresentação sobre Context Engineering"
- "novo deck para o Encontro 3"
"Esta skill é real - é a que eu uso para criar estas apresentações! O Claude segue o template, os padrões visuais, a estrutura pedagógica. Resultado consistente toda vez."
Exercício Prático — 15 min

Crie sua Skill

1. Pensem em uma tarefa que fazem repetidamente no trabalho

2. Escrevam uma skill com Description, Instructions e Examples

3. Salvem em .claude/skills/

4. Testem: ativem a skill e vejam o resultado

Ideias: skill de relatório, skill de email padrão, skill de revisão de código, skill de deploy

15 min prática. Circular. Sugestões: "gerar relatório semanal", "formatar parecer técnico", "criar pull request". Se alguém travar, sugerir: peça ao Claude para ajudar a escrever a skill.
Atividade Final — 20 min

Recap em Duplas

1. Formem duplas

2. Mostrem ao colega o CLAUDE.md hierárquico que criaram

3. Compartilhem a skill que cada um criou

4. Discutam: que skill o colega criou que vocêtambém usaria?

Min 135-155. Recap em duplas. Circular e ouvir. Nos últimos 5 min, pedir 2-3 duplas para compartilhar a skill mais criativa com a turma.

3 Perguntas para as Duplas

1

Qual a diferença entre Prompt Engineering e Context Engineering?

2

Quando usar CLAUDE.md de pasta vs memory file?

3

Que tarefa repetitiva do seu trabalho viraria uma boa skill?

Projetar as perguntas. Ajuda as duplas a focar. Circular e ouvir respostas.

Fechamento

O que levar do Encontro 2

Context Engineering ≠ Prompt Engineering — é muito mais abrangente

6 componentes: system prompts, tools, RAG, memory, state, structured data

CLAUDE.md hierárquico = system prompt persistente do agente

Skills = habilidades reutilizáveis que escalam seu trabalho

Recap rápido. Enfatizar: "Vocês agora sabem algo que 95% dos usuários de IA não sabem: como alimentar o contexto de forma profissional."

Próximo Encontro

Encontro 3:
Sub-Agentes e Agent Teams

Se hoje aprenderam a alimentar UM agente, da próxima vez vão aprender a orquestrar MÚLTIPLOS agentes trabalhando juntos.

Tarefa: Refinem o CLAUDE.md e criem pelo menos 2 skills para o projeto de vocês.
Testem em sessões diferentes e observem: o agente manteve o contexto?

Dar a tarefa. Criar expectativa para o E3: sub-agentes, paralelização, agent teams. "Vocês vão fazer um agente delegar trabalho para outros agentes."

Até o próximo
encontro!

Curso 3: Desenvolvimento Agêntico

Rodrigo Pinto

Método Tempo para o que Importa

Encerrar no horário. Agradecer a participação. Lembrar da tarefa: refinar CLAUDE.md + criar 2 skills.
1 / 36