Especificación de Visualización de Flujos de Código
Este Skill proporciona un conjunto de plantillas y métodos reutilizables para analizar flujos de código y generar documentación visual.
Principio fundamental: Explicar con texto y diagramas ASCII "de dónde vienen los datos, por qué capas pasan y a dónde llegan".
Cuándo usar
Utilice este Skill en los siguientes escenarios:
- El usuario pregunta "cómo funciona esta funcionalidad"
- Se necesita diseñar el flujo de datos para una nueva funcionalidad
- Es necesario revisar la lógica existente antes de una refactorización
- Se está redactando documentación técnica o explicaciones arquitectónicas
- Durante revisiones de código, se necesita visualizar la cadena de llamadas
Plantillas principales
1. Diagrama de flujo completo (comparación de múltiples escenarios)
Adecuado para: analizar varios escenarios de uso de una funcionalidad (por ejemplo, manual vs. automático, éxito vs. fallo)
┌─────────────────────────────────────────────────────────────────────┐
│ Nombre de la funcionalidad (ej. ciclo de vida │
│ de gestión de límites) │
└─────────────────────────────────────────────────────────────────────┘
═══════════════════════════════════════════════════════════════════════
Escenario 1: Nombre del escenario (ej. consulta automática de estado de límite)
═══════════════════════════════════════════════════════════════════════
Comando del usuario
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ uv run python -m src.cli.xxx ... │
└────────────────┬────────────────────────────────────────────────┘
│
▼
┌────────────────┐
│ Capa CLI │ Llama a la función Flow
│ _do_xxx() │ ────────────────────┐
└────────────────┘ │
▼
┌──────────────────────────┐
│ Capa Flow │
│ xxx_flow() │
└───────┬──────────────────┘
│
▼
┌─────────────────────────────┐
│ Capa Datos │
│ XxxRepo / XxxClient │
└────────┬─────────────────────┘
│
▼
┌────────────────────────────┐
│ Sistema externo / BD │
│ (SQLite / API / etc) │
└──────────┬─────────────────┘
│ Devuelve datos
▼
┌──────────────────────────────────┐
│ Procesamiento de datos │
│ (parseo/conversión) │
└─────────────┬────────────────────┘
│
▼
┌──────────────────────┐
│ Clase de datos de │ ← Explica por qué se conserva/simplifica
│ retorno │
│ (Result / Item / ...)│
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ Salida formateada │
│ de la capa CLI │
└──────────────────────┘
│
▼
╔══════════════════════════════════════════════════╗
║ Ejemplo de salida en terminal ║
║ (rodeado con bordes, destacando el efecto ║
║ visible para el usuario final) ║
╚══════════════════════════════════════════════════╝
═══════════════════════════════════════════════════════════════════════
Escenario 2: Otro escenario
═══════════════════════════════════════════════════════════════════════
(Repetir la estructura anterior, destacando las diferencias)
2. Explicación de estructura de tabla de base de datos
Adecuado para: explicar las tablas de base de datos involucradas en una funcionalidad
CREATE TABLE table_name (
id INTEGER PRIMARY KEY AUTOINCREMENT, -- ← Explica la función de la clave primaria
field1 TEXT NOT NULL, -- Explica el significado del campo
field2 TEXT, -- Significado de NULL
...
);
-- Índices (explica por qué se necesita este índice)
CREATE INDEX idx_xxx ON table_name(field1, field2);
Tabla de datos de ejemplo:
| id | field1 | field2 | field3 | Descripción |
|---|---|---|---|---|
| 42 | valor1 | valor2 | valor3 | Explica el significado de negocio de este registro |
| 43 | ... | ... | ... | ... |
Consultas típicas:
-- Explicación del escenario: ¿cuándo se necesita esta consulta?
SELECT * FROM table_name
WHERE condition1 = ?
AND (condition2 IS NULL OR condition2 >= ?);
3. Diagrama simplificado de cadena de llamadas en capas
Adecuado para: explicar rápidamente la relación de llamadas entre funciones
Capa CLI (_do_xxx)
│
└─> Capa Flow (xxx_flow)
│
├─> Datos/Repo (xxx_repo.get)
│ │
│ └─> SQLite (SELECT ...)
│
└─> Datos/Client (xxx_client.fetch)
│
└─> API externa (HTTP GET ...)
4. Tabla de análisis de diseño de clases de datos
Adecuado para: evaluar si las clases de datos intermedias son necesarias
| Nombre de clase | Nº de campos | Propósito | Decisión | Motivo |
|---|---|---|---|---|
XxxResult | 6 | Agregación de múltiples campos + visualización en CLI | ✅ Conservar | Satisface el "principio de mínima necesidad" |
XxxWrapper | 1 | Envoltorio de un solo campo | ❌ Eliminar | Envoltorio excesivo, devolver directamente el tipo original |
XxxItem | 3 | Elemento de detalle de lista | ✅ Conservar | Tiene semántica de negocio |
Ejemplo comparativo:
# ❌ Envoltorio excesivo
@dataclass
class XxxResult:
field: SomeType # Solo un campo
def xxx_flow() -> XxxResult:
return XxxResult(field=value)
# ✅ Simplificado
def xxx_flow() -> SomeType: # Devuelve directamente
return value
5. Anotaciones de puntos clave de negocio
Adecuado para: destacar reglas de negocio y decisiones de diseño
┌─────────────────────────────────────────────────────────────┐
│ Puntos clave de negocio │
├──────────────────────┬──────────────────────────────────────┤
│ ¿Por qué diseñado │ Decisión específica │
│ así? │ │
├──────────────────────┼──────────────────────────────────────┤
│ • Precisión de datos │ Montos con Decimal, 2 decimales │
│ • Idempotencia │ Restricción única por (fund_code, │
│ │ date) │
│ • Trazabilidad │ record_id como identificador único │
│ │ global │
└──────────────────────┴──────────────────────────────────────┘
Método de uso
Paso 1: Determinar el objetivo del análisis
Responda las siguientes preguntas:
- ¿De qué funcionalidad quiere conocer el flujo el usuario?
- ¿Cuántos escenarios tiene esta funcionalidad? (éxito/fallo, manual/automático, etc.)
- ¿Qué capas están involucradas? (CLI → Flow → Data → DB/API)
- ¿Cuáles son las clases de datos clave? ¿Por qué están diseñadas así?
Paso 2: Seleccionar la plantilla adecuada
- Comparación de múltiples escenarios → Plantilla 1 (diagrama de flujo completo)
- Flujo único → Plantilla 3 (diagrama de llamadas en capas)
- Diseño de base de datos → Plantilla 2 (estructura de tabla + datos de ejemplo)
- Evaluación de clases de datos → Plantilla 4 (tabla de análisis)
Paso 3: Rellenar el contenido
Principios:
- Usar diagramas ASCII en lugar de texto extenso
- Usar flechas (
│ ▼ ┐ ┘ └ ├ ─) para conectar los flujos de datos - Usar bordes (
┌ ┐ └ ┘ │ ─) para separar capas - Usar bordes dobles (
╔ ╗ ╚ ╝ ║ ═) para destacar partes visibles al usuario - Añadir comentarios en nodos clave (
← Explicación)
Normas de uso de símbolos:
| Símbolo | Propósito | Ejemplo |
|---|---|---|
│ ▼ | Flujo vertical | Datos de arriba a abajo |
→ ← | Explicación horizontal | record_id: int ← Clave primaria de BD |
┌ ┐ └ ┘ | Bordes simples | Rodear bloques de código, comandos |
╔ ╗ ╚ ╝ | Bordes dobles | Destacar salida de terminal, resultados importantes |
═══ | Línea de separación | Separar diferentes escenarios |
Paso 4: Añadir análisis comparativo
Antes vs. Después (escenario de refactorización):
# Antes (versión problemática)
...código...
# Problemas:
# - Envoltorio excesivo
# - Campos redundantes
# - Aumenta la carga cognitiva
# Después (versión mejorada)
...código...
# Mejoras:
# - Devuelve directamente tipos significativos
# - Reduce capas intermedias
# - Reduce costos de mantenimiento
Ejemplos reales
Ejemplo 1: Flujo de gestión de límites (versión completa)
(Vea el ejemplo de la plantilla 1 anterior, con el flujo completo de 4 escenarios)
Ejemplo 2: Evaluación de clases de datos (módulo fund_restriction)
| Función | Retorno anterior | Retorno actual | Decisión | Motivo |
|---|---|---|---|---|
add_restriction | AddRestrictionResult (6 campos) | Conservar | ✅ | CLI necesita mostrar todos los campos |
end_restriction | EndRestrictionResult (4 campos) | bool | ❌ | Solo necesita éxito/fallo |
check_trading_status | CheckStatusResult (2 campos) | ParsedRestriction | None | ❌ | Es solo un envoltorio simple |
Lista de verificación de salida (Checklist)
Al generar documentación de visualización de flujo, asegúrese de incluir:
- Resumen de alto nivel (objetivo de la funcionalidad, módulos involucrados)
- Enumeración de escenarios (éxito/fallo, manual/automático, etc.)
- Diagrama de flujo por capas (CLI → Flow → Data → Externo)
- Estructura de tabla de base de datos (si aplica)
- Datos de ejemplo y consultas (para ayudar a la comprensión)
- Explicación de clases de datos clave (por qué se conservan/simplifican)
- Motivos de diseño (¿por qué se hizo así?)
- Puntos de extensión futura (TODO o interfaces reservadas)
Antipatrones (NO hacer esto)
❌ Descripción del flujo puramente textual
Primero se llama a la función _do_xxx de la capa CLI, luego _do_xxx llama a la función xxx_flow de la capa Flow,
xxx_flow luego llama al método xxx_repo.get de la capa Datos...
✅ Usar diagrama ASCII
CLI (_do_xxx) → Flow (xxx_flow) → Datos (xxx_repo.get) → SQLite
❌ Tabla sin puntos destacados
| Campo | Tipo |
|---|---|
| id | int |
| name | str |
✅ Destacar significado de negocio
| Campo | Tipo | Descripción | Restricción de negocio |
|---|---|---|---|
| id | int | Clave primaria | Generado automáticamente, único global |
| name | str | Nombre del fondo | No nulo, usado para visualización |
❌ SQL sin explicación del escenario
SELECT * FROM table WHERE id = ?;
✅ Con escenario de negocio
-- Escenario: El usuario consulta los detalles de un registro de restricción específico
SELECT * FROM fund_restrictions WHERE id = ?;
-- Escenario: Al realizar análisis DCA, verificar si un día tiene límite
SELECT * FROM fund_restrictions
WHERE fund_code = ? AND start_date <= ? AND (end_date IS NULL OR end_date >= ?);
Colaboración con otros Skills
- code-style: Seguir las normas de codificación al mostrar ejemplos de código
- architecture: Los diagramas de flujo deben cumplir con las restricciones de la arquitectura de capas
- dev-workflow: Leer el código y la documentación relevantes antes de analizar el flujo
Resumen
El valor fundamental de este Skill:
- Plantillas reutilizables: reduce el tiempo de empezar desde cero
- Estilo visual unificado: diagrama ASCII + tabla + bordes
- Perspectiva de negocio: no solo el flujo de código, sino también el "por qué"
- Análisis comparativo: antes/después de refactorización, comparación de múltiples escenarios
- Verificación con lista: asegura no omitir información clave
Frecuencia de uso: Cada vez que sea necesario explicar "cómo funciona una funcionalidad".