Communitygithub.com

diseño-de-fronteras-semánticas

Skill para agente que asigna dueños de decisiones semánticas a través de fronteras de representación.

¿Qué es diseño-de-fronteras-semánticas?

Este skill guía al agente para prevenir la deriva semántica en sistemas donde múltiples capas observan, pasan o renderizan los mismos datos. Asigna un único propietario a cada decisión que define el significado (identidad, ciclo de vida, permisos, comandos, rutas, eventos, compatibilidad o presentación). Es útil antes o durante trabajo entre capas cuando una capacidad cruza varias representaciones, aparecen alias, fallbacks o reglas de ciclo de vida, o cuando un adaptador comienza a preservar política de producto en lugar de traducir formas. Funciona en cualquier plataforma de agente (Claude Code, Cursor, Codex, etc.) y sigue un flujo operativo de 8 pasos que incluye nombrar la capacidad, listar cruces de representación, asignar dueños, definir fronteras de llamante, refactorizar solo lo justificado, agregar guardas y delegar a skills adyacentes. Incluye reglas de selección de dueño, olores de deriva, guardas requeridas y un contrato de salida con campos como 'Capability', 'Representation Crossings', 'Semantic Decisions', 'Owner Ledger', 'Caller Boundaries', 'Drift Smells', 'Required Guards' y 'Handoffs'.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add perhapsspy/semantic-boundary-design

Preguntar en tu IA favorita

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

Documentación

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-audit encuentra propietarios actuales a partir de evidencia. Este skill coloca decisiones semánticas una vez que la pregunta de propietario necesita diseño.
  • structure-first acota 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-flow se 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

  1. Nombra la capacidad en términos de usuario o dominio.
  2. 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.
  3. 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.
  4. 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/autoridad y nombra quién debe decidir solo cuando ese propietario de decisión esté evidenciado o proporcionado explícitamente.
  5. 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.
  6. Refactoriza solo el alcance justificado por la tarea actual.
  7. Agrega guardas que fallen cuando las decisiones semánticas se filtren en los llamantes.
  8. 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 || z fuera 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/dominio
  • Representation Crossings: formas de datos o control involucradas
  • Semantic Decisions: decisiones que podrían derivar
  • Owner Ledger: decisión -> propietario o decisión necesaria -> motivo
  • Caller Boundaries: comportamiento permitido del llamante e interpretación prohibida
  • Drift Smells: fugas observadas o probables
  • Required Guards: pruebas, esquemas o comprobaciones
  • Handoffs: 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 necesaria nombrado?
  • ¿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?

Skills relacionados