# 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](https://cookiecutter-data-science.drivendata.org/). 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:

```plaintext
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`](http://context.md) (objetivos) e o `01_experiments_`[`backlog.md`](http://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`](http://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`](http://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`](http://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.