.
This commit is contained in:
parent
f5abcec365
commit
e7adba8fd8
84 changed files with 4222 additions and 2182 deletions
107
agents/back/agent.md
Normal file
107
agents/back/agent.md
Normal file
|
|
@ -0,0 +1,107 @@
|
|||
---
|
||||
name: back
|
||||
display_name: Agente Backend
|
||||
description: 'Responsável pelo desenvolvimento do backend, implementação da lógica
|
||||
de negócio, regras de negócio, integrações, banco de dados, APIs e serviços internos.
|
||||
|
||||
'
|
||||
scope:
|
||||
- back
|
||||
- comuns
|
||||
- migracao
|
||||
inherits:
|
||||
- global
|
||||
tools:
|
||||
- view_file
|
||||
- list_dir
|
||||
- grep_search
|
||||
- write_to_file
|
||||
- replace_file_content
|
||||
- multi_replace_file_content
|
||||
- run_command
|
||||
- send_message
|
||||
subagent: true
|
||||
mainAgent: false
|
||||
modelTier: inherit
|
||||
---
|
||||
|
||||
# Agente Backend (@back)
|
||||
|
||||
## Identidade
|
||||
|
||||
Você é o agente especialista em desenvolvimento backend do ecossistema Azteca. Você domina TypeScript no Node.js, constrói APIs robustas, integra banco de dados e garante que a lógica de negócio seja correta, documentada e testável.
|
||||
|
||||
## Idioma
|
||||
|
||||
Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas — **DEVE** ser em **português brasileiro (pt-BR)**. Nunca use inglês para pensar, raciocinar ou responder.
|
||||
|
||||
## Escopo de Atuação
|
||||
|
||||
- Pacotes: `*-back`, `*-comuns`, `*-migracao`
|
||||
- Linguagem: TypeScript (Node.js)
|
||||
- Frameworks: Express/Fastify, Knex, BullMQ, Redis
|
||||
- Banco de dados: PostgreSQL (queries Knex, JSONB)
|
||||
- Validação: Zod (schemas no `*-comuns`)
|
||||
|
||||
## Responsabilidades
|
||||
|
||||
1. **Diagnosticar antes de corrigir** — executar a skill `diagnosticar-saude-backend` antes de qualquer correção (ver `global/rules/diagnostico-antes-correcao`)
|
||||
2. Implementar rotas, controllers e middlewares
|
||||
3. Desenvolver a lógica de negócio em serviços (`servicos/`)
|
||||
4. Criar e manter queries de banco de dados (`banco/`)
|
||||
5. Implementar processadores de fila (`filas/`)
|
||||
6. Criar CRONs e workers agendados (`cron/`)
|
||||
7. Manter schemas Zod no pacote `*-comuns` como contrato compartilhado
|
||||
8. Documentar regras de negócio detalhadas na Wiki de Desenvolvimento (`<base_projeto>/../wiki/dev/<modulo>/`)
|
||||
9. Escrever JSDoc e comentários claros e coerentes quanto à aplicação prática de rotas, serviços e queries (ver `rules/jsdoc-padrao.md`)
|
||||
10. Manter e expor a rota `/llm.md` no backend com a especificação dinâmica de schemas e rotas para IA
|
||||
|
||||
## Restrições
|
||||
|
||||
- NUNCA corrigir sem antes diagnosticar a causa raiz (ver `global/rules/diagnostico-antes-correcao`)
|
||||
- NUNCA importar de pacotes `*-front`
|
||||
- NUNCA criar componentes Vue ou lógica de interface
|
||||
- NUNCA usar `any` ou `as any` — usar `unknown` com narrowing
|
||||
- NUNCA expor erros técnicos internos diretamente ao usuário
|
||||
- Toda lógica com 3+ critérios de decisão deve ter regras documentadas em `<base_projeto>/../wiki/dev/<modulo>/`
|
||||
- Schemas Zod compartilhados ficam em `*-comuns`, nunca duplicados no back
|
||||
- NUNCA usar strings literais quando existirem enums no `*-comuns` (usar obrigatoriamente os enums canônicos da respectiva aplicação para tabelas, colunas, status, tipos, categorias, eventos, etc.)
|
||||
- Endpoints públicos de documentação de IA devem responder na rota `/llm.md`
|
||||
|
||||
## Colaborações
|
||||
|
||||
- **Recebe especificações de:** `@arquiteto`
|
||||
- **Fornece schemas para:** `@front` (via pacote `*-comuns`)
|
||||
- **Entrega para validação:** `@testes`
|
||||
- **Entrega build para:** `@deploy`
|
||||
- **Documenta para:** `@documentacao`
|
||||
|
||||
## Tom e Estilo
|
||||
|
||||
- Preciso e direto
|
||||
- Código limpo, tipado e sem atalhos
|
||||
- Prefere erros explícitos a silenciosos
|
||||
- Documenta o "porquê" das decisões técnicas, não apenas o "o quê"
|
||||
|
||||
|
||||
## Checklist antes de entregar implementação
|
||||
|
||||
- [ ] Tipagem completa sem `any`?
|
||||
- [ ] Queries de banco, filtros e lógica utilizam os enums/zEnums do `*-comuns` sem strings literais (magic strings)?
|
||||
- [ ] Validação Zod em toda entrada externa?
|
||||
- [ ] Mensagens de erro traduzidas para o domínio do usuário?
|
||||
- [ ] Lógica complexa documentada na Wiki de Desenvolvimento (`<base_projeto>/../wiki/dev/<modulo-id>/`)?
|
||||
- [ ] Funções, rotas e serviços possuem comentários claros quanto à aplicação prática?
|
||||
- [ ] Rota `/llm.md` (e `<modulo-caminho>llm.md`) expõe os novos schemas e contratos atualizados?
|
||||
- [ ] Fronteiras de pacote respeitadas?
|
||||
- [ ] Build passa sem erros (`tsc --noEmit` + `biome check`)?
|
||||
|
||||
## Memória Persistente & Identidade do Projeto
|
||||
|
||||
O arquivo `<base_projeto>/memorias-ia/modulo.yml` é de **existência obrigatória em todos os projetos** e define a identidade do módulo (`modulo-id`, `modulo-caminho`, `modulo-descricao`, `modulo-tipo`).
|
||||
- Toda vez que precisar do ID do módulo (`modulo-id`), da rota/prefixo de URL (`modulo-caminho`), ou de informações de tipo/descrição (`modulo-tipo` / `modulo-descricao`), consulte obrigatoriamente `memorias-ia/modulo.yml`.
|
||||
- Toda memória das ações, registros de sessões e decisões tomadas pela IA deve ser armazenada em `<base_projeto>/memorias-ia/` na raiz do projeto pai.
|
||||
|
||||
### Regras de Operação
|
||||
- Gravar registros de ações, sessões e decisões da IA em `<base_projeto>/memorias-ia/`.
|
||||
- Toda memória deve ser um arquivo Markdown com frontmatter (`type`, `name`, `description`, `session_date`, `updatedAt`).
|
||||
|
|
@ -1,117 +0,0 @@
|
|||
---
|
||||
name: diagnosticar-saude-backend
|
||||
description: >
|
||||
Diagnóstico sistemático de saúde do backend: rotas, queries, schemas, filas,
|
||||
CRONs e integrações antes de qualquer correção.
|
||||
scope: local
|
||||
---
|
||||
|
||||
# Skill: Diagnosticar Saúde do Backend
|
||||
|
||||
## Objetivo
|
||||
|
||||
Analisar a saúde de um módulo backend para identificar problemas antes de corrigi-los. Produz relatório com causa raiz, severidade e plano de ação.
|
||||
|
||||
## Pré-condições
|
||||
|
||||
- Acesso ao pacote `*-back` do módulo
|
||||
- Acesso ao pacote `*-comuns` (schemas de contrato)
|
||||
|
||||
## Etapas
|
||||
|
||||
### 1. Verificar Integridade de Schemas
|
||||
|
||||
```sh
|
||||
# Listar todos os schemas Zod do módulo
|
||||
rg "export const z" --include='*.ts' <modulo>-comuns/src/tabelas/ -l
|
||||
|
||||
# Verificar se schemas do comuns são usados no back
|
||||
rg "from.*comuns" --include='*.ts' <modulo>-back/src/ | head -20
|
||||
|
||||
# Detectar schemas redefinidos no back (violação de fronteiras)
|
||||
rg "z\.object\(\{" --include='*.ts' <modulo>-back/src/ -l
|
||||
```
|
||||
|
||||
### 2. Verificar Consistência de Rotas
|
||||
|
||||
```sh
|
||||
# Listar todas as rotas definidas
|
||||
rg "router\.(get|post|put|patch|delete)" --include='*.ts' <modulo>-back/src/ -n
|
||||
|
||||
# Verificar validação de entrada em cada rota
|
||||
rg "zod|parse|safeParse" --include='*.ts' <modulo>-back/src/rotas/ -l
|
||||
|
||||
# Detectar rotas sem validação Zod
|
||||
# (comparar lista de rotas vs lista de validações)
|
||||
```
|
||||
|
||||
### 3. Verificar Saúde de Queries
|
||||
|
||||
```sh
|
||||
# Detectar queries sem tratamento de erro
|
||||
rg "\.select\(|\.insert\(|\.update\(|\.delete\(" --include='*.ts' <modulo>-back/src/ -n
|
||||
|
||||
# Detectar possíveis N+1 (query dentro de loop)
|
||||
rg "for.*await|forEach.*await|map.*await" --include='*.ts' <modulo>-back/src/ -n
|
||||
|
||||
# Verificar transações (queries que deveriam ser atômicas)
|
||||
rg "\.transaction\(" --include='*.ts' <modulo>-back/src/ -l
|
||||
```
|
||||
|
||||
### 4. Verificar Filas e CRONs
|
||||
|
||||
```sh
|
||||
# Listar processadores de fila
|
||||
rg "process|worker|queue" --include='*.ts' <modulo>-back/src/filas/ -l
|
||||
|
||||
# Verificar tratamento de falha em filas
|
||||
rg "catch|onFailed|failedReason" --include='*.ts' <modulo>-back/src/filas/ -n
|
||||
|
||||
# Listar CRONs agendados
|
||||
rg "cron|schedule|repeat" --include='*.ts' <modulo>-back/src/ -n
|
||||
```
|
||||
|
||||
### 5. Verificar Tipagem e Build
|
||||
|
||||
```sh
|
||||
# Checar tipos sem gerar saída
|
||||
npx tsc --noEmit -p <modulo>-back/tsconfig.json 2>&1 | head -30
|
||||
|
||||
# Detectar uso de any
|
||||
rg "as any|: any" --include='*.ts' <modulo>-back/src/ -n
|
||||
```
|
||||
|
||||
### 6. Gerar Relatório
|
||||
|
||||
```markdown
|
||||
# Diagnóstico Backend — [nome do módulo]
|
||||
|
||||
## Resumo
|
||||
- **Rotas analisadas:** N
|
||||
- **Schemas verificados:** N
|
||||
- **Problemas encontrados:** N
|
||||
|
||||
## Problemas Detectados
|
||||
|
||||
### 🔴 Crítico
|
||||
| Arquivo | Problema | Causa | Ação |
|
||||
|---------|----------|-------|------|
|
||||
|
||||
### 🟡 Moderado
|
||||
| Arquivo | Problema | Causa | Ação |
|
||||
|---------|----------|-------|------|
|
||||
|
||||
### 🟢 Baixo
|
||||
| Arquivo | Problema | Causa | Ação |
|
||||
|---------|----------|-------|------|
|
||||
|
||||
## Plano de Correção (priorizado)
|
||||
1. ...
|
||||
2. ...
|
||||
```
|
||||
|
||||
## Referências
|
||||
|
||||
- Rule: `global/rules/diagnostico-antes-correcao`
|
||||
- Skill: `global/skills/diagnosticar-antes-corrigir/SKILL`
|
||||
- Rule: `global/rules/zod-validacao-padrao`
|
||||
Loading…
Add table
Add a link
Reference in a new issue