cidadao-ai-onboarding

name: cidadao-ai-onboarding description: Use quando estagiário novo ou contribuidor pela primeira vez fizer setup do Cidadão.AI ou primeira contribuição. Carrega checklist de setup local, primeira PR, code review, comunicação com orientador. Ative ao detectar perguntas tipo "como começar", "qual minha primeira tarefa", "como faço o setup", ou ao revisar PR de iniciante.

Cidadão.AI — Onboarding

Guia para estagiários do Neural LAB e novos contribuidores. Passo a passo das primeiras 1-2 semanas.

Setup local (dia 1)

1. Clonar repos relevantes

mkdir -p ~/cidadao && cd ~/cidadao
git clone https://github.com/anderson-ntlabs/cidadao.ai-backend.git
git clone https://github.com/anderson-ntlabs/cidadao.ai-frontend.git
git clone https://github.com/anderson-ntlabs/cidadao.ai-docs.git

2. Backend setup

cd cidadao.ai-backend

# Python 3.11+
python -m venv .venv
source .venv/bin/activate

# Dependências
pip install -e ".[dev]"

# Pre-commit hooks
pre-commit install

# .env
cp .env.example .env
# editar .env com:
#   JWT_SECRET_KEY=test
#   SECRET_KEY=test
#   MARITACA_API_KEY=...    (pedir ao orientador)
#   ANTHROPIC_API_KEY=...   (pedir ao orientador)

3. Validar setup

# Lint
make lint

# Format check
make format

# Testes (sempre com env vars)
JWT_SECRET_KEY=test SECRET_KEY=test pytest tests/unit/ -v

# Server local
make run-dev
# abrir http://localhost:8000/docs

4. Skills (recomendado)

# instalar skills do projeto
git clone https://github.com/anderson-ntlabs/cidadao-ai-skill.git ~/cidadao-ai-skill
mkdir -p ~/.claude/skills
ln -sfn ~/cidadao-ai-skill/cidadao-ai-* ~/.claude/skills/

Primeira semana — leitura obrigatória

Primeira contribuição (semana 2)

1. Pegar tarefa

• Issues abertas em anderson-ntlabs/cidadao.ai-backend/issues
• Filtrar por label good-first-issue (se existir) ou perguntar ao orientador
• Tarefas típicas para iniciante:
  • Aumentar cobertura de teste de um agente específico
  • Adicionar docstring/typing em service
  • Implementar endpoint simples em route existente
  • Bug fix com escopo bem-definido

2. Workflow git

git checkout main && git pull
git checkout -b feat/<nome-da-feature>
# ... implementação ...
make check    # roda lint + type-check + test
git add <arquivos específicos>   # nunca git add -A
git commit -m "feat(scope): summary"
git push -u origin feat/<nome-da-feature>
gh pr create --title "..." --body "..."

3. Antes de abrir PR — checklist

• make lint passa
• make format aplicado
• make check passa (lint + type + test)
• Cobertura não regrediu (idealmente sobe)
• Sem print() esquecido
• Sem credenciais hardcoded (.env, chaves, tokens)
• Commit em inglês, conventional, foco no "why"
• Sem menção a IA/Claude/ChatGPT em commit ou código
• CHANGELOG [Unreleased] atualizado se mudança visível

4. PR description — formato esperado

## Summary
- bullet 1
- bullet 2

## Test plan
- [ ] item 1 testado
- [ ] item 2 testado

## Screenshots (se UI)

Code review — o que esperar

Anderson revisa procurando:

1. Aderência às convenções (env vars, lint, testes passando)
2. Padrão arquitetural (lazy loader, semantic routing, fallback chain) — não quebrar
3. Cobertura — código novo vem com teste
4. Segurança — input validation, sem exposição de credenciais, RLS quando aplicável
5. "Why" claro — commit e PR description explicam motivação, não só mudança

Comentários comuns em revisão:

• "Por que essa abordagem?" — explica trade-off
• "Tem teste para X?" — sim, sempre
• "Esse import direto quebra lazy loading" — usar agent_lazy_loader
• "Falta env var no test" — JWT_SECRET_KEY=test SECRET_KEY=test

Comunicação com orientador

• Daily/weekly: dependente do contrato de estágio. Atualizações curtas, focadas em entregas.
• Bloqueado >2h: pergunta. Não trava.
• Decisões de arquitetura: sempre confirma antes de implementar.
• Reuniões: chega preparado com perguntas concretas.
• Documentação semanal: relatório de PRs abertos/mergeados, blockers, próximos passos.

Cadência típica de estágio (10 semanas / 160h)

Anti-patterns de iniciante

• ❌ git add -A ou git add . — adiciona arquivos não-intencionais (.env, .idea/, etc.)
• ❌ Commit gigante misturando muitas mudanças — quebrar em commits atômicos
• ❌ PR sem teste para código novo
• ❌ Ignorar pre-commit hook (--no-verify) — corrige a causa
• ❌ Nome de branch inconsistente — usar feat/..., fix/..., docs/..., refactor/...
• ❌ Push direto na main — sempre PR
• ❌ Pedir review sem ter rodado make check primeiro
• ❌ Esperar Anderson achar bug óbvio — autovalidar

Onde pedir ajuda

1. Skills: cidadao-ai-architecture, cidadao-ai-agents, cidadao-ai-conventions, cidadao-ai-data
2. CLAUDE.md na raiz do repo
3. cidadao.ai-docs — documentação geral
4. Issues fechadas (busca antes de perguntar)
5. Anderson — última opção para perguntas que skills/docs já cobrem; primeira opção para decisões de arquitetura