"IA" em todo o lado. E agora?

• Abre o LinkedIn: IA
• Abre o feed de notícias: IA
• O teu manager manda um link sobre IA
• A empresa anuncia uma "estratégia de IA"
• O teu colega já usa três ferramentas diferentes e tu ainda não percebeste bem nenhuma.

Se te sentes assim, não estás sozinho. A velocidade a que surgem novas ferramentas, frameworks e buzzwords é genuinamente esmagadora. "Agentic coding", "vibe coding", "prompt engineering", "MCP servers"... para quem está a tentar fazer o seu trabalho e entregar código que funcione, este ruído todo pode ser paralisante. O resultado? Muita gente simplesmente não começa.

Ou começa da pior forma possível: Colar código no ChatGPT e rezar para que funcione o que vem como resposta.

Este artigo é para ti se estás nesse ponto. Sem buzzwords desnecessários, sem teoria abstrata. Vamos ver uma ferramenta concreta, o Claude Code, e como ela pode mudar a forma como trabalhas no dia-a-dia. E mais importante: vamos ver como começar, passo a passo.

Copias um traceback, colas numa janela de chat, recebes uma correção que parte outra coisa num ficheiro que a IA nem sabia que existia. Explicas a estrutura do projeto, o contexto perde-se a meio, abres uma nova conversa e voltas à estaca zero.

Parece familiar? Não és tu. É o modelo de interação. Ferramentas baseadas em chat não veem o teu projeto, não conseguem correr os teus testes, e esquecem tudo quando a janela de contexto enche. O resultado? O trabalho de integração recai todo sobre ti: copiar código entre janelas, reexplicar o projeto, rever output em que não confias totalmente.

Existe uma forma diferente de trabalhar.

O Claude Code é uma ferramenta de coding agêntico criada pela Anthropic que vive diretamente no teu terminal (e não só). Ao contrário dos assistentes de chat tradicionais, ele lê os teus ficheiros, edita-os diretamente, corre testes, vê os erros, corrige-os, e gere o git. Tudo dentro do teu projeto real.

A diferença fundamental: em vez de tu seres o mensageiro entre a IA e o teu codebase, o agente trabalha dentro do codebase. Ele percebe a estrutura dos teus ficheiros, as dependências, e o contexto completo do projeto.

O Claude Code está disponível no terminal (CLI), no VS Code, no Cursor, no Google Antigravity, nos IDEs JetBrains (IntelliJ, PyCharm, WebStorm), como app desktop, e até numa versão web em claude.ai/code. Suporta os modelos Claude Opus 4.6 e Sonnet 4.6, com até 1M tokens de contexto.

Uma das barreiras de entrada mais comuns é a instalação. Fica aqui todos os métodos disponíveis. Escolhe o que faz sentido para o teu setup.

macOS / Linux / WSL:

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell:

irm https://claude.ai/install.ps1 | iex

Windows CMD:

curl -fsSL https://claude.ai/install.cmd -o 
install.cmd && install.cmd && del install.cmd

Precisas do Git for Windows instalado antes. Se vires um erro sobre &&, provavelmente estás no PowerShell em vez do CMD. Usa o comando de PowerShell acima.

Via Homebrew (macOS/Linux)

brew install --cask claude-code

Via WinGet (Windows)

winget install Anthropic.ClaudeCode

Via npm (para quem já tem Node.js)

npm install -g @anthropic-ai/claude-code

Se não queres instalar nada localmente, podes usar o Claude Code diretamente no browser em claude.ai/code. Funciona com repositórios GitHub sem precisares de os ter clonados localmente.

Extensões de IDE Se preferes trabalhar dentro do teu editor:

• VS Code / Cursor : procura "Claude Code" no marketplace de extensões
• Google Antigravity : sendo um fork do VS Code, o Antigravity é 100% compatível com as extensões do VS Code. Basta instalar a extensão "Claude Code" da mesma forma. Se já usas o Antigravity como IDE principal (com Gemini 3 Pro incluído gratuitamente), podes combinar o melhor dos dois mundos: os agentes do Antigravity para certas tarefas e o Claude Code para o teu workflow de SDLC
• JetBrains (IntelliJ, PyCharm, WebStorm) : instala o plugin "Claude Code" do JetBrains Marketplace

App Desktop Disponível para download direto:

• macOS (Intel e Apple Silicon) : Download
• Windows x64 : Download

Depois de instalar por qualquer um dos métodos, navega até ao teu projeto e arranca:

cd o-teu-projeto
claude

Assim que estiveres dentro do Claude Code, podes simplesmente escrever em linguagem natural:

Analisa este projeto e diz-me a estrutura geral, as dependências principais, e se há testes configurados.

O conceito mais poderoso do Claude Code é o ficheiro CLAUDE.md. Colocado na raiz do teu projeto, funciona como um "briefing" persistente que o agente lê automaticamente em cada sessão.

Aqui defines:

• Arquitetura do projeto : stack tecnológica, estrutura de pastas
• Comandos úteis : como correr o dev server, os testes, o linter
• Convenções da equipa : "usa sempre interfaces em vez de types", "escreve testes antes do código", "cada PR precisa de docstring atualizada"
• Aprendizagens acumuladas : lições aprendidas que o agente deve ter em conta

Projeto: API de Gestão de Clientes

## Arquitetura
- Node.js 22 + TypeScript 5.7
- Fastify + Prisma + PostgreSQL
- Vitest para testes

## Comandos
- `npm run dev` : servidor de desenvolvimento
- `npm run test` : suite de testes
- `npm run lint` : ESLint + Prettier

## Convenções
- Interface over Type para object shapes
- Error handling com Result pattern (nunca throw em lógica de negócio)
- Todos os endpoints retornam { data, error, meta }
- Testes obrigatórios antes de merge

## Aprendizagens
- 2026-03-15: Sempre invalidar cache de sessão ao alterar permissões
- 2026-03-20: Usar connection pooling para ambientes com +50 conexões

Plan Mode: Pensar Antes de Agir

 /plan Reescrever o módulo de autenticação para usar JWT com refresh tokens

O agente analisa o codebase, identifica os ficheiros afetados, propõe uma abordagem com passos claros, e espera pela tua aprovação antes de tocar em qualquer linha de código. Tu revês, ajustas, e só depois dás luz verde.

Isto é transformador: em vez de receberes código que não percebes, participas na decisão arquitetural e depois deixas o agente executar o plano aprovado.

O Claude Code permite criar slash commands, comandos personalizados que definem workflows reutilizáveis. Guardas ficheiros .md em .claude/commands/ e usas com /nome-do-comando.

Por exemplo, um comando /feature que define o teu processo completo de desenvolvimento:

<!-- .claude/commands/feature.md -->
## Feature Development Workflow

1. Lê o CLAUDE.md e o STATUS.md do projeto
2. Analisa o codebase existente para perceber padrões
3. Planeia a implementação (mostra o plano e espera aprovação)
4. Implementa o código seguindo as convenções do projeto
5. Escreve testes unitários e de integração
6. Corre os testes e corrige falhas
7. Atualiza a documentação
8. Cria um commit com mensagem descritiva
9. Abre um Pull Request

Os slash commands individuais são úteis, mas o verdadeiro salto acontece quando os organizas num workflow completo que cobre todo o ciclo de vida do software, da descoberta à retrospetiva.

Escrevi sobre este tema em detalhe em dois artigos anteriores (em inglês):

Stop Using AI Just for Code Completion: Here's a Workflow That Covers Your Entire SDLC : explica o porquê e o como de cada uma das 10 fases do workflow, incluindo code intelligence, semantic retrieval, visualização com HTML, integração com n8n, e web scraping com Firecrawl.

Prompt Examples: AI-SDLC Workflow in Practice : exemplos práticos de prompts com GOAL e GUARDRAILS para cenários reais: prototipar uma feature nova, corrigir um bug, fazer um hotfix de emergência, adicionar testes a código legado, refatorizar um monólito, e muito mais.

O repositório open source com todo o workflow está aqui:

claude-code-ai-development-workflow

/discover : Define o scope, deteta a stack tecnológica, cria o issue e o dashboard de progresso.

/research : Análise profunda do codebase existente, padrões, dependências e riscos.

/design-system : Arquitetura, ADRs (Architecture Decision Records), especificação do sistema.

/plan : Plano de implementação detalhado com fases, tarefas e estratégia de testes.

/implement : Código + testes, fase a fase, seguindo o plano aprovado.

/review : Revisão de código com checklist de qualidade.

/security : Auditoria de segurança com OWASP, STRIDE e scan de dependências.

/deploy-plan : Estratégia de deployment com rollout e plano de rollback.

/observe : Observabilidade com logging, métricas, alertas e dashboards.

/retro : Retrospetiva que atualiza automaticamente o CLAUDE.md com lições aprendidas.

Começar a Usar

# Copia a pasta .claude/ para a raiz do teu projeto
cp -r .claude/ /caminho/para/o/teu/projeto/.claude/

# Inicia com a discovery de uma nova feature
/discover Adicionar autenticação JWT com refresh tokens e RBAC

O contexto é o recurso mais valioso ao trabalhar com agentes de IA. Algumas boas práticas:

• Até 50% de contexto usado : trabalha livremente
• 50-70% : começa a prestar atenção ao que pedes
• 70-90% : usa /compact para comprimir o contexto
• 90%+ : usa /clear obrigatoriamente e recomeça

O Claude Code tem comandos nativos para isto. /compact comprime a conversa mantendo os pontos essenciais, /clear limpa tudo, e /context mostra quanto da janela já está ocupado.

Se estás numa equipa de consultoria ou numa squad de produto, estas práticas fazem a diferença:

Partilha o CLAUDE.md no repositório. Toda a equipa beneficia das mesmas convenções e o agente comporta-se de forma consistente para todos.

Usa Plan Mode para decisões arquiteturais. Antes de implementar features complexas, revê o plano em equipa. O agente documenta a abordagem, e a equipa valida antes da execução.

Cria slash commands para os workflows da equipa. Se o vosso processo é "branch -implement - test - PR - code review", codifica isso num comando. Reduz fricção e garante consistência.

Regista aprendizagens no CLAUDE.md. Cada sprint, cada retrospetiva, adiciona uma linha ao ficheiro. O agente torna-se progressivamente melhor no vosso projeto.

Revê sempre o código gerado. O Claude Code é uma ferramenta poderosa, mas a responsabilidade pela qualidade continua a ser tua. Usa o agente para acelerar, não para substituir o julgamento humano.

A transição de "chat com IA" para "agente no terminal" muda fundamentalmente a forma como trabalhas:

Deixas de ser mensageiro. O agente lê e escreve no teu projeto diretamente.

O contexto persiste. O CLAUDE.md garante que o agente sabe como o teu projeto funciona, sessão após sessão.

O workflow é reproduzível. Slash commands transformam processos em rotinas automatizadas.

A revisão é sobre qualidade, não sobre integração. Em vez de gastares tempo a colar código e verificar se encaixa, concentras-te em validar a lógica e a arquitetura.

O sistema melhora com o tempo. A cada /retro, as lições aprendidas alimentam as próximas features. O agente fica progressivamente mais calibrado ao teu projeto.