CesarChv19/claude-skills_MC

Implementación de requerimiento (estructura de carpetas + bitácora)

Indicaciones generales a aplicar cuando se empieza a construir un requerimiento ya analizado (no para la fase de análisis). Reconstruido a partir del patrón ya usado en RV2-054-132-019_ Integración proceso ADG (CONSUBANCO), que es donde se aplicó por primera vez. Esta skill es portable: aplica igual sin importar en qué proyecto/cliente se use, siguiendo la regla de anclaje de la §0.

0. Dónde vive esto (portabilidad entre proyectos)

Este prompt no asume una ruta absoluta ni el nombre de un cliente en particular. La regla de anclaje, válida en cualquier proyecto donde se use:

• Siempre existe una carpeta que agrupa todos los requerimientos de ese proyecto/cliente — el nombre literal puede variar (Req\, Requerimientos\, u otro que el usuario indique la primera vez que se trabaja en un proyecto nuevo) — y dentro de ella, una subcarpeta por requerimiento, nombrada con su código (ej. RV2-054-132-019, a veces seguido de _<nombre corto>, ej. RV2-054-132-019_ Integración proceso ADG).
• Todo lo demás en este documento (README.md, Compartidos\, EchasXC\, SCRIPTS\...) es relativo a ESA subcarpeta del requerimiento específico, sin importar cómo se llame la carpeta contenedora de arriba. No hace falta preguntar el nombre de la carpeta contenedora cada vez — si ya existe una en el proyecto (Req\ o Requerimientos\), usar esa; si no existe ninguna todavía (proyecto nuevo), preguntar al usuario cómo la quiere nombrar antes de crearla.
• Un requerimiento nuevo y separado (ver §10) se identifica por tener (o necesitar) su propia subcarpeta bajo esa carpeta contenedora, con su propio código — nunca se mete dentro de la carpeta de otro requerimiento ya existente, aunque esté en el mismo cliente/módulo.

Árbol concreto (todo lo de §1-§4 cuelga directo de la carpeta del requerimiento, nada vive un nivel más arriba ni más abajo de lo que muestra este árbol):

Req\                                     (o "Requerimientos\", el nombre que ya use el proyecto)
└─ RV2-054-132-019_ Integración ADG\     ← carpeta del requerimiento (§0), ancla de todo lo demás
   ├─ README.md                         ← §1, la bitácora
   ├─ Compartidos\                      ← §2, HU/imágenes/evidencia/llaves
   ├─ EchasXC\                     ← §4, todo lo que Claude genera que no es entregable formal
   │  └─ SCRIPTS\                       ← §3, la carpeta DE TRABAJO de Claude (no la raíz)
   │     ├─ ORG\                       ← rollback, numeración propia
   │     └─ MOD\
   │        ├─ ALTERS\                 ← solo tablas
   │        ├─ SP\                     ← solo stored procedures
   │        ├─ FN\                     ← solo funciones
   │        └─ VI\                    ← solo vistas
   ├─ SCRIPTS\                          ← carpeta raíz que cura el usuario (§3), NO tocar sin permiso
   ├─ Analisis_Impacto_[CÓDIGO].docx    ← entregables de la fase de análisis (si se pidieron)
   ├─ Estimacion_tiempos_[CÓDIGO].xlsx
   └─ Plan_Implementacion_[CÓDIGO].docx

1. Bitácora de cambios — README.md en la raíz de la carpeta del requerimiento

Un solo archivo, vivo, que se actualiza cada vez que se construye/modifica algo, se resuelve o se agrega una pregunta pendiente, o cambia el estado de algo. Estructura fija:

• Encabezado con código y nombre del requerimiento + "Última actualización: AAAA-MM-DD".
• Qué es esto — resumen de 2-4 líneas del requerimiento.
• Estado general — qué ya está construido — una viñeta por fase/módulo, marcando construido / parcial / pendiente.
• Arquitectura (dónde está cada cosa) — rutas de pantallas, SPs clave (con sus banderas), jobs, tablas clave, archivos de config. Acceso a BD (servidor, nombre de base, usuario y contraseña) NO se documenta aquí ni en ningún archivo — cambia según el portal/proyecto, y el usuario lo da en el momento que se necesite, junto con la contraseña (ver §7).
• Pendientes — separado en "Preguntas al cliente" (tachar con ~~texto~~ cuando se resuelvan, sin borrarlas) y "Desarrollo pendiente".
• Bitácora de cambios — una entrada por sesión/fecha (**AAAA-MM-DD (título corto)**), más reciente arriba, con: qué hueco/bug real se encontró, qué se decidió y por qué, qué archivos cambiaron, qué falta que el usuario haga (correr script, recompilar, probar en pantalla).

No reemplaza Analisis_Impacto_[CÓDIGO].docx ni Plan_Implementacion_[CÓDIGO].docx (esos son entregables de la fase de análisis) — este README es el estado vivo de la construcción.

Rotación cuando crece demasiado — si README.md se acerca o supera ~200KB, archivar las sesiones más viejas antes de seguir agregando (caso real ya ocurrido: un README.md llegó a pasar 256KB y el tool de lectura dejó de poder abrirlo). Mecánica: mover las entradas de bitácora más antiguas a un archivo nuevo README_historico_AAAA.md (uno por año, o el que haga falta), dejando en el README.md activo solo las ~10-15 sesiones más recientes + un resumen de 2-3 líneas de lo archivado (para no perder continuidad leyendo solo el activo). Las demás secciones (Qué es esto, Estado general, Arquitectura, Pendientes) nunca se archivan, siempre viven en el activo — solo la bitácora de sesiones rota.

2. Carpeta Compartidos\

Todo lo que es insumo o evidencia compartida con el cliente/proveedor externo, no código: HU y sus anexos, imágenes/capturas embebidas extraídas del documento, llaves (PGP/certificados), archivos de mapeo de datos, archivos de prueba recibidos o enviados a un tercero (ej. CDC).

Si aparece un documento en Compartidos\ cuyo tema no corresponde al requerimiento actual (ej. una HU de "Logs/auditoría" dentro de la carpeta de "Integración proceso ADG"): no asumir ninguna de las dos salidas fáciles — ni tratarlo como evidencia de este requerimiento solo por estar ahí, ni ignorarlo/moverlo por cuenta propia. Preguntar al usuario cuál de estos tres casos es:

• Mal ubicado — pertenece a otra carpeta, se copió por error.
• Requerimiento nuevo y separado que todavía no tiene su propia carpeta — crearle una con esta misma estructura, y si comparte objetos de BD/pantalla con el actual, documentarlo en "Requerimientos relacionados" de ambos (§10).
• Set de requerimientos agrupados a propósito en una sola carpeta de cliente (existe un precedente de este patrón en la plantilla de correo de pase a QA, que contempla explícitamente un "Set de requerimientos") — si es así, confirmar si igual conviene una subcarpeta por código.

3. Carpeta de scripts — SCRIPTS\ORG\ y SCRIPTS\MOD\

Hay dos carpetas SCRIPTS distintas en la carpeta del requerimiento: <requerimiento>\SCRIPTS\ (raíz) y <requerimiento>\EchasXC\SCRIPTS\. La de trabajo, donde Claude va dejando cada script según lo construye, es EchasXC\SCRIPTS\. La carpeta raíz SCRIPTS\ la cura el usuario manualmente, promoviendo desde EchasXC\SCRIPTS\ cuando él considere que algo ya está bien — no tocar esa carpeta raíz salvo que el usuario lo pida explícitamente.

MOD\ — una subcarpeta por tipo de objeto, sin agrupar, cada una con numeración secuencial propia e independiente (no comparten numeración entre sí):

• MOD\ALTERS\ — solo tablas (CREATE TABLE / ALTER TABLE).
• MOD\SP\ — solo stored procedures.
• MOD\FN\ — solo funciones (CREATE FUNCTION).
• MOD\VI\ — solo vistas.
• Si aparece un tipo de objeto que no tiene carpeta dedicada (índice, trigger, job, etc.), preguntar al usuario cómo quiere llamar la carpeta en vez de asumir dónde va o meterlo en la que "se parece". (Error real ya cometido una vez: una función se puso primero en SP\, luego en ALTERS\, hasta que el usuario pidió crear FN\ dedicada.)
• Patrón de nombre en todas: objeto ya existente que se modifica → N_NOMBRE_MOD.sql; objeto completamente nuevo (no existe en BD) → N_NOMBRE_NEW.sql.

ORG\ — rollback de los objetos que se modifican (los _NEW no llevan pareja aquí: el rollback de algo nuevo es simplemente eliminarlo, no hay nada previo que capturar). Antes de tocar un objeto existente, extraer su definición actual tal como vive hoy en BD y guardarla aquí — ese archivo ES el rollback.

• ORG\ NO es un espejo numérico de MOD\. Es fácil asumirlo y es incorrecto — llevan numeración independiente. Puede incluso numerarse por categoría dentro de sí misma (p. ej. un rollback consolidado de todos los MOD\ALTERS en una sola pasada respetando dependencias, y por separado un rollback por cada SP tocado). Confirmar con el usuario el esquema de numeración de ORG\ antes de asumir "mismo número que en MOD" — ya se corrigió una vez por asumir esto mal.
• Cada vez que se toque/despliegue un objeto, avisar explícitamente al usuario cuál es (nombre) para que quede claro qué se movió.

Reglas generales para cualquier script de este apartado:

• DDL siempre idempotente (IF NOT EXISTS / COL_LENGTH(...) IS NULL).
• Un SP nuevo que llama a otro SP nuevo se define en el mismo archivo/batch que su dependencia, nunca en un número de archivo posterior.
• Si luego se "unifican"/limpian scripts incrementales (columnas agregadas después vía ALTER sueltos que se doblan de vuelta al CREATE original): el ALTER de respaldo se deja igual debajo del CREATE ya completo (las dos rutas conviven, no se elige una); el ORG correspondiente no necesita cambios si ya hace DROP completo del objeto — si hace rollback columna por columna, revisar orden (índices/constraints se dropean antes de tocar la columna en el rollback, se crean después de fijar la nulabilidad final en el alta).

4. Material de trabajo que no es entregable — EchasXC\

Todo lo que Claude genera para apoyar la construcción pero que no se entrega formalmente al cliente ni al equipo (queries de validación, pruebas manuales, hojas técnicas, correos borrador): va en una subcarpeta EchasXC\, separada de Compartidos\ y de los entregables formales.

5. Encoding — por ningún motivo modificar el ya establecido en el archivo

Antes de editar cualquier archivo con acentos (.aspx/.aspx.vb/.master/scripts, etc.), no asumir que es UTF-8 solo porque lo declara o porque file lo reporta así. Algunos archivos viejos de portales legacy son realmente ISO-8859-1/Windows-1252 por dentro (acentos como bytes altos únicos), y el Edit/Write estándar decodifica/reescribe TODO el archivo como UTF-8 — cualquier acento preexistente en el archivo completo (no solo cerca de la edición) se convierte a basura (U+FFFD, se ve como "�" o similar en el navegador), de forma silenciosa y permanente en cuanto se guarda.

• Verificar encoding real antes de tocar un archivo de este tipo (file archivo.aspx, y ojo: un archivo YA corrompido antes puede reportar "UTF-8" limpio sin serlo realmente).
• Si es ISO-8859-1, editar vía PowerShell con [System.Text.Encoding]::GetEncoding("ISO-8859-1") — decodificar bytes crudos con esa codificación, reemplazar en memoria, reescribir con la misma codificación. Nunca con el Edit/Write tool estándar sobre un archivo con esta sospecha.
• Verificar después de CADA edición, no solo antes: si el repo tiene git, git diff --stat inmediatamente después — un número de deletions mucho mayor a lo que se intentó cambiar es la señal de corrupción, no la edición esperada. Sin git, comparar tamaño de archivo antes/después.
• Si ya se corrompió sin darse cuenta: revertir con git checkout -- archivo (recupera los bytes originales intactos) antes de reintentar con el método correcto — los acentos perdidos no se pueden recuperar una vez sobrescritos.
• Para archivos nuevos que Claude crea (no edita): sí llevan BOM UTF-8 explícito si el proyecto lo requiere (confirmar con el usuario si aplica).

6. Postura general — actuar como senior, nunca dar nada por hecho

No asumir que algo "debería funcionar así", que un patrón se repite igual que en otro lado, o que un dato/esquema es el que la memoria o la lectura superficial sugieren. Validar el proceso real siempre:

• Contra la BD real (DEV) antes de afirmar esquema, datos o comportamiento — no asumir, consultar.
• Contra el código real (grep/leer el archivo) antes de afirmar qué hace una pantalla/SP — no confiar en el nombre o en la primera lectura.
• Contra la HU/documento del requerimiento antes de agregar algo que "parece necesario" — si no está explícito, no se construye por inercia.
• Validando el resultado de cada cambio (SET PARSEONLY ON, git diff, ejecución de prueba) antes de darlo por terminado, en vez de asumir que compiló/corrió bien porque la lógica se ve correcta.

7. Reglas de ejecución contra BD (aplica a todo, no solo DDL de script)

• Nunca ejecutar INSERT/UPDATE/DELETE/DDL contra la BD, ni en DEV, ni con confirmación explícita en el chat. El usuario ejecuta él mismo todo lo que escriba en BD; el rol de Claude es preparar el script y, después de que el usuario lo corra, validar con SELECT que quedó como se esperaba. Esto es independiente de la regla de carpetas ORG/MOD — aplica también a catálogos, datos de prueba, cualquier escritura.
• Consultas de solo lectura (SELECT, INFORMATION_SCHEMA, sys.sql_modules) sí son libres, sin pedir permiso cada vez.
• Servidor, nombre de base, usuario y contraseña de BD no se documentan en ningún archivo (README.md, Compartidos\, scripts .sql, comentarios de código) — el nombre de la base en particular cambia según el portal/proyecto, así que no hay un valor fijo que valga la pena fijar por escrito. El usuario los da en el chat cuando se necesiten, junto con la contraseña, y se usan solo por variable de entorno en el comando de esa sesión — pedirlos de nuevo la próxima vez, no guardarlos "para no tener que volver a preguntar". Si ya se tiene una contraseña/cone...