Pare de fazer copy-paste de Código: Deixa o agente trabalhar no teu projeto.
Este é mais um dos meus textos escrito em parceria com/para o Blog da Aubay
"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.
O Problema Que Provavelmente Reconheces
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 Que é o Claude Code?
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.
Instalação: Escolhe o Método Que Te Serve
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.
Instalação Nativa (Recomendada)
A forma mais direta, com atualizações automáticas em background.
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
Nota para Windows: 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
Não atualiza automaticamente. Corre
brew upgrade claude-codeperiodicamente.
Via WinGet (Windows)
winget install Anthropic.ClaudeCode
Também não atualiza automaticamente. Usa
winget upgrade Anthropic.ClaudeCodepara atualizar.
Via npm (para quem já tem Node.js)
npm install -g @anthropic-ai/claude-code
Sem Instalar Nada: Versão Web
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:
Depois de instalar por qualquer um dos métodos, navega até ao teu projeto e arranca:
cd o-teu-projeto
claude
Na primeira utilização, vais ser guiado pelo processo de autenticação. Precisas de uma subscrição Claude Pro (a partir de $20/mês) ou de uma conta na Anthropic Console com acesso à API.
O Primeiro Pedido
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 agente vai explorar os teus ficheiros, ler o package.json ou pyproject.toml ou composer.json, encontrar configurações de teste, e dar-te um resumo completo. Sem que precises de copiar ou colar nada.
CLAUDE.md: O Ficheiro Que Muda Tudo
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
Com este ficheiro, o agente segue automaticamente as tuas regras em cada feature que constrói. Não precisas de repetir instruções sessão após sessão.
Plan Mode: Pensar Antes de Agir
Um dos erros mais comuns ao trabalhar com IA é pedir-lhe que implemente logo. O Claude Code tem um Plan Mode que separa o pensamento da execução:
/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.
Slash Commands Personalizados: O Teu Workflow Automatizado
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
Agora, cada vez que escreves /feature Adicionar endpoint de exportação CSV, o agente segue todo este fluxo de forma estruturada.
De Slash Commands a um Workflow Completo de SDLC
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
As 10 Fases em Resumo
┌─────────────┐ ┌──────────────┐ ┌────────────────┐ ┌──────────────┐
│ 1. DISCOVER │───▶│ 2. RESEARCH │───▶│ 3. DESIGN │───▶│ 4. PLAN │
│ /discover │ │ /research │ │ /design-system │ │ /plan │
└─────────────┘ └──────────────┘ └────────────────┘ └──────────────┘
│
┌─────────────────────────────────────────────────────────────┘
▼
┌──────────────┐ ┌────────────────┐ ┌──────────────┐ ┌──────────────┐
│ 5. IMPLEMENT │───▶│ 6. REVIEW │───▶│ 7. SECURITY │───▶│ 8. DEPLOY │
│ /implement │ │ /review │ │ /security │ │ /deploy-plan │
└──────────────┘ └────────────────┘ └──────────────┘ └──────────────┘
│
┌─────────────────────────────────────────────────────────────┘
▼
┌──────────────┐ ┌──────────────┐
│ 9. OBSERVE │───▶│ 10. RETRO │
│ /observe │ │ /retro │
└──────────────┘ └──────────────┘
/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
Nem Tudo Precisa de 10 Fases
O workflow é flexível. Usa o bom senso:
| Tipo de Alteração | Fases Recomendadas |
|---|---|
| Correção de typo | Corrige diretamente |
| Bug simples | Research → Implement → Review |
| Feature média | Discover → Research → Plan → Implement → Review |
| Feature grande | Todas as 10 fases |
| Emergência |
/hotfix (Research → Fix → Review → Deploy comprimido) |
Model Routing Inteligente
As fases que exigem raciocínio profundo (research, design, planning, implementation) usam o modelo Opus. As fases baseadas em checklists (review, security, deploy, observe) usam o Sonnet, resultando numa poupança de 40-60% por ciclo completo de SDLC, sem perda de qualidade.
Auto-Deteção de Stack
O /discover analisa automaticamente o teu projeto e ativa comandos especializados como /language/typescript-pro, /language/python-pro, /language/terraform-pro, /language/kubernetes-pro, entre muitos outros, para que cada fase use as boas práticas específicas da tua stack.
Gestão de Contexto: O Detalhe Que Faz a Diferença
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
/compactpara comprimir o contexto -
90%+ : usa
/clearobrigatoriamente 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.
Boas Práticas para Equipas
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.
Isto Não é Só Para Uma Linguagem
O Claude Code é agnóstico em relação à linguagem e à stack. Funciona com TypeScript, JavaScript, Python, PHP, Go, Rust, Ruby, Terraform, Ansible, Kubernetes, OpenShift, e com qualquer cloud provider (AWS, Azure, GCP). O repositório de workflow inclui comandos especializados para cada uma destas stacks, ativados automaticamente quando o /discover deteta o teu projeto.
O Que Muda Na Prática?
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.
Recursos
- 📖 Documentação oficial do Claude Code
- 🔧 Meu Repositório: AI-SDLC Workflow completo : slash commands para as 10 fases do ciclo de desenvolvimento
- 🌐 AI-SDLC Web : visão geral do workflow em formato web
- 📄 Artigo: Stop Using AI Just for Code Completion : o porquê e o como de cada fase
- 📄 Artigo: Prompt Examples, AI-SDLC in Practice : exemplos práticos de prompts para cenários reais
- 💰 Planos e preços do Claude Code : Claude Pro a partir de $20/mês
Top comments (0)