Diseño de Fronteras Semánticas
Propósito
Prevenir la deriva semántica asignando un único propietario a cada decisión que define el significado.
Muchas capas pueden observar, pasar o renderizar los mismos datos. Solo una capa debe decidir qué significan esos datos para identidad, ciclo de vida, permisos, comandos, rutas, eventos, compatibilidad o presentación.
Usar / No Usar
Usa este skill antes o durante trabajo entre capas cuando:
- una capacidad cruza varias representaciones
- los alias, fallbacks, etiquetas, estados, permisos o reglas de ciclo de vida se están propagando entre llamantes
- un llamante no propietario empieza a parsear, normalizar, traducir o inferir significado
- un adaptador comienza a preservar política de producto en lugar de traducir formas
- las pruebas congelan internos de helpers en lugar del comportamiento de frontera del propietario
No uses este skill para:
- ediciones locales pequeñas sin movimiento de frontera semántica
- descubrimiento de propietarios existentes de solo lectura; usa
source-owner-audit - limpieza local de frontera de cambio o flujo una vez que los propietarios están claros; usa
structure-first - trabajo puro de frescura, capacidad de respuesta o interacción propensa a condiciones de carrera; usa
interactive-state-flow - control del alcance del cambio solo; usa
structure-first
Skills Adyacentes
source-owner-auditencuentra propietarios actuales a partir de evidencia. Este skill coloca decisiones semánticas una vez que la pregunta de propietario necesita diseño.structure-firstacota y da forma a la unidad actual después de que los propietarios son conocidos. Este skill comienza en el libro mayor de propietarios a nivel de capacidad.interactive-state-flowse especializa en comportamiento de frescura, pendiente, obsoleto y presentación asíncrona. Este skill maneja frescura/fallback/revisión solo cuando es propiedad de contrato semántico entre representaciones.
Flujo Operativo
- Nombra la capacidad en términos de usuario o dominio.
- Lista los cruces de representación: registro fuente, modelo de lectura, borrador de UI, intención de usuario, estado de ruta/consulta, entrada de comando, payload de API, resultado de comando, parche en tiempo real, modelo de presentación, adaptador de compatibilidad.
- Lista las decisiones semánticas: identidad/alias, ciclo de vida/estado, permiso/capacidad, gramática de comando, gramática de ruta/navegación, frescura/conflicto/revisión/pendiente/fallback, proyección/presentación, compatibilidad.
- Asigna un propietario por decisión. Elige el propietario durable más pequeño solo cuando la fuente actual o el contexto explícito de la tarea muestre suficiente evidencia y autoridad para decidir el significado. Si ninguna capa tiene ambas, escribe
decisión necesaria -> falta evidencia/autoridady nombra quién debe decidir solo cuando ese propietario de decisión esté evidenciado o proporcionado explícitamente. - Define las fronteras del llamante: los llamantes pueden pasar, seleccionar, invocar, mostrar o renderizar; los llamantes no deben interpretar, normalizar, volver a decidir ni preservar política a menos que sean propietarios de esa decisión.
- Refactoriza solo el alcance justificado por la tarea actual.
- Agrega guardas que fallen cuando las decisiones semánticas se filtren en los llamantes.
- Transfiere el descubrimiento de fuente, la forma local del código, la frescura asíncrona o el control de alcance al skill propietario adyacente cuando ese aspecto se vuelva primario.
Reglas de Selección de Propietario
- Alias de esquema o campo -> propietario del registro/contrato.
- Forma de intención de usuario -> propietario de la superficie de UI o de la entrada de comando.
- Payload de comando final -> propietario de sesión/comando.
- Parseo de solicitud de API -> propietario de ruta de aplicación, no envoltorio de framework.
- Gramática de ruta o consulta -> propietario de navegación.
- Permiso o capacidad -> propietario de política.
- Etiquetas y acciones -> propietario de superficie/modelo de vista.
- Envoltorio de resultado, parche o semántica de resincronización -> propietario de resultado de aplicación/tiempo real.
- Aceptación de obsoleto, pendiente, fallback, conflicto o revisión -> propietario de ruta, sesión o pantalla que posee la frescura.
- Comportamiento de compatibilidad -> el adaptador traduce formas; la propiedad de política requiere una asignación explícita.
Olores de Deriva
- Cadenas de fallback
x || y || zfuera del propietario de registro/contrato. - Comprobaciones duplicadas de ciclo de vida o estado.
- Código de UI construye payloads de comando final directamente desde registros.
- Componentes de ruta parsean o construyen gramática de consulta compartida.
- Envoltorios de API leen campos de solicitud de negocio.
- Manejadores de tiempo real o eventos vuelven a decidir ciclo de vida, permiso o política.
- Claves de revisión, conflicto, pendiente, fallback o frescura están duplicadas.
- Los adaptadores preservan política en lugar de traducir al propietario.
- Las pruebas afirman internos de helpers en lugar de comportamiento de frontera de propietario.
Guardas Requeridas
Elige la guarda más pequeña que proteja la frontera del propietario:
- pruebas de contrato para normalización de alias, forma de payload de comando, gramática de ruta/consulta o envoltorios de resultado
- pruebas de frontera que muestren que los llamantes pasan/renderizan/invocan sin reinterpretar significado
- casos negativos para comportamiento obsoleto, fallback, permiso, ciclo de vida o compatibilidad
- restricciones de tipo o esquema que dificulten expresar interpretación duplicada
- pruebas de regresión para comportamiento visible para el usuario que dependa de la decisión semántica
No congeles internos de helpers. Afirma que el propietario decide el significado una vez y que los llamantes no pueden elegir silenciosamente otro significado.
Contrato de Salida
Usa esta forma compacta al reportar un plan, revisión o nota de implementación:
Capability:capacidad de usuario/dominioRepresentation Crossings:formas de datos o control involucradasSemantic Decisions:decisiones que podrían derivarOwner Ledger:decisión -> propietario o decisión necesaria -> motivoCaller Boundaries:comportamiento permitido del llamante e interpretación prohibidaDrift Smells:fugas observadas o probablesRequired Guards:pruebas, esquemas o comprobacionesHandoffs:skills adyacentes o propietarios de seguimiento
Puertas Finales
- ¿Está la capacidad nombrada en términos de usuario/dominio?
- ¿Cada decisión semántica tiene exactamente un propietario, o un
decisión necesarianombrado? - ¿Pueden los llamantes observar, pasar, renderizar o invocar sin decidir significado?
- ¿Están los adaptadores limitados a traducción a menos que la propiedad de política sea explícita?
- ¿Están las decisiones de fallback, frescura, ciclo de vida, permiso y compatibilidad en manos de quien puede verificarlas?
- ¿Está el alcance de la refactorización limitado a la tarea actual?
- ¿Verifican las guardas el comportamiento de frontera del propietario en lugar de los internos de helpers?