Aula 2 – Curso de Claude Code do Básico ao Avançado

O contexto dos agentes de IA modernos

A evolução da inteligência artificial nos últimos anos passou por transformações significativas. Começou com assistentes simples, evoluiu para sistemas com protocolo MCP e agora entra na era dos agentes de código verdadeiros. Este vídeo, a segunda aula do curso de Claude Code do básico ao avançado, marca o ponto de transição onde os desenvolvedores deixam de trabalhar com prompts únicos e monolíticos para construir arquiteturas distribuídas de inteligência artificial. A era dos agentes de código representa uma mudança de paradigma: em vez de um único modelo gigante tentando resolver tudo, múltiplos agentes especializados trabalham em conjunto, cada um com suas responsabilidades claras e contextos específicos.

Por que janelas de contexto são limitadas

Um dos principais desafios técnicos enfrentados por desenvolvedores que trabalham com grandes modelos de linguagem é a limitação de contexto. Quando um prompt cresce indefinidamente, adicionando instruções, exemplos, históricos e mais dados, o desempenho do modelo começaa decair exponencialmente. Isso não é apenas uma questão de velocidade: é também uma questão de qualidade. Quanto maior o prompt, maior a probabilidade de alucinação, onde o modelo gera informações fictícias ou incorretas porque perdeu a coerência interna. O vídeo ilustra isso com um exemplo prático: descrever uma casa inteira em um único prompt genérico resulta em perda de foco e inconsistência. A solução não é expandir ainda mais o contexto, mas dividir inteligentemente o problema em unidades menores e especializadas.

O que são Skills e como elas resolvem alucinação

Skills são a unidade fundamental da especialização em Claude Code. Uma Skill é um repositório focado de conhecimento e capacidades que a IA pode acessar sob demanda. Em vez de carregar tudo na memória de uma única conversa, Skills permitem que agentes busquem apenas o conhecimento relevante no momento certo. Isso resolve o problema da alucinação porque reduz drasticamente a quantidade de informação irrelevante disponível em qualquer momento. Quando um agente precisa lidar com uma tarefa específica, ele acessa a Skill correspondente, executa suas instruções e retorna o resultado. Isso preserva o contexto, mantém a clareza das instruções e evita que o modelo se perca em ruídos. O vídeo mostra como criar a primeira Skill no app do Claude Code, estabelecendo um padrão que será replicado em projetos mais complexos.

Diferença entre Skills de usuário e de projeto

Não todas as Skills são criadas da mesma forma. Existem Skills de usuário, que são globais e reutilizáveis em qualquer projeto, e Skills de projeto, que são específicas para um contexto particular. Skills de usuário funcionam como templates e bibliotecas reutilizáveis, enquanto Skills de projeto contêm lógica e conhecimento exclusivo de um produto ou cliente. Essa distinção é fundamental para arquitetar sistemas de IA escaláveis. Um desenvolvedor pode criar uma Skill de usuário para "análise de sentimento" e usá-la em múltiplos projetos. Paralelamente, cada projeto pode ter suas próprias Skills especializadas para domínios únicos, como regras de negócio específicas ou integrações proprietárias. A escolha entre um tipo e outro depende do escopo: se a funcionalidade será reutilizada, cria-se uma Skill de usuário; se é única para um projeto, cria-se uma Skill de projeto.

Front Matter: metadados que controlam o comportamento

Cada Skill possui um arquivo skill.md que começa com Front Matter, um bloco de metadados em YAML que define como aquela Skill se comporta. O Front Matter é onde se específicam coisas como: quais ferramentas a Skill pode usar (allowed-tools), qual modelo de linguagem deve executá-la, se ela está desabilitada, permissões de acesso e outras configurações avançadas. Esse é um dos conceitos mais poderosos do Claude Code porque permite fine-tuning granular sem precisar modificar o código da Skill em si. Um desenvolvedor pode criar uma Skill com acesso completo a APIs externas, mas depois configurar uma versão restrita apenas com certain-tools para um cliente específico. O Front Matter também permite desabilitar uma Skill temporariamente ou atribuir um modelo diferente para sua execução, oferecendo controle total sobre o comportamento sem refatoração.

Subagents: delegação e especialização em paralelo

Subagents são a camada de coordenação que permite que múltiplos Claudes trabalhem em paralelo. Enquanto uma Skill é uma unidade de conhecimento, um Subagent é um agente especializado que pode ser invocado para resolver problemas específicos. A arquitetura permite que um agente pai delegue tarefas para Subagents, que retornam resultados mantendo cada um seu próprio contexto. Isso é crucial para paralelização: em vez de um único agente processando tudo sequêncialmente, múltiplos agentes trabalham simultaneamente em diferentes aspectos do problema. O vídeo demonstra como estruturar Subagents com permissões apropriadas e Skills atreladas, criando times de IA que funcionam como uma equipe real. Cada Subagent pode ter suas próprias habilidades, restrições e modelos de execução, permitindo especialização verdadeira.

Estrutura de pastas e organização do projeto

A arquitetura visual de um projeto Claude Code segue um padrão claro: diretórios .claude/agents e .claude/skills contêm toda a definição de comportamento. Essa organização não é apenas por conveniência, é estrutural. Cada arquivo dentro dessas pastas segue um padrão preciso: o skill.md contém o Front Matter e as instruções, e o projeto pode referenciar múltiplas Skills e Agents. Quando o comando /init é executado, gera-se o CLAUDE.md, um arquivo de orquestração que mapeia toda a arquitetura. Esse arquivo se torna a fonte de verdade para como o projeto funciona. Navegar pela estrutura de pastas torna-se intuitivo: um desenvolvedor pode rapidamente entender quais Subagents existem, quais Skills estão disponíveis e como se relacionam. O terminal do Claude Code oferece comandos para listar tudo isso, tornando a exploração e o debugging muito mais simples.

Começando hoje sem sobrecarregar a complexidade

Embora a arquitetura completa de times de agentes seja poderosa, o vídeo enfatiza que é possível começar simples. A recomendação prática é: crie uma Skill focada, teste-a, valide o comportamento, e só então escale para Subagents e estruturas mais complexas. A tentação é criar tudo de uma vez, mas isso leva a alucinação, bugs difíceis de diagnosticar e projetos que não se comportam como esperado. O padrão iterativo de crescimento é mais sustentável. Começar com uma única Skill bem definida permite validar os conceitos, entender as limitações da janela de contexto e aprender na prática como MCP, hooks e slash commands se comportam.