Estrutura de Diretórios Padronizada: Onde Cada Coisa Deve Viver

Estrutura de Diretórios Padronizada: Onde Cada Coisa Deve Viver — aula do módulo Princípios do Método OKAM, na trilha Governança Ágil com Método OKAM da…

Leitura de aproximadamente 5 minutos.

Módulo: Princípios do Método OKAM · Curso: Governança Ágil com Método OKAM · Formação: Formação Nível Zero: Ferramentas Essenciais e Gratuitas de IA e Código

Estrutura de Diretórios Padronizada: Onde Cada Coisa Deve Viver

O que você vai aprender

1. Por Que a Estrutura de Pastas Importa Tanto para a IA?

Imagine entrar em um escritório onde contratos jurídicos, notas fiscais, rascunhos de papel e ferramentas de manutenção estão jogados em uma única gaveta gigante. Encontrar qualquer documento exigiria vasculhar todo o entulho.

No desenvolvimento de software assistido por Inteligência Artificial, o cenário é idêntico. Quando você abre uma pasta no seu editor (como o VS Code ou o Antigravity IDE), as extensões e os agentes de IA escaneiam os nomes dos arquivos e seus caminhos para entender o contexto do projeto.

Se você colocar todos os arquivos soltos na raiz (como script.js, texto.txt, teste.py, manual.docx e dados.csv), o modelo de linguagem enfrentará dois problemas graves:

1. Poluição de Janela de Contexto: A IA gastará parte significativa de sua cota de leitura inspecionando arquivos irrelevantes para a tarefa solicitada. 2. Ambiguidade de Responsabilidade: O assistente não saberá se deve alterar o arquivo principal ou o arquivo de rascunho, aumentando a chance de apagar informações importantes por engano.

A solução é adotar uma Estrutura Canônica de Diretórios — um mapa padronizado e previsível onde cada elemento possui um endereço fixo.

2. A Estrutura Canônica de Diretórios do OKAM

O padrão OKAM organiza qualquer projeto em cinco compartimentos principais, garantindo separação clara entre o que é código executável, o que é documentação e o que são regras para a inteligência artificial:


+-------------------------------------------------------------------------------+
|                       ESTRUTURA CANÔNICA DE PASTAS OKAM                       |
+-------------------------------------------------------------------------------+
|                                                                               |
|  meu-projeto/                                                                 |
|  ├── src/                <-- Código-fonte da aplicação (HTML, CSS, JS, Python)|
|  ├── docs/               <-- Manuais, diagramas e especificações para humanos |
|  ├── scripts/            <-- Utilitários de automação e ferramentas de build  |
|  ├── tests/              <-- Verificações automatizadas e massas de teste     |
|  ├── .agents/            <-- Regras, diretrizes e prompts para os assistentes |
|  ├── .gitignore          <-- Arquivos ignorados pelo controle de versão Git   |
|  ├── README.md           <-- Apresentação e guia de uso do projeto            |
|  └── AGENTS.md           <-- Constituição e limites operacionais para a IA    |
|                                                                               |
+-------------------------------------------------------------------------------+

Detalhamento das Responsabilidades

A tabela a seguir resume a função de cada pasta e o que não deve ser colocado nela:

| Diretório | O que vive aqui | O que NUNCA deve ser colocado aqui | |---|---|---| | src/ (Source) | Código principal do produto (páginas HTML, folhas de estilo CSS, scripts funcionais). | Arquivos de teste, manuais de texto longo ou scripts de manutenção. | | docs/ (Documentation) | Explicações arquiteturais, guias de usuário e anotações conceituais. | Código executável em produção ou credenciais e senhas. | | scripts/ (Utilities) | Scripts auxiliares (ex.: geradores de relatório, limpadores de dados). | Regras centrais do negócio ou lógica do frontend. | | tests/ (Testing) | Testes automatizados que comprovam que o código de src/ funciona. | Arquivos de produção modificados manualmente. | | .agents/ (Governance) | Regras customizadas, personas e fluxos de trabalho dos agentes de IA. | Código-fonte da aplicação ou dados de clientes. |

3. A Separação entre Código e Governança

Um dos diferenciais do Framework OKAM é a separação rígida entre a lógica da aplicação e as diretrizes de governança da IA.

Ao manter essa divisão clara, você pode trocar de modelo de IA, adicionar novos colaboradores ou migrar de editor sem alterar uma única linha do código do seu produto.

4. Armadilhas Comuns e Como Evitar

[!WARNING]
Salvar Arquivos Temporários e Credenciais na Raiz do Projeto: Um erro frequente de quem está iniciando é salvar arquivos com senhas, chaves de API (.env) ou planilhas de teste soltos na pasta principal do projeto. Além do risco de segurança (enviar segredos sem querer para o GitHub), a IA pode ler esses arquivos temporários e tentar usá-los como se fossem o código oficial da aplicação. Sempre coloque arquivos de dados em pastas específicas e configure o .gitignore para protegê-los.

Exercício Prático

Vamos criar a estrutura completa do padrão OKAM no seu terminal em menos de dois minutos:

1. Abra o seu terminal: Abra o Git Bash ou o PowerShell na pasta onde você guarda os seus projetos (por exemplo: projetos). 2. Crie a pasta do projeto e entre nela:


   mkdir meu-primeiro-projeto-okam
   cd meu-primeiro-projeto-okam

3. Crie todas as pastas padrão de uma só vez:


   mkdir src docs scripts tests .agents

4. Crie os arquivos fundamentais de documentação e governança:


   touch README.md AGENTS.md .gitignore

5. Verifique a estrutura criada:


     ls -la


     Get-ChildItem

Observe como o diretório está imediatamente organizado e pronto para receber código e regras claras.

Outras aulas do módulo