aprenda a instalar o Claude Code, escrever seu primeiro agente do zero e chegar a algo real: um agente funcional que lê uma pasta, identifica problemas e escreve um relatório, sem precisar de experiência em programação.
um chatbot espera você fazer uma pergunta e a responde. um agente de IA é diferente: você dá a ele um objetivo, e ele descobre as etapas, lê arquivos, executa comandos e age por conta própria até que o trabalho esteja 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 comandos um de cada vez. você está construindo algo que faz o trabalho enquanto você foca em outra coisa.
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; o 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. cada comando neste guia está escrito por extenso. você copia, cola e pressiona Enter.
custo para seguir este guia: $0 além da sua assinatura. O Claude Code está incluído em todos os planos pagos do Claude.
Instalar 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 Código no centro superior da tela.
se a aba Código 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 Código ativa e nenhuma mensagem de erro. esse é o seu espaço de trabalho do agente. tudo o que você constrói vive aqui.
O Que Você Vai Construir
você vai construir um agente específico e usá-lo ao longo de todo este guia.
o trabalho 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: Criar Sua Pasta de Trabalho
crie uma nova pasta em 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:
\\`
Title: My Article
\\`
deixe os outros dois arquivos completamente vazios. o trabalho 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: Escrever 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:
\\`
My File Checker Agent
Your job
Check every .txt file inside the /articles folder.
What to look for
A valid file starts with a line that reads exactly: Title:
If the first line does not start with "Title:", the file is missing its title.
What to do
- Read every .txt file in /articles one by one.
- Note which files are missing the Title line.
- Write a file called missing-titles.txt in the main folder.
- In that file, list every filename that failed the check, one per line.
- If all files pass, write "All files have titles." in missing-titles.txt instead.
What not to do
Do 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: Apontar o Claude Code para Sua Pasta
abra o aplicativo desktop do 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:
\\`bash
cd ~/Desktop/my-agent
claude
\\`
o comando \cd\ significa "change directory" (mudar diretório). Ele move você para dentro da sua pasta \my-agent\. digitar \claude\ inicia a sessão do agente de dentro dessa pasta.
Passo 4: Executar o Agente
na caixa de prompt na parte inferior da interface do Claude Code, digite exatamente isto:
\\`
Read 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: O Claude lê quatro arquivos, identifica dois sem título e cria \missing-titles.txt\ em 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 "listar os arquivos", escreva "escreva cada nome de arquivo em sua própria linha, assim: post-two.txt". exemplos concretos em suas instruções produzem saída concreta 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: Verificar e Estender
abra \missing-titles.txt\ e confirme se ele lista exatamente os dois arquivos que você deixou vazios. se sim, seu agente funcionou corretamente do início ao fim.
você agora 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":
\\`
A valid file also has more than 5 lines of content.
If 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 você supervisionar 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 você mudar 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 cronograma usando o recurso integrado de Rotinas do Claude Code.
dúvidas sobre alguma etapa? deixe-as abaixo.
