Normas de Visualização de Fluxo de Código
Este Skill fornece um conjunto de modelos reutilizáveis e metodologias para organizar fluxos de código e gerar documentação visual.
Princípio central: Explicar claramente com texto e diagramas ASCII "de onde os dados vêm, por quais camadas passam e para onde vão".
Quando usar
Use este Skill nos seguintes cenários:
- O usuário pergunta "como essa funcionalidade funciona"
- Uma nova funcionalidade precisa de design de fluxo de dados
- Antes de uma refatoração, para organizar a lógica existente
- Ao escrever documentação técnica ou explicações de arquitetura
- Durante revisões de código, para visualizar a cadeia de chamadas
Modelos Principais
1. Fluxograma Completo (Comparação de Múltiplos Cenários)
Adequado para: Organizar vários cenários de uso de uma funcionalidade (ex: manual vs. automático, sucesso vs. falha)
┌─────────────────────────────────────────────────────────────────────┐
│ Nome da Funcionalidade (ex: Ciclo de Vida Completo da Gestão de Limites) |
└─────────────────────────────────────────────────────────────────────┘
═══════════════════════════════════════════════════════════════════════
Cenário 1: Nome do Cenário (ex: Consulta Automática do Status do Limite)
═══════════════════════════════════════════════════════════════════════
Comando do Usuário
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ uv run python -m src.cli.xxx ... │
└────────────────┬────────────────────────────────────────────────┘
│
▼
┌────────────────┐
│ Camada CLI │ Chama a função Flow
│ _do_xxx() │ ────────────────────┐
└────────────────┘ │
▼
┌──────────────────────────┐
│ Camada Flow │
│ xxx_flow() │
└───────┬──────────────────┘
│
▼
┌─────────────────────────────┐
│ Camada de Dados │
│ XxxRepo / XxxClient │
└────────┬─────────────────────┘
│
▼
┌────────────────────────────┐
│ Sistema Externo / Banco │
│ (SQLite / API / etc) │
└──────────┬─────────────────┘
│ Retorna dados
▼
┌──────────────────────────────────┐
│ Processamento de Dados (Parsing/Transformação)│
└─────────────┬────────────────────┘
│
▼
┌──────────────────────┐
│ Classe de Dados de │ ← Explica por que manter/simplificar
│ Retorno │
│ (Result / Item / ...)│
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ Saída Formatada pela │
│ Camada CLI │
└──────────────────────┘
│
▼
╔══════════════════════════════════════════════════╗
║ Exemplo de Saída no Terminal ║
║ (Com bordas, destacando o efeito visto ║
║ pelo usuário final) ║
╚══════════════════════════════════════════════════╝
═══════════════════════════════════════════════════════════════════════
Cenário 2: Outro Cenário
═══════════════════════════════════════════════════════════════════════
(Repita a estrutura acima, destacando as diferenças)
2. Explicação da Estrutura de Tabela do Banco de Dados
Adequado para: Explicar as tabelas do banco de dados envolvidas em uma funcionalidade
CREATE TABLE nome_tabela (
id INTEGER PRIMARY KEY AUTOINCREMENT, -- ← Explica o papel da chave primária
campo1 TEXT NOT NULL, -- Explica o significado do campo
campo2 TEXT, -- Significado do NULL no negócio
...
);
-- Índice (Explica por que esse índice é necessário)
CREATE INDEX idx_xxx ON nome_tabela(campo1, campo2);
Tabela de Dados de Exemplo:
| id | campo1 | campo2 | campo3 | Descrição |
|---|---|---|---|---|
| 42 | valor1 | valor2 | valor3 | Explica o significado desta linha no negócio |
| 43 | ... | ... | ... | ... |
Consulta Típica:
-- Contexto do cenário: Quando precisamos fazer essa consulta?
SELECT * FROM nome_tabela
WHERE condicao1 = ?
AND (condicao2 IS NULL OR condicao2 >= ?);
3. Diagrama de Cadeia de Chamadas em Camadas (Versão Simplificada)
Adequado para: Explicar rapidamente a relação de chamadas entre funções
Camada CLI (_do_xxx)
│
└─> Camada Flow (xxx_flow)
│
├─> Dados/Repo (xxx_repo.get)
│ │
│ └─> SQLite (SELECT ...)
│
└─> Dados/Client (xxx_client.fetch)
│
└─> API Externa (HTTP GET ...)
4. Tabela de Análise de Design de Classes de Dados
Adequado para: Avaliar se as classes de dados intermediárias são necessárias
| Nome da Classe | Nº de Campos | Uso | Decisão | Motivo |
|---|---|---|---|---|
XxxResult | 6 | Agregação de múltiplos campos + exibição CLI | ✅ Manter | Atende ao "princípio da necessidade mínima" |
XxxWrapper | 1 | Empacotamento de campo único | ❌ Remover | Empacotamento excessivo; retornar diretamente o tipo original |
XxxItem | 3 | Item de detalhe em lista | ✅ Manter | Possui semântica de negócio |
Exemplo de Comparação:
# ❌ Empacotamento excessivo
@dataclass
class XxxResult:
campo: SomeType # Apenas um campo
def xxx_flow() -> XxxResult:
return XxxResult(campo=valor)
# ✅ Após simplificação
def xxx_flow() -> SomeType: # Retorna diretamente
return valor
5. Destaque de Pontos Críticos de Negócio
Adequado para: Destacar regras de negócio e decisões de design
┌─────────────────────────────────────────────────────────────┐
│ Pontos Críticos de Negócio │
├──────────────────────┬──────────────────────────────────────┤
│ Por que foi desenhado assim? │ Decisão Específica │
├──────────────────────┼──────────────────────────────────────┤
│ • Precisão de dados │ Valores monetários como Decimal, 2 casas decimais│
│ • Idempotência │ Restrição única por (fund_code, date) │
│ • Rastreabilidade │ record_id como identificador único global │
└──────────────────────┴──────────────────────────────────────┘
Método de Uso
Etapa 1: Definir o Objetivo da Análise
Responda às seguintes perguntas:
- O usuário deseja entender o fluxo de qual funcionalidade?
- Essa funcionalidade tem quantos cenários? (Sucesso/Falha, Manual/Automático, etc.)
- Quais camadas estão envolvidas? (CLI → Flow → Data → DB/API)
- Quais são as classes de dados principais? Por que foram desenhadas assim?
Etapa 2: Escolher o Modelo Adequado
- Comparação de múltiplos cenários → Modelo 1 (Fluxograma completo)
- Fluxo único → Modelo 3 (Cadeia de chamadas em camadas)
- Design de banco de dados → Modelo 2 (Estrutura de tabela + dados de exemplo)
- Avaliação de classes de dados → Modelo 4 (Tabela de análise)
Etapa 3: Preencher o Conteúdo
Princípios:
- Use diagramas ASCII em vez de texto longo
- Use setas (
│ ▼ ┐ ┘ └ ├ ─) para conectar o fluxo de dados - Use caixas com bordas (
┌ ┐ └ ┘ │ ─) para separar camadas - Use caixas com bordas duplas (
╔ ╗ ╚ ╝ ║ ═) para destacar partes visíveis ao usuário - Adicione comentários nos nós principais (
← Explicação)
Normas de Uso de Símbolos:
| Símbolo | Uso | Exemplo |
|---|---|---|
│ ▼ | Fluxo vertical | Dados de cima para baixo |
→ ← | Explicação horizontal | record_id: int ← Chave primária do banco |
┌ ┐ └ ┘ | Caixa com borda simples | Cercar blocos de código, comandos |
╔ ╗ ╚ ╝ | Caixa com borda dupla | Destacar saída do terminal, resultados importantes |
═══ | Linha de separação | Separar diferentes cenários |
Etapa 4: Adicionar Análise Comparativa
Antes vs Depois (cenário de refatoração):
# Antes (versão problemática)
...código...
# Problemas:
# - Empacotamento excessivo
# - Campos redundantes
# - Aumenta a carga cognitiva
# Depois (versão melhorada)
...código...
# Melhorias:
# - Retornar tipos com significado direto
# - Reduzir camadas intermediárias
# - Menor custo de manutenção
Exemplos Práticos
Exemplo 1: Fluxo de Gestão de Limites (Versão Completa)
(Veja o exemplo do Modelo 1 acima; expanda o fluxo completo para 4 cenários)
Exemplo 2: Avaliação de Classes de Dados (Módulo fund_restriction)
| Função | Antes Retornava | Agora Retorna | Decisão | Motivo |
|---|---|---|---|---|
add_restriction | AddRestrictionResult(6 campos) | Manter | ✅ | CLI precisa exibir todos os campos |
end_restriction | EndRestrictionResult(4 campos) | bool | ❌ | Só precisa de sucesso/falha |
check_trading_status | CheckStatusResult(2 campos) | ParsedRestriction | None | ❌ | Apenas um empacotamento simples |
Lista de Verificação (Checklist)
Ao gerar documentação de visualização de fluxo, certifique-se de incluir:
- Visão geral do topo (objetivo da funcionalidade, módulos envolvidos)
- Enumeração de cenários (sucesso/falha, manual/automático, etc.)
- Fluxograma em camadas (CLI → Flow → Data → Externo)
- Estrutura de tabelas do banco de dados (se aplicável)
- Dados de exemplo e consultas (para ajudar na compreensão)
- Explicação das classes de dados principais (por que manter/simplificar)
- Razões de design (por que foi feito assim?)
- Pontos de extensão futura (TODO ou interfaces reservadas)
Antipadrões (Não Faça Isso)
❌ Descrever o fluxo apenas com texto
Primeiro chama a função _do_xxx na camada CLI, depois _do_xxx chama a função xxx_flow na camada Flow,
xxx_flow então chama o método xxx_repo.get na camada de Dados...
✅ Usar diagrama ASCII
CLI (_do_xxx) → Flow (xxx_flow) → Dados (xxx_repo.get) → SQLite
❌ Tabela sem foco
| Campo | Tipo |
|---|---|
| id | int |
| nome | str |
✅ Destacar o significado de negócio
| Campo | Tipo | Descrição | Restrição de Negócio |
|---|---|---|---|
| id | int | Chave primária | Gerado automaticamente, único global |
| nome | str | Nome do fundo | Não nulo, usado para exibição |
❌ SQL sem contexto de cenário
SELECT * FROM tabela WHERE id = ?;
✅ Com contexto de negócio
-- Cenário: Usuário consulta detalhes de um registro de restrição
SELECT * FROM fund_restrictions WHERE id = ?;
-- Cenário: Análise DCA para verificar se um dia está com limite
SELECT * FROM fund_restrictions
WHERE fund_code = ? AND start_date <= ? AND (end_date IS NULL OR end_date >= ?);
Colaboração com Outros Skills
- code-style: Siga os padrões de codificação ao exibir exemplos de código
- architecture: O fluxograma deve respeitar as restrições da arquitetura em camadas
- dev-workflow: Antes de organizar o fluxo, leia o código e a documentação relevantes
Resumo
O valor central deste Skill:
- Modelos reutilizáveis: Reduz o tempo de começar do zero
- Estilo visual unificado: Diagramas ASCII + Tabelas + Bordas
- Perspectiva de negócio: Não apenas o fluxo do código, mas também o "porquê"
- Análise comparativa: Antes e depois da refatoração, comparação de múltiplos cenários
- Lista de verificação: Garante que nenhuma informação essencial seja omitida
Frequência de uso: Sempre que for necessário explicar "como uma funcionalidade funciona".