backend-silk

Habilidade de codificação. Padrões compartilhados de engenharia para projetos backend e API em Python (Flask, FastAPI, Django, FastMCP) e Node.js (Express). Abrange estrutura de projeto, camadas de rotas, helpers e serviços, regras de código baseadas em classes, tratamento de erros e códigos de status, casos extremos, logging, configuração com .env, autenticação e propriedade de dados, comunicação entre repositórios, higiene de git e testes. Use esta habilidade ao criar, estender, depurar, refatorar ou revisar qualquer backend Python, API REST, servidor MCP ou backend RAG.

O que é backend-silk?

O Backend Silk é uma habilidade de codificação que estabelece padrões compartilhados de engenharia para projetos backend e API, com foco em Python (Flask, FastAPI, Django, FastMCP) e Node.js (Express). Seu principal objetivo é evitar dois grandes fracassos: estrutura incorreta (lógica na camada errada, arquivos desnecessários) e superengenharia (abstrações antes de existir uma aplicação funcional). A habilidade define uma arquitetura clara de camadas (rotas -> helpers -> serviços -> banco de dados/sistemas externos), regras de código rígidas (funções classe-based, sem funções aninhadas ou com underscore), tratamento padronizado de erros com códigos de status específicos, logging centralizado, e configuração segura via .env. Ela é projetada para ser usada ao criar, estender, depurar, refatorar ou revisar qualquer backend, garantindo que as alterações não quebrem comportamentos existentes. A habilidade complementa outras habilidades 'spider' (como flask-spider, mcp-spider) e 'silk' (como sql-silk), que lidam com detalhes específicos de frameworks ou bancos de dados, enquanto esta foca nos princípios estruturais e de design.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/VivekShevale/eight-eye/tree/HEAD/skills/backend/backend-silk

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Backend Silk: padrões compartilhados de backend

Atue como um engenheiro sênior de backend Python que escreve código simples e de nível de produção. Os dois fracassos que esta habilidade existe para prevenir são estrutura errada (lógica na camada errada, arquivos que ninguém precisa) e superengenharia (abstrações antes de existir uma aplicação funcional). Um terceiro fracasso, mais silencioso, é igualmente custoso: uma alteração ou refatoração que silenciosamente remove um comportamento que funcionava.

Habilidades complementares

Nomenclatura: habilidades *-spider constroem um tipo específico de projeto; habilidades *-silk são os padrões compartilhados que cada spider tece. Esta habilidade contém os princípios compartilhados por todo backend. Carregue também as complementares correspondentes:

SituaçãoUse também
Projeto Flask / FastAPI / Djangoflask-spider / fastapi-spider / django-spider
Projeto Node.js / Expressnode-spider (as regras aqui se aplicam; exemplos de código Python são Python)
Servidor MCP ou cliente MCPmcp-spider
PostgreSQL, MySQL, SQLite (SQLAlchemy, Django ORM)sql-silk
MongoDBmongodb-silk
LLM, embeddings, armazenamento vetorial, RAGrag-spider

Habilidades de framework decidem a mecânica do framework; esta habilidade decide princípios. Se parecerem conflitar, siga a habilidade do framework para sintaxe e esta para estrutura.

Antes de alterar código

  1. Leia o código real primeiro. Verifique a estrutura de pastas, modelos, configuração e o arquivo que você está prestes a alterar. Nunca adivinhe um nome de campo, assinatura de função, nome de arquivo ou caminho de importação; leia-o. (Um date adivinhado em vez do real expense_date já quebrou schema, helper e resposta de uma só vez.) Quando não tiver certeza de como uma biblioteca instalada funciona, verifique sua API real em vez de assumir.
  2. Decida as rotas primeiro. Para uma funcionalidade, liste cada endpoint (método, caminho, requisição, resposta, códigos de status, autenticação) antes de implementar.
  3. Escopo vem do requisito. Construa o que a declaração do problema precisa. Endpoints extras, análises, caching, limitação de taxa, reclassificação, rastreamento de custos, endpoints de download/pesquisa que ninguém pediu: mencione em uma linha como "possível depois", não construa.
  4. Preserve o comportamento funcional. Ao reescrever uma função, liste o que ela faz agora (filtros, paginação, validação, logging, campos de resposta) e certifique-se de que a nova versão ainda faz tudo isso.

Camadas

routes -> helpers -> services -> database / sistemas externos
            |            |
          utils        utils
PastaÉ dona deNão pode conter
routes/ (blueprints Flask, routers FastAPI, views.py + urls.py do Django, tools/ do MCP)URL, método, decorador/dependência de autenticação, código de status, modelo de resposta, uma chamada para um helperLógica de negócio, consultas, código de validação, try/except, logging
helpers/Lógica de negócio para uma funcionalidade, como um controlador: validação além do schema, verificações de propriedade, consultas e filtros específicos da funcionalidade, orquestração de serviços, mapeamento de falhas esperadas para erros HTTP, construção da respostaAbrir/fechar sessões de BD, commit/rollback, criar clientes LLM ou SDK
services/Um sistema externo ou peça de infraestrutura cada: conexão de BD e CRUD genérico (db_service.py), LLM, embeddings, armazenamento vetorial, PDF, email, API de outro repositórioRegras de negócio específicas da funcionalidade, conhecimento HTTP (HTTPException, códigos de status), chamadas para helpers
utils/Código baseado em classes reutilizado por vários módulos: LogUtils, ErrorHandlers, AuthUtils, conversores purosCódigo usado por apenas uma funcionalidade, chamadas de API externa
schemas/Modelos de requisição/resposta Pydantic (Django: serializers.py)Modelos de BD
models/Modelos de persistênciaLógica de negócio
prompts/Templates de prompt como código (apenas quando um LLM é usado)Prompts em .env
config.pyUm objeto de configurações carregado de .envLógica

Regras que decorrem da tabela:

  • A direção é única. Rotas chamam helpers, helpers chamam serviços. Um serviço nunca chama um helper; um utilitário nunca chama um helper.
  • Divisão do banco de dados. O helper constrói consultas de funcionalidade (filtros, pesquisa, propriedade); o serviço de BD as executa e é dono da conexão, sessão, commit e rollback. Detalhes em sql-silk / mongodb-silk. Com Django, o ORM é a camada de BD, então não há db_service.
  • Sem camadas de passagem. Se um helper apenas encaminha para um serviço, delete o helper e chame o serviço. Cada arquivo deve merecer seu lugar.
  • Utils vs helpers. Usado em muitos lugares → utils/. Usado por uma funcionalidade → o helper dessa funcionalidade.
  • Crie pastas e arquivos quando uma necessidade real aparecer, não antecipadamente. Uma função nunca justifica uma nova pasta (errors/, exceptions.py, core/); adicione-a à classe existente que se encaixa.
  • Nomenclatura: <dominio>_routes.py (contendo <dominio>_router, ou <dominio>_bp no Flask), <dominio>_helper.py → XHelper, <dominio>_service.py → XService, <dominio>_schema.py, <dominio>_utils.py → XUtils, <nome>_prompt.py → NAME_PROMPT. Um nome de classe sempre corresponde à sua pasta (um class ExpenseService dentro de helpers/ está errado).

Funções completas das pastas e árvores iniciais: references/architecture.md.

Regras de código

  1. Módulos baseados em classes. Helpers, serviços e utilitários são classes. Use @staticmethod/@classmethod para código sem estado e instâncias apenas quando a classe contém uma dependência (ex.: uma sessão ou cliente injetado). Arquivos de rota e urls.py do Django permanecem no nível do módulo. Não force herança, classes base abstratas ou interfaces sem duas implementações reais.
  2. Funções ficam em torno de 40–50 linhas. Divida uma função longa em métodos significativos da mesma classe (ex.: list_expenses → parse_filter_parameters + apply_expense_filters), não em blocos arbitrários.
  3. Nenhum nome de função começando com _. Nenhuma função definida dentro de funções. Registre handlers com chamadas explícitas como app.add_exception_handler(...) em vez de funções decoradas aninhadas.
  4. Todos os imports no topo do arquivo, agrupados stdlib → terceiros → app.*. Corrija imports circulares movendo o código para o módulo correto, não importando dentro de funções. A única exceção aceita são imports de blueprint Flask dentro de create_app().
  5. Use bibliotecas estabelecidas em vez de lógica escrita manualmente: password-validator, email-validator/EmailStr, PyJWT, bcrypt, loaders e splitters do LangChain, httpx.
  6. Valide uma vez. Se o schema Pydantic já impõe uma regra, não a verifique novamente no helper.
  7. Não compute a mesma coisa duas vezes em uma requisição e falhe rápido. Faça verificações baratas antes das caras (verificação de email duplicado antes de hashing com bcrypt).
  8. Sem configuração codificada: URLs, nomes de modelo, limites, top_k, temperatura e segredos vêm de config.py.
  9. Sem código morto: funções não utilizadas, imports não utilizados, arquivos placeholder vazios e sobras de startapp são removidos.
  10. Type hints e um docstring de uma linha em toda classe e método público. Comentários apenas onde a razão não é óbvia.
  11. Nunca engula exceções. Capture exceções específicas onde você pode agir sobre elas; deixe o resto alcançar o handler global.

Verificação de superengenharia

Antes de adicionar um arquivo, classe, camada, dependência ou padrão, pergunte: a necessidade atual requer isso, e algo existente já faz isso? Todos estes foram construídos e depois removidos:

  • pydantic-settings ou frameworks de validação antes da aplicação executar (uma dataclass frozen de configuração é suficiente)
  • um novo módulo de exceção ou classe para um erro
  • helpers que apenas chamam um serviço
  • pares de chaves RS256 entre dois serviços que você possui (um segredo compartilhado HS256 é suficiente)
  • valores derivados armazenados (total_tokens quando entrada + saída existem)
  • duas coleções ou tabelas onde uma com uma lista embutida funciona
  • prompts longos e descrições longas de ferramentas

Quando vários designs funcionam, escolha o mais simples que ainda seja seguro para produção.

Esquemas de requisição e resposta (resumo)

  • Cada endpoint valida seu corpo e parâmetros de consulta com um schema de requisição que rejeita campos desconhecidos e de propriedade do servidor; o código após validação usa apenas o objeto validado.
  • Toda resposta bem-sucedida é construída a partir de um schema de resposta: o recurso em si (XResponse), uma lista {"items", "page", "page_size", "total", "total_pages"}, ou um schema de resultado de ação (TokenResponse). Sem envelope, sem literais de objeto montados no handler.
  • Códigos de status carregam sucesso e falha: 200 leitura/atualização, 201 criação, 204 exclusão sem corpo, erros com ErrorResponse. Nunca uma falha com 200.

Contrato completo e onde os schemas vivem por framework: references/api-design.md.

Erros (resumo)

  • Toda resposta de erro tem uma forma, de assets/common_schema.py: {"status": "error", "message": "...", "details": [{"field": "...", "message": "..."}]} (details apenas quando há erros de campo)
  • Serviços levantam exceções simples ou de biblioteca; helpers levantam erros HTTP para casos esperados; uma classe ErrorHandlers em utils/error_handlers.py mapeia erros de dependência e captura todo o resto como 500.
  • Códigos de status: 400 entrada inválida, 401 não autenticado, 404 ausente ou registro de outro usuário, 409 duplicata, 413 muito grande, 422 validação de schema, 424 dependência própria fora do ar (banco de dados, armazenamento vetorial), 429 limite de taxa upstream, 502 upstream retornou um erro, 503 outro serviço inacessível, 504 timeout upstream, 500 inesperado. Nunca 200 para uma falha.
  • Usuários veem uma mensagem segura curta, nunca um traceback, host, string de conexão ou chave.

Lista de verificação de casos extremos e padrões de handler: references/errors-and-edge-cases.md. Chamadas entre repositórios: references/cross-repo-communication.md.

Logging (resumo)

Uma classe LogUtils (assets/log_utils.py) configurada uma vez na inicialização a partir de LOG_LEVEL e LOG_TO_FILE em .env; todos os outros módulos apenas fazem logger = LogUtils.get_logger(__name__). Formato %(asctime)s | %(levelname)s | %(name)s | %(message)s, mensagens como Evento | chave=valor, sem segredos ou dados pessoais, cada falha registrada uma vez. Detalhes: references/logging.md.

Configuração e segurança (resumo)

  • config.py com uma dataclass frozen carregada de .env (assets/config.py); .env.example commitado com placeholders e comentários (assets/env.example), .env nunca commitado (assets/gitignore).
  • Senhas: política password-validator apenas no registro, hashing bcrypt/werkzeug, "Email ou senha inválidos." genérico no login.
  • JWT: segredo de .env, id de usuário obtido apenas do token verificado, nunca do corpo da requisição.
  • Toda consulta é limitada ao usuário atual; registros de outros usuários retornam 404.

Detalhes: references/security.md. Convenções de API (métodos, paginação, filtragem, parâmetros de pesquisa): references/api-design.md.

Git e testes (resumo)

  • Nunca commitado: .env, chaves, credenciais, uploads, dados vetoriais, bancos de dados locais, logs, ambientes virtuais, relatórios gerados. Migrações são commitadas com a alteração de modelo que as produziu.
  • Mensagens de commit seguem Conventional Commits (feat:, fix:, refactor:, chore:, test:, docs:, perf:), uma preocupação por commit, um commit por repositório.
  • Testes cobrem caminhos críticos: autenticação, propriedade entre usuários, validação, respostas de erro, falhas de dependência (simuladas). Serviços externos (LLMs, outros repositórios) são simulados.
  • Avaliações (conjuntos de dados dourados, scripts de avaliação, relatórios) existem apenas quando explicitamente solicitadas; veja rag-spider / mcp-spider.

Detalhes: references/git-and-testing.md.

Lista de verificação de código

  • Camadas respeitadas; nenhum arquivo de passagem; nomes de classe correspondem às pastas
  • Sem funções com underscore inicial ou aninhadas; imports no topo; funções ≤ ~50 linhas
  • Comportamento existente preservado (filtros, paginação, validação, campos de resposta)
  • Cada endpoint tem um schema de requisição e um schema de resposta; sem objetos de resposta ad-hoc
  • Casos extremos de references/errors-and-edge-cases.md tratados com códigos de status corretos
  • Novas configurações em config.py e .env.example; nada codificado; sem segredos no código ou logs
  • Logging adicionado onde se encaixa, no nível correto
  • Nenhum import não utilizado ou código morto deixado para trás

Arquivos de referência (leia apenas quando necessário)

ArquivoLeia quando
references/architecture.mdCriando um projeto, adicionando uma pasta de funcionalidade, sem certeza de onde o código pertence
references/errors-and-edge-cases.mdEscrevendo endpoints, handlers de erro, ou revisando caminhos de falha
references/cross-repo-communication.mdUm serviço chama outro repositório, servidor MCP ou API externa
references/logging.mdConfigurando ou revisando logging
references/security.mdAutenticação, senhas, JWT, uploads, segredos, CORS
references/api-design.mdProjetando endpoints, schemas de requisição/resposta, paginação, filtros, pesquisa
references/git-and-testing.mdCommits, descrições de PR, o que nunca é commitado, testes, abordagem de depuração

Arquivos de ativos (copie para o projeto e adapte)

Copie templates seletivamente: mantenha apenas as partes que este projeto usa agora (seções de .gitignore, chaves de .env.example, campos de configuração). Linhas restantes para funcionalidades que o projeto não tem são poluição e enganam o próximo leitor.

ArquivoTorna-se
assets/log_utils.pyapp/utils/log_utils.py
assets/common_schema.pyapp/schemas/common_schema.py
assets/config.pyapp/config.py
assets/env.example.env.example
assets/gitignore.gitignore (a seção "Sempre" mais apenas as seções marcadas que se aplicam)

Habilidades Relacionadas