Gera ou atualiza documentação técnica obrigatória do repositório (como rodar, build, testes, funcionalidades, decisões, roadmap, uso de IA). Use ao criar README, documentar setup, entregar MVP, revisar docs do projeto ou quando o usuário pedir documentação técnica, guia de contribuição ou visão de stack.
Manter um documento principal (geralmente README.md ou seção equivalente) com estrutura previsível, alinhada ao repositório real (package.json, scripts, porta do dev server). Stack e convenções de código: .cursor/rules/core-project.mdc, .cursor/rules/next-frontend.mdc — não duplicar no README.
Incluir, nesta ordem lógica (títulos podem usar o tom do projeto; emojis opcionais):
[ ]README.md, apenas um link curto para docs/AI_USAGE.md. O conteúdo completo (por ferramenta: etapas, prompts de exemplo, adaptações manuais, validação) fica em docs/AI_USAGE.md, não duplicado no README.package.json (ver também core-project.mdc).package.json).technical-decision-documentation).docs/AI_USAGE.md com prompts úteis e o que foi revisado manualmente (segurança, tipos, testes). No README, manter só uma seção breve com link para esse arquivo.Ajuste nomes de scripts e portas ao projeto.
## Como rodar
### Desenvolvimento
\`\`\`bash
npm install
npm run dev
\`\`\`
Abre em `http://localhost:4003` (Next.js — conferir `package.json`).
### Build e produção local
\`\`\`bash
npm run build
npm run start
\`\`\`
Mesma porta em dev/produção local conforme scripts. Sem `preview` estilo Vite.
### Typecheck, lint e formatação
\`\`\`bash
npm run typecheck
npm run lint
npm run format:check
\`\`\`
Inclua `npm run test` apenas se existir no `package.json`.
Se o projeto usar pnpm/yarn, substituir o gerenciador e comandos de forma consistente.
## Funcionalidades
- [Item 1 — linguagem de produto]
- [Item 2]
## Decisões técnicas
- **Nome da stack/lib:** breve justificativa
- **Outro item:** breve justificativa
## Melhorias futuras
- [ ] Item backlog 1
- [ ] Item backlog 2
## Uso de ferramentas de IA
Registro detalhado: [docs/AI_USAGE.md](docs/AI_USAGE.md).
docs/AI_USAGE.md)Crie o arquivo na pasta docs/ com título de nível 1. Estrutura por ferramenta (mesmo padrão de conteúdo que antes ia no README):
# Ferramentas IA utilizadas
### [Nome da ferramenta — ex.: Claude via Cursor]
**Etapas:** [fases em que ajudou]
**Prompts exemplo:**
- "[prompt curto 1]"
- "[prompt curto 2]"
**Adaptações manuais:** [refino, tipos, performance, segurança]
**Validação:** [testes, review, checklist]
### [Outra ferramenta — ex.: GitHub Copilot]
**Etapas:** [...]
**Mais efetivo:** [...]
**Adaptações:** [...]
**Validação:** [...]