aprenda a instalar o Claude Code, escreva seu primeiro agente do zero e termine com algo real: um agente funcional que lê uma pasta, identifica problemas e escreve um relatório, sem necessidade de experiência em programação.
um chatbot espera você fazer uma pergunta e responde. um agente de IA é diferente: você dá um objetivo a ele, e ele descobre as etapas, lê arquivos, executa comandos e age por conta própria até o trabalho ser concluído. você não está controlando cada movimento. você está definindo o destino.
essa diferença é importante porque muda o que você pode automatizar. você não está digitando prompts um de cada vez. você está construindo algo que faz o trabalho enquanto você foca em outras coisas.
O Que Você Precisa Antes de Começar
aqui está tudo o que é necessário antes de tocar em qualquer comando:
- uma conta Claude com um plano pago (Pro a $20/mês é o mínimo; Claude Code está incluído)
- um Mac com macOS 13 ou superior, ou um PC com Windows, ou uma máquina Linux
- uma conexão com a internet
- aproximadamente 30 a 45 minutos para a configuração completa e a primeira construção
nenhuma experiência prévia em programação é necessária. todos os comandos neste guia estão escritos por completo. você copia, cola e pressiona Enter.
custo para seguir este guia: $0 além da sua assinatura. Claude Code está incluído em todos os planos pagos do Claude.
Instale o Claude Code (Rota do Aplicativo Desktop, Sem Necessidade de Terminal)
o caminho mais fácil para um iniciante é o aplicativo desktop. Ele oferece todo o poder do Claude Code sem a necessidade de aprender comandos de terminal primeiro.
vá para claude.ai e baixe o aplicativo desktop para sua plataforma. no macOS, abra o arquivo .dmg e arraste o Claude para a pasta de Aplicativos. no Windows, execute o instalador. inicie o aplicativo, faça login com sua conta Claude e clique na aba Code no centro superior da tela.
se a aba Code pedir para você atualizar seu plano, seu plano atual não inclui o Claude Code. se ela pedir para você fazer login online, complete o login e reinicie o aplicativo. de qualquer forma, você chegará a um espaço de trabalho limpo assim que estiver dentro.
qual é a aparência do sucesso: você vê uma caixa de prompt em branco com uma aba Code ativa e nenhuma mensagem de erro. esse é o seu espaço de trabalho do agente. tudo que você construir vive aqui.
O Que Você Vai Construir
você vai construir um agente específico e usá-lo durante todo este guia.
a função do agente: ler uma pasta de arquivos de texto, encontrar qualquer arquivo que esteja faltando uma linha de título no topo e escrever um relatório chamado missing-titles.txt listando cada arquivo que precisa de correção.
esta é uma tarefa real e útil. Ela mostra todos os comportamentos principais do agente: ler arquivos, tomar decisões e escrever saídas. E é simples o suficiente para verificar visualmente quando funciona.
Passo 1: Crie Sua Pasta de Trabalho
crie uma nova pasta na sua Área de Trabalho chamada my-agent. é aqui que o agente vai trabalhar. Ele só pode ver e tocar em arquivos dentro desta pasta, o que mantém tudo seguro e contido.
dentro de my-agent, crie uma segunda pasta chamada articles. é aqui que o agente vai procurar arquivos para verificar.
agora crie quatro arquivos de texto simples dentro de articles. nomeie-os como post-one.txt, post-two.txt, post-three.txt e post-four.txt. abra dois deles e adicione isto como a primeira linha:
1Title: My Article
deixe os outros dois arquivos completamente vazios. a função do agente é encontrar aqueles vazios.
qual é a aparência do sucesso: sua estrutura de pastas é my-agent/articles/ e contém quatro arquivos .txt, dois com uma linha de título e dois sem.
Passo 2: Escreva o Arquivo de Instruções CLAUDE.md
CLAUDE.md é um arquivo de texto simples que o Claude Code lê no início de cada sessão. são as instruções permanentes do seu agente, o equivalente a uma descrição de cargo que ele nunca esquece.
dentro da pasta my-agent (não dentro de articles), crie um novo arquivo chamado CLAUDE.md. abra-o em qualquer editor de texto, incluindo o Bloco de Notas no Windows ou o TextEdit no Mac, e cole exatamente isto:
1# My File Checker Agent23## Your job45Check every .txt file inside the /articles folder.67## What to look for89A valid file starts with a line that reads exactly: Title:1011If the first line does not start with "Title:", the file is missing its title.1213## What to do14151. Read every .txt file in /articles one by one.16171. Note which files are missing the Title line.18191. Write a file called missing-titles.txt in the main folder.20211. In that file, list every filename that failed the check, one per line.22231. If all files pass, write "All files have titles." in missing-titles.txt instead.2425## What not to do2627Do not edit any of the article files. Read only. Write only to missing-titles.txt.
salve o arquivo. este é o cérebro inteiro do seu agente. O Claude Code lerá isso antes de fazer qualquer coisa.
qual é a aparência do sucesso: você tem um arquivo em my-agent/CLAUDE.md e ele contém as instruções acima.
Passo 3: Aponte o Claude Code para Sua Pasta
abra o aplicativo desktop Claude Code e clique no ícone da pasta ou na opção "Abrir pasta" para navegar até sua pasta my-agent. selecione-a e confirme.
O Claude Code lerá seu arquivo CLAUDE.md automaticamente. você não verá uma mensagem de confirmação para isso, isso acontece silenciosamente em segundo plano toda vez que você abre uma pasta.
se você estiver usando o terminal em vez do aplicativo desktop, abra seu terminal e execute:
1cd ~/Desktop/my-agent2claude
o comando cd significa "change directory" (mudar de diretório). Ele move você para dentro da sua pasta my-agent. digitar claude inicia a sessão do agente a partir dessa pasta.
Passo 4: Execute o Agente
na caixa de prompt na parte inferior da interface do Claude Code, digite exatamente isto:
1Read every .txt file in the articles folder. Find any file missing a Title line at the top. Write the results to missing-titles.txt as instructed in CLAUDE.md.
pressione Enter. observe o que acontece.
O Claude Code mostrará seu trabalho enquanto executa: quais arquivos está lendo, o que encontra em cada um e o que escreve. essa transparência é intencional. Você pode ver cada ação antes que ela aconteça e pará-la se algo parecer errado.
qual é a aparência do sucesso: Claude lê quatro arquivos, identifica dois sem título e cria missing-titles.txt na sua pasta my-agent. abra esse arquivo e você deve ver os dois nomes de arquivo listados, um por linha.
Erro Comum de Iniciante: O Agente Diz Que Terminou, Mas o Arquivo Está Vazio
isso acontece quando o agente escreve missing-titles.txt mas não coloca nada dentro dele. a causa é quase sempre uma instrução CLAUDE.md muito vaga.
a correção: abra CLAUDE.md e torne as instruções de saída mais explícitas. em vez de "liste os arquivos", escreva "escreva cada nome de arquivo em sua própria linha, assim: post-two.txt". exemplos concretos em suas instruções produzem resultados concretos toda vez.
se o agente escrever os nomes de arquivo errados ou pular um, verifique se seus arquivos de artigo realmente têm extensões .txt e não .txt.txt, o que pode acontecer no Windows quando as extensões de arquivo estão ocultas. ative "mostrar extensões de arquivo" nas configurações do seu Explorador de Arquivos para verificar.
Passo 5: Verifique e Estenda
abra missing-titles.txt e confirme que ele lista exatamente os dois arquivos que você deixou vazios. se sim, seu agente funcionou corretamente do início ao fim.
agora você tem um agente funcional. Ele vive em my-agent, lê de CLAUDE.md e pode ser executado sempre que você colocar novos arquivos na pasta articles e executar o mesmo prompt.
o próximo passo claro: atualize CLAUDE.md para também verificar se cada arquivo tem mais de cinco linhas. adicione isto em "What to look for":
1A valid file also has more than 5 lines of content.23If a file has 5 lines or fewer, flag it as "too short" alongside the title check.
execute o agente novamente com o mesmo prompt. Ele agora verificará duas coisas em vez de uma, sem alterações no seu prompt, apenas uma mudança no arquivo de instruções.
O Que Você Acabou de Construir e Por Que Isso Importa
você construiu um agente que lê arquivos, toma decisões e escreve saídas, sem que você supervisione cada etapa. esse é o padrão central por trás de todos os agentes mais avançados que você construirá.
o arquivo CLAUDE.md é a parte que escala. cada nova regra, nova verificação ou novo formato de saída que você adiciona lá muda o que o agente faz sem que você mude como o executa. o prompt permanece o mesmo. as instruções evoluem.
a partir daqui, as extensões naturais são: verificar mais tipos de arquivo, escrever o relatório em um formato diferente como CSV, ou executar a verificação em um agendamento usando o recurso Routines integrado do Claude Code.
dúvidas sobre alguma etapa? deixe-as abaixo.
