System prompt, output styles e statusline: a personalidade do agente

# NUNCA comece substituindo — APPEND é o que você quer:
claude --append-system-prompt "Sempre retorne respostas em PT-BR.
Use o padrão de erros Result<T,E> do projeto.
Nunca modifique arquivos fora de src/ sem confirmar explicitamente."

# Ou via arquivo (mais prático pra prompts longos):
claude --system-prompt-file ./.claude/project-voice.md

# ❌ ARRISCADO: substitui o prompt padrão inteiro
# Só faz sentido se você sabe EXATAMENTE o que está perdendo:
claude --system-prompt "You are a helpful assistant."
# ← Perde: instruções de tool use correto, guardrails, comportamento agêntico.
# Resultado típico: Claude para de usar tools, responde como chat genérico.

# Onde definir permanentemente (por projeto):
# .claude/settings.json — systemPromptFile aponta pra arquivo commitado
{
  "systemPromptFile": ".claude/project-voice.md"
}

# Hierarquia: enterprise append + user append + project append
# (Anthropic: system prompt nunca é SUBSTITUÍDO por configs — só appended)

# Debugging — ver o prompt efetivo:
claude --debug prompt
# Loga o system prompt montado antes de cada request

# .claude/project-voice.md — exemplo para projeto Python + FastAPI

## Voz
Você é um colaborador técnico deste projeto, não um assistente genérico.
Fale em PT-BR, tom direto, sem floreio. Se faltar contexto, pergunte —
não invente.

## Stack e convenções do projeto
- Python 3.12 com type hints em 100% das APIs públicas
- FastAPI + Pydantic v2 + SQLAlchemy async
- Testes: pytest + pytest-asyncio, fixtures em conftest.py
- Logging: structlog em JSON, nunca print()
- Erros: raise HTTPException com status correto; nunca return {"error": ...}

## Padrões de código
- Imports: stdlib, third-party, local (separados por linha em branco)
- Docstrings: Google style, apenas em funções públicas
- Comentários: só quando o "por quê" é não-óbvio
- Funções: max 30 linhas; extraia helpers se crescer
- Sem classes utilitárias; prefira funções puras

## O que NÃO fazer
- Não usar requests (use httpx)
- Não usar time.sleep em código async (use asyncio.sleep)
- Não silenciar exceptions com try/except Exception: pass
- Não editar alembic/versions/ manualmente (use alembic revision)

## Fluxo de trabalho
Antes de modificar um endpoint:
1. Leia o handler + schemas Pydantic + testes existentes
2. Proponha mudança citando arquivos/linhas específicos
3. Aguarde aprovação para mudanças não-triviais
4. Execute testes depois: pytest -xvs tests/api/

// .claude/output-styles/incident-mode.json
{
  "name": "incident-mode",
  "responsePrefix": "🚨 [INCIDENT-MODE]",
  "toolCallFormat": "⏱ {timestamp} | {severity} | {toolName}({toolArgsSummary})",
  "toolResultFormat": "✓ {durationMs}ms | {resultSummary}",
  "errorFormat": "🔴 ERRO [{category}]: {message}\n   Sugestão: {suggestion}",
  "sectionHeaders": {
    "proposal": "▶ PROPOSTA DE AÇÃO",
    "reasoning": "▶ RACIOCÍNIO",
    "risks": "▶ RISCOS IDENTIFICADOS"
  },
  "colors": {
    "primary": "red",
    "accent": "yellow"
  }
}

// Uso:
// Via /config → selecionar output style
// Ou em settings.json:
{
  "outputStyle": "incident-mode"
}

// Combine com --output-format para pipelines:
claude -p "analise falha no job X" \
  --output-format stream-json \
  --outputStyle incident-mode
// stream-json é consumido por scripts; style afeta display humano quando há TUI

#!/bin/bash
# ~/.claude/statusline.sh
# Executado periodicamente (refreshInterval em settings.json)

# Git context
BRANCH=$(git branch --show-current 2>/dev/null || echo "—")
CHANGES=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
COMMITS_AHEAD=$(git rev-list --count @{u}..HEAD 2>/dev/null || echo "0")

# Deploy status (se houver arquivo .deploy-status)
DEPLOY_STATUS="—"
if [ -f ".deploy-status" ]; then
  DEPLOY_STATUS=$(cat .deploy-status)
fi

# Ticket atual (se houver .current-ticket)
TICKET="—"
if [ -f ".current-ticket" ]; then
  TICKET=$(cat .current-ticket)
fi

# Time
TIME=$(date +%H:%M)

# Monta a linha
printf "🌿 %s" "$BRANCH"
[ "$CHANGES" != "0" ] && printf " (%s mod)" "$CHANGES"
[ "$COMMITS_AHEAD" != "0" ] && printf " ↑%s" "$COMMITS_AHEAD"
printf " | 🚀 %s" "$DEPLOY_STATUS"
printf " | 🎫 %s" "$TICKET"
printf " | ⏰ %s" "$TIME"

// .claude/settings.json
{
  "statusLine": {
    "type": "command",
    "command": ".claude/statusline.sh",
    "refreshInterval": 5000
  }
}

// Gerar baseline a partir do seu $PS1:
// /statusline
// → cria ~/.claude/statusline.sh com sua config atual do shell

// Combine com hooks que atualizam arquivos lidos pelo statusline:
// hook PostToolUse(Bash(./deploy.sh:*)) → escreve em .deploy-status
// hook UserPromptSubmit → parseia ticket Jira do prompt e escreve em .current-ticket
// → statusline automaticamente reflete o estado sem Claude precisar printar

# Themes afetam apenas cores (não formatação/comportamento):
/theme
# Opções: auto, light, dark, daltonized, ANSI

# Output styles afetam FORMATO; themes afetam CORES — combinam.
# Exemplo: output style "compact" + theme "dark" + statusline custom

# Outras flags de rendering:
CLAUDE_CODE_NO_FLICKER=1  # rendering smooth (alt-screen mode)
/tui fullscreen           # modo fullscreen com alt-screen
/tui default              # modo inline (padrão)

# Focus mode — esconde tudo exceto último prompt + resposta:
/focus   # toggle

# Command palette pra acesso rápido:
Cmd+K    # macOS
Ctrl+K   # linux/win

# Keybindings customizados:
/keybindings  # edita ~/.claude/keybindings.json
# Você pode remapear qualquer atalho (ex: trocar Ctrl+O por Ctrl+Shift+L)