| name | scope-guard |
| description | Contrato de escopo explícito que bloqueia over-engineering antes de qualquer implementação |
| triggers | ["scope-guard","contrato de escopo","FAZER","NÃO FAZER","arquivos","done_when"] |
| globs | ["**/*.md"] |
/scope-guard - Contrato de Escopo Canônico
Regra de Ouro: Sem contrato de escopo = sem código
Quando Usar
OBRIGATÓRIO - antes de escrever QUALQUER código, sem exceção.
- Nova feature
- Bug fix
- Refatoração
- Documentação
- Qualquer tarefa nova
Propósito
- Bloquear over-engineering: Impedir que o modelo "melhore" o que não foi pedido
- Definir limites claros: Arquivos específicos que PODEM ser modificados
- Criar critérios objetivos: DONE_WHEN verificável, não subjetivo
- Prevent spec vaga: Contract força especificidade
Estrutura do Contrato
# CONTRATO DE ESCOPO - [Nome da Task]
## IDENTIFICAÇÃO
- **Task**: [nome resumido]
- **Tipo**: [feature|bugfix|refactor|docs]
- **Complexidade**: [baixa|média|alta]
- **Estimativa**: [tempo estimado]
## FAZER (Lista branca - SÓ o que está aqui é permitido)
1. [Funcionalidade específica 1]
2. [Funcionalidade específica 2]
3. [Funcionalidade específica N]
## NÃO FAZER (Lista negra - NUNCA fazer)
1. [Funcionalidade explícita que NÃO fazer]
2. [Funcionalidade explícita que NÃO fazer]
## ARQUIVOS (Lista branca - SÓ esses arquivos podem ser modificados)
- `caminho/arquivo1.php`
- `caminho/arquivo2.js`
- `database/migrations/YYYY_MM_DD_*.php`
## ARQUIVOS PROIBIDOS (NUNCA modificar)
- `app/Models/User.php` (exemplo)
- `config/auth.php` (exemplo)
## DEPENDÊNCIAS
- [Dependência externa 1]
- [Dependência externa 2]
## DONE_CRITERIA (Objetivos e verificáveis)
- [Critério 1 verificável]
- [Critério 2 verificável]
- [Critério 3 verificável]
## RISCO_IDENTIFICADO
- [Riscos conhecidos da task]
Processo de Execução
Step 1: Solicitar Contrato
Quando usuário faz uma solicitação:
Entendi. Antes de implementar, preciso do contrato de escopo.
# Contrato de Escopo - [resumo da task]
## FAZER
- [ Liste cada funcionalidade específica ]
## NÃO FAZER
- [ Liste o que NÃO fazer ]
## ARQUIVOS
- [ Liste arquivos que podem ser modificados ]
## DONE_CRITERIA
- [ Liste critérios verificáveis ]
Step 2: Aguardar Aprovação
- Se usuário não responder em 30s → prosseguir com melhor interpretação
- Se usuário completar contrato → VALIDAR antes de proceed
Step 3: Verificação Contínua
A cada 3-5 arquivos modificados:
CHECKPOINT ESCOPO:
- Modificados até agora: [lista]
- Dentro do ARQUIVOS? ✅/❌
- Dentro do FAZER? ✅/❌
- Algo do NÃO FAZER? ✅/❌
Step 4: Bloqueio
Se detected escape from scope:
🛑 ESCOPO VIOLADO!
- Detectado: [o que fugiu do escopo]
- Contrato: [ref]
- Ação: PARAR eperguntar se pode incluir
Anti-Patterns
| Errado | Certo |
|---|
| Começar a codar sem contrato | Contrato primeiro |
| "Vou melhorar X enquanto estou aqui" | NÃO FAZER bloqueia |
| Modificar arquivo não listado | ARQUIVOS é lista branca |
| "Done quando ficar bom" | Critérios objetivos |
Exemplo Completo
Input do Usuário:
"Adicionar autenticação OAuth2"
Output (Contrato):
# CONTRATO DE ESCOPO - Autenticação OAuth2
## IDENTIFICAÇÃO
- **Task**: Login Google OAuth2
- **Tipo**: feature
- **Complexidade**: média
- **Estimativa**: 2h
## FAZER
1. Implementar login via Google OAuth2
2. Criar tabela oauth_providers (se não existir)
3. Adicionar botão "Entrar com Google" na view de login
4. Salvar access_token e refresh_token
5. Criar rota callback
## NÃO FAZER
- NÃO implementar OAuth Facebook/GitHub
- NÃO criar registro manual (email/senha)
- NÃO modificar User table existente
- NÃO implementar 2FA
- NÃO criar login social para admin
## ARQUIVOS
- `app/Http/Controllers/Auth/OAuthController.php` (novo)
- `app/Models/OAuthProvider.php` (novo)
- `routes/auth.php`
- `resources/views/auth/login.blade.php`
- `config/services.php`
- `database/migrations/2026_03_31_create_oauth_providers_table.php` (novo)
## ARQUIVOS PROIBIDOS
- `app/Models/User.php`
- `app/Http/Controllers/Auth/LoginController.php`
## DONE_CRITERIA
- [ ] Usuário consegue fazer login via Google
- [ ] Token armazenado no banco com encryption
- [ ] Redirect para /dashboard após login
- [ ] Logout funciona (revoga token)
- [ ] Testes passando (min 3 novos)
- [ ] Pint passou
Débito que previne: D16 (Especificações vagas → over-engineering)
Referência: Perfil do Desenvolvedor - Sprint 1 /scope-guard
