# Instalação global
npm install -g @anthropic-ai/claude-code

# Verificar instalação
claude --version

# Iniciar sessão (abre o browser para autenticação)
claude

# CLAUDE.md — [Nome do projecto]

## Visão geral do projecto
Aplicação web em Next.js com TypeScript, backend em Node.js/Express
e base de dados PostgreSQL. Serve clientes enterprise B2B.

## Stack técnica
- Frontend: Next.js 14, TypeScript, Tailwind CSS
- Backend: Node.js 20, Express, Prisma ORM
- Base de dados: PostgreSQL 15
- Testes: Jest + Playwright (E2E)
- Estado: Zustand (cliente)

## Comandos essenciais
```bash
npm run dev        # Iniciar dev server
npm run test       # Correr testes
npm run lint       # ESLint + Prettier
npm run build      # Build de produção
npm run db:migrate # Aplicar migrações
```

## Estrutura de ficheiros
- `src/components/` — componentes React
- `src/pages/api/` — rotas da API
- `src/lib/` — utilitários partilhados
- `prisma/` — schema e migrações

## Convenções de código
- TypeScript strict mode em todo o projecto
- Componentes funcionais com hooks (sem class components)
- Nomes de ficheiros em kebab-case
- Imports absolutos a partir de `@/`
- Testes obrigatórios para funções públicas

## Regras de negócio críticas
- Nunca apagar registos — usar soft delete (`deletedAt`)
- Toda a autenticação passa pelo middleware `withAuth`
- Logs de auditoria obrigatórios em operações de escrita

## O que evitar
- NÃO usar `any` no TypeScript
- NÃO commitar sem correr `npm run lint`
- NÃO alterar o schema Prisma sem migração

# Adicionar servidor stdio (local)
claude mcp add playwright npx @playwright/mcp@latest

# Adicionar servidor remoto (HTTP)
claude mcp add github https://mcp.github.com/sse

# Listar servidores ligados
claude mcp list

# Remover servidor
claude mcp remove playwright

{
  "mcpServers": {
    "github": {
      "type": "url",
      "url": "https://mcp.github.com/sse"
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["@modelcontextprotocol/server-postgres"],
      "env": { "DATABASE_URL": "${DATABASE_URL}" }
    },
    "notion": {
      "type": "url",
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

# Criar directório de comandos do projecto
mkdir -p .claude/commands

# Comando simples
echo "Analisa este código para vulnerabilidades de segurança:" \
  > .claude/commands/security.md

# Comando com argumento ($ARGUMENTS)
echo 'Corrige o issue #$ARGUMENTS seguindo os nossos padrões de código' \
  > .claude/commands/fix-issue.md

# Usar na sessão
/project:fix-issue 1234
/security

---
description: Faz review de código e cria PR
allowed-tools: Bash(git *), Read, Write
---

# PR Review

Faz um code review completo das alterações em `$ARGUMENTS` e cria um PR.

## Passos
1. Lê os ficheiros alterados com `!git diff $ARGUMENTS`
2. Verifica convenções de código
3. Corre os testes: `!npm test`
4. Cria o PR com mensagem descritiva

# Estrutura no sistema de ficheiros
.claude/
  skills/
    security-review/
      SKILL.md        # Ficheiro obrigatório (case-sensitive)
      checklist.md    # Ficheiros de suporte opcionais
      patterns.ts     # Scripts ou templates

---
name: security-review
description: >
  Faz revisão de segurança de código. Usar quando alguém pede
  para verificar vulnerabilidades, analisar autenticação, ou
  rever código antes de deployment em produção.
allowed-tools: Read, Grep, Glob
argument-hint: [caminho ou ficheiro a rever]
disable-model-invocation: false
---

# Security Review

Analisa o código em `$ARGUMENTS` como um auditor de segurança sénior.

## O que verificar
- Injecção SQL / NoSQL
- Autenticação e autorização
- Exposição de dados sensíveis (chaves, passwords)
- Validação de inputs
- CSRF e XSS
- Dependências com vulnerabilidades conhecidas

## Output esperado
Relatório com: severidade (crítica/alta/média/baixa), 
descrição, linha afectada e sugestão de correcção.

---
name: code-reviewer
description: >
  Revê código para melhorias de qualidade, performance e boas práticas.
  Usar para code review antes de criar PRs ou após implementação.
tools: Read, Grep, Glob
model: sonnet
permissionMode: acceptEdits
maxTurns: 20
hooks:
  PostToolUse:
    - matcher: "Read"
      hooks:
        - type: command
          command: "echo 'Ficheiro lido pelo reviewer'"
---

# Code Reviewer

És um engenheiro sénior especializado em code review.
O teu papel é identificar problemas de qualidade, performance,
segurança e manutenibilidade.

## Foco
- Legibilidade e clareza
- Performance e eficiência
- Cobertura de casos extremos
- Consistência com o estilo do projecto

## Output
Devolve um relatório estruturado com prioridades claras.
Cada issue deve ter: localização, problema, sugestão.

# Linguagem natural — Claude delega automaticamente pela descrição
Usa o agente code-reviewer para analisar src/auth/

# Explícito
Use the code-reviewer subagent on 'src/auth/middleware.ts'

# Menu interactivo
/agents

# Executar em paralelo (num prompt)
Lança 3 agentes em paralelo:
1. code-reviewer em src/api/
2. security-review em src/auth/
3. test-writer em src/utils/

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{
          "type": "command",
          "command": "npm run lint --fix 2>&1 | tail -5"
        }]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": "./scripts/validate-command.sh"
        }]
      }
    ],
    "Stop": [
      {
        "hooks": [{
          "type": "command",
          "command": "echo '✅ Claude terminou' | osascript -e 'display notification stdin'"
        }]
      }
    ]
  }
}

#!/bin/bash
# Lê o input JSON do Claude Code via stdin
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')

# Bloqueia queries de escrita
if echo "$COMMAND" | grep -qiE 'INSERT|UPDATE|DELETE|DROP|TRUNCATE'; then
  echo "Operação de escrita bloqueada em modo read-only" >&2
  exit 2  # Exit 2 = bloquear e informar Claude
fi

exit 0  # Permitir

1. Abre o IDE JetBrains (IntelliJ, PyCharm, WebStorm…)
2. Settings / Preferences → Plugins → Marketplace
3. Pesquisa "Claude Code [Beta]"
4. Instala da listagem da Anthropic PBC
5. Reinicia o IDE
6. Abre o terminal integrado na raiz do projecto
7. Corre: claude
   (o plugin liga-se automaticamente ao processo CLI)

# Executar tarefa sem interacção humana
claude -p "Analisa o código, corre os testes e corrige os erros" \
  --permission-mode bypassPermissions \
  --output-format json

# Usar como biblioteca (Agent SDK)
npx @anthropic-ai/claude-code run \
  --task "Implementa o endpoint /api/users seguindo a especificação em spec.md"

# Criar tarefa agendada (revê PRs abertos toda segunda de manhã)
claude trigger create \
  --schedule "0 9 * * 1" \
  --prompt "Revê os PRs abertos e faz sumário do estado"

# Loop dentro de uma sessão (a cada 5 minutos)
/loop 5m /project:check-queue

# Criar worktree para uma feature
git worktree add ../projecto-feature-auth feature/auth

# Abrir sessão Claude Code no worktree
cd ../projecto-feature-auth && claude

# O contexto é completamente independente da branch principal

# Activar sandbox para uma sessão
claude --sandbox docker

# Ou definir no settings.json do projecto
"sandbox": { "type": "docker" }