150 lines
6.7 KiB
Text
150 lines
6.7 KiB
Text
# arquivo: .agent
|
||
# Agente de desenvolvimento para o projeto e-li.nps
|
||
#
|
||
# Projeto:
|
||
# Widget NPS embutível via 1 arquivo JS + API em Go.
|
||
# Foco em robustez, segurança, tipagem consistente, observabilidade
|
||
# e operação simples em ambientes reais (Docker / Proxy / Produção).
|
||
|
||
agent_name: "quero_nps"
|
||
|
||
# -------------------------------------------------------------------
|
||
# Descrição do projeto (fonte de verdade)
|
||
# -------------------------------------------------------------------
|
||
project_description:
|
||
- "Widget NPS carregado via 1 arquivo JavaScript (e-li.nps.js)."
|
||
- "API HTTP escrita em Go."
|
||
- "PostgreSQL como banco de dados."
|
||
- "Painel administrativo opcional protegido por senha."
|
||
- "Uso por aplicações externas via <script>."
|
||
- "Fail-closed: se a API falhar, o widget não abre."
|
||
- "CORS liberado para uso amplo."
|
||
|
||
# -------------------------------------------------------------------
|
||
# Stack
|
||
# -------------------------------------------------------------------
|
||
project_stack:
|
||
backend: "Go 1.22+"
|
||
database: "PostgreSQL 14+"
|
||
widget: "JavaScript puro (arquivo único)"
|
||
frontend_internal:
|
||
- "HTML server-side"
|
||
- "HTMX (opcional, apenas se já estiver presente no painel)"
|
||
optional_logic_layer:
|
||
- "Go → WebAssembly (WASM), apenas se adotado explicitamente no projeto"
|
||
|
||
# -------------------------------------------------------------------
|
||
# Regras gerais
|
||
# -------------------------------------------------------------------
|
||
rules:
|
||
- "Respeitar fielmente o comportamento descrito no README.md."
|
||
- "Não alterar contratos públicos do widget sem versionamento."
|
||
- "Evitar mudanças que quebrem widgets já embedados em clientes."
|
||
- "Mudanças que impactem desenvolvedores OU usuários DEVEM ser documentadas."
|
||
- "Código deve ser previsível, explícito e fácil de auditar."
|
||
|
||
# -------------------------------------------------------------------
|
||
# Linguagem, nomes e comentários
|
||
# -------------------------------------------------------------------
|
||
naming_and_language:
|
||
- "Nomes de variáveis, funções e arquivos preferencialmente em português."
|
||
- "Nomes orientados ao domínio NPS (ex: `registrarPedido`, `finalizarResposta`)."
|
||
- "Comentários SEMPRE em português."
|
||
- "Comentários devem explicar regras de negócio e decisões técnicas."
|
||
|
||
# -------------------------------------------------------------------
|
||
# Contratos e tipagens
|
||
# -------------------------------------------------------------------
|
||
typing_and_contracts:
|
||
- "Contratos de API devem ser explícitos e estáveis."
|
||
- "Campos-chave das regras de exibição: produto + inquilino_codigo + usuario_codigo."
|
||
- "Normalizações técnicas NÃO alteram valores exibidos ao usuário."
|
||
- "Tipagens JS/TS são auxiliares e não substituem validação no backend."
|
||
- "Validação SEMPRE no servidor."
|
||
|
||
# -------------------------------------------------------------------
|
||
# Widget JavaScript
|
||
# -------------------------------------------------------------------
|
||
widget_policy:
|
||
- "Widget deve ser carregado via um único <script>."
|
||
- "Nenhuma dependência externa no cliente."
|
||
- "Cache controlado exclusivamente pelo servidor via ETag."
|
||
- "Browser sempre revalida o JS."
|
||
- "Se a API falhar, o widget NÃO deve abrir (fail-closed)."
|
||
|
||
# -------------------------------------------------------------------
|
||
# Backend Go
|
||
# -------------------------------------------------------------------
|
||
backend_policy:
|
||
- "Servidor Go é a autoridade de regras e persistência."
|
||
- "Tabelas criadas automaticamente por produto: nps_{produto}."
|
||
- "Normalização de produto SOMENTE para uso técnico."
|
||
- "Nunca usar dados não normalizados em SQL."
|
||
- "Painel só habilita se SENHA_PAINEL estiver definida."
|
||
|
||
# -------------------------------------------------------------------
|
||
# Segurança: prevenção de SQL Injection (OBRIGATÓRIO)
|
||
# -------------------------------------------------------------------
|
||
sql_injection_prevention:
|
||
- "NUNCA concatenar SQL com entrada do usuário."
|
||
- "Usar queries parametrizadas SEMPRE."
|
||
- "Identificadores dinâmicos SOMENTE via normalização + regex + allowlist."
|
||
- "Regex obrigatória: ^[a-z_][a-z0-9_]*$."
|
||
- "ORDER BY dinâmico apenas com colunas previamente definidas."
|
||
- "Toda decisão dinâmica de SQL deve ser comentada."
|
||
|
||
# -------------------------------------------------------------------
|
||
# Observabilidade e logs (OBRIGATÓRIO)
|
||
# -------------------------------------------------------------------
|
||
logging_policy:
|
||
- "Registrar logs relevantes em toda a aplicação."
|
||
- "Logar: inicialização, rotas, chamadas de API, banco e erros."
|
||
- "Registrar tempo de execução das requisições."
|
||
- "Incluir IP real do usuário quando disponível."
|
||
- "Evitar log excessivo ou redundante."
|
||
|
||
# -------------------------------------------------------------------
|
||
# Proteção de segredos nos logs (CRÍTICO)
|
||
# -------------------------------------------------------------------
|
||
secrets_policy:
|
||
- "NUNCA logar senhas, tokens, cookies, Authorization, secrets ou DSN."
|
||
- "Campos sensíveis devem ser omitidos ou mascarados."
|
||
- "Na dúvida, NÃO LOGAR."
|
||
- "Usar '[REDACTED]' quando necessário."
|
||
|
||
# -------------------------------------------------------------------
|
||
# Proxy e IP real
|
||
# -------------------------------------------------------------------
|
||
proxy_policy:
|
||
- "Respeitar X-Forwarded-For e X-Real-IP."
|
||
- "Uso de middleware RealIP é obrigatório."
|
||
- "Persistir IP real para auditoria."
|
||
|
||
# -------------------------------------------------------------------
|
||
# README.md — regra OBRIGATÓRIA
|
||
# -------------------------------------------------------------------
|
||
readme_policy:
|
||
- "O README.md é a fonte de verdade operacional do projeto."
|
||
- "SE a mudança for IMPORTANTE para o DESENVOLVEDOR, atualizar o README.md."
|
||
- "SE a mudança for IMPORTANTE para o USUÁRIO, atualizar o README.md."
|
||
- "Considera-se mudança importante:"
|
||
- "– alteração de API, contrato ou payload"
|
||
- "– mudança no widget ou forma de embed"
|
||
- "– cache, ETag ou comportamento de atualização"
|
||
- "– variáveis de ambiente"
|
||
- "– segurança, CORS, autenticação ou painel"
|
||
- "– forma de rodar, build ou deploy"
|
||
- "O README deve explicar o impacto da mudança e como usar o novo comportamento."
|
||
|
||
# -------------------------------------------------------------------
|
||
# Checklist final
|
||
# -------------------------------------------------------------------
|
||
checklist:
|
||
- "[ ] Compatível com widgets já publicados"
|
||
- "[ ] SQL 100% parametrizado"
|
||
- "[ ] Identificadores normalizados e validados"
|
||
- "[ ] Logs relevantes presentes"
|
||
- "[ ] Nenhum segredo em logs"
|
||
- "[ ] Cache do JS controlado por ETag"
|
||
- "[ ] README.md atualizado se a mudança impacta dev ou usuário"
|
||
- "[ ] Fluxo principal testado manualmente"
|