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 data comes from, which layers it passes through, and where it ends up."
When to Use
Use this Skill in the following scenarios:
- The user asks "how does this feature work?"
- Designing data flow for new features
- Reviewing existing logic before refactoring
- Writing technical documentation or architecture descriptions
- Needing to visualize call chains during code review
Core Templates
1. Full Flowchart (Multi-Scenario Comparison)
Best for: Organizing multiple usage scenarios of a feature (e.g., manual vs. automatic, success vs. failure)
┌─────────────────────────────────────────────────────────────────────┐
│ Feature Name (e.g., Limit Management Lifecycle) │
└─────────────────────────────────────────────────────────────────────┘
═══════════════════════════════════════════════════════════════════════
Scenario 1: Scenario Name (e.g., Auto-query Limit Status)
═══════════════════════════════════════════════════════════════════════
User Command
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ uv run python -m src.cli.xxx ... │
└────────────────┬────────────────────────────────────────────────┘
│
▼
┌────────────────┐
│ CLI Layer │ Calls Flow Function
│ _do_xxx() │ ────────────────────┐
└────────────────┘ │
▼
┌──────────────────────────┐
│ Flow Layer │
│ xxx_flow() │
└───────┬──────────────────┘
│
▼
┌─────────────────────────────┐
│ Data Layer │
│ XxxRepo / XxxClient │
└────────┬─────────────────────┘
│
▼
┌────────────────────────────┐
│ External System / Database │
│ (SQLite / API / etc) │
└──────────┬─────────────────┘
│ Returns Data
▼
┌──────────────────────────────────┐
│ Data Processing (Parse/Transform) │
└─────────────┬────────────────────┘
│
▼
┌──────────────────────┐
│ Return Data Class │ ← Explain why kept/simplified
│ (Result / Item / ...)│
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ CLI Layer Formatting │
└──────────────────────┘
│
▼
╔══════════════════════════════════════════════════╗
║ Terminal Output Example ║
║ (Enclosed in borders to highlight user-facing ║
║ result) ║
╚══════════════════════════════════════════════════╝
═══════════════════════════════════════════════════════════════════════
Scenario 2: Another Scenario
═══════════════════════════════════════════════════════════════════════
(Repeat the above structure, highlighting differences)
2. Database Table Structure Description
Best for: Explaining database tables relevant to a feature
CREATE TABLE table_name (
id INTEGER PRIMARY KEY AUTOINCREMENT, -- ← Explain primary key role
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);
Sample Data Table:
| id | field1 | field2 | field3 | Description |
|---|---|---|---|---|
| 42 | value1 | value2 | value3 | Explain the business meaning of this record |
| 43 | ... | ... | ... | ... |
Typical Query:
-- Scenario: When do we need to query like this?
SELECT * FROM table_name
WHERE condition1 = ?
AND (condition2 IS NULL OR condition2 >= ?);
3. Layered Call Chain Diagram (Simplified)
Best 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
Best for: Evaluating whether intermediate data classes are necessary
| Class Name | Field Count | Purpose | Verdict | Reason |
|---|---|---|---|---|
XxxResult | 6 | Multi-field aggregation + CLI display | ✅ Keep | Satisfies the "minimum necessary principle" |
XxxWrapper | 1 | Single field wrapper | ❌ Remove | Over-packaging, return raw type directly |
XxxItem | 3 | List item detail | ✅ Keep | Has business semantics |
Comparison Example:
# ❌ Over-packaging
@dataclass
class XxxResult:
field: SomeType # Only one field
def xxx_flow() -> XxxResult:
return XxxResult(field=value)
# ✅ Simplified
@dataclass
class XxxResult:
field: SomeType
def xxx_flow() -> SomeType: # Return directly
return value
5. Business Key Points Annotation
Best for: Highlighting business rules and design decisions
┌─────────────────────────────────────────────────────────────┐
│ Business Key Points │
├──────────────────────┬──────────────────────────────────────┤
│ Why design this │ Specific Decision │
│ way? │ │
├──────────────────────┼──────────────────────────────────────┤
│ • Data Precision │ Use Decimal for amounts, 2 decimal places |
│ • Idempotency │ Unique constraint on (fund_code, date) |
│ • Traceability │ record_id as globally unique identifier |
└──────────────────────┴──────────────────────────────────────┘
Usage
Step 1: Define the Analysis Goal
Answer the following questions:
- Which feature does the user want to understand?
- How many scenarios does this feature have? (success/failure, manual/auto, etc.)
- Which layers are involved? (CLI → Flow → Data → DB/API)
- Key data classes: What are they and why are they designed that way?
Step 2: Choose the Appropriate Template
- Multi-scenario comparison → Template 1 (Full Flowchart)
- Single flow → Template 3 (Layered Call Chain)
- Database design → Template 2 (Table Structure + Sample Data)
- Data class evaluation → Template 4 (Analysis Table)
Step 3: Fill in the Content
Principles:
- Use ASCII diagrams instead of long text
- Use arrows (
│ ▼ ┐ ┘ └ ├ ─) to connect data flow - Use borders (
┌ ┐ └ ┘ │ ─) to separate layers - Use double borders (
╔ ╗ ╚ ╝ ║ ═) to highlight user-visible parts - Add comments at key nodes (
← Explanation)
Symbol Usage Standards:
| Symbol | Purpose | Example |
|---|---|---|
│ ▼ | Vertical flow | Data top to bottom |
→ ← | Horizontal explanation | record_id: int ← Database primary key |
┌ ┐ └ ┘ | Single border | Enclosing code blocks, commands |
╔ ╗ ╚ ╝ | Double border | Highlight terminal output, important results |
═══ | Separator line | Separating different scenarios |
Step 4: Add Comparison Analysis
Before vs After (refactoring scenarios):
# Before (problematic version)
...code...
# Issues:
# - Over-packaging
# - Redundant fields
# - Increased cognitive load
# After (improved version)
...code...
# Improvements:
# - Return meaningful types directly
# - Reduce intermediate layers
# - Lower maintenance cost
Real-World Examples
Example 1: Limit Management Flow (Full Version)
(See Template 1 example above; expand 4 scenarios into a full flow)
Example 2: Data Class Evaluation (fund_restriction Module)
| Function | Previous Return | Current Return | Verdict | Reason |
|---|---|---|---|---|
add_restriction | AddRestrictionResult (6 fields) | Keep | ✅ | CLI needs to display all fields |
end_restriction | EndRestrictionResult (4 fields) | bool | ❌ | Only need success/failure |
check_trading_status | CheckStatusResult (2 fields) | `ParsedRestriction | None` | ❌ |
Output Checklist
When generating a flow visualization document, ensure it includes:
- Top-level overview (feature goal, involved modules)
- Scenario enumeration (success/failure, manual/auto, etc.)
- Layered flow diagram (CLI → Flow → Data → External)
- Database table structure (if applicable)
- Sample data and queries (to aid understanding)
- Key data class explanation (why kept/simplified)
- Design rationale (why this approach?)
- Future expansion points (TODO or reserved interfaces)
Anti-Patterns (What Not to Do)
❌ 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
❌ Table without focus
| 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, for display |
❌ SQL without scenario explanation
SELECT * FROM table WHERE id = ?;
✅ Include business scenario
-- Scenario: User queries details of a specific restriction record
SELECT * FROM fund_restrictions WHERE id = ?;
-- Scenario: DCA analysis checks if a date is limited
SELECT * FROM fund_restrictions
WHERE fund_code = ? AND start_date <= ? AND (end_date IS NULL OR end_date >= ?);
Collaboration with Other Skills
- code-style: Follow coding standards when outputting code examples
- architecture: Flow diagrams must adhere to layered architecture constraints
- dev-workflow: Read relevant code and documentation before organizing flows
Summary
The core value of this Skill is:
- Reusable templates: Reduce time starting from scratch
- Consistent visual style: ASCII diagrams + tables + borders
- Business perspective: Not just code flow, but focusing on "why"
- Comparison analysis: Before/after refactoring, multi-scenario comparison
- Checklist verification: Ensure no key information is missed
Usage frequency: Use whenever you need to explain "how a feature works."