Padrão Oficial do GitHub

O GitHub é a fonte oficial da documentação técnica. Todo repositório da AEX segue a mesma estrutura de raiz — abrir um projeto novo é sempre encontrar as coisas nos mesmos lugares.

O GitHub é a fonte oficial da documentação técnica. Todo repositório da AEX segue a mesma estrutura de raiz — abrir um projeto novo é sempre encontrar as coisas nos mesmos lugares.

Estrutura de raiz

project/
├── src/                  # Código-fonte da aplicação
├── docs/                 # Documentação técnica do projeto
├── .github/              # Automações e utilitários (CI/CD, templates)
├── docker/               # Configurações de containers
├── README.md             # Porta de entrada do repositório
├── PROJECT_CONTEXT.md    # Contexto de negócio do projeto
├── CLAUDE.md             # Regras para a IA atuar no repo
├── .env.example          # Modelo das variáveis de ambiente
├── LICENSE
└── package.json          # Manifesto de dependências da stack

Pastas

Pasta	Conteúdo
`src/`	Código-fonte da aplicação.
`docs/`	Documentação técnica do projeto (os documentos obrigatórios que não ficam na raiz).
`.github/`	Automações e utilitários: workflows de CI/CD, templates de issue e de Pull Request.
`docker/`	Configurações de containers (Dockerfile, compose e afins).

Arquivos de raiz

Arquivo	Função
`README.md`	Porta de entrada: objetivo do projeto e como executá-lo.
`PROJECT_CONTEXT.md`	Contexto de negócio e do problema.
`CLAUDE.md`	Regras e diretrizes para a IA atuar no repositório.
`.env.example`	Modelo das variáveis de ambiente. Nunca commite um `.env` real.
`LICENSE`	Licença do projeto.
`package.json`	Manifesto de dependências. Use o equivalente da stack quando não for Node (ex.: `pyproject.toml`).

Documentação técnica

Todo projeto mantém os documentos obrigatórios vivos e atualizados. README.md, PROJECT_CONTEXT.md e CLAUDE.md ficam na raiz; os demais vivem em docs/.

O conjunto completo, com a função de cada documento, está em DOCUMENTATION_STANDARD.

Fluxo no repositório

O trabalho dentro do repositório segue os padrões específicos:

Branches → BRANCH_STANDARD
Commits → COMMIT_STANDARD
Publicação → DEPLOY_STANDARD
Pull Requests → todo PR passa pelo checklist de code review e nenhum PR é mesclado sem documentação.

Modelos para iniciar um repositório no padrão estão em templates/project/.

Regras (resumo)

Todo repositório segue a estrutura de raiz padrão.
A documentação técnica vive dentro do repositório, versionada junto ao código.
README.md, PROJECT_CONTEXT.md e CLAUDE.md estão sempre na raiz.
.env.example está sempre presente; segredos reais nunca são commitados.
Nenhum Pull Request é mesclado sem documentação atualizada.