Especificación de Visualización de Flujos de Código
Esta habilidad proporciona un conjunto de plantillas reutilizables y metodologías para analizar flujos de código y generar documentación visual.
Principio fundamental: Explicar claramente con texto y diagramas ASCII "de dónde vienen los datos, por qué capas pasan y a dónde van finalmente".
Cuándo usar
Utilice esta habilidad en los siguientes escenarios:
- El usuario pregunta "¿cómo funciona esta funcionalidad?"
- Se necesita diseñar el flujo de datos para una nueva funcionalidad
- Se requiere analizar la lógica existente antes de una refactorización
- Se está escribiendo documentación técnica o explicaciones de arquitectura
- Se necesita visualizar la cadena de llamadas durante una revisión de código
Plantillas principales
1. Diagrama de flujo completo (comparación de múltiples escenarios)
Adecuado para: Analizar múltiples escenarios de uso de una funcionalidad (ej. manual vs automático, éxito vs fallo)
┌─────────────────────────────────────────────────────────────────────┐
│ Nombre de la funcionalidad (ej. Ciclo de vida │
│ de la gestión de límites) │
└─────────────────────────────────────────────────────────────────────┘
═══════════════════════════════════════════════════════════════════════
Escenario 1: Nombre del escenario (ej. Consulta automática del estado del 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 de Datos │
│ XxxRepo / XxxClient │
└────────┬─────────────────────┘
│
▼
┌────────────────────────────┐
│ Sistema externo / Base de │
│ datos (SQLite / API / etc)│
└──────────┬─────────────────┘
│ Devuelve datos
▼
┌──────────────────────────────────┐
│ Procesamiento de datos │
│ (análisis/transformación) │
└─────────────┬────────────────────┘
│
▼
┌──────────────────────┐
│ Clase de datos de │ ← Explicar por qué se mantiene/simplifica
│ retorno (Result / │
│ Item / ...) │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ Salida formateada │
│ de la capa CLI │
└──────────────────────┘
│
▼
╔══════════════════════════════════════════════════╗
║ Ejemplo de salida en terminal ║
║ (Rodeado con bordes dobles para resaltar ║
║ el efecto visible para el usuario final) ║
╚══════════════════════════════════════════════════╝
═══════════════════════════════════════════════════════════════════════
Escenario 2: Otro escenario
═══════════════════════════════════════════════════════════════════════
(Repetir la estructura anterior, destacando las diferencias)
2. Descripción de la estructura de la tabla de base de datos
Adecuado para: Explicar las tablas de base de datos involucradas en una funcionalidad
CREATE TABLE nombre_tabla (
id INTEGER PRIMARY KEY AUTOINCREMENT, -- ← Explicar el propósito de la clave primaria
campo1 TEXT NOT NULL, -- Explicar el significado del campo
campo2 TEXT, -- Significado de NULL en el negocio
...
);
-- Índice (explicar por qué es necesario)
CREATE INDEX idx_xxx ON nombre_tabla(campo1, campo2);
Tabla de datos de ejemplo:
| id | campo1 | campo2 | campo3 | Descripción |
|---|---|---|---|---|
| 42 | valor1 | valor2 | valor3 | Explicar el significado de este registro en el negocio |
| 43 | ... | ... | ... | ... |
Consultas típicas:
-- Descripción del escenario: ¿Cuándo es necesaria esta consulta?
SELECT * FROM nombre_tabla
WHERE condicion1 = ?
AND (condicion2 IS NULL OR condicion2 >= ?);
3. Diagrama de cadena de llamadas en capas (versión simplificada)
Adecuado para: Explicar rápidamente las relaciones de llamada entre funciones
Capa CLI (_do_xxx)
│
└─> Capa Flow (xxx_flow)
│
├─> Datos/Repo (xxx_repo.get)
│ │
│ └─> SQLite (SELECT ...)
│
└─> Datos/Cliente (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úmero de campos | Propósito | Decisión | Motivo |
|---|---|---|---|---|
XxxResult | 6 | Agregación de múltiples campos + visualización en CLI | ✅ Mantener | Satisface el "principio de mínima necesidad" |
XxxWrapper | 1 | Envoltura de un solo campo | ❌ Eliminar | Envoltura excesiva, devolver el tipo original directamente |
XxxItem | 3 | Elemento de detalle de lista | ✅ Mantener | Tiene semántica de negocio |
Ejemplo de comparación:
# ❌ Envoltura excesiva
@dataclass
class XxxResult:
campo: SomeType # Solo un campo
def xxx_flow() -> XxxResult:
return XxxResult(campo=valor)
# ✅ Simplificado
def xxx_flow() -> SomeType: # Devolver directamente
return valor
5. Anotación de puntos clave del negocio
Adecuado para: Resaltar reglas de negocio y decisiones de diseño
┌─────────────────────────────────────────────────────────────┐
│ Puntos clave del negocio │
├──────────────────────┬──────────────────────────────────────┤
│ ¿Por qué está │ Decisión específica │
│ diseñado 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 │
└──────────────────────┴──────────────────────────────────────┘
Cómo usar
Paso 1: Determinar el objetivo del análisis
Responda las siguientes preguntas:
- ¿Qué funcionalidad quiere entender el usuario?
- ¿Cuántos escenarios tiene esta funcionalidad? (éxito/fallo, manual/automático, etc.)
- ¿Qué capas están involucradas? (CLI → Flow → Datos → 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 (Cadena 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: Completar el contenido
Principios:
- Use diagramas ASCII en lugar de texto extenso
- Use flechas (
│ ▼ ┐ ┘ └ ├ ─) para conectar el flujo de datos - Use bordes (
┌ ┐ └ ┘ │ ─) para separar capas - Use bordes dobles (
╔ ╗ ╚ ╝ ║ ═) para resaltar partes visibles para el usuario - Agregue comentarios en los nodos clave (
← Descripció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 |
┌ ┐ └ ┘ | Borde simple | Rodear bloques de código, comandos |
╔ ╗ ╚ ╝ | Borde doble | Resaltar salida de terminal, resultados importantes |
═══ | Línea separadora | Separar diferentes escenarios |
Paso 4: Agregar análisis comparativo
Antes vs Después (escenario de refactorización):
# Antes (versión problemática)
...código...
# Problemas:
# - Envoltura excesiva
# - 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)
(Véase el ejemplo de la Plantilla 1 anterior, desarrolle 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) | Mantener | ✅ | La CLI necesita mostrar todos los campos |
end_restriction | EndRestrictionResult(4 campos) | bool | ❌ | Solo necesita éxito/fallo |
check_trading_status | CheckStatusResult(2 campos) | ParsedRestriction | None | ❌ | Envoltura simple |
Lista de verificación (Checklist)
Al generar un documento 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 en capas (CLI → Flow → Datos → Externo)
- Estructura de tabla de base de datos (si aplica)
- Datos de ejemplo y consultas (para ayudar a la comprensión)
- Explicación de las clases de datos clave (por qué se mantienen/simplifican)
- Razones 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 solo con texto
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,
y xxx_flow llama al método xxx_repo.get de la capa de Datos...
✅ Usar diagramas ASCII
CLI (_do_xxx) → Flow (xxx_flow) → Datos (xxx_repo.get) → SQLite
❌ Tabla sin enfoque
| Campo | Tipo |
|---|---|
| id | int |
| name | str |
✅ Resaltar el significado de negocio
| Campo | Tipo | Descripción | Restricción de negocio |
|---|---|---|---|
| id | int | Clave primaria | Autogenerado, único global |
| name | str | Nombre del fondo | No nulo, para visualización |
❌ SQL sin descripción del escenario
SELECT * FROM tabla WHERE id = ?;
✅ Con escenario de negocio
-- Escenario: El usuario consulta los detalles de un registro de restricción
SELECT * FROM fund_restrictions WHERE id = ?;
-- Escenario: Durante el análisis DCA, verificar si una fecha está limitada
SELECT * FROM fund_restrictions
WHERE fund_code = ? AND start_date <= ? AND (end_date IS NULL OR end_date >= ?);
Colaboración con otras habilidades
- code-style: Seguir las normas de codificación al mostrar ejemplos de código
- architecture: El diagrama de flujo debe cumplir con las restricciones de la arquitectura en capas
- dev-workflow: Leer el código y la documentación relevantes antes de analizar el flujo
Resumen
El valor fundamental de esta habilidad:
- Plantillas reutilizables: Reduce el tiempo de empezar desde cero
- Estilo visual unificado: Diagramas ASCII + tablas + bordes
- Perspectiva de negocio: No solo el flujo de código, sino también el "por qué"
- Análisis comparativo: Comparación antes/después, múltiples escenarios
- Lista de verificación: Asegura que no se omita información clave
Frecuencia de uso: Se puede usar siempre que sea necesario explicar "cómo funciona una funcionalidad".