---
name: nuxt-docs-init
description: Analisa um projeto Nuxt existente e gera a estrutura completa de documentação para agentes AI — CLAUDE.md, AGENTS.md, .ai/architecture.md, .ai/guardrails.md e .docs/ com templates de negócio e técnico.
---

# nuxt-docs-init — Inicializar Documentação do Projeto

Você está gerando a estrutura de documentação para um projeto Nuxt existente. O objetivo é criar contexto suficiente para que agentes AI possam trabalhar no projeto sem exploração desnecessária do código.

## 1. Explorar o projeto

Antes de gerar qualquer arquivo, faça uma análise do projeto:

- Leia `package.json` para identificar stack, dependências e scripts
- Leia `nuxt.config.ts` para identificar módulos, `routeRules`, `runtimeConfig`
- Liste os diretórios `app/`, `server/`, `shared/` para mapear a estrutura
- Leia `shared/types/index.d.ts` para mapear os tipos de domínio
- Verifique se já existem `CLAUDE.md`, `AGENTS.md`, `.ai/`, `.docs/` — se sim, pergunte ao usuário se quer sobrescrever ou complementar

## 2. Identificar padrões existentes

Durante a exploração, identifique:
- **Stack** — quais módulos Nuxt, banco de dados, auth
- **Rotas** — mapeamento de `routeRules` (SSR, layouts, middlewares)
- **Handlers** — que tipo de `defineEventHandler` o projeto usa
- **Fetch** — como o cliente faz requisições (useAPI? useFetch? $fetch?)
- **Tipos de domínio** — entidades principais do negócio
- **Padrões violados** — componentes soltos, $fetch direto, any sem comentário

## 3. Gerar `CLAUDE.md`

Crie na raiz do projeto. Estrutura obrigatória:

```markdown
# [Nome do Projeto] — Guia de Desenvolvimento

> **Leia primeiro:** `.ai/architecture.md`
> **Guardrails obrigatórios:** `.ai/guardrails.md`

## Stack

| Camada | Tecnologia |
|---|---|
[preencher com o stack detectado]

## Princípios Gerais

- Mínimo de dependências
- Máximo 300 linhas por arquivo
- `<script setup>` mínimo — lógica em composables ou utils
- TypeScript sempre — nenhum `any` sem comentário justificando
- Português para labels/mensagens UI, inglês para código e URLs

## Gerenciador de Pacotes

[pnpm ou outro detectado — com comandos]

## Estrutura de Diretórios

[gerar árvore baseada na estrutura real encontrada]

## Componentes

[padrão pasta/index.vue + regras detectadas]

## Composables

[global vs co-localizado — baseado no que existe]

## API Routes (Server)

[padrão de handler detectado com exemplo real do projeto]

## Dados e Fetch no Cliente

[como o projeto faz fetch — com exemplos reais]

## Banco de Dados

[padrão detectado — Supabase db(), Firestore, etc.]

## Email

[se Resend ou outro detectado]

## Padrões a Evitar

[baseado nos padrões do projeto e nos anti-padrões encontrados]
```

## 4. Gerar `.ai/architecture.md`

Referência rápida para agentes. Deve ser conciso e direto:

```markdown
# Arquitetura — Referência Rápida

## Arquivos-Chave

| Arquivo | Propósito |
|---|---|
[listar os arquivos mais importantes encontrados]

## Fluxo de Autenticação

[diagrama textual baseado no middleware/auth detectado]
Cliente → middleware (auth.ts) → verifica token → claims → acesso

## Fluxo de Request

[diagrama textual]
Página → useAPI() → Authorization header + AppCheck → API Route → defineAuthenticatedEventHandler → db()

## Tipos Globais

[listar tipos encontrados em shared/types/index.d.ts]

## Módulos Nuxt Registrados

[listar de nuxt.config.ts]

## Route Rules

[tabela com rotas, SSR, layout, middleware — extraída de nuxt.config.ts]
```

## 5. Gerar `.ai/guardrails.md`

Regras inegociáveis. Personalize com base no que o projeto usa:

```markdown
# Guardrails — Regras Inegociáveis

Estas regras superam qualquer convenção. Não negocie.

## Segurança

- [ ] Nunca exponha `SUPABASE_SECRET_KEY` (ou equivalente) em `runtimeConfig.public`
- [ ] Nunca commite `.env` com valores reais
- [ ] Nunca execute operações destrutivas no banco sem confirmação do usuário
- [ ] Sempre valide input do usuário nas API routes

## Fetch (Cliente)

- [ ] **Nunca use `$fetch` diretamente** — quebra autenticação silenciosamente
- [ ] Use `useAPI()` para dados reativos
- [ ] Use `apiPost()`, `apiPut()`, `apiDelete()` para mutações

## Componentes

- [ ] Nunca crie componentes soltos (`Button.vue`) — sempre `Button/index.vue`
- [ ] Nunca busque dados em componentes folha — dados chegam via props

## TypeScript

- [ ] Nunca use `any` sem comentário `// eslint-disable-next-line @typescript-eslint/no-explicit-any` com justificativa

## Banco de Dados

- [ ] Nunca acesse o banco diretamente do cliente
- [ ] Migrations são imutáveis após merge — crie sempre uma nova

## Roteamento

- [ ] Nunca use `definePageMeta` para rotas cobertas por `routeRules`
- [ ] URLs de API sempre em inglês

## Gerenciador de Pacotes

- [ ] Sempre use `pnpm` — nunca `npm` ou `yarn`

## Tamanho de Arquivos

- [ ] Máximo 300 linhas por arquivo — divida em subcomponentes ou composables
```

## 6. Gerar `AGENTS.md`

Contexto compacto para agentes AI:

```markdown
# [Nome do Projeto] — Contexto para Agentes AI

## O que é este projeto

[descrição em 2-3 linhas do que o projeto faz]

## Stack Resumido

[stack em bullet points]

## Como rodar

\`\`\`bash
pnpm install
pnpm run dev
\`\`\`

## Onde encontrar cada coisa

| O que você quer | Onde está |
|---|---|
| Tipos de domínio | `shared/types/index.d.ts` |
| Handler autenticado | `server/utils/handlers/auth.ts` |
| Cliente fetch | `app/utils/api/index.ts` |
| Composable reativo | `app/composables/api.ts` |
| Banco de dados | `server/utils/database/` |
| Sidebar/Nav | `app/layouts/dashboard.vue` |
[adicionar conforme o projeto]

## Convenções críticas

- Componentes: sempre `NomeComponente/index.vue`
- API routes: `recurso.get.ts`, `recurso/[id].put.ts`
- URLs de API: sempre inglês
- Fetch: nunca `$fetch` — use `useAPI()` ou `apiPost()`
- Lógica: composables para state reativo, utils para funções puras
```

## 7. Criar estrutura `.docs/`

```
.docs/
  business/
    README.md
    glossario.md      (se houver termos de domínio identificados)
  technical/
    README.md
    decisions/
      001-stack.md    (documental da decisão de stack)
  api/
    README.md
```

### `.docs/business/README.md`
```markdown
# Documentação de Negócio

Documente aqui as regras de negócio, fluxos de usuário e glossário do domínio.

## Estrutura sugerida

- `glossario.md` — termos e definições do domínio
- `fluxos/` — diagramas ou descrições de fluxos principais
- `regras/` — regras de negócio por funcionalidade
```

### `.docs/technical/README.md`
```markdown
# Documentação Técnica

Decisões de arquitetura (ADRs), integrações e contratos técnicos.

## Estrutura sugerida

- `decisions/` — Architecture Decision Records (ADRs)
- `integrations/` — documentação de integrações externas
- `deployment.md` — processo de deploy

## Formato de ADR (decisions/NNN-titulo.md)

\`\`\`markdown
# NNN — Título da Decisão

**Status:** Aceito | Proposto | Depreciado  
**Data:** YYYY-MM-DD

## Contexto
O que motivou essa decisão?

## Decisão
O que foi decidido?

## Consequências
Quais são os trade-offs?
\`\`\`
```

### `.docs/api/README.md`
```markdown
# Documentação de API

Contratos de API e endpoints públicos.

## Estrutura sugerida

- Um arquivo por recurso: `schedule.md`, `volunteers.md`, etc.
- Documente: método, URL, autenticação necessária, body, resposta, exemplos
```

### `.docs/technical/decisions/001-stack.md`
Gere este arquivo com base no stack detectado:

```markdown
# 001 — Stack Tecnológico

**Status:** Aceito  
**Data:** [data atual]

## Contexto

[descrição do problema que motivou as escolhas]

## Decisão

- **Framework:** Nuxt 4 com compatibilityDate [detectada]
- **UI:** [detectado]
- **Auth:** [detectado]
- **Banco:** [detectado]
- **Gerenciador:** pnpm

## Consequências

[trade-offs das escolhas]
```

## 8. Exibir relatório final

Ao terminar, mostre:

```
Documentação gerada com sucesso!

Arquivos criados:
  ✓ CLAUDE.md
  ✓ AGENTS.md
  ✓ .ai/architecture.md
  ✓ .ai/guardrails.md
  ✓ .docs/business/README.md
  ✓ .docs/technical/README.md
  ✓ .docs/technical/decisions/001-stack.md
  ✓ .docs/api/README.md

Padrões detectados que merecem atenção:
  [listar qualquer anti-padrão encontrado durante a exploração]

Próximos passos:
  1. Revise CLAUDE.md e ajuste para sua realidade
  2. Preencha .docs/business/ com as regras de negócio do projeto
  3. Complete .ai/architecture.md com os tipos de domínio reais
```