CLAUDE.md — AEX Engineering

Instruções para ferramentas de IA (Claude, Cursor, ChatGPT) que trabalham neste repositório.

Identidade do repositório

• aex-engineering é a fonte oficial da engenharia da AEX Hub Capital.
• Contém padrões, processos, documentação, templates e checklists.
• Não contém código de aplicação. O código de cada produto vive no repositório próprio dele.
• Público-alvo: desenvolvedores (referência e onboarding) e ferramentas de IA (base de conhecimento).
• Objetivo da IA aqui: escrever e manter documentação no padrão da empresa, de forma consistente com humanos.

Contexto da empresa

• AEX Hub Capital é uma Venture Builder e Holding de Tecnologia.
• Cria, valida, opera e escala produtos próprios; não presta serviço para terceiros.
• Modelo mental: fábrica de MVPs — lançar rápido, validar hipóteses, investir em infraestrutura complexa só após validação de mercado.

Filosofia (aplicar em toda decisão)

• Simplicidade acima de complexidade.
• Padronização acima de improvisação.
• Documentação faz parte do desenvolvimento — não documentado é não entregue.
• Automação sempre que possível.
• Infraestrutura escalável apenas quando necessária.
• Todo projeto deve ser fácil de entender por qualquer desenvolvedor.

Como escrever neste repositório

• Escreva em português (PT-BR). Mantenha termos técnicos consagrados em inglês (deploy, commit, branch, pull request).
• Priorize clareza, concisão e organização. Sem burocracia e sem texto de enchimento.
• Um assunto por arquivo. Não duplique conteúdo entre handbook/ e standards/ — se a regra é normativa, ela vive em standards/; os demais documentos apenas referenciam.
• Prefira listas, tabelas e exemplos a parágrafos longos.
• Todo documento deve escalar para dezenas de desenvolvedores sem virar peso.
• Ao criar um documento, siga o modelo correspondente em templates/ quando existir.

Convenções de nomes

• Documentos normativos e templates: UPPER_SNAKE_CASE.md (ex.: COMMIT_STANDARD.md, PRD_TEMPLATE.md).
• Guias de ferramenta e índices: lowercase.md (ex.: cursor.md, README.md).
• Pastas: kebab-case (ex.: sample-project/).
• README.md não usa frontmatter YAML (renderiza como portal no GitHub).

Onde cada coisa mora

• handbook/ — visão geral da engenharia e onboarding.
• standards/ — padrões oficiais (a camada normativa; ler antes de agir).
• templates/project/ — documentação padrão de um novo projeto.
• templates/clickup/ — modelos de itens de gestão.
• templates/prompts/ — prompts padronizados para IA.
• checklists/ — listas de verificação por atividade.
• tools/ — como usamos cada ferramenta da stack.
• examples/ — padrões aplicados na prática.
• assets/ — marca (logo e brand book).

Padrões oficiais (leia sob demanda antes de escrever)

Ao trabalhar em um tema, leia o padrão correspondente e siga-o:

• Gestão no ClickUp → standards/CLICKUP_STANDARD.md
• Repositório e documentação técnica → standards/GITHUB_STANDARD.md
• Documentos obrigatórios de projeto → standards/DOCUMENTATION_STANDARD.md
• Branches → standards/BRANCH_STANDARD.md
• Commits → standards/COMMIT_STANDARD.md
• Deploy → standards/DEPLOY_STANDARD.md

Stack oficial

• Código e gestão: GitHub, ClickUp.
• Runtime e infraestrutura: Coolify, Docker, Supabase, PostgreSQL, Redis, N8N.
• Desenvolvimento com IA: Cursor, Claude, ChatGPT.

Regras oficiais (inegociáveis)

1. Código vive no GitHub. Gestão vive no ClickUp.
2. Se não está no ClickUp, não existe.
3. Toda feature pertence a uma Milestone → tarefa principal → subtarefas.
4. Nenhum Pull Request sem documentação.
5. Documentação faz parte da entrega.
6. Automatize antes de repetir.
7. Arquitetura antes de implementação.
8. Sempre pensar em escalabilidade.

Nunca faça (guardrails)

• Não adicione código de aplicação a este repositório.
• Não commite segredos, credenciais ou .env reais — use apenas modelos de exemplo.
• Não crie uma segunda fonte de verdade: não repita em um arquivo o que já é normativo em standards/.
• Não invente processos, ferramentas ou padrões que contrariem este arquivo ou a filosofia.
• Não gere documentos genéricos "de IA": todo conteúdo deve refletir o contexto real da AEX.
• Em caso de conflito entre instruções, prevalece o que está em standards/; se ainda houver dúvida, pergunte antes de assumir.