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
- Lado a lado. AS-IS a la izquierda, TO-BE a la derecha. Nunca apilados verticalmente.
- 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)").
- Dibujar solo las capas cambiadas. Una capa sin cambios obtiene «변경 없음» ("sin cambio") más una línea de evidencia. Sin tablas vacías.
- Cada flecha tiene evidencia. Un
archivo:líneao un commit por cada enlace de la ruta de impacto. Sin evidencia, márcalo como «추정:» ("estimado:"). - 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.
- 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. - 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.
codedentro 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-markclaro, no los colores de chip oscuros. Renderiza una vez en cada esquema y una vez a 420px. - 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
| Capa | Qué comparar | De 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 modelo | Migraciones, 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 campo | Diff de OpenAPI, DTOs de respuesta, fixtures de prueba |
| Comportamiento (동작) | El resultado que el servidor y el cliente producen para la misma entrada | Diff de aserciones de prueba, código de transición de estado |
| Pantalla (화면) | Dos capturas de la pantalla en el mismo estado | La 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 despliegue | Criterios 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 conmaincomo 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>...HEADen el árbol de trabajo, con<base>como el punto de bifurcación, calculado desde la raíz del repositorio (elmainlocal está desactualizado y mezcla cientos de archivos):
Si el diff incluye archivos no relacionados con el issue, la base es incorrecta. Recalcula antes de dividir en capas.git fetch origin main git merge-base origin/main HEAD - 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, oHEADmismo para trabajo sin commit). - Árbol de trabajo sin commits: AS-IS es
HEAD, TO-BE es el árbol de trabajo.git diff HEADomite archivos nuevos, así que también leegit 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.
- 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. - 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 depython3 -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/nullpara 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. - 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
tobeal script conasis_noteindicando 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.
- 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:
- 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 3para los largos,--mask id,timepara 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 grepel 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]