# Instalar o Claude Code globalmente via npm
npm install -g @anthropic-ai/claude-code

# Verificar a instalação
claude –version

# Se tiveres erro EACCES (permissões npm), usar:
sudo npm install -g @anthropic-ai/claude-code
# OU configurar npm para instalar sem sudo:
# https://docs.npmjs.com/resolving-eacces-permissions-errors

# Instalar Node 20 se necessário (via nvm — recomendado)
# macOS / Linux:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 20
nvm use 20

# Windows (WSL2) — instalar dentro do terminal WSL Ubuntu:
sudo apt update && sudo apt install -y curl
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 20

# Opção A — variável de sessão (só para este terminal)
export ANTHROPIC_API_KEY=sk-ant-api03-…
claude

# Opção B — variável persistente (adicionar ao ~/.zshrc ou ~/.bashrc)
echo ‘export ANTHROPIC_API_KEY=”sk-ant-api03-…”‘ >> ~/.zshrc
source ~/.zshrc

# Opção C — definir no /config do Claude Code (interactivo)
claude
# Dentro do Claude Code: /config → “Use custom API key”

# Lançar o Claude Code — na primeira vez abre o browser para OAuth
claude

# Para ambientes sem browser (CI/CD, servidores remotos):
claude setup-token
# Gera um CLAUDE_CODE_OAUTH_TOKEN para usar em pipelines
export CLAUDE_CODE_OAUTH_TOKEN=o_token_gerado

# Passo 1 — Descarregar modelo de coding via Ollama
ollama pull qwen2.5-coder:14b # recomendado (9 GB, 16 GB RAM)
# Alternativa mais leve (8 GB RAM):
ollama pull qwen2.5-coder:7b

# Passo 2 — Confirmar que o Ollama está a responder
curl http://localhost:11434/api/tags

# Passo 3 — Configurar variáveis e lançar Claude Code
# O Ollama expõe a API Anthropic no endpoint /api/
export ANTHROPIC_BASE_URL=http://localhost:11434
export ANTHROPIC_AUTH_TOKEN=ollama # valor arbitrário — Ollama não verifica
export ANTHROPIC_API_KEY=“”

# Lançar o Claude Code apontando para o modelo local
claude –model qwen2.5-coder:14b

# Para persistir, adicionar ao ~/.zshrc ou ~/.bashrc:
echo ‘export ANTHROPIC_BASE_URL=”http://localhost:11434″‘ >> ~/.zshrc
echo ‘export ANTHROPIC_AUTH_TOKEN=”ollama”‘ >> ~/.zshrc
echo ‘export ANTHROPIC_API_KEY=””‘ >> ~/.zshrc

# LM Studio — após instalar o modelo e arrancar o servidor local:
# 1. Abrir o LM Studio, carregar o modelo (ex: Gemma 4 26B A4B)
# 2. Ir a “Local Server” e clicar “Start Server”
# 3. Configurar context window para 65536 no LM Studio

# 4. Configurar as variáveis no terminal
export ANTHROPIC_BASE_URL=http://localhost:1234
export ANTHROPIC_AUTH_TOKEN=lmstudio
export ANTHROPIC_API_KEY=“”

# Lançar com o modelo exacto carregado no LM Studio
claude –model gemma-4-26b-a4b-it

// .claude/settings.json — guardar na raiz do projecto e fazer commit
{
“model”: “claude-sonnet-4-6”, // modelo por defeito do projecto
“permissions”: {
“allow”: [
“Bash(git status)”,
“Bash(git diff *)”,
“Bash(git log *)”,
“Bash(npm run *)”,
“Bash(npm test)”,
“Bash(python -m pytest *)”
],
“deny”: [
“Bash(git push –force *)”, // bloquear force push
“Bash(rm -rf *)”, // bloquear remoções recursivas
“Bash(* production *)” // bloquear comandos com “production”
]
},
“hooks”: {
“PostToolUse”: [
{
“matcher”: “Edit|Write”,
“hooks”: [
{
“type”: “command”,
“command”: “npx prettier –write \”$CLAUDE_TOOL_INPUT_FILE_PATH\” 2>/dev/null || true”
}
]
}
]
}
}

# Dentro do Claude Code (/config abre o menu de configuração)
/config # menu principal — modelo, API key, output style
/config model # mudar o modelo activo

# Seleccionar estilo de output
# Explanatory — detalhado e passo a passo
# Concise — breve, focado em acções
# Technical — preciso, jargão técnico

# Modo plano — Claude planeia antes de executar (recomendado para tarefas grandes)
claude –plan
# Ou dentro da sessão:
/plan

# Ver permissões configuradas
/permissions

# Ver hooks configurados
/hooks

# Activar esforço alto para tarefas complexas (raciocínio adaptativo)
/effort high

# CLAUDE.md — exemplo para projecto Python + FastAPI

## Projecto
API REST em FastAPI + PostgreSQL. Stack: Python 3.12, FastAPI, SQLAlchemy 2.0, Alembic, pytest.

## Comandos
– `make dev` — servidor de desenvolvimento (localhost:8000)
– `make test` — pytest com cobertura
– `make lint` — ruff + mypy
– `make migrate` — aplicar migrações Alembic

## Padrões NON-NEGOTIABLE
– Controller → Service → Repository — nunca lógica de negócio em routers
– Todas as funções async — sem código síncrono no FastAPI
– Type hints obrigatórios em todas as funções
– Testes para todas as novas funcionalidades antes de implementar

## Verificação
Após cada alteração: `make lint` e `make test`. Só fazer commit se ambos passarem.

## Regras de segurança
– Nunca fazer commit de credenciais ou .env
– Nunca alterar ficheiros de migração já aplicados
– Nunca fazer push directo para main

# .claude/skills/code-review/SKILL.md
—
name: code-review
description: Faz code review das alterações. Usar após implementar uma feature ou antes de criar um PR.
—

Ao fazer code review, verificar sempre:

1. **Correctude** — a lógica está correcta? Há edge cases não tratados?
2. **Segurança** — há exposição de dados sensíveis, SQL injection, ou inputs não validados?
3. **Performance** — há N+1 queries, loops desnecessários, ou operações custosas?
4. **Legibilidade** — o código é claro? Os nomes são descritivos?
5. **Testes** — existe cobertura para os caminhos feliz e de erro?

Apresentar o resultado em formato:
– ✅ **Aprovado:** [o que está bem]
– ⚠️ **Sugestões:** [melhorias não críticas]
– ❌ **Problemas:** [issues que devem ser corrigidos]

Usar `git diff HEAD~1` para ver as alterações recentes se não for especificado.

# .claude/skills/criar-pr/SKILL.md
—
name: criar-pr
description: Cria um commit com mensagem Conventional Commits e prepara a descrição do PR. Usar quando estás pronto para submeter.
—

Para criar um PR:

1. Verificar que todos os testes passam: `make test`
2. Verificar que o linting passa: `make lint`
3. Criar a mensagem de commit seguindo Conventional Commits:
– `feat:` nova funcionalidade
– `fix:` correção de bug
– `refactor:` refactoring sem mudança de comportamento
– `docs:` documentação
– `test:` testes
– `chore:` manutenção
4. Gerar a descrição do PR em português com:
– O que foi feito e porquê
– Alterações de comportamento (se existirem)
– Como testar
5. Executar `git add -A && git commit -m “[mensagem]”`
6. Mostrar o comando para criar o PR com `gh pr create`

# .claude/skills/debug/SKILL.md
—
name: debug
description: Analisa e resolve um bug ou erro. Usar quando há um erro, comportamento inesperado, ou teste a falhar.
—

Processo de debug:

1. **Reproduzir**: verificar se o erro é reprodutível. Se não, perceber as condições.
2. **Isolar**: identificar o ficheiro e a função onde ocorre o problema.
3. **Hipótese**: formular 2-3 hipóteses para a causa raiz.
4. **Verificar**: testar cada hipótese com o mínimo de código possível.
5. **Corrigir**: aplicar a correcção mais simples que resolve o problema.
6. **Testar**: confirmar que o bug está resolvido e que não há regressões.

Nunca mudar mais do que o necessário para corrigir o bug.
Adicionar um teste de regressão que falha sem a correcção.

# .claude/skills/analise-logs/SKILL.md
—
name: analise-logs
description: Analisa ficheiros de log para encontrar erros, padrões e causa raiz. Usar quando há um incidente ou anomalia nos logs.
—

Ao analisar logs:

1. Identificar o tipo de log (aplicação, sistema, segurança, acesso)
2. Encontrar os erros mais recentes e mais frequentes
3. Identificar padrões temporais (quando começou, frequência)
4. Correlacionar eventos — o que aconteceu imediatamente antes do erro
5. Apresentar:
– **Resumo executivo**: o que está a falhar, em que contexto
– **Evidências**: linhas de log relevantes (não mais de 10)
– **Causa raiz provável**: hipótese mais plausível com justificação
– **Próximos passos**: 3 acções concretas para investigar ou resolver

Usar `grep`, `awk`, `tail`, `journalctl` conforme o tipo de log.
Para logs Windows, usar `Get-WinEvent` via PowerShell.

# .claude/skills/script-infra/SKILL.md
—
name: script-infra
description: Gera scripts de infraestrutura (PowerShell ou Bash) para automação IT. Usar quando precisas de automatizar tarefas de sysadmin.
—

Ao gerar scripts de infraestrutura:

**PowerShell:**
– Usar `[CmdletBinding(SupportsShouldProcess)]` para suporte a -WhatIf
– try/catch em cada operação com erro descritivo
– Logging em ficheiro com timestamp: `Add-Content -Path “C:\Logs\script.log”`
– Nunca hardcoded credentials — usar `Get-Credential` ou variáveis de ambiente
– Comentários em PT-PT, uma linha por bloco lógico

**Bash:**
– Sempre começar com `set -euo pipefail`
– Verificar dependências no início do script
– Mensagens de erro para stderr: `echo “Erro: …” >&2`
– Função de cleanup com `trap cleanup EXIT`
– `–dry-run` flag para testar sem executar

Apresentar o script completo com comentários, e uma secção de como testar antes de usar em produção.

#!/bin/bash
# .claude/hooks/block-destructive.sh
# Bloqueia comandos destrutivos antes de executar

COMMAND=$(jq -r ‘.tool_input.command’ 2>/dev/null || echo “”)

if echo “$COMMAND” | grep -qE ‘(rm -rf|DROP TABLE|truncate|format [A-Z]:)’; then
jq -n ‘{
hookSpecificOutput: {
hookEventName: “PreToolUse”,
permissionDecision: “deny”,
permissionDecisionReason: “Comando destrutivo bloqueado pelo hook de segurança”
}
}’
exit 2
fi

exit 0

// No .claude/settings.json — formatar com Prettier após cada edição
{
“hooks”: {
“PostToolUse”: [
{
“matcher”: “Edit|Write”,
“hooks”: [
{
“type”: “command”,
“command”: “npx prettier –write \”$CLAUDE_TOOL_INPUT_FILE_PATH\” 2>/dev/null || true”
}
]
}
]
}
}

# Adicionar um servidor MCP
claude mcp add

# Exemplos de MCPs úteis para sysadmins/developers:

# GitHub — ler issues, PRs, criar comentários
claude mcp add github

# PostgreSQL — consultar a base de dados directamente
claude mcp add postgres

# Playwright — browser automation para testes E2E
claude mcp add playwright

# Brave Search ou Tavily — pesquisa web
claude mcp add tavily

# Ver MCPs instalados
claude mcp list

# Ver o marketplace de plugins (inclui MCPs pré-configurados)
/plugin

# Iniciar o Claude Code num projecto
cd ~/projecto
claude

# Explorar um codebase novo
“Explica a arquitectura deste projecto — como os módulos estão organizados e qual o fluxo de um request HTTP de entrada até à resposta”

# Implementar uma nova feature
“Implementa endpoint POST /api/users/{id}/notifications que:
– Aceita lista de IDs de notificação no body
– Marca-as como lidas no PostgreSQL
– Segue o padrão Controller-Service-Repository do projecto
– Inclui testes pytest”

# Debugging com o contexto completo
“O endpoint GET /api/reports está a devolver 500 em produção. Aqui está o traceback: [colar traceback]. Investiga a causa raiz e corrige.”

# Refactoring de um módulo
“Refactora o módulo auth.py para usar a nova classe UserRepository em vez de acesso directo à sessão SQLAlchemy. Manter todos os testes a passar.”

# Análise de dependências antes de actualizar
“Verifica o package.json e identifica dependências desactualizadas com vulnerabilidades conhecidas. Propõe um plano de actualização seguro.”

# Analisar logs de sistema
cd /var/log
claude
“Analisa o nginx/error.log das últimas 2 horas e resume os erros mais frequentes, a sua causa provável, e sugere correcções”

# Gerar script de automação
“Cria um script Bash que:
– Verifica espaço em disco em /var e /home
– Se acima de 80%, envia alerta por email
– Remove logs com mais de 30 dias em /var/log/app/
– Corre como cron job diário às 2h
– Inclui logging e modo –dry-run”

# Auditar configurações de segurança
“Lê o /etc/ssh/sshd_config e o /etc/nginx/nginx.conf e identifica configurações inseguras ou não alinhadas com as melhores práticas de 2026”

# Criar documentação de infra
“Lê os ficheiros docker-compose.yml e .env.example e gera documentação Markdown explicando a arquitectura do serviço, os serviços dependentes e como fazer o deploy”

# Script PowerShell para M365
“Cria um script PowerShell que usa o módulo Microsoft.Graph para listar os utilizadores sem MFA activo no tenant. Output em CSV com UPN, DisplayName e data de criação.”