# Guia de Referência: Como Usar os Arquivos Markdown com IA

Este arquivo explica como combinar os guias desta biblioteca sem sobrecarregar o contexto da IA.

---

## 1. Regra principal

Anexe **somente os arquivos necessários para a tarefa**. O melhor contexto não é o maior contexto: é o conjunto mínimo que define as decisões técnicas relevantes.

## 2. Fluxo universal

1. Anexe o(s) `.md`.
2. Informe projeto, stack e arquivos relevantes.
3. Declare objetivo e comportamento que deve ser preservado.
4. Peça diagnóstico antes do código.
5. Peça alternativas e trade-offs.
6. Implemente em passos verificáveis.
7. Rode testes/checklist.
8. Faça revisão final contra os guias.

## 3. Combinações úteis

- **Nova aplicação Web:** `web-platform-mdn.md` + `html-mdn.md` + `css-mdn.md` + `javascript-moderno.md`; adicione `bootstrap-5.3.8.md` se Bootstrap for usado.
- **Arquitetura:** `05-arquitetura-limpa.md` + guia específico da tecnologia.
- **Legado:** `02-refatoracao.md` + `10-codigo-limpo.md` + testes/tecnologia.
- **UI/UX:** `06-ux-usabilidade.md` + HTML/CSS/Bootstrap.
- **Padrão específico:** anexe somente o padrão individual + arquitetura do projeto.
- **Deploy:** `08-devops-na-pratica.md` + `09-git-github.md`.

## 4. Prompt universal

```text
Use os .md anexados como referência de engenharia.
Primeiro diagnostique o problema e identifique quais seções realmente se aplicam.
Não aplique padrões ou abstrações sem justificar.
Compare uma alternativa mais simples.
Preserve o comportamento existente salvo requisito explícito.
Implemente incrementalmente e finalize com testes, checklist e trade-offs.

Contexto: [DESCREVA o sistema, stack, arquitetura atual e onde a mudança será feita]
Objetivo: [DESCREVA o resultado observável que deve existir ao final]
Restrições: [DESCREVA o que não pode mudar, compatibilidade, segurança, prazo e limites técnicos]
```


### 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: Sistema interno de atendimento jurídico em HTML, CSS e JavaScript, com API REST e publicação no Cloudflare Pages.
Objetivo: Adicionar confirmação de exclusão e feedback visual de sucesso sem alterar o fluxo de cadastro.
Restrições: Preservar endpoints e dados existentes; funcionar em desktop/mobile; acessível por teclado; mudanças incrementais e reversíveis.
```