cpf-validador: Instructions file for Claude Code

CLAUDE.md

Guia para o Claude Code ao trabalhar neste repositório.

Comandos

# Instalar dependências (requirements-trt3.txt inclui o PyTorch da CRNN)
pip install -r requirements-trt3.txt

# Rodar localmente (FastAPI + FastMCP na porta 8000)
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

# Docker (porta 8002 conforme docker-compose.yaml)
docker compose up --build -d
docker compose down

Testes automatizados (mockam o TRT3, rodam no CI):

pip install -r requirements-dev.txt
ruff check app/
pytest tests/ -v

Testes manuais via:

• Interface web: http://localhost:8000/
• FastAPI docs (apenas ENV=development): http://localhost:8000/docs
• MCP transport: http://localhost:8000/mcp (streamable-http)

Dados reais nunca entram no repositório

O repositório é público. CPF, nome ou certidão de pessoa real não vão para teste, fixture, exemplo de API, README, CHANGELOG nem mensagem de commit — inclusive o CPF que alguém informou para reproduzir um bug e a versão "corrigida" dele.

• CPF de exemplo do projeto: 151.879.820-95. Para um caso inválido, derive dele (151.879.820-98, 151.979.820-95)
• Nome de exemplo: FULANO DE TAL
• Antes de commitar, git grep pelo dado que foi usado na reprodução
• Se vazar: reescrever o commit e push --force-with-lease antes que o release rode. O commit antigo continua acessível pelo SHA no GitHub até o suporte purgar

Commits e release

• Um commit por mudança, mensagem em português no padrão fix: / fix(ui): / build: / ci: / chore:. Sem Co-Authored-By nem assinatura de ferramenta
• Toda mudança é documentada no README (no padrão existente) e ganha entrada no CHANGELOG.md, sob ## vX.Y.Z
• A versão vive em app/main.py (version="X.Y.Z"). Push no master → workflow CI → workflow Release: se a tag vX.Y.Z ainda não existe, publica a imagem em ghcr.io/opastorello/cpf-validador e cria a release com a seção da versão recortada do CHANGELOG. Subir a versão e dar push já é publicar