Trabalhar com o Claude Code como um profissional

Fundamentos: como o Claude Code pensa

O Claude Code é um agente: lê ficheiros, corre comandos, edita código e verifica o resultado, em ciclo. Ser eficiente é dar-lhe contexto certo, um objetivo claro e uma forma de se verificar.

O ciclo de ouro: Explorar → Planear → Implementar → Verificar

1. Explorar. Pede-lhe para ler os ficheiros relevantes sem escrever código ainda. Ex.: “Lê src/auth/ e explica-me como funciona o login. Não alteres nada.”
2. Planear. Entra em Plan Mode (Shift+Tab até aparecer “plan mode”). O Claude investiga e propõe um plano, sem tocar em ficheiros. Revês e ajustas.
3. Implementar. Aprovas o plano e ele executa. Podes interromper a qualquer momento com Esc.
4. Verificar. Testes, build, lint, screenshot. Um agente que se consegue verificar sozinho é muito mais fiável.

Atalhos e comandos que vais usar todos os dias

CLAUDE.md: a memória permanente

O CLAUDE.md é carregado automaticamente no início de cada sessão. É o sítio para tudo aquilo que te cansas de repetir: comandos, convenções, armadilhas do projeto.

Onde vive (hierarquia)

Os ficheiros somam-se, não se substituem. Edita-os rapidamente com /memory.

O que inserir (e o que não inserir)

Exemplo de um bom CLAUDE.md

# Projeto: Loja Online
Next.js 15 (App Router) + TypeScript + Prisma + PostgreSQL.

## Comandos
- `pnpm dev`        → servidor local (porta 3000)
- `pnpm test`       → testes (Vitest). Corre um ficheiro: `pnpm test path/to/file`
- `pnpm lint --fix` → lint + formatação
- `pnpm db:migrate` → migrações Prisma

## Estrutura
- `app/`        rotas e páginas
- `lib/`        lógica de negócio (sem React aqui)
- `components/` UI reutilizável

## Convenções
- Usa sempre named exports; nunca default exports.
- Valida inputs de API com Zod em `lib/schemas/`.
- Preços são guardados em cêntimos (inteiros), nunca floats.

## Armadilhas
- NUNCA editar `prisma/migrations/` à mão.
- `lib/legacy-payments.ts` está congelado — perguntar antes de alterar.

## Fluxo
- Depois de alterar código: corre `pnpm lint --fix` e os testes afetados.
- Mensagens de commit em inglês, formato Conventional Commits.

Mais detalhes da API: @docs/api-guide.md

Exemplo de CLAUDE.md pessoal (global)

# Preferências pessoais
- Responde em português de Portugal; código e commits em inglês.
- Prefiro soluções simples; não adiciones dependências sem perguntar.
- Antes de dizer que algo está feito, corre os testes e mostra o resultado.
- Uso pnpm, não npm.

Gestão de contexto e prompts eficientes

A janela de contexto é o recurso mais precioso. Quanto mais cheia, mais lento e menos preciso o Claude fica. Gerir contexto é a competência nº1 de quem trabalha bem com agentes.

Hábitos que fazem a diferença

1. /clear entre tarefas diferentes. Acabaste a feature A? Limpa antes de começar a B. Contexto antigo distrai.
2. /compact em tarefas longas. Podes orientar o resumo: /compact mantém as decisões sobre a API e a lista de ficheiros alterados.
3. /context para ver o que ocupa espaço (ficheiros de memória, MCP, ferramentas, conversa).
4. Delega investigação a subagentes. Eles leem 50 ficheiros no contexto deles e devolvem só a conclusão (ver Módulo 6).
5. Se o Claude se enganou duas vezes, recomeça. /clear + um prompt melhor é quase sempre mais rápido do que corrigir em cima de uma conversa “poluída”.

Prompt fraco vs. prompt forte

Ingredientes de um prompt forte: o quê · onde (ficheiros com @) · restrições · como verificar. Podes também colar screenshots ou arrastar imagens para o terminal.

Settings e permissões: menos interrupções, mais segurança

Os ficheiros settings.json controlam o que o Claude pode fazer sem te perguntar, variáveis de ambiente, hooks e muito mais.

Permissões allow / deny

{
  "permissions": {
    "allow": [
      "Bash(pnpm test:*)",
      "Bash(pnpm lint:*)",
      "Bash(git status)",
      "Bash(git diff:*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./secrets/**)",
      "Bash(rm -rf:*)"
    ]
  }
}

deny ganha sempre a allow. Também podes gerir isto interativamente com /permissions, ou escolher “não voltar a perguntar” quando o Claude pede autorização.

Skills: ensina-lhe receitas reutilizáveis

Uma skill é uma pasta com um SKILL.md: instruções (e opcionalmente scripts/ficheiros de apoio) para um tipo de tarefa. O Claude vê só o nome e a descrição; carrega o resto apenas quando precisa — por isso não gasta contexto.

Passo a passo: criar a skill “review-pr”

1. Cria a pasta: mkdir -p .claude/skills/review-pr
2. Cria o ficheiro SKILL.md com frontmatter (nome + descrição) e as instruções.
3. Abre uma sessão nova e escreve /review-pr — ou simplesmente “revê as minhas alterações”.

---
name: review-pr
description: Revê as alterações atuais (git diff) à procura de bugs, problemas de segurança e falta de testes. Usa quando o utilizador pedir uma revisão de código.
allowed-tools: Bash(git diff:*), Bash(git log:*), Read, Grep
---

# Revisão de código

1. Corre `git diff main...HEAD` para ver as alterações.
2. Para cada ficheiro alterado, verifica:
   - erros de lógica e casos limite
   - inputs não validados, segredos no código
   - código novo sem testes
3. Responde com uma tabela: ficheiro · linha · gravidade · problema · sugestão.
4. Termina com um veredito: ✅ pronto / ⚠️ pequenas correções / ❌ precisa de trabalho.

Foco extra (se indicado pelo utilizador): $ARGUMENTS

Subagentes: especialistas com contexto próprio

Um subagente é um “Claude assistente” com o seu próprio prompt de sistema, ferramentas e janela de contexto. O agente principal delega-lhe uma tarefa e recebe apenas o resultado — o teu contexto fica limpo.

Passo a passo: criar o agente “test-runner”

1. Forma fácil: escreve /agents → “Create new agent” → o Claude ajuda-te a gerar o ficheiro.
2. Forma manual: cria .claude/agents/test-runner.md (projeto) ou ~/.claude/agents/test-runner.md (pessoal).
3. Usa: “Usa o test-runner para verificar as minhas alterações” — ou deixa o Claude delegar sozinho, com base na descrição.

---
name: test-runner
description: Corre os testes, analisa falhas e propõe correções. Usa proativamente depois de alterações de código.
tools: Bash, Read, Grep, Glob
model: sonnet
---

És um especialista em testes.

1. Identifica os testes afetados pelas alterações recentes (`git diff --name-only`).
2. Corre-os com `pnpm test <ficheiros>`.
3. Para cada falha: lê o teste e o código, identifica a causa raiz.
4. Devolve um relatório curto:
   - ✅ / ❌ por ficheiro
   - causa de cada falha (1 linha)
   - correção sugerida (diff mínimo)

Não alteres ficheiros: apenas relata.

Hooks: automação garantida

Instruções no CLAUDE.md são sugestões que o Claude normalmente segue. Hooks são comandos shell que correm sempre, em momentos definidos. Se algo tem de acontecer 100% das vezes, é um hook.

Exemplo 1 — formatar automaticamente depois de cada edição

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

O hook recebe um JSON no stdin com os detalhes da chamada (ex.: tool_input.file_path). O matcher filtra por nome de ferramenta (aceita regex).

Exemplo 2 — proteger o ficheiro .env

#!/usr/bin/env bash
file=$(jq -r '.tool_input.file_path // empty')
if [[ "$file" == *.env* ]]; then
  echo "Bloqueado: não é permitido editar ficheiros .env" >&2
  exit 2   # exit 2 = bloqueia a ação; o stderr é enviado ao Claude
fi
exit 0

// em .claude/settings.json
"PreToolUse": [{
  "matcher": "Edit|Write",
  "hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-env.sh" }]
}]

MCP e Plugins: liga o Claude ao mundo

O MCP (Model Context Protocol) dá ao Claude ferramentas externas: GitHub, Notion, bases de dados, browsers, Figma… Os plugins empacotam skills, agentes, hooks e servidores MCP para instalares de uma vez.

Adicionar um servidor MCP

# Servidor remoto (HTTP)
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Servidor local (stdio) — tudo depois de -- é o comando a correr
claude mcp add playwright -- npx @playwright/mcp@latest

# Partilhar com a equipa (grava em .mcp.json na raiz do projeto)
claude mcp add --scope project --transport http github https://api.githubcopilot.com/mcp/

# Gerir
claude mcp list
claude mcp remove notion

Dentro de uma sessão, /mcp mostra o estado dos servidores e permite autenticar (OAuth).

Plugins

Escreve /plugin para navegar em marketplaces e instalar pacotes prontos (ex.: um plugin de revisão de código traz skills + agentes + hooks). Ótimo para partilhar o teu setup com a equipa: em vez de copiar 10 ficheiros, publicas um plugin.

Mapa mental final: o que usar quando

A tua nota final