O Teu Primeiro Projeto com Claude Code

Cinco minutos. É tudo o que precisas para lançar a tua primeira app a funcionar com Claude Code. Esquece o Hello World. Vamos construir um gestor de tarefas pessoal que vais usar todos os dias.

Solução rápida: Cola isto para começar:

mkdir smart-todos && cd smart-todos && claude

O teu workspace existe. O Claude Code está ativo dentro dele. Observa o que acontece a seguir.

Diz ao Claude o que queres, em linguagem simples:

O prompt: "Create a CLI task manager where I can add tasks, mark them done, and see my list. Make it save to a file so tasks persist."

Um plano completo chega de volta. Vais ver o Claude pensar sobre:

• Estrutura de ficheiros (uma app Node.js simples)
• Comportamento principal (adicionar, concluir, listar)
• Persistência (um ficheiro JSON em disco)
• Interface (output limpo no terminal)

O Que o Claude Está a Fazer Por Baixo do Capô

Esse prompt não é um gerador de texto a escrever um parágrafo para ti. Uma cadeia de ferramentas corre. O Claude lê o teu diretório atual primeiro, vê que está vazio e constrói um plano: o que escrever, em que ordem, que dependências buscar. Depois usa a ferramenta Write para cada ficheiro, a ferramenta Bash para correr npm init -y e instalar pacotes, e às vezes a ferramenta Read para verificar o que acabou de escrever. Cada chamada de ferramenta aparece na conversa em tempo real.

Um chatbot despeja código numa caixa de resposta. O Claude Code edita o teu sistema de ficheiros e corre comandos no teu terminal. Os ficheiros em disco são reais. A pasta node_modules que aparece também é real.

O Claude cria ficheiros funcionais diretamente:

// Claude creates tasks.js automatically
#!/usr/bin/env node
import fs from 'fs';
import path from 'path';

const TASKS_FILE = path.join(process.cwd(), 'tasks.json');
// ... complete working code appears

Testa o teu novo gestor de tarefas imediatamente:

node tasks.js add "Learn Claude Code"
node tasks.js add "Build something amazing"
node tasks.js list

Output esperado:

✓ Added: Learn Claude Code
✓ Added: Build something amazing

Your Tasks:
□ 1. Learn Claude Code
□ 2. Build something amazing

Dois minutos. Persistência de ficheiros, tratamento de erros e formatação de output organizada estão todos a funcionar, numa app CLI real.

Agora a parte divertida. Refinas através da conversa. Tenta estas:

Adicionar cores: "Make completed tasks show in green and pending in yellow"

Sistema de prioridades: "Let me add priority levels - high, medium, low"

Datas de entrega: "Allow setting due dates and show overdue tasks in red"

Função de pesquisa: "Add ability to search tasks by keyword"

Cada pedido chega quase instantaneamente. Sem abas do Stack Overflow. Sem labirintos de configuração. Descreves o comportamento e ele aparece.

A forma antiga obrigava-te a saber tudo antes de começar:

• Que bibliotecas escolher
• Como estruturar os ficheiros
• Parsing de argumentos de linha de comandos
• Operações de I/O de ficheiros
• Padrões de tratamento de erros

O Claude Code elimina toda essa fricção. Tu descreves o resultado. O Claude trata da mecânica.

O que realmente construíste:

• Operações de ficheiros multiplataforma
• Persistência de dados JSON
• Parsing de argumentos
• Output de terminal com cores
• Tratamento de erros adequado
• Mensagens de ajuda amigáveis

Um projeto assim normalmente consome tempo real de setup e pesquisa de dependências. Aqui, um prompt cobriu tudo.

Já estás preso? O guia de instalação tem o walkthrough detalhado de configuração.

"Permission denied" ao correr tasks.js no Mac ou Linux:

chmod +x tasks.js

Erros "Module not found":

npm init -y && npm install commander chalk

Queres correr a partir de qualquer lugar? Adiciona isto ao package.json:

{
  "bin": {
    "todo": "./tasks.js"
  }
}

Depois corre npm link. Agora todo add "anything" funciona de qualquer pasta no teu sistema.

Às vezes a primeira tentativa não acerta no que tinhas em mente. É normal. O desenvolvimento conversacional prevê isso.

O Claude escreveu código mas dá erro ao correr. Cola o erro diretamente no Claude Code. Diz: "I got this error when running the app" e acrescenta o stack trace completo. O erro é lido, a causa é identificada e o ficheiro é corrigido. A maioria dos problemas na primeira execução são dependências em falta ou uma incompatibilidade de versão do Node.js.

A app corre mas não faz o que descreveste. Sê mais específico no próximo prompt. Esquece "não está certo" e diz exatamente o que esperavas e o que viste. "The list command shows tasks in the order they were added, but I want them sorted by priority" dá ao Claude um alvo concreto. Feedback vago produz correções vagas.

O Claude construiu demasiados ficheiros ou complicou demais. Prompts abrangentes causam isso. Para o Claude, "task manager" pode implicar uma base de dados, um sistema de configuração e vários módulos. Na próxima iteração, define o âmbito: "a single-file Node.js script, no database, store tasks in a JSON file." Âmbito apertado produz código apertado.

O Claude continua a pedir permissão antes de correr comandos. É o sistema de permissões a proteger a tua máquina. Pausa em comandos shell, instalações de pacotes e escritas fora do teu projeto. Escreve "y" para aprovar cada um, ou configura aprovação automática para os comandos em que já confias.

O que acabou de acontecer:

• Descreveste uma ideia em linguagem simples
• O Claude construiu uma app completa e funcional
• Estás a corrê-la em menos de cinco minutos

Isto é programação conversacional. Pensa em problemas e soluções. Esquece sintaxe e APIs.

O teu gestor de tarefas funciona. Tenta isto a seguir:

Próximo prompt: "Add a web interface so I can manage tasks from my browser. Keep the CLI working too."

Um servidor Express aparece. A interface HTML também. O teu CLI continua a funcionar, intacto. Uma app full-stack em minutos.

Ou segue numa direção diferente:

• Vê exemplos de projetos reais para ter ideias
• Configura o Claude Code para se adaptar ao teu fluxo de trabalho
• Vai ao troubleshooting quando algo correr mal

Os tutoriais tradicionais ensinam sintaxe. O que acabaste de aprender é o padrão de desenvolvimento com Claude Code. O mesmo ciclo de cinco passos funciona num CLI e numa SaaS full-stack.

1. Descreve o resultado que queres. Foca-te no que o produto final faz, não em como o construirias. "A task manager where I can add, complete, and list tasks" bate "create a Node.js script using Commander.js with a JSON file store." Os detalhes de implementação são problema do Claude. A direção vem depois.

2. Deixa o Claude arquitetar a solução. A tua descrição é decomposta em estrutura de ficheiros, dependências e ordem de construção. As bibliotecas são escolhidas. Os padrões são selecionados. Centenas de pequenas decisões que te custariam uma hora de pesquisa são tomadas por ti. Discordas de alguma? Basta dizer "use sqlite instead of JSON files" e seguir em frente.

3. Testa imediatamente. No momento em que o Claude para de escrever, corre o output. Não o lias linha a linha primeiro. Os problemas reais (dependências em falta, erros de runtime) aparecem rapidamente quando corres a coisa. Qualquer erro colado de volta no Claude torna-se uma correção instantânea.

4. Melhora conversacionalmente. Cada prompt de follow-up adiciona uma funcionalidade ou ajusta o comportamento. "Add due dates." "Make the output prettier." "Add a search command." O código existente é modificado no local, e o que já funciona continua a funcionar. Este ciclo é mais rápido do que planear com antecedência porque cada decisão é tomada contra um protótipo a correr.

5. Lança com confiança. Quando estás no terceiro ou quarto ciclo de melhoria, a tua app foi testada a cada passo. Os casos extremos foram descobertos durante o desenvolvimento conversacional. Faz push para Git. Lança.

O padrão mantém-se a qualquer dimensão. Devs solo constroem apps SaaS completas com ele. Equipas usam-no para prototipar funcionalidades antes do sprint planning.

Construíste algo real. O próximo passo é fazer o Claude Code comportar-se da forma como pensas. Dois guias são onde ir:

Configurar o Claude Code cobre definições, permissões e seleção de modelo. É onde ativas a aprovação automática para comandos de confiança, escolhes entre Sonnet e Opus por tarefa e afinares a experiência no terminal.

O guia do CLAUDE.md orienta-te pelo ficheiro que controla como o Claude se comporta em cada projeto. De tudo o que podes fazer após o teu primeiro projeto, este é o que mais recompensa. Um CLAUDE.md sólido significa que os teus padrões de codificação são seguidos, os teus padrões preferidos são usados e as decisões são tomadas da forma como tu as tomarias.

Para além da configuração:

• Lê o guia de skills para dar ao Claude expertise profunda numa área
• Explora os fundamentos de agentes para correr vários agentes em paralelo em tarefas grandes
• Vai ao troubleshooting quando as coisas quebram