# Repositorio IA First

Como estruturar um repositorio para que qualquer LLM entenda o projeto com rapidez e seguranca.

## Objetivo

Transformar o repositorio em uma base clara, navegavel e autoexplicavel, para que ferramentas como Claude, ChatGPT, Copilot e Cursor consigam localizar regras, integracoes, fluxos criticos e pontos de risco sem comecar do zero.

**A IA deve conseguir responder:**
- Onde esta a regra de negocio
- Onde esta a integracao externa
- Quais modulos compoem o sistema
- Como executar localmente
- Como rodar testes
- Quais fluxos sao mais sensiveis
- Quais arquivos precisam ser alterados para uma funcionalidade especifica

**Resultados esperados:**
- Menor tempo para entendimento do legado
- Melhor suporte assistido por IA
- Refatoracao com mais seguranca
- Diagnostico mais rapido de incidentes
- Base mais pronta para testes, observabilidade e automacao

## 1. Principio central

Um bom repositorio para IA deve concentrar o contexto certo no lugar certo.

- **Contexto facil de achar** -- Explicacoes principais perto do codigo. IA nao deve depender de adivinhacao.
- **Estrutura consistente** -- Pastas, camadas e convencoes devem seguir padrao claro.
- **Nomes explicitos** -- Arquivos, classes e metodos devem explicar a intencao e o efeito.
- **Fronteiras claras** -- UI, regra de negocio, acesso a dados e integracoes bem separados.
- **Documentacao curta e util** -- Documentos objetivos, especializados e proximos ao contexto.

## 2. Estrutura base

```
/repositorio
├── README.md
├── AI_CONTEXT.md
├── ARCHITECTURE.md
├── DOMAIN_GLOSSARY.md
├── SUPPORT_GUIDE.md
├── CHANGELOG.md
├── .editorconfig
├── .gitignore
├── /docs
├── /scripts
├── /tests
├── /src
└── /infra
```

## 3. Papel de cada arquivo raiz

| Arquivo | Proposito |
|---------|-----------|
| README.md | Ponto de entrada humano e da IA. O que e o sistema, quais modulos, qual stack, como rodar, como testar. |
| AI_CONTEXT.md | Manual de entrada para LLMs. Proposito, modulos, regras, padroes, pontos frageis, o que nao alterar. |
| ARCHITECTURE.md | Visao tecnica macro. Projetos, dependencias, responsabilidades por camada, divida tecnica. |
| DOMAIN_GLOSSARY.md | Evita interpretacao errada. Termos como O.S., parceiro, profissional possuem significado proprio. |
| SUPPORT_GUIDE.md | Base para suporte assistido por IA. Sintomas, causas provaveis, ordem de investigacao. |
| HOTSPOTS.md | Areas de alta sensibilidade. |
| CHANGELOG.md | Mudancas importantes, historico recente. |

## 4. Pasta /docs: documentacao complementar segmentada

```
/docs
├── fluxos/
│   ├── fluxo-criacao-os.md
│   ├── fluxo-finalizacao-os.md
│   ├── fluxo-encaminhamento.md
│   └── fluxo-integracao-erp.md
├── integracoes/
│   ├── voalle.md
│   ├── hubsoft.md
│   └── webhook.md
├── banco/
│   ├── tabelas-principais.md
│   ├── views-importantes.md
│   └── procedures-criticas.md
├── decisoes-arquiteturais/
│   ├── adr-001-separacao-regra-admin.md
│   └── adr-002-padrao-logs.md
└── incidentes/
    ├── incidente-os-nao-finaliza.md
    └── incidente-status-inconsistente.md
```

## 5. Pasta /src: codigo organizado por dominio

```
/src
├── Admin.Web
├── App.Api
├── WebHub
├── Core.Domain
├── Application
├── Infrastructure
└── Shared
```

## 6. Padroes que deixam o repositorio pronto para LLM

- Nomes de arquivos e classes explicitos (evitar Utils, Helper, Geral)
- Metodos pequenos e orientados a intencao
- Comentarios e sumarios uteis (documentar intencao, restricoes, pre-condicoes)
- Padrao de logs com contexto suficiente
- Testes claros e espelhados
- Scripts de diagnostico e operacao

## 7. Catalogo de integracoes e mapa de fluxos criticos

Cada integracao documentada com: objetivo, eventos, endpoints, autenticacao, payloads, erros comuns, logs e impacto da falha.

Cada fluxo critico com: objetivo, entrada, etapas e pontos de falha.

## 8. O que evitar

- Arquivos gigantes sem divisao
- Nomes genericos
- Regra de negocio escondida em UI
- Utilitarios que fazem de tudo
- Classes com multiplas responsabilidades
- Comentarios desatualizados
- Ausencia de README por modulo
- Duplicacao nao mapeada
- Dependencias implicitas
- Pastas "diversos"
- SQL espalhado sem padrao
- Segredos hardcoded

## 9. Exemplo pratico (Donc)

```
/repositorio-donc
├── README.md
├── AI_CONTEXT.md
├── ARCHITECTURE.md
├── DOMAIN_GLOSSARY.md
├── SUPPORT_GUIDE.md
├── HOTSPOTS.md
├── CHANGELOG.md
├── /docs (fluxos, integracoes, banco, decisoes-arquiteturais)
├── /src (Admin.Web, App.Api, WebHub, Core.Domain, Application, Infrastructure, Shared)
├── /tests (Core.Domain.Tests, Application.Tests, Integration.Tests, Regression.Tests)
├── /scripts (sql, deploy, diagnostico)
└── /infra (ambientes.md, variaveis.md, publicacao.md)
```

## 10. Ordem para implantar no legado

1. **Etapa 1** -- Criar os arquivos raiz (README, AI_CONTEXT, ARCHITECTURE, DOMAIN_GLOSSARY, SUPPORT_GUIDE, HOTSPOTS)
2. **Etapa 2** -- Mapear fluxos criticos em /docs/fluxos
3. **Etapa 3** -- Organizar a pasta /src, melhorar nomes
4. **Etapa 4** -- Padronizar codigo e observabilidade (logs, comentarios, nomes)
5. **Etapa 5** -- Criar testes e scripts de apoio

> **Regra de ouro:** se uma IA entrar no repositorio sem contexto e em cerca de 10 minutos conseguir entender o que o sistema faz, quais modulos existem, quais fluxos sao criticos, onde fica cada regra e onde estao os pontos perigosos, entao o repositorio esta realmente ficando pronto para LLM.