Normas de Visualização de Fluxo de Código
Esta Skill fornece um conjunto de modelos e métodos reutilizáveis para organizar fluxos de código e gerar documentação visual.
Princípio Central: Use texto e diagramas ASCII para explicar claramente "de onde os dados vêm, por quais camadas passam e para onde vão".
Quando usar
Use esta Skill nos seguintes cenários:
- O usuário pergunta "como esta funcionalidade funciona"
- Uma nova funcionalidade precisa de um design de fluxo de dados
- Precisa organizar a lógica existente antes de uma refatoração
- Escrever documentação técnica ou explicações de arquitetura
- Revisão de código que requer visualização da cadeia de chamadas
Modelos Principais
1. Fluxograma Completo (Comparação de Múltiplos Cenários)
Adequado para: Organizar múltiplos cenários de uso de uma funcionalidade (ex: manual vs automático, sucesso vs falha)
┌─────────────────────────────────────────────────────────────────────┐
│ Nome da Funcionalidade (ex: Ciclo de Vida 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 Função Flow
│ _do_xxx() │ ────────────────────┐
└────────────────┘ │
▼
┌──────────────────────────┐
│ Camada Flow │
│ xxx_flow() │
└───────┬──────────────────┘
│
▼
┌─────────────────────────────┐
│ Camada Data │
│ XxxRepo / XxxClient │
└────────┬─────────────────────┘
│
▼
┌────────────────────────────┐
│ Sistema Externo / Banco de Dados │
│ (SQLite / API / etc) │
└──────────┬─────────────────┘
│ Retorna Dados
▼
┌──────────────────────────────────┐
│ Processamento de Dados (Parse/Transformação)│
└─────────────┬────────────────────┘
│
▼
┌──────────────────────┐
│ Classe de Dados de Retorno│ ← Explica por que manter/simplificar
│ (Result / Item / ...)│
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ Saída Formatada pela Camada CLI │
└──────────────────────┘
│
▼
╔══════════════════════════════════════════════════╗
║ Exemplo de Saída no Terminal ║
║ (Delimitado por bordas, destacando o efeito visto pelo usuário final) ║
╚══════════════════════════════════════════════════╝
═══════════════════════════════════════════════════════════════════════
Cenário 2: Outro Cenário
═══════════════════════════════════════════════════════════════════════
(Repita a estrutura acima, destacando as diferenças)
2. Descrição da Estrutura da 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 de negócio de NULL
...
);
-- Índice (Explica por que este í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 de negócio deste registro |
| 43 | ... | ... | ... | ... |
Consulta Típica:
-- Explicação do cenário: Quando precisamos consultar assim?
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 as relações de chamada de funções
Camada CLI (_do_xxx)
│
└─> Camada Flow (xxx_flow)
│
├─> Data/Repo (xxx_repo.get)
│ │
│ └─> SQLite (SELECT ...)
│
└─> Data/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 | Propósito | Decisão | Motivo |
|---|---|---|---|---|
XxxResult | 6 | Agregação de múltiplos campos + Exibição no 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 lista de detalhes | ✅ Manter | Tem 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)
# ✅ Simplificado
def xxx_flow() -> SomeType: # Retorna diretamente
return valor
5. Marcação de Pontos-Chave de Negócio
Adequado para: Destacar regras de negócio e decisões de design
┌─────────────────────────────────────────────────────────────┐
│ Pontos-Chave de Negócio │
├──────────────────────┬──────────────────────────────────────┤
│ Por que projetado assim? │ Decisão Específica │
├──────────────────────┼──────────────────────────────────────┤
│ • Precisão de dados │ Valores monetários usam Decimal, 2 casas decimais │
│ • Idempotência │ Restrição única por (fund_code, date) │
│ • Rastreabilidade │ record_id como identificador único global │
└──────────────────────┴──────────────────────────────────────┘
Modo de Usar
Etapa 1: Definir o Objetivo da Análise
Responda às seguintes perguntas:
- O usuário quer entender o fluxo de qual funcionalidade?
- Esta 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 chave? Por que foram projetadas assim?
Etapa 2: Escolher o Modelo Apropriado
- Comparação de múltiplos cenários → Modelo 1 (Fluxograma Completo)
- Fluxo único → Modelo 3 (Diagrama de Cadeia 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 bordas (
┌ ┐ └ ┘ │ ─) para separar camadas - Use bordas duplas (
╔ ╗ ╚ ╝ ║ ═) para destacar partes visíveis ao usuário - Adicione comentários nos pontos-chave (
← Descrição)
Normas de Uso de Símbolos:
| Símbolo | Propósito | Exemplo |
|---|---|---|
│ ▼ | Fluxo vertical | Dados de cima para baixo |
→ ← | Descrição horizontal | record_id: int ← Chave primária do banco |
┌ ┐ └ ┘ | Borda simples | Para envolver blocos de código, comandos |
╔ ╗ ╚ ╝ | Borda dupla | Destacar saída do terminal, resultados importantes |
═══ | Linha separadora | Separar diferentes cenários |
Etapa 4: Adicionar Análise Comparativa
Antes vs Depois (cenário de refatoração):
# Antes (versão com problemas)
...código...
# Problemas:
# - Empacotamento excessivo
# - Campos redundantes
# - Aumenta a carga cognitiva
# Depois (versão melhorada)
...código...
# Melhorias:
# - Retorna diretamente um tipo significativo
# - Reduz camadas intermediárias
# - Diminui custo de manutenção
Casos Práticos
Caso 1: Fluxo de Gestão de Limites (Versão Completa)
(Veja o exemplo do Modelo 1 acima, expandindo o fluxo completo para 4 cenários)
Caso 2: Avaliação de Classes de Dados (módulo fund_restriction)
| Função | Retorno Anterior | Retorno Agora | Decisão | Motivo |
|---|---|---|---|---|
add_restriction | AddRestrictionResult(6 campos) | Manter | ✅ | CLI precisa exibir todos os campos |
end_restriction | EndRestrictionResult(4 campos) | bool | ❌ | Precisa apenas 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 da tabela do banco de dados (se aplicável)
- Dados de exemplo e consultas (para ajudar no entendimento)
- Descrição das classes de dados chave (por que manter/simplificar)
- Motivo do design (por que foi feito assim?)
- Pontos de extensão futura (TODO ou interfaces reservadas)
Antipadrões (Não Faça Isso)
❌ Descrição puramente textual do fluxo
Primeiro, a função _do_xxx da camada CLI é chamada, então _do_xxx chama a função xxx_flow da camada Flow,
xxx_flow então chama o método xxx_repo.get da camada Data...
✅ Use diagramas ASCII
CLI (_do_xxx) → Flow (xxx_flow) → Data (xxx_repo.get) → SQLite
❌ Tabela sem foco
| Campo | Tipo |
|---|---|
| id | int |
| name | str |
✅ Destaque o significado de negócio
| Campo | Tipo | Descrição | Restrição de Negócio |
|---|---|---|---|
| id | int | Chave primária | Gerado automaticamente, único global |
| name | str | Nome do fundo | Não nulo, usado para exibição |
❌ SQL sem explicação do cenário
SELECT * FROM tabela WHERE id = ?;
✅ Com cenário 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 verifica 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 Outras Skills
- code-style: Siga as normas de codificação ao fornecer exemplos de código
- architecture: Os fluxogramas devem respeitar as restrições da arquitetura em camadas
- dev-workflow: Leia o código e a documentação relevantes antes de organizar o fluxo
Resumo
O valor central desta 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 de código, mas focar no "porquê"
- Análise comparativa: Comparação antes/depois, múltiplos cenários
- Verificação por lista: Garante que informações-chave não sejam perdidas
Frequência de uso: Pode ser usada sempre que for necessário explicar "como uma funcionalidade funciona".