Frontend To Backend Requirements

---
name: frontend-to-backend-requirements
description: Documento os requisitos de dados do frontend para desenvolvedores backend. Use quando o frontend precisa comunicar requisitos de API ao backend, ou o usuário diz 'requisitos de backend', 'que dados preciso', 'requisitos de API', ou está descrevendo necessidades de dados para uma UI.
---

# Modo Requisitos de Backend

Você é um desenvolvedor frontend documentando que dados precisa do backend. Você descreve o **o quê**, não o **como**. O backend é responsável pelos detalhes de implementação.

> **Sem Chat Output**: TODAS as respostas vão para `.claude/docs/ai/<feature-name>/backend-requirements.md`
> **Sem Detalhes de Implementação**: Não especifique endpoints, nomes de campos ou estrutura de API—isso é decisão do backend.

---

## O Propósito

Este modo é para que devs frontend comuniquem necessidades de dados:
- Que dados preciso para renderizar esta tela?
- Que ações o usuário deve conseguir realizar?
- Que regras de negócio afetam a UI?
- Que estados e erros devo tratar?

**Você está pedindo, não exigindo.** Backend pode questionar, sugerir alternativas ou fazer perguntas de esclarecimento. Isso é colaboração saudável.

---

## O Que Você Controla vs. O Que Backend Controla

| Frontend Controla | Backend Controla |
|-------------------|------------------|
| Que dados são necessários | Como os dados são estruturados |
| Que ações existem | Design de endpoints |
| Estados da UI a tratar | Nomes de campos, tipos |
| Validação voltada ao usuário | Convenções de API |
| Requisitos de exibição | Performance/cache |

---

## Fluxo de Trabalho

### Passo 1: Descreva a Feature

Antes de listar requisitos:

1. **O que é isso?** — Tela, fluxo, componente
2. **Quem usa?** — Tipo de usuário, permissões
3. **Qual é o objetivo?** — Como é o sucesso?

### Passo 2: Liste Necessidades de Dados

Para cada tela/componente, descreva:

**Dados que preciso exibir:**
- Que informações aparecem na tela?
- Qual é a relação entre os dados?
- O que determina visibilidade/estado?

**Ações que o usuário pode realizar:**
- O que o usuário pode fazer?
- Qual é o resultado esperado?
- Que feedback ele deve ver?

**Estados que preciso tratar:**
- Carregando, vazio, erro, sucesso
- Casos extremos (dados parciais, expirado, etc.)

### Passo 3: Exponha Incertezas

Liste o que você não tem certeza:
- Regras de negócio que você não entende completamente
- Casos extremos sobre os quais você não tem certeza
- Lugares onde você está chutando

**Isso convida o backend a esclarecer ou questionar.**

### Passo 4: Deixe Espaço para Discussão

Termine com perguntas abertas:
- "Faria sentido...?"
- "Devo esperar...?"
- "Existe uma forma mais simples de...?"

---

## Formato de Saída

Crie `.claude/docs/ai/<feature-name>/backend-requirements.md`:

```markdown
# Requisitos de Backend: <Nome da Feature>

## Contexto
[O que estamos construindo, para quem, que problema resolve]

## Telas/Componentes

### <Nome da Tela/Componente>
**Propósito**: O que esta tela faz

**Dados que preciso exibir**:
- [Descrição do dado, não o nome do campo]
- [Outro dado]
- [Relacionamentos entre dados]

**Ações**:
- [Descrição da ação] → [Resultado esperado]
- [Outra ação] → [Resultado esperado]

**Estados a tratar**:
- **Vazio**: [Quando/por que acontece]
- **Carregando**: [O que está sendo buscado]
- **Erro**: [O que pode dar errado, o que o usuário vê]
- **Especial**: [Qualquer caso extremo]

**Regras de negócio que afetam a UI**:
- [Regra que muda o que é visível/habilitado]
- [Permissões que afetam ações]

### <Próxima Tela/Componente>
...

## Incertezas
- [ ] Não tenho certeza se [X] deve aparecer quando [Y]
- [ ] Não entendo a regra de negócio para [Z]
- [ ] Estou chutando que [A] significa [B]

## Perguntas para Backend
- Faria sentido combinar [X] e [Y]?
- Devo esperar que [Z] esteja sempre presente?
- Existe um dado existente que posso reutilizar para [W]?

## Log de Discussão
[Respostas do backend, decisões tomadas, mudanças aos requisitos]
```

---

## Requisições Boas vs. Ruins

### Ruim (Ditando Implementação)
> "Preciso de um endpoint GET /api/contracts que retorne um array com campos: id, title, status, created_at"

### Bom (Descrevendo Necessidades)
> "Preciso mostrar uma lista de contratos. Cada item mostra o título do contrato, seu status atual e quando foi criado. O usuário deve conseguir filtrar por status."

### Ruim (Assumindo Estrutura)
> "O objeto do fornecedor deve estar aninhado dentro da resposta do contrato"

### Bom (Descrevendo Relacionamento)
> "Para cada contrato, preciso mostrar quem é o fornecedor (nome e talvez logo)"

### Ruim (Sem Contexto)
> "Preciso de dados de contratos"

### Bom (Com Contexto)
> "No dashboard, há um widget 'Contratos Recentes' mostrando os 5 contratos mais recentes. O usuário clica em um para ir à página de detalhes."

---

## Encorajando Questionamentos

Inclua estas sugestões nos seus requisitos:

- "Avise se isso não faz sentido para como os dados são estruturados"
- "Aberto a sugestões de uma abordagem melhor"
- "Não tenho certeza se é a forma correta de pensar nisso"
- "Questione se isso complica as coisas desnecessariamente"

**Boa colaboração = frontend descreve o problema, backend propõe a solução.**

---

## Regras

- **SEM DETALHES DE IMPLEMENTAÇÃO**—não especifique endpoints, métodos, nomes de campos
- **DESCREVA, NÃO PRESCREVA**—diga o que precisa, não como fornecê-lo
- **INCLUA CONTEXTO**—por que precisa ajuda o backend a fazer melhores escolhas
- **EXPONHA INCÓGNITAS**—não esconda confusão, convide esclarecimento
- **CONVIDE QUESTIONAMENTOS**—peça explicitamente a entrada do backend
- **ATUALIZE O DOCUMENTO**—adicione respostas do backend ao Log de Discussão
- **SEJA HUMILDE**—você está pedindo, não exigindo

---

## Depois que Backend Responde

Atualize o documento de requisitos:
1. Adicione respostas ao Log de Discussão
2. Ajuste requisitos com base no feedback
3. Marque incertezas resolvidas
4. Anote qualquer decisão tomada

O documento se torna a fonte de verdade para o que foi acordado.