# Guia de Referência: Git e GitHub: Versionamento e Fluxo de Trabalho

Este guia organiza práticas de controle de versão para manter mudanças pequenas, rastreáveis e colaborativas. A IA deve escolher comandos Git considerando estado atual, histórico compartilhado e risco de reescrita.

---

## 1. Fundamentos de Versionamento

* **Repositório:** Git mantém histórico completo e permite comparar, recuperar e integrar mudanças.
* **Stage:** A área de preparação permite selecionar exatamente o que fará parte do próximo commit.
* **Commit:** Cada commit deve representar uma unidade compreensível, com mensagem que explique intenção.
* **Diff e log:** Revise o que mudou e o histórico antes de operações importantes.

---

## 2. Branches e Trabalho Paralelo

* **Feature branch:** Isole uma funcionalidade para desenvolver e revisar sem desestabilizar a branch principal.
* **Branches remotas:** Use remotos para colaboração, sincronização e backup.
* **Integração:** Atualize-se com a principal antes de integrar e resolva conflitos conscientemente.

---

## 3. Merge e Rebase

* **Merge:** Preserva o contexto de integração e cria histórico explícito quando necessário.
* **Rebase:** Lineariza commits locais, mas reescreve histórico; não rebase commits compartilhados sem coordenação.
* **Pull com rebase:** Pode ser apropriado para reaplicar commits locais ainda não compartilhados sobre a versão remota atualizada.

---

## 4. Conflitos

* **Entenda os lados:** Leia o conflito e o contexto antes de aceitar automaticamente "ours" ou "theirs".
* **Teste:** Após resolver, execute testes e revise o diff final.
* **Artefatos:** Remova arquivos temporários de merge e não comite resíduos acidentais.

---

## 5. Tags, Releases e GitHub

* **Tags:** Marque versões importantes e compartilhe tags quando fizerem parte do processo de release.
* **Pull request:** Use PRs para revisão, discussão e integração controlada.
* **Fork:** Adequado para colaboração quando contribuidores não têm escrita direta no repositório central.
* **Modelo de branches:** Escolha um fluxo proporcional ao tamanho da equipe e frequência de entrega.

---

## 6. Como Usar com IA

Use este arquivo ao pedir comandos Git. A IA deve começar por `git status`, explicar o impacto de cada comando e evitar operações destrutivas ou reescrita de histórico compartilhado sem autorização explícita.

---

## Diretrizes de Execução para IA

Ao criar, revisar ou reestruturar uma aplicação, garanta:

1.  **Inspecione o estado** com `git status`, `git diff` e histórico antes de alterar referências.
2.  **Evite `push --force` e resets destrutivos** sem pedido e justificativa claros.
3.  **Mantenha commits pequenos e coerentes**.
4.  **Não reescreva histórico compartilhado** sem coordenação.
5.  **Use tags/releases** quando o projeto precisar de marcos reproduzíveis.


---

## Roteiro de Uso Operacional com IA

1. **Contextualize o projeto:** informe domínio, stack, arquitetura atual, restrições e objetivo da mudança.
2. **Selecione o recorte:** diga qual princípio/capítulo deste guia deve orientar a tarefa; não aplique tudo ao mesmo tempo.
3. **Peça diagnóstico antes do código:** a IA deve identificar sintomas, riscos, dependências e alternativas.
4. **Defina critérios de aceite:** comportamento, testes, acessibilidade, performance, segurança ou operação conforme o tema.
5. **Implemente incrementalmente:** mudanças pequenas, reversíveis e verificadas.
6. **Faça revisão final:** peça à IA que confronte a solução com este guia e liste desvios deliberados.

### Prompt de aplicação

```text
Use este guia como referência técnica para a tarefa abaixo.
Não copie regras mecanicamente. Primeiro diagnostique o problema e selecione apenas os princípios aplicáveis.
Mostre: (1) diagnóstico, (2) decisão, (3) implementação proposta, (4) testes/verificações, (5) trade-offs e (6) checklist final.

Contexto: [DESCREVA o sistema, stack, estado atual e cenário da mudança]
Objetivo: [DESCREVA o resultado esperado e o comportamento que deve existir]
Restrições: [DESCREVA limites de escopo, compatibilidade, segurança, prazo e o que não pode mudar]
```


### Como preencher os campos

- **Contexto:** descreva o tipo de sistema, stack/versões, arquitetura atual, onde a mudança acontece e o comportamento relevante já existente.
- **Objetivo:** descreva o resultado observável que deve existir ao final, não apenas a tecnologia que você quer usar.
- **Restrições:** informe o que não pode mudar, compatibilidade, prazo, segurança, acessibilidade, performance, legado, dependências e limites de escopo.

### Exemplo preenchido

```text
Contexto: Repositório com branch main e várias funcionalidades simultâneas; equipe tem conflitos frequentes e tags não são usadas.
Objetivo: Definir fluxo simples de branches, integração, commits e tags para releases com histórico compreensível.
Restrições: Não reescrever commits já compartilhados; preservar main estável; documentar estratégia de merge/rebase e recuperação.
```