Communitygithub.com

renatoxm/leanagentkit

Una alternativa más ligera a GitHub Spec Kit

¿Qué es leanagentkit?

Este skill proporciona un marco estructurado, basado en la Arquitectura Limpia, para diseñar sistemas de software donde las reglas de negocio permanezcan independientes de frameworks, bases de datos y mecanismos de entrega. Está diseñado para desarrolladores y agentes de IA que trabajan en la revisión de arquitecturas, la definición de límites entre módulos o la gestión de dependencias. El skill es compatible con agentes como Claude Code o Cursor, y su documentación detallada (SKILL.md) guía la aplicación de la Regla de Dependencia, los principios SOLID, la organización en capas concéntricas y la definición de componentes. Al seguir estas pautas, se logra que el sistema sea testeable, flexible y resistente a cambios en tecnologías externas, permitiendo diferir decisiones y reemplazar implementaciones sin afectar la lógica central del negocio. Incluye además un diagnóstico rápido con puntuación (0-10), referencias a casos de uso y ejemplos de código en varios contextos como capas, controladores, presentadores y pasarelas.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add renatoxm/leanagentkit

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Marco de Arquitectura Limpia

Un enfoque disciplinado para estructurar software de manera que las reglas de negocio permanezcan independientes de frameworks, bases de datos y mecanismos de entrega. Aplica estos principios al diseñar la arquitectura del sistema, revisar los límites de los módulos o asesorar sobre la gestión de dependencias.

Principio Central

Las dependencias del código fuente deben apuntar hacia adentro — hacia las políticas de más alto nivel. Nada en un círculo interno puede saber nada acerca de un círculo externo. Esta única regla produce sistemas que son comprobables e independientes de frameworks, IU, base de datos y cualquier agencia externa. Las reglas de negocio son lo que importa; las bases de datos, los frameworks web y los mecanismos de entrega son detalles — cuando los detalles dependen de las políticas, puedes aplazar decisiones, intercambiar implementaciones y probar la lógica de negocio de forma aislada.

Puntuación

Objetivo: 10/10. Asigna un punto por cada una de las siete filas del Diagnóstico Rápido que la arquitectura cumpla (0-7), luego asigna a una banda de 0-10: 6-7 cumplidas = 9-10 (la Regla de Dependencia se cumple, la lógica de negocio es independiente del framework y la BD); 4-5 = 6-8 (el núcleo es comprobable pero algunos detalles se filtran hacia adentro); 2-3 = 3-5 (el framework o la persistencia dictan la estructura); 0-1 = 0-2 (sin límites — las reglas de negocio viven en controladores y modelos ORM). Reporta la puntuación, las filas de diagnóstico fallidas y la inversión específica necesaria para corregir cada una.

1. Regla de Dependencia y Círculos Concéntricos

Concepto central: Organiza la arquitectura como círculos concéntricos — Entidades (reglas de negocio empresariales) en el centro, luego Casos de Uso (reglas de negocio de la aplicación), luego Adaptadores de Interfaz, con Frameworks y Controladores en el exterior. Las dependencias del código fuente siempre apuntan hacia adentro.

Por qué funciona: Cuando las políticas de alto nivel no dependen de los detalles de bajo nivel, puedes intercambiar la base de datos, el framework web o el estilo de API sin tocar la lógica de negocio — el sistema se vuelve resistente a las partes más volátiles de la pila.

Perspectivas clave:

  • Los círculos internos no pueden mencionar nombres de círculos externos — sin clases, funciones, variables o formatos de datos del exterior
  • Los datos que cruzan un límite deben estar en la forma más conveniente para el círculo interno, nunca dictada por el externo
  • La Inversión de Dependencia (interfaces definidas hacia adentro, implementadas hacia afuera) es el mecanismo que impone la regla
  • El número de círculos no es fijo — cuatro es típico; la regla sigue siendo la misma
  • Los frameworks son detalles, no arquitectura — pertenecen al círculo más externo

Aplicaciones de código:

ContextoPatrónEjemplo
Dirección de capasLos círculos internos definen interfaces; los externos implementanInterfaz UserRepository en Casos de Uso; PostgresUserRepository en Adaptadores
Cruce de datosLos DTOs cruzan límites, no las entidades ORMEl Caso de Uso devuelve un DTO UserResponse, no un modelo ActiveRecord
Dirección de dependenciaLas importaciones siempre apuntan hacia adentroEl Controlador importa el Caso de Uso; el Caso de Uso nunca importa el Controlador

Consulta references/dependency-rule.md cuando una importación de un círculo interno apunte hacia afuera y necesites el recorrido de código de los cuatro círculos, las reglas de cruce de datos y el procedimiento de inversión de dependencia en cuatro pasos para corregirlo.

2. Entidades y Casos de Uso

Concepto central: Las Entidades encapsulan las reglas de negocio a nivel empresarial — reglas que existirían incluso sin software. Los Casos de Uso contienen reglas específicas de la aplicación que orquestan el flujo de datos hacia y desde las Entidades.

Por qué funciona: Separar lo que el negocio hace (Entidades) de cómo la aplicación lo orquesta (Casos de Uso) permite reutilizar Entidades en múltiples aplicaciones y cambiar el comportamiento de la aplicación sin alterar las reglas de negocio centrales.

Perspectivas clave:

  • Las Entidades no son filas de base de datos — son objetos o funciones puras que encapsulan reglas de negocio críticas
  • Los Casos de Uso aceptan Modelos de Solicitud y devuelven Modelos de Respuesta — nunca objetos del framework
  • Cada Caso de Uso es una operación única de la aplicación (CreateOrder, ApproveExpense)
  • El patrón Interactor: una clase Caso de Uso implementa una interfaz de límite de entrada y llama a una interfaz de límite de salida
  • Los cambios en un Caso de Uso nunca deben afectar a una Entidad; los cambios en una Entidad pueden propagarse a los Casos de Uso

Aplicaciones de código:

ContextoPatrónEjemplo
Diseño de EntidadReglas de negocio críticas, cero dependencias del frameworkOrder.calculateTotal() aplica reglas fiscales; no sabe nada sobre HTTP
Solicitud/RespuestaEstructuras de datos simples cruzan el límiteCreateOrderRequest { items, customerId } — sin modelos ORM
Responsabilidad únicaUn Caso de Uso por operaciónPlaceOrder, CancelOrder, RefundOrder como clases separadas
InteractorImplementa el Puerto de Entrada, llama al Puerto de SalidaPlaceOrderInteractor implements PlaceOrderInput

Consulta references/entities-use-cases.md al diseñar un Interactor o decidir qué pertenece a una Entidad versus un Caso de Uso — tratamiento completo de Reglas de Negocio Empresariales vs. de Aplicación con ejemplos de modelos de solicitud/respuesta.

3. Adaptadores de Interfaz y Frameworks

Concepto central: Los Adaptadores de Interfaz convierten datos entre la forma conveniente para los Casos de Uso/Entidades y la forma requerida por las agencias externas. Los Frameworks y Controladores son la capa más externa — código de pegamento con el mundo exterior.

Por qué funciona: Cuando el framework web, ORM o cola de mensajes está confinado a los círculos externos, reemplazar cualquiera de ellos es un cambio localizado. La base de datos es un detalle; la web es un detalle; los detalles deben ser complementos para tus reglas de negocio, no el esqueleto de la aplicación.

Perspectivas clave:

  • Los Controladores traducen HTTP a entrada del Caso de Uso; los Presentadores traducen la salida del Caso de Uso a modelos de vista
  • Las Pasarelas implementan interfaces de repositorio definidas por los Casos de Uso — el círculo interno define el contrato, el externo lo cumple
  • Las reglas de negocio nunca saben si los datos viven en SQL, NoSQL o archivos planos, o que la entrega es HTTP
  • Trata a los frameworks con sospecha — quieren que te acoples a ellos; mantenlos a distancia

Aplicaciones de código:

ContextoPatrónEjemplo
ControladorMecanismo de entrega → entrada del Caso de UsoOrderController.create(req) construye CreateOrderRequest, llama al Interactor
PresentadorSalida del Caso de Uso → modelo de vistaOrderPresenter.present(response) formatea para JSON/HTML
PasarelaInterfaz de Repositorio implementada por BDSqlOrderRepository implements OrderRepository
Límite del frameworkEl framework llama hacia adentro, nunca al revésEl manejador de ruta de Express llama al Controlador; el Controlador nunca importa Express

Consulta references/adapters-frameworks.md al cablear controladores, presentadores o pasarelas, o al argumentar que la base de datos/web es un detalle — cubre la arquitectura de complementos y cómo confinar un framework a los bordes.

4. Principios de Componentes

Concepto central: Los componentes son las unidades de despliegue. Tres principios de cohesión gobiernan lo que va dentro de un componente; tres principios de acoplamiento gobiernan las relaciones entre componentes.

Por qué funciona: Los componentes mal compuestos crean efectos dominó donde un cambio obliga a redesplegar código no relacionado; los principios mantienen los cambios localizados y los lanzamientos independientes.

Perspectivas clave:

  • REP (Equivalencia de Reutilización/Lanzamiento): las clases en un componente deben poder versionarse y lanzarse como una unidad
  • CCP (Cierre Común): las clases que cambian por la misma razón al mismo tiempo pertenecen juntas — SRP para componentes
  • CRP (Reutilización Común): no obligues a los usuarios a depender de clases que no usan
  • ADP (Dependencias Acíclicas): el grafo de componentes no debe tener ciclos — rómpelos con DIP o un nuevo componente
  • SDP (Dependencias Estables): depende en la dirección de la estabilidad
  • SAP (Abstracciones Estables): los componentes estables deben ser abstractos; los inestables, concretos

Aplicaciones de código:

ContextoPatrónEjemplo
Agrupación de componentesAgrupa clases que cambian juntas (CCP)Todos los Casos de Uso relacionados con pedidos en un componente
Romper ciclosAplica DIP para invertir una arista de dependenciaExtraer una interfaz en un nuevo componente para romper el ciclo
Métricas de estabilidadInestabilidad I = Ce / (Ca + Ce)Muchas dependencias entrantes, ninguna saliente → I cerca de 0 (estable)

Consulta references/component-principles.md al agrupar clases en componentes desplegables o romper un ciclo de dependencia — cada uno de REP, CCP, CRP, ADP, SDP, SAP trabajados con la métrica de inestabilidad.

5. Principios SOLID

Concepto central: Cinco principios a nivel de clase y módulo — Responsabilidad Única, Abierto-Cerrado, Sustitución de Liskov, Segregación de Interfaz, Inversión de Dependencia — los bloques de construcción de nivel medio que hacen posible la Regla de Dependencia.

Por qué funciona: Cada principio aborda una forma específica en que las dependencias salen mal, previniendo la rigidez, fragilidad e inmovilidad que convierten las bases de código en pesadillas heredadas.

Perspectivas clave:

  • SRP: un módulo tiene una razón para cambiar — sirve a un actor (no "hace una cosa")
  • OCP: extiende el comportamiento añadiendo nuevo código, no modificando el existente — patrones de estrategia y complemento
  • LSP: los subtipos deben ser utilizables a través de la interfaz base sin que el cliente lo sepa — violado por excepciones inesperadas o métodos ignorados
  • ISP: los clientes no deben depender de métodos que no usan — las interfaces grandes crean acoplamiento innecesario
  • DIP: los módulos de alto nivel y los de bajo nivel dependen de abstracciones definidas por el módulo de alto nivel

Aplicaciones de código:

ContextoPatrónEjemplo
Violación de SRPClase sirve a múltiples actoresEmployee maneja nómina (CFO), informes (COO), persistencia (CTO)
OCP mediante estrategiaNuevo comportamiento a través de nuevas clasesAñadir ExpressShipping implementando ShippingStrategy; Order intacto
Violación de LSPSubtipo cambia el comportamiento esperadoSquare extends Rectangle rompe el contrato setWidth()/setHeight()
Aplicación de ISPDivide interfaces grandes en interfaces de rolPrinter, Scanner, Fax en lugar de un MultiFunctionDevice
Cableado de DIPAlto nivel define interfaz; bajo nivel implementaOrderService depende de PaymentGateway, no de StripeClient

Consulta references/solid-principles.md al aplicar SRP/OCP/LSP/ISP/DIP a una clase específica o diagnosticar una violación — cada principio trabajado con ejemplos de código y el olor que previene.

6. Límites y Anatomía de Límites

Concepto central: Un límite es una línea entre cosas que importan y cosas que son detalles, implementada mediante polimorfismo: las dependencias cruzan apuntando hacia adentro mientras que el flujo de control puede cruzar en cualquier dirección.

Por qué funciona: Cada límite compra la opción de aplazar una decisión o intercambiar una implementación; la colocación estratégica de límites determina si un sistema es un placer o un dolor de mantener durante años.

Perspectivas clave:

  • Los límites completos usan interfaces recíprocas en ambos lados; los límites parciales usan una estrategia o fachada más simple
  • Patrón Objeto Humilde: divide el código del límite en una parte difícil de probar (cerca del límite) y una parte fácil de probar (la lógica)
  • Los servicios no son automáticamente límites arquitectónicos — un microservicio con un modelo de datos compartido grande es un monolito con llamadas de red
  • Las pruebas son el componente más aislado: dependen hacia adentro, nada depende de ellas
  • Los límites prematuros son costosos, pero también lo son los que faltan — dibújalos en puntos de volatilidad probable

Aplicaciones de código:

ContextoPatrónEjemplo
Límite completo vs. parcialPuertos recíprocos, o una estrategia solitariaEl Caso de Uso define PlaceOrderInput/PlaceOrderOutput; casos más simples toman una ShippingStrategy
Objeto HumildeSepara la lógica comprobable de la infraestructuraPresenterLogic (comprobable) produce ViewModel; View (humilde) lo renderiza
Main como complementoLa raíz de composición ensambla el sistemamain() conecta todas las implementaciones concretas e inicia la aplicación

Consulta references/boundaries.md al decidir dónde dibujar un límite, elegir entre completo y parcial, o aplicar el patrón Objeto Humilde — también cubre servicios como límites, límites de prueba y Main como el complemento definitivo.

Errores Comunes

ErrorPor qué FallSolución
ORM filtrándose en la lógica de negocioLas Entidades se acoplan al esquema; cambios en BD reescriben reglas de negocioSepara las entidades de dominio de los modelos de persistencia; mapea en la capa adaptadora
Reglas de negocio en controladoresNo comprobable sin HTTP; duplicado entre endpointsMueve la lógica a Interactores de Casos de Uso; los controladores solo traducen y delegan
Arquitectura primero-frameworkEl framework dicta la estructura; intercambiarlo significa reescribirTrata el framework como un complemento; estructura el código por capacidad de negocio
Dependencias circulares de componentesLos cambios se propagan impredeciblemente; sin lanzamientos independientesAplica DIP o extrae un componente de abstracción compartido
Un Caso de Uso gigante por funcionalidadOrquestadores inflados de mil líneasDivide en Casos de Uso enfocados de una sola operación
Saltarse límites "porque es simple"El acoplamiento se acumula silenciosamente hasta que el costo es enormeDibuja límites proactivamente en puntos de volatilidad probable
Microservicios como buena arquitectura automáticaUn monolito distribuido es peor que un monolito limpioAplica la Regla de Dependencia dentro y entre servicios; los servicios son límites de despliegue, no arquitectónicos

Diagnóstico Rápido

PreguntaSi NoAcción
¿Puedes probar las reglas de negocio sin BD, servidor web o framework?Las reglas están acopladas a la infraestructuraExtrae entidades y casos de uso detrás de interfaces; simula capas externas
¿Todas las dependencias del código fuente apuntan hacia adentro?Hay dependencias hacia afueraAplica Inversión de Dependencia: define la interfaz en el círculo interno; implementa en el externo
¿Los casos de uso no importan desde frameworks?Los casos de uso dependen de objetos del frameworkReemplaza importaciones de framework con parámetros de tipo/función definidos por el caso de uso
¿Las entidades no tienen dependencias de frameworks?Las entidades importan desde ORM, HTTP u otros frameworksElimina importaciones de framework; usa estructuras simples de datos/control
¿Los controladores contienen solo lógica de traducción?Los controladores contienen reglas de negocioMueve reglas de negocio a interactores de casos de uso
¿Los presentadores son independientes del framework?Los presentadores usan objetos del framework de IUAísla la lógica de presentación de los detalles del framework de IU
¿Los adaptadores de base de datos implementan interfaces definidas por el caso de uso?La capa de base de datos está ausente o expone directamente APIs de BDDefine interfaces de repositorio en la capa de caso de uso; haz que los adaptadores las implementen

Este skill se publica bajo licencia MIT. Consulte el repositorio original de wondelai/skills (v1.4.0) para más información.

Skills relacionados