CommunityImagengithub.com

asis-tobe

Genera una página HTML que muestra cómo un cambio (PR, rama, árbol de trabajo sin commit, conjunto de PRs en varios repos o un issue) afecta cada capa — datos, payload de API, comportamiento del servidor, pantalla, resultado para el usuario — colocando AS-IS y TO-BE lado a lado y vinculando las capas con una cadena causal.

¿Qué es asis-tobe?

El skill `asis-tobe` es una herramienta de comparación de impacto de cambios en múltiples capas, diseñada para asistentes de IA como Claude Code. Su objetivo es generar un documento HTML autocontenido que muestre, de forma visual y estructurada, cómo un cambio de código (un PR, una rama, cambios sin commit, o incluso un conjunto de PRs en varios repositorios) afecta cada capa de un sistema: desde los datos (tablas, esquemas ORM), pasando por la especificación de la API (payloads, tipos), el comportamiento del servidor, la pantalla que ve el usuario, hasta el impacto final en el usuario. El resultado es una página con dos columnas (AS-IS a la izquierda, TO-BE a la derecha) para cada capa afectada, con flechas de causalidad que conectan los cambios entre capas (por ejemplo, "este campo se eliminó, por lo que la respuesta cambia, y por lo tanto esto desaparece de la pantalla"). Esto es especialmente útil para PRs que afectan tanto al servidor como al cliente, permitiendo a revisores y planificadores entender el impacto completo en un solo vistazo. El skill incluye principios de diseño (como comparar artefactos reales, no inventar cambios, y priorizar la evidencia), un procedimiento detallado para recolectar artefactos de cada capa (desde migraciones de base de datos hasta capturas de pantalla), y reglas para generar el documento final (incluyendo un resumen ejecutivo, tarjetas de preguntas, y un diseño responsivo con dos esquemas de color). El skill está escrito originalmente en coreano, pero se ha adaptado al español para esta traducción.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/chordpli/asis-tobe/tree/main

Installed? Explore more Imagen skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

Preguntar en tu IA favorita

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

Documentación

AS-IS / TO-BE

Encuentra las capas que un cambio toca, coloca AS-IS y TO-BE lado a lado para cada una, y vincula las capas con flechas respaldadas por evidencia: "este campo se elimina, por lo que esta respuesta cambia, por lo que esto desaparece de (o aparece en) esta pantalla". Si el código cambia pero lo que el usuario ve sigue igual, decir eso es la conclusión. No inventes cambios.

<skill> en los comandos siguientes es el directorio base de este skill: la carpeta que contiene este SKILL.md (~/.claude/skills/asis-tobe para una instalación a nivel de usuario, <project>/.claude/skills/asis-tobe para una a nivel de proyecto). Reemplázalo con la ruta real antes de ejecutar un comando.

Principios

  1. Lado a lado. AS-IS a la izquierda, TO-BE a la derecha. Nunca apilados verticalmente.
  2. Comparar artefactos reales. Payloads según «실물 고르는 순서» más abajo, pantallas a partir de capturas de pantalla reales, esquemas a partir de migraciones y diffs de modelos reales. Sin el artefacto real: «실물 없음: <razón>» ("sin artefacto real: <razón>"). Ejemplos hechos a mano: «예시(손으로 만듦)» ("ejemplo (hecho a mano)").
  3. Dibujar solo las capas cambiadas. Una capa sin cambios obtiene «변경 없음» ("sin cambio") más una línea de evidencia. Sin tablas vacías.
  4. Cada flecha tiene evidencia. Un archivo:línea o un commit por cada enlace de la ruta de impacto. Sin evidencia, márcalo como «추정:» ("estimado:").
  5. Indica quién sigue usando la especificación antigua. Todo lo que siga ejecutando código antiguo después de que esto se envíe: compilaciones de la aplicación ya en la tienda, pestañas del navegador aún abiertas en la página antigua, otros servicios, otros sitios de llamada como una herramienta de administración o un bot. Esto decide el orden de fusión y despliegue.
  6. Resumen primero. El cuadro de resumen en la parte superior debe ser suficiente para tomar la decisión: una conclusión de una oración en las palabras del usuario (sin nombres de campo ni códigos de estado), qué cambia para el usuario, cómo se envía, si se puede revertir; 3 elementos o menos por grupo. Justo debajo, tres tarjetas responden a lo que cualquier lector pregunta a continuación, nombradas por la pregunta y no por un rol: «정해야 할 것» (lo que el cambio decidió en nombre de alguien), «먼저 볼 곳» (tamaño, los archivos que abrir primero, premisas que el código establece), «직접 확인하는 법» (elementos a verificar, luego cómo ejecutarlo) — reglas en references/document.md ("Tarjetas de preguntas"). Las dos cosas en las que se basa una decisión, la insignia y la reversión, son lo más visible en la primera pantalla. Di cada hecho una vez: una oración ya en la conclusión o la advertencia no se repite en el encabezado, las tarjetas de preguntas ni un escenario. Todo lo demás es evidencia. Pliega payloads largos y tablas exhaustivas dentro de <details>; no los elimines. Sin introducción, narrativa de progreso ni comentarios de cierre.
  7. El diseño es contenido. A 420px de ancho, la página no debe desplazarse horizontalmente (solo las tablas pueden). Ancho del cuerpo limitado a 880px; solo las tablas y las comparaciones lado a lado usan el ancho completo. code dentro de las tablas solo para identificadores; solo las rutas de archivo y los identificadores son monoespaciados, las descripciones en coreano nunca. Frases de alrededor de 70 caracteres, modificadores recortados. Dos esquemas de color conmutados por un interruptor sobre el título: predeterminado Dusk, beige (AS-IS) y azul pizarra (TO-BE); Bloom, rosa (AS-IS) y menta (TO-BE). No sigas la configuración del modo oscuro del sistema. Las líneas discontinuas y sólidas siempre acompañan al color. Los resaltados de código en línea usan el --a-mark, --b-mark claro, no los colores de chip oscuros. Renderiza una vez en cada esquema y una vez a 420px.
  8. Términos de la industria, explicados una vez. Usa palabras que los desarrolladores, QA y planificadores entiendan de inmediato. En el documento en coreano usa 레이어, 필드, API 스펙, 호출처, deprecated, breaking change, mock 응답, con una explicación sencilla entre paréntesis solo en el primer uso (por ejemplo, codegen(서버 스펙으로 자동 생성한 타입 파일) — "archivos de tipos generados automáticamente a partir de la especificación del servidor"). Para jerga interna (「AC」, apodos de pantalla inventados), indica qué es en el primer uso. Glosario: references/terms.md. Si un término te bloquea, léelo allí; no omitas el paso.

Capas

CapaQué compararDe dónde proviene el artefacto real
Datos (데이터)Tablas, campos, tipos, enumeraciones, restricciones, índices. Un diagrama de entidades de solo las entidades cambiadas, y el código del modeloMigraciones, esquema ORM (prisma, etc.), diff de DDL
Especificación de API (API 스펙)Payloads de solicitud y respuesta, eventos, tipos codegen. Adiciones, eliminaciones, cambios de tipo, cambios semánticos por campoDiff de OpenAPI, DTOs de respuesta, fixtures de prueba
Comportamiento (동작)El resultado que el servidor y el cliente producen para la misma entradaDiff de aserciones de prueba, código de transición de estado
Pantalla (화면)Dos capturas de la pantalla en el mismo estadoLa herramienta de captura de pantalla del proyecto (references/adapters.md, «프로젝트 어댑터»)
Impacto en el usuario (사용자 영향)Lo que los usuarios ahora pueden hacer o ya no pueden hacer, números que cambian. Incluye estados intermedios causados por el orden de despliegueCriterios de aceptación del issue, la suma de las capas anteriores, tabla de compatibilidad

Listas de verificación por capa y errores comunes: references/layers.md.

Elección del artefacto real (실물 고르는 순서, API spec)

Fixture de prueba del servidor > Ejemplo de OpenAPI > Llamada real registrada > Respuesta simulada del cliente. Toma el primero que exista por completo. Si una fuente superior es solo parcial (un fixture construido a partir de variables, o pruebas que construyen la solicitud en línea y afirman campo por campo) y registraste una llamada real, muestra la fuente superior en el panel y la llamada registrada como el texto completo, cada una etiquetada con su fuente. Una llamada registrada lleva valores que difieren en cada ejecución (IDs, marcas de tiempo); compara dichos payloads con code_diff.py --mask id,time y dílo en la línea de origen, para que un nuevo ID no se cuente como un campo cambiado. Una simulación del cliente (por ejemplo, una respuesta falsa para capturas de pantalla) no es el artefacto real del servidor. Escribe la ruta de la fuente elegida debajo del payload. Si el fixture está construido a partir de variables sin un JSON completo, transfíbelo de los valores esperados de la prueba, etiquétalo como 「예시(테스트 기대값에서 옮김)」 ("ejemplo (transferido de expectativas de prueba)"), y usa … donde se haya acortado. No completes campos ausentes de los valores esperados; déjalos como …. Si tomaste prestado un valor de otro lugar (una respuesta simulada, etc.), anota la fuente junto a ese campo.

Procedimiento

1. Establecer el alcance

  • Entrada de PR: obtén el diff por número de PR (gh pr diff <n> -R <repo>). Una ruta o rama sola da un PR apilado con main como base y mezcla cambios de otras personas.
  • Entrada de issue: encuentra los PRs en cada repositorio (gh pr list -R <repo> --search <key> --state all). Dos o más repositorios van en un solo documento.
  • Sin PR: git diff <base>...HEAD en el árbol de trabajo, con <base> como el punto de bifurcación, calculado desde la raíz del repositorio (el main local está desactualizado y mezcla cientos de archivos):
    git fetch origin main
    git merge-base origin/main HEAD
    
    Si el diff incluye archivos no relacionados con el issue, la base es incorrecta. Recalcula antes de dividir en capas.
  • Sin remoto: omite el fetch y toma la base que el usuario nombre, o si no, el commit desde el que comenzó el trabajo (git merge-base main HEAD, o HEAD mismo para trabajo sin commit).
  • Árbol de trabajo sin commits: AS-IS es HEAD, TO-BE es el árbol de trabajo. git diff HEAD omite archivos nuevos, así que también lee git ls-files --others --exclude-standard. Siempre que se solicite un SHA de HEAD, escribe 「커밋 전」 ("no confirmado"). No hagas commit, stash ni checkout para hacer la comparación.
  • Sin PR ni issue: el objetivo se nombra por lo que es (「 작업 트리 변경」, 「 브랜치」). La tabla de despliegue obtiene una fila por unidad que se envía (una rama, 「작업 트리 커밋」) con la celda del PR nombrándola; la clave del issue se elimina, no se inventa.
  • Por repositorio, escribe una línea <repo> <SHA base corto> → <SHA de rama corto>. Úsala textualmente en el informe. En el documento, los PRs y SHAs van una vez en la tabla de orden de despliegue de la tarjeta de resumen y la tabla base (references/document.md), no en el encabezado.

2. Asignar archivos cambiados a capas

Cada archivo va a una o más capas; si no está claro, ábrelo. Los archivos de prueba no se asignan; son evidencia para la capa de Comportamiento (동작). Esta tabla decide qué secciones de capa recibe el documento; es material de trabajo y no se imprime en el documento.

3. Primero decidir si la pantalla realmente cambia

Incluso si el código de la pantalla cambió, pregunta antes de capturar: ¿la rama cambiada es alcanzable con los datos actuales? Elige un valor del que dependa la rama y averigua si el servidor realmente lo produce.

# Ejemplo: se eliminó la rama donde la app mostraba una insignia 「품절」 ("agotado") cuando stockState === 'SOLD_OUT'
git -C <repo del servidor> grep -n "SOLD_OUT" -- <archivos fuente>      # ¿el servidor pone este valor en alguna respuesta?
git -C <repo de la app> grep -n "stockState" -- <tipos generados>   # valores que permite el tipo generado

Ningún código del servidor que establezca el valor (solo definiciones de tipo o enumeración) significa inalcanzable, incluso si el tipo generado lo permite. Registra el archivo:línea como evidencia para 「변경 없음」.

Si solo el lugar que calcula un valor se mueve (por ejemplo, el ERROR del servidor ahora es calculado por la app como lastError), coloca ambas fórmulas lado a lado con su archivo:línea. Mismo valor para la misma entrada: misma pantalla. Diferente: encuentra una entrada que produzca un valor diferente y captura ese estado.

  • Alcanzable: captura en el paso 4.
  • Inalcanzable: la capa de Pantalla obtiene 「현재 데이터로는 변경 없음: <razón y evidencia>» ("sin cambio con los datos actuales: <razón y evidencia>"). Registra el estado desaparecido bajo 「실물 없음» y muestra su apariencia anterior a través de las cadenas de prueba cuyas aserciones verificaban ese estado. Si se necesita confirmación, captura un escenario representativo y muestra la igualdad con md5.
  • No estoy seguro: captura.

4. Recopilar artefactos reales por capa

  • Datos: tres partes, en este orden.
    1. Diagrama de entidades, abierto. Solo las entidades cambiadas y las directamente adjuntas, 6 o menos por lado. Escríbelas como JSON y deja que el script dibuje ambos lados como SVG en línea: python3 -I <skill>/scripts/erd.py <spec.json> (el formato de la especificación está en el encabezado del script). Nunca dibujes el SVG a mano y nunca cargues una biblioteca de diagramas; la página es autocontenida. El script marca campos y entidades añadidos, eliminados y cambiados él mismo comparando los dos lados, así que escribe cada lado tal como es realmente en ese commit.
    2. Código del modelo, plegado (<details>): el modelo tal como lo mantiene el código (struct, clase, esquema ORM) en la base y ahora. Un diff de una línea por modelo a partir de python3 -I <skill>/scripts/code_diff.py <ASIS.txt> <TOBE.txt> --label "<nombre (ruta)>" --start-a <línea> --start-b <línea>; un modelo nuevo o eliminado usa /dev/null para el lado faltante. El script calcula las líneas cambiadas y muestra ambas vistas (나란히 lado a lado, 합쳐서 unificada) para que el lector cambie; nunca marques líneas a mano.
    3. Tabla de campos, plegada: lo que el diagrama omite (valores predeterminados, restricciones, índices, manejo de filas existentes). Un solo campo cambiado sin relación involucrada no necesita diagrama: una fila en la tabla de campos, mostrada abierta. Si AS-IS no tenía un esquema almacenado (en memoria, un archivo), da solo tobe al script con asis_note indicando dónde vivían los datos (archivo:línea); el código del modelo es entonces la evidencia de AS-IS, así que deja ese <details> abierto. La migración que crea las primeras tablas es TO-BE. Si esto limpia después de una migración ya enviada, 「이미 반영()» ("ya aplicado ()") es el primer enlace de la ruta de impacto.
  • Especificación de API: el payload antes y después como un diff de líneas de scripts/code_diff.py (el mismo script que para el código del modelo; una llamada por payload, --context 3 para los largos, --mask id,time para llamadas registradas). Debajo, 필드 | AS-IS | TO-BE | 시맨틱 변경 (campo | AS-IS | TO-BE | cambio semántico). Un cambio solo de nombre o tipo fusiona ambas celdas en una línea: <code class="old">start_time</code> → <code class="new">starts_at</code>. Sitios de llamada:
    • git grep <campo> en cada repositorio, desde la raíz del repositorio (un subdirectorio hace que las rutas sean relativas y devuelve 0 resultados).
    • También en la versión publicada: git grep -n <campo> <SHA>. Su resultado decide el orden de fusión y despliegue y la insignia. Lee references/adapters.md ("Encontrar la versión publicada") antes de hacer esto. Debes: solo un SHA de la lista de compilación está confirmado, otros son 「추정:»; si las fuentes difieren, grepea cada SHA y cuenta cualquier resultado como 「배포된 앱이 읽는다» ("la app publicada lo lee"); nunca elijas solo por nombre de etiqueta (las etiquetas pueden pertenecer a otro desplegable en el mismo repositorio). Respaldo ligero cuando la lista de compilación falla (por ejemplo, sin inicio de sesión en el servicio de compilación): SHAs del issue o notas de la versión, o si no, un límite inferior 「추정:».
    • La salida de codegen no es un sitio de llamada; se regenera a partir de la especificación del servidor. Anota por separado 「다시 뽑으면 무엇이 바뀌나» ("qué cambia si se regenera").
    • También git grep el campo eliminado en las respuestas simuladas y fixtures de prueba del cliente. Si permanece, la verificación de tipos puede romperse una vez que el codegen se regenere después de que el servidor se envíe. Enumera esos archivos como el último paso de despliegue (「codegen 재생성과 fixture 정리」, "regenerar codegen y limpiar fixtures").
  • Comportamiento: 입력·상태 | AS-IS | TO-BE | 근거(테스트 이름) (entrada/estado | AS-IS | TO-BE | evidencia (nombre de la prueba)).
  • Pantalla: lee references/screens.md ("Captura") antes de capturar. Mismo escenario, datos, un idioma y tamaño en ambos lados, en un árbol de trabajo temporal (base para AS-IS, rama para TO-BE) o, para trabajo sin commit o un repositorio que no debas tocar, en dos copias fuera del repositorio; instalaciones y capturas en segundo plano, comparación md5, luego, una vez que el paso 10 haya re-medido lo que necesita, detén los servidores y elimina el árbol de trabajo temporal o las copias (mantenlos si el usuario quiere que la ejecución sea reproducible); nunca los confirmes. Sin herramienta de captura simulada, ejecuta el servidor real de cada versión en su propio puerto y captúralo. Comandos de captura por proyecto: references/adapters.md. Omite la captura solo cuando la plataforma no se pueda capturar (por ejemplo, nativa) o el paso 3 encontró que la rama es inalcanzable; entonces 「실물 없음: <razón>» más cadenas de aserción de prueba. Si no estás seguro, captura.

4b. Llenar el carril de escenarios

Lee references/scenario-rail.md antes de llenar 「시나리오별 전후». Nombres de celdas para otros dominios: references/domains.md.

| Esqueleto | Web/app

...

[truncado para traducción]

Skills relacionados