Code Flow Visualization Standards
This Skill provides a set of reusable templates and methods for organizing code flows and generating visual documentation.
Core Principle: Use text and ASCII diagrams to clearly explain "where does the data come from, which layers does it pass through, and where does it end up."
When to Use
Use this skill in the following scenarios:
- The user asks "how does a certain feature work"
- A new feature requires data flow design
- Refactoring requires auditing existing logic
- Writing technical documentation or architecture explanations
- Code review requires visualizing the call chain
Core Templates
1. Complete Flowchart (Multi-Scenario Comparison)
Suitable for: Organizing multiple usage scenarios of a feature (e.g., manual vs. automatic, success vs. failure)
┌─────────────────────────────────────────────────────────────────────┐
│ Feature Name (e.g., Full Limit Management Lifecycle) │
└─────────────────────────────────────────────────────────────────────┘
═══════════════════════════════════════════════════════════════════════
Scenario 1: Scenario Name (e.g., Automatically Query Limit Status)
═══════════════════════════════════════════════════════════════════════
User Command
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ uv run python -m src.cli.xxx ... │
└────────────────┬────────────────────────────────────────────────┘
│
▼
┌────────────────┐
│ CLI Layer │ Call Flow Function
│ _do_xxx() │ ────────────────────┐
└────────────────┘ │
▼
┌──────────────────────────┐
│ Flow Layer │
│ xxx_flow() │
└───────┬──────────────────┘
│
▼
┌─────────────────────────────┐
│ Data Layer │
│ XxxRepo / XxxClient │
└────────┬─────────────────────┘
│
▼
┌────────────────────────────┐
│ External System / Database │
│ (SQLite / API / etc) │
└──────────┬─────────────────┘
│ Return Data
▼
┌──────────────────────────────────┐
│ Data Processing (Parse/Transform) │
└─────────────┬────────────────────┘
│
▼
┌──────────────────────┐
│ Return Value Data Class │ ← Explain why kept/simplified
│ (Result / Item / ...)│
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ CLI Layer Formatted Output│
└──────────────────────┘
│
▼
╔══════════════════════════════════════════════════╗
║ Terminal Output Example ║
║ (Use box borders to highlight what the end user sees) ║
╚══════════════════════════════════════════════════╝
═══════════════════════════════════════════════════════════════════════
Scenario 2: Another Scenario
═══════════════════════════════════════════════════════════════════════
(Repeat the above structure, highlighting differences)
2. Database Table Structure Explanation
Suitable for: Explaining database tables involved in a feature
CREATE TABLE table_name (
id INTEGER PRIMARY KEY AUTOINCREMENT, -- ← Explain primary key purpose
field1 TEXT NOT NULL, -- Explain field meaning
field2 TEXT, -- Business meaning of NULL
...
);
-- Index (explain why this index is needed)
CREATE INDEX idx_xxx ON table_name(field1, field2);
Example Data Table:
| id | field1 | field2 | field3 | Description |
|---|---|---|---|---|
| 42 | value1 | value2 | value3 | Explain the business meaning of this record |
| 43 | ... | ... | ... | ... |
Typical Queries:
-- Scenario explanation: When is this query needed?
SELECT * FROM table_name
WHERE condition1 = ?
AND (condition2 IS NULL OR condition2 >= ?);
3. Layered Call Chain Diagram (Simplified)
Suitable for: Quickly explaining function call relationships
CLI Layer (_do_xxx)
│
└─> Flow Layer (xxx_flow)
│
├─> Data/Repo (xxx_repo.get)
│ │
│ └─> SQLite (SELECT ...)
│
└─> Data/Client (xxx_client.fetch)
│
└─> External API (HTTP GET ...)
4. Data Class Design Analysis Table
Suitable for: Evaluating whether intermediate data classes are necessary
| Class Name | Number of Fields | Purpose | Verdict | Reason |
|---|---|---|---|---|
XxxResult | 6 | Multi-field aggregation + CLI display | ✅ Keep | Satisfies "minimum necessary principle" |
XxxWrapper | 1 | Single-field wrapper | ❌ Remove | Over-wrapping, return raw type directly |
XxxItem | 3 | List detail item | ✅ Keep | Has business semantics |
Comparison Example:
# ❌ Over-wrapping
@dataclass
class XxxResult:
field: SomeType # Only one field
def xxx_flow() -> XxxResult:
return XxxResult(field=value)
# ✅ Simplified
def xxx_flow() -> SomeType: # Return directly
return value
5. Business Key Point Annotations
Suitable for: Highlighting business rules and design decisions
┌─────────────────────────────────────────────────────────────┐
│ Business Key Points │
├──────────────────────┬──────────────────────────────────────┤
│ Why was it designed this way? │ Specific Decision │
├──────────────────────┼──────────────────────────────────────┤
│ • Data Precision │ Monetary values use Decimal, 2 decimals│
│ • Idempotency │ Unique constraint on (fund_code, date)│
│ • Traceability │ record_id as global unique identifier │
└──────────────────────┴──────────────────────────────────────┘
Usage Instructions
Step 1: Define the Analysis Goal
Answer these questions:
- Which feature's flow does the user want to understand?
- How many scenarios does this feature have? (success/failure, manual/automatic, etc.)
- Which layers are involved? (CLI → Flow → Data → DB/API)
- What are the key data classes? Why are they designed this way?
Step 2: Choose the Appropriate Template
- Multi-scenario comparison → Template 1 (Complete flowchart)
- Single flow → Template 3 (Layered call chain)
- Database design → Template 2 (Table structure + example data)
- Data class evaluation → Template 4 (Analysis table)
Step 3: Fill in the Content
Guidelines:
- Use ASCII diagrams instead of long text descriptions
- Use arrows (
│ ▼ ┐ ┘ └ ├ ─) to connect data flows - Use box borders (
┌ ┐ └ ┘ │ ─) to separate layers - Use double-line boxes (
╔ ╗ ╚ ╝ ║ ═) to highlight user-visible parts - Add comments at key nodes (
← explanation)
Symbol Usage Conventions:
| Symbol | Purpose | Example |
|---|---|---|
│ ▼ | Vertical flow | Data from top to bottom |
→ ← | Horizontal explanation | record_id: int ← Database primary key |
┌ ┐ └ ┘ | Single-line box | Surround code blocks, commands |
╔ ╗ ╚ ╝ | Double-line box | Highlight terminal output, important results |
═══ | Separator line | Separate different scenarios |
Step 4: Add Comparison Analysis
Before vs After (refactoring scenario):
# Before (problematic version)
...code...
# Issues:
# - Over-wrapping
# - Redundant fields
# - Increased cognitive load
# After (improved version)
...code...
# Improvements:
# - Directly return meaningful types
# - Reduce intermediate layers
# - Lower maintenance cost
Practical Examples
Example 1: Limit Management Flow (Full Version)
(See template 1 example above, expand all 4 scenarios with complete flows)
Example 2: Data Class Evaluation (fund_restriction module)
| Function | Previous Return | Current Return | Verdict | Reason |
|---|---|---|---|---|
add_restriction | AddRestrictionResult (6 fields) | Keep | ✅ | CLI needs all fields displayed |
end_restriction | EndRestrictionResult (4 fields) | bool | ❌ | Only success/failure needed |
check_trading_status | CheckStatusResult (2 fields) | ParsedRestriction | None | ❌ | Simple wrapper |
Output Checklist
When generating flow visualization documentation, ensure it includes:
- Top-level overview (feature goal, modules involved)
- Scenario enumeration (success/failure, manual/automatic, etc.)
- Layered flowchart (CLI → Flow → Data → External)
- Database table structure (if applicable)
- Example data and queries (for understanding)
- Key data class explanation (why kept/simplified)
- Design reasoning (why was it done this way?)
- Future extension points (TODO or reserved interfaces)
Anti-Patterns (Avoid Doing This)
❌ Pure textual description of flow
First, call the CLI layer's _do_xxx function, then _do_xxx calls the Flow layer's xxx_flow function,
xxx_flow then calls the Data layer's xxx_repo.get method...
✅ Use ASCII diagrams
CLI (_do_xxx) → Flow (xxx_flow) → Data (xxx_repo.get) → SQLite
❌ Tables without emphasis
| Field | Type |
|---|---|
| id | int |
| name | str |
✅ Highlight business meaning
| Field | Type | Description | Business Constraint |
|---|---|---|---|
| id | int | Primary key | Auto-generated, globally unique |
| name | str | Fund name | Non-null, used for display |
❌ SQL without scenario explanation
SELECT * FROM table WHERE id = ?;
✅ With business scenario
-- Scenario: User queries details of a specific restriction record
SELECT * FROM fund_restrictions WHERE id = ?;
-- Scenario: Check if a specific day is restricted during DCA analysis
SELECT * FROM fund_restrictions
WHERE fund_code = ? AND start_date <= ? AND (end_date IS NULL OR end_date >= ?);
Collaboration with Other Skills
- code-style: Adhere to coding standards when outputting code examples
- architecture: Flowcharts must comply with layered architecture constraints
- dev-workflow: Read relevant code and documentation before organizing flows
Summary
Core value of this skill:
- Reusable templates: Reduces time starting from scratch
- Unified visual style: ASCII diagrams + tables + box borders
- Business perspective: Not just code flow, but focusing on "why"
- Comparison analysis: Before/after refactoring, multi-scenario comparison
- Checklist review: Ensures no key information is missed
Usage Frequency: Use whenever you need to explain "how a certain feature works."