Organizando a Casa: Um Framework Prático para Projetos de Data Science (Além do Cookiecutter)

Quando falamos sobre organizar processos e repositórios, a Engenharia de Software tem bibliotecas inteiras de conteúdo. Mas, quando afunilamos para Ciência de Dados, o material se torna escasso.

A referência mais conhecida é, sem dúvida, o Cookiecutter Data Science. Embora apresente uma estrutura madura, ele ainda carrega o DNA da Engenharia de Software, o que gera uma certa estranheza no dia a dia exploratório de um cientista.

Do outro lado, temos frameworks de processo como CRISP-DM, TDSP e o MLOps Lifecycle. Todos são excelentes, mas costumam deixar lacunas:

• CRISP-DM: É o "avô" da área (quase 40 anos!). Define bem as etapas (Dados -> Modelagem -> Deploy), mas ignora dores modernas como versionamento de código, organização de arquivos e iterações rápidas.

• TDSP (Microsoft): Foca muito em colaboração e agile (ótimo para times), mas dá pouco suporte para o "depois do deploy": monitoramento e retreino.

• MLOps Lifecycle: Cobre muito bem a produção (Design -> Ops -> Monitoring), mas muitas vezes passa rápido demais pela fase de experimentação e modelagem.

Este artigo propõe uma forma prática de organizar seu repositório e seu projeto. O objetivo é aproveitar o melhor desses frameworks, mas priorizando o mindset do Cientista: fugir da rigidez excessiva do desenvolvedor, mas evitar que fiquemos presos eternamente no laboratório sem entregar valor.

O Mindset: Setup Linear e Loop Infinito

O segredo para usar esse framework é entender o pensamento por trás dele: construir o fluxo de ponta a ponta o mais rápido possível (Setup) e, só então, iterar para melhorar etapas pontuais (Loop).

Vamos mergulhar nessas duas etapas.

1. O SETUP (A Construção do Baseline)

Esta é a etapa inicial onde descrevemos o contexto e construímos a "Versão Zero". Assim como no CRISP-DM, começamos pelo Entendimento do Negócio: contexto, dores, dados disponíveis e métricas de sucesso. A melhor forma de registrar isso é simples: arquivos Markdown (.md) na pasta de documentação.

Neste momento, temos um desafio claro: construir o modelo de "uma tarde". No setup, o objetivo é ter um modelo rodando com todo o pipeline (pré e pós-processamento) no menor tempo possível.

• O modelo vai ser ruim? Vai.

• A acurácia vai ser baixa? Sim.

Não tenha medo disso. O objetivo do setup não é performance, é infraestrutura. Um modelo baseline, mesmo que "burro", permite que o Engenheiro de MLOps comece a criar a esteira de deploy e o Engenheiro de Dados valide o delivery das tabelas. Ninguém fica esperando o Cientista encontrar o hiperparâmetro perfeito para começar a trabalhar.

Regra de Ouro do Setup: Se um obstáculo não é impeditivo, documente-o como uma "Proposta de Experimento" e siga em frente. Isso te dá velocidade e cria um backlog valioso para a próxima fase.

Um detalhe crucial: O Ambiente. Não adianta ter pastas organizadas se as bibliotecas são uma caixa preta. Ainda na fase de setup, crie um arquivo requirements.txt (ou use Poetry/Conda). A regra é simples: instalou uma lib nova para testar? Adicione ao arquivo de dependências imediatamente. Reprodutibilidade não é luxo, é pré-requisito para que o "modelo de uma tarde" rode na máquina do seu colega.

A Estrutura de Pastas (Pós-Setup)

Ao final dessa tarde de configuração, seu repositório deve ter esta cara:

data/
|---raw/
|---processed/
docs/
|---00_context.md
|---01_experiments_backlog.md
experiments/
|---00_setup.ipynb
|---archive/
jobs/
|---01_preprocess.py
|---02_featuring.py
|---03_model_train.py
|---04_model_predict.py
|---05_evaluate.py
|---06_posprocess.py

Entendendo cada diretório:

• data/: Onde os dados (ou as queries) moram. Separar em raw, processed e predict ajuda a entender o ciclo de vida da informação.

• docs/: A memória do projeto. Já nasce com o 00_context.md (objetivos) e o 01_experiments_backlog.md (lista de ideias que você teve durante o setup mas não implementou).

• experiments/: O Laboratório. É aqui que testamos, falhamos e descobrimos, sem medo de quebrar a produção. Usamos Notebooks numerados (00_setup.ipynb é o primeiro) para manter uma ordem cronológica.

  • Gerenciando o Caos: Com o tempo, essa pasta pode ficar cheia. Crie uma subpasta archive/ e mova para lá experimentos antigos ou descartados. Mantenha na raiz apenas o que é recente ou referência ativa.

• jobs/: A Fábrica. É a fonte da verdade. O código aqui deve ser "sério", limpo e modularizado em scripts .py numerados pela ordem de execução.

  • Por que separar? Isso facilita muito a vida do MLOps. Se o pipeline quebrar, ele sabe exatamente qual script falhou (02_featuring.py) e pode re-executar dali para frente, sem precisar rodar um notebook gigante desde o início.

2. O LOOP (A Melhoria Contínua)

Com o baseline em produção (ou pronto para tal), entramos no ciclo de melhoria científica.

A. Escolha do Experimento Vá até o seu docs/01_experiments_backlog.md. Baseado no tempo que você tem e na dor do modelo, escolha uma carta.

• Quer reduzir custo? Pegue um experimento de Feature Selection.

• A métrica de negócio está ruim? Teste uma nova arquitetura de modelo.

B. Preparo do Experimento (A "Capa" do Notebook) Crie um novo notebook na pasta experiments/ (ex: 05_teste_xgboost.ipynb). Para evitar que ele vire um código "zumbi" que ninguém entende daqui a 2 meses, padronize a primeira célula com os metadados do estudo:

• Nome: Um título descritivo (mais que o nome do arquivo).

• Status: Em Andamento / Concluído / Aprovado / Descartado. (Essencial para leitura dinâmica).

• Job Associado: Qual script da pasta jobs esse experimento pretende melhorar?

• Benefício Esperado: O que esperamos ganhar com isso?

• Metodologia: Breve descrição do que será feito (quais libs, qual técnica).

• Conclusão: (Preenchido ao final) O resultado foi atingido? Vamos levar para produção?

C. Execução e POO (Dica de Ouro) Agora você coda e mede o impacto. Mantenha o isolamento: mude apenas uma variável por vez para ter certeza da causalidade.

Dica Pro (Nível Sênior): Se você já está confortável com Python, use Programação Orientada a Objetos (POO). Se seus scripts em jobs/ forem classes, você pode importá-las dentro do notebook de experimento e usar polimorfismo para alterar apenas o método que você quer testar. Isso evita aquele "copia e cola" perigoso entre notebook e script oficial.

D. Conclusão e Ajuste dos Jobs O experimento deu certo? O gráfico subiu? Ótimo.

1. Atualize a "Capa" do notebook com a Conclusão e mude o status para Aprovado.

2. Atualize o docs/01_experiments_backlog.md.

3. Vá até a pasta jobs/.

4. Refatore. Pegue a lógica validada no notebook (sem os gráficos e prints) e atualize o script .py oficial.

5. O Teste de Paridade (Trust, but Verify): Este é o passo que separa amadores de profissionais. Antes de comemorar, rode o novo script job e o notebook original com o mesmo input. Os resultados devem ser exatamente idênticos. Se houver uma divergência mínima (0.01%), existe um erro na refatoração. Nunca faça o merge sem essa validação.

Conclusão: A Resposta para o "Quanto tempo falta?"

Essa estrutura não organiza apenas seus arquivos; ela organiza sua cabeça e a comunicação com o time.

Existem aditivos para projetos maiores? Claro: pastas src (para código compartilhado), tests (unitários), conf (para tirar parâmetros do código) e infra (Terraform/Docker). Mas isso é assunto para um próximo artigo.

O ponto central aqui é conectar nosso papel ao método científico. Ao trabalhar em blocos (Setup -> Loop), você para de dar respostas vagas como "Posso melhorar o modelo para sempre, não sei quando vai estar pronto".

Agora, sua resposta para o gerente é técnica e precisa:

"O baseline já está rodando. Tenho 10 experimentos priorizados no backlog. Estimo 2 dias para cada. Daqui a 20 dias teremos a melhor versão possível dentro do prazo, mas o produto já existe hoje."

Isso é Ciência de Dados profissional.