¿Qué hace Backend Silk: estándares compartidos de backend?
Actúa como un ingeniero senior de backend en Python que escribe código simple y de producción. Los dos fallos que este skill existe para prevenir son estructura incorrecta (lógica en la capa equivocada, archivos que nadie necesita) y sobre-ingeniería (abstracciones antes de tener una app funcionando). Un tercer fallo, más silencioso, es igual de costoso: un cambio o refactorización que elimina silenciosamente un comportamiento que solía funcionar.
Skills complementarios
Nomenclatura: los skills *-spider construyen un tipo específico de proyecto; los skills *-silk son los estándares compartidos que cada spider teje. Este skill contiene los principios compartidos por todos los backends. Carga también los complementos correspondientes:
| Situación | Usar también |
|---|---|
| Proyecto Flask / FastAPI / Django | flask-spider / fastapi-spider / django-spider |
| Proyecto Node.js / Express | node-spider (las reglas aquí aplican; los ejemplos de código son Python) |
| Servidor MCP o cliente MCP | mcp-spider |
| PostgreSQL, MySQL, SQLite (SQLAlchemy, Django ORM) | sql-silk |
| MongoDB | mongodb-silk |
| LLM, embeddings, vector store, RAG | rag-spider |
Los skills de framework deciden la mecánica del framework; este skill decide los principios. Si parecen conflictivos, sigue el skill de framework para la sintaxis y este skill para la estructura.
Antes de modificar código
- Lee el código real primero. Revisa la estructura de carpetas, modelos, configuración y el archivo que estás a punto de modificar. Nunca adivines un nombre de campo, firma de función, nombre de archivo o ruta de importación; léelo. (Una
dateadivinada en lugar de la realexpense_daterompió esquema, helper y respuesta de una sola vez.) Cuando no estés seguro de cómo funciona una librería instalada, consulta su API real en lugar de asumir. - Decide las rutas primero. Para una funcionalidad, enumera cada endpoint (método, ruta, request, response, códigos de estado, autenticación) antes de implementar.
- El alcance proviene del requisito. Construye lo que la declaración del problema necesita. Endpoints extra, analíticas, caché, limitación de tasa, re-ranking, seguimiento de costos, endpoints de descarga/búsqueda que nadie pidió: menciónalos en una línea como "posible más adelante", no los construyas.
- Preserva el comportamiento funcional. Al reescribir una función, enumera lo que hace ahora (filtros, paginación, validación, logging, campos de respuesta) y asegúrate de que la nueva versión todavía lo haga todo.
Capas
rutas -> ayudantes -> servicios -> base de datos / sistemas externos
| |
utilidades utilidades
| Carpeta | Posee | No debe contener |
|---|---|---|
routes/ (blueprints de Flask, routers de FastAPI, views.py + urls.py de Django, tools/ de MCP) | URL, método, dependencia/decorador de autenticación, código de estado, modelo de respuesta, una llamada a un helper | Lógica de negocio, consultas, código de validación, try/except, logging |
helpers/ | Lógica de negocio para una funcionalidad, como un controlador: validación más allá del esquema, comprobaciones de propiedad, consultas y filtros específicos de la funcionalidad, orquestación de servicios, mapeo de fallos esperados a errores HTTP, construcción de la respuesta | Abrir/cerrar sesiones de BD, commit/rollback, crear clientes LLM o SDK |
services/ | Un sistema externo o pieza de infraestructura cada uno: conexión a BD y CRUD genérico (db_service.py), LLM, embeddings, vector store, PDF, email, API de otro repositorio | Reglas de negocio específicas de la funcionalidad, conocimiento HTTP (HTTPException, códigos de estado), llamadas a helpers |
utils/ | Código basado en clases reutilizado por varios módulos: LogUtils, ErrorHandlers, AuthUtils, convertidores puros | Código usado por una sola funcionalidad, llamadas a APIs externas |
schemas/ | Modelos de request/response de Pydantic (Django: serializers.py) | Modelos de BD |
models/ | Modelos de persistencia | Lógica de negocio |
prompts/ | Plantillas de prompts como código (solo cuando se usa un LLM) | Prompts en .env |
config.py | Un objeto de configuración cargado desde .env | Lógica |
Reglas que se derivan de la tabla:
- La dirección es unidireccional. Las rutas llaman a helpers, los helpers llaman a servicios. Un servicio nunca llama a un helper; una utilidad nunca llama a un helper.
- División de base de datos. El helper construye consultas de funcionalidad (filtros, búsqueda, propiedad); el servicio de BD las ejecuta y posee la conexión, sesión, commit y rollback. Detalles en
sql-silk/mongodb-silk. Con Django, el ORM es la capa de BD, por lo que no haydb_service. - Sin capas de paso directo. Si un helper solo reenvía a un servicio, elimina el helper y llama al servicio. Cada archivo debe ganarse su lugar.
- Utils vs helpers. Usado en muchos lugares →
utils/. Usado por una funcionalidad → el helper de esa funcionalidad. - Crea carpetas y archivos cuando aparezca una necesidad real, no por adelantado. Una función nunca justifica una nueva carpeta (
errors/,exceptions.py,core/); agrégala a la clase existente que corresponda. - Nomenclatura:
<dominio>_routes.py(que contiene<dominio>_router, o<dominio>_bpen Flask),<dominio>_helper.py→XHelper,<dominio>_service.py→XService,<dominio>_schema.py,<dominio>_utils.py→XUtils,<nombre>_prompt.py→NOMBRE_PROMPT. El nombre de una clase siempre coincide con su carpeta (unaclass ExpenseServicedentro dehelpers/es incorrecto).
Roles completos de carpetas y árboles iniciales: references/architecture.md.
Reglas de código
- Módulos basados en clases. Los helpers, servicios y utilidades son clases. Usa
@staticmethod/@classmethodpara código sin estado e instancias solo cuando la clase contenga una dependencia (por ejemplo, una sesión o cliente inyectado). Los archivos de rutas yurls.pyde Django se mantienen a nivel de módulo. No fuerces herencia, clases base abstractas o interfaces sin dos implementaciones reales. - Las funciones se mantienen alrededor de 40–50 líneas. Divide una función larga en métodos significativos de la misma clase (por ejemplo,
list_expenses→parse_filter_parameters+apply_expense_filters), no en fragmentos arbitrarios. - Ningún nombre de función que comience con
_. Ninguna función definida dentro de otra función. Registra manejadores con llamadas explícitas comoapp.add_exception_handler(...)en lugar de funciones decoradas anidadas. - Todas las importaciones al principio del archivo, agrupadas stdlib → terceros →
app.*. Corrige importaciones circulares moviendo el código al módulo correcto, no importando dentro de funciones. La única excepción aceptada son las importaciones de blueprints de Flask dentro decreate_app(). - Usa librerías establecidas en lugar de lógica escrita a mano:
password-validator,email-validator/EmailStr, PyJWT, bcrypt, cargadores y divisores de LangChain,httpx. - Valida una sola vez. Si el esquema de Pydantic ya impone una regla, no la vuelvas a comprobar en el helper.
- No calcules lo mismo dos veces en una solicitud, y falla rápido. Realiza comprobaciones baratas antes que las costosas (comprobación de email duplicado antes del hash bcrypt).
- Sin configuración hardcodeada: URLs, nombres de modelo, límites, top_k, temperatura y secretos provienen de
config.py. - Sin código muerto: funciones no utilizadas, importaciones no utilizadas, archivos placeholder vacíos y restos de
startappse eliminan. - Type hints y un docstring de una línea en cada clase y método público. Comentarios solo donde la razón no sea obvia.
- Nunca tragues excepciones. Captura excepciones específicas donde puedas actuar sobre ellas; deja que el resto llegue al manejador global.
Verificación de sobre-ingeniería
Antes de agregar un archivo, clase, capa, dependencia o patrón, pregúntate: ¿el requisito actual lo necesita, y ya existe algo que lo haga? Todo esto se construyó y luego se eliminó:
- pydantic-settings o frameworks de validación antes de que la app se ejecute (una dataclass congelada de configuración es suficiente)
- un nuevo módulo o clase de excepción para un solo error
- helpers que solo llaman a un servicio
- pares de claves RS256 entre dos servicios que posees (un secreto compartido HS256 es suficiente)
- valores derivados almacenados (
total_tokenscuando existen input + output) - dos colecciones o tablas cuando una con una lista incrustada funciona
- prompts largos y descripciones largas de herramientas
Cuando varios diseños funcionen, elige el más simple que siga siendo seguro para producción.
Esquemas de solicitud y respuesta (resumen)
- Cada endpoint valida su cuerpo y parámetros de consulta con un esquema de solicitud que rechaza campos desconocidos y campos propiedad del servidor; el código posterior a la validación usa solo el objeto validado.
- Cada respuesta exitosa se construye a partir de un esquema de respuesta: el recurso en sí (
XResponse), una lista{"items", "page", "page_size", "total", "total_pages"}, o un esquema de resultado de acción (TokenResponse). Sin envoltorio, sin literales de objeto ensamblados en el manejador. - Los códigos de estado indican éxito y fracaso: 200 lectura/actualización, 201 creación, 204 eliminación sin cuerpo, errores con
ErrorResponse. Nunca un fracaso con 200.
Contrato completo y dónde viven los esquemas por framework: references/api-design.md.
Errores (resumen)
- Cada respuesta de error tiene una forma, desde
assets/common_schema.py:{"status": "error", "message": "...", "details": [{"field": "...", "message": "..."}]}(detailssolo cuando hay errores de campo) - Los servicios lanzan excepciones simples o de librería; los helpers lanzan errores HTTP para casos esperados; una clase
ErrorHandlersenutils/error_handlers.pymapea errores de dependencia y captura todo lo demás como 500. - Códigos de estado: 400 entrada incorrecta, 401 no autenticado, 404 faltante o registro de otro usuario, 409 duplicado, 413 demasiado grande, 422 validación de esquema, 424 dependencia propia caída (base de datos, vector store), 429 límite de tasa upstream, 502 upstream devolvió un error, 503 otro servicio inalcanzable, 504 timeout upstream, 500 inesperado. Nunca 200 para un fracaso.
- Los usuarios ven un mensaje corto y seguro, nunca un traceback, host, cadena de conexión o clave.
Lista de verificación de casos extremos y patrones de manejador: references/errors-and-edge-cases.md. Llamadas entre repositorios: references/cross-repo-communication.md.
Logging (resumen)
Una clase LogUtils (assets/log_utils.py) configurada una vez al inicio desde LOG_LEVEL y LOG_TO_FILE en .env; cada otro módulo solo hace logger = LogUtils.get_logger(__name__). Formato %(asctime)s | %(levelname)s | %(name)s | %(message)s, mensajes como Evento | clave=valor, sin secretos ni datos personales, cada fracaso registrado una vez. Detalles: references/logging.md.
Configuración y seguridad (resumen)
config.pycon una dataclass congelada cargada desde.env(assets/config.py);.env.exampleconfirmado con placeholders y comentarios (assets/env.example),.envnunca confirmado (assets/gitignore).- Contraseñas: política de
password-validatorsolo en el registro, hashing bcrypt/werkzeug, mensaje genérico "Email o contraseña inválidos." en el inicio de sesión. - JWT: secreto de
.env, id de usuario tomado solo del token verificado, nunca del cuerpo de la solicitud. - Cada consulta está limitada al usuario actual; los registros de otros usuarios devuelven 404.
Detalles: references/security.md. Convenciones de API (métodos, paginación, filtrado, parámetros de búsqueda): references/api-design.md.
Git y pruebas (resumen)
- Nunca confirmado:
.env, claves, credenciales, subidas, datos vectoriales, bases de datos locales, logs, entornos virtuales, informes generados. Las migraciones se confirman con el cambio de modelo que las produjo. - Los mensajes de commit siguen Conventional Commits (
feat:,fix:,refactor:,chore:,test:,docs:,perf:), un asunto por commit, un commit por repositorio. - Las pruebas cubren caminos críticos: autenticación, propiedad entre usuarios, validación, respuestas de error, fallos de dependencia (simulados). Los servicios externos (LLMs, otros repos) se simulan.
- Evaluaciones (golden datasets, scripts de evaluación, informes) solo existen cuando se solicitan explícitamente; ver
rag-spider/mcp-spider.
Detalles: references/git-and-testing.md.
Lista de verificación de código
- Capas respetadas; ningún archivo de paso directo; nombres de clases coinciden con carpetas
- Sin funciones con guión bajo al inicio o anidadas; importaciones al principio; funciones ≤ ~50 líneas
- Comportamiento existente preservado (filtros, paginación, validación, campos de respuesta)
- Cada endpoint tiene un esquema de solicitud y un esquema de respuesta; sin objetos de respuesta ad-hoc
- Casos extremos de
references/errors-and-edge-cases.mdmanejados con códigos de estado correctos - Nuevas configuraciones en
config.pyy.env.example; nada hardcodeado; sin secretos en código o logs - Logging agregado donde corresponde, en el nivel correcto
- Sin importaciones no utilizadas ni código muerto dejado atrás
Archivos de referencia (leer solo cuando sea necesario)
| Archivo | Leer cuando |
|---|---|
references/architecture.md | Crear un proyecto, agregar una carpeta de funcionalidad, no estar seguro de dónde pertenece el código |
references/errors-and-edge-cases.md | Escribir endpoints, manejadores de errores, o revisar caminos de fallo |
references/cross-repo-communication.md | Un servicio llama a otro repositorio, servidor MCP, o API externa |
references/logging.md | Configurar o revisar logging |
references/security.md | Autenticación, contraseñas, JWT, subidas, secretos, CORS |
references/api-design.md | Diseñar endpoints, esquemas de solicitud/respuesta, paginación, filtros, búsqueda |
references/git-and-testing.md | Commits, descripciones de PR, qué nunca se confirma, pruebas, enfoque de depuración |
Archivos de activos (copiar al proyecto y adaptar)
Copia las plantillas de forma selectiva: conserva solo las partes que este proyecto usa ahora (secciones de .gitignore, claves de .env.example, campos de configuración). Las líneas sobrantes para funcionalidades que el proyecto no tiene son basura y confunden al próximo lector.
| Archivo | Se convierte en |
|---|---|
assets/log_utils.py | app/utils/log_utils.py |
assets/common_schema.py | app/schemas/common_schema.py |
assets/config.py | app/config.py |
assets/env.example | .env.example |
assets/gitignore | .gitignore (la sección "Siempre" más solo las secciones marcadas que apliquen) |