代碼流程可視化規範 是做什麼的?
本 Skill 提供一套可複用的模板和方法,用於梳理代碼流程、生成可視化文檔。
核心原則:用文字和 ASCII 圖表講清楚「數據從哪來、經過哪些層、最後到哪去」。
When to use
在以下場景使用本 Skill:
- 用戶詢問「某個功能是怎麼工作的」
- 新增功能需要設計數據流
- 重構前需要梳理現有邏輯
- 編寫技術文檔或架構說明
- 代碼審查時需要可視化呼叫鏈
核心模板
1. 完整流程圖(多場景對比)
適用於:梳理一個功能的多種使用場景(如手動 vs 自動、成功 vs 失敗)
┌─────────────────────────────────────────────────────────────────────┐
│ 功能名稱(如:限額管理全生命週期) │
└─────────────────────────────────────────────────────────────────────┘
═══════════════════════════════════════════════════════════════════════
場景 1:場景名稱(如:自動查詢限額狀態)
═══════════════════════════════════════════════════════════════════════
用戶命令
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ uv run python -m src.cli.xxx ... │
└────────────────┬────────────────────────────────────────────────┘
│
▼
┌────────────────┐
│ CLI 層 │ 呼叫 Flow 函數
│ _do_xxx() │ ────────────────────┐
└────────────────┘ │
▼
┌──────────────────────────┐
│ Flow 層 │
│ xxx_flow() │
└───────┬──────────────────┘
│
▼
┌─────────────────────────────┐
│ Data 層 │
│ XxxRepo / XxxClient │
└────────┬─────────────────────┘
│
▼
┌────────────────────────────┐
│ 外部系統 / 資料庫 │
│ (SQLite / API / etc) │
└──────────┬─────────────────┘
│ 返回數據
▼
┌──────────────────────────────────┐
│ 數據處理(解析/轉換) │
└─────────────┬────────────────────┘
│
▼
┌──────────────────────┐
│ 返回值數據類 │ ← 說明為什麼保留/簡化
│ (Result / Item / ...)│
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ CLI 層格式化輸出 │
└──────────────────────┘
│
▼
╔══════════════════════════════════════════════════╗
║ 終端輸出範例 ║
║ (用框線包圍,突出最終用戶看到的效果) ║
╚══════════════════════════════════════════════════╝
═══════════════════════════════════════════════════════════════════════
場景 2:另一個場景
═══════════════════════════════════════════════════════════════════════
(重複上述結構,突出差異點)
2. 資料庫表結構說明
適用於:解釋某個功能涉及的資料庫表
CREATE TABLE table_name (
id INTEGER PRIMARY KEY AUTOINCREMENT, -- ← 說明主鍵作用
field1 TEXT NOT NULL, -- 說明欄位含義
field2 TEXT, -- NULL 的業務含義
...
);
-- 索引(說明為什麼需要這個索引)
CREATE INDEX idx_xxx ON table_name(field1, field2);
範例資料表:
| id | field1 | field2 | field3 | 說明 |
|---|---|---|---|---|
| 42 | value1 | value2 | value3 | 解釋這條記錄的業務含義 |
| 43 | ... | ... | ... | ... |
典型查詢:
-- 場景說明:什麼時候需要這樣查?
SELECT * FROM table_name
WHERE condition1 = ?
AND (condition2 IS NULL OR condition2 >= ?);
3. 分層呼叫鏈圖(簡化版)
適用於:快速說明函數呼叫關係
CLI 層 (_do_xxx)
│
└─> Flow 層 (xxx_flow)
│
├─> Data/Repo (xxx_repo.get)
│ │
│ └─> SQLite (SELECT ...)
│
└─> Data/Client (xxx_client.fetch)
│
└─> 外部 API (HTTP GET ...)
4. 資料類設計分析表
適用於:評估中間資料類是否必要
| 類名 | 欄位數 | 用途 | 判定 | 理由 |
|---|---|---|---|---|
XxxResult | 6 | 多欄位聚合 + CLI 展示 | ✅ 保留 | 滿足「最小必要原則」 |
XxxWrapper | 1 | 單欄位包裝 | ❌ 刪除 | 過度包裝,直接返回原始類型 |
XxxItem | 3 | 列表明細項 | ✅ 保留 | 有業務語義 |
對比範例:
# ❌ 過度包裝
@dataclass
class XxxResult:
field: SomeType # 只有一個欄位
def xxx_flow() -> XxxResult:
return XxxResult(field=value)
# ✅ 簡化後
def xxx_flow() -> SomeType: # 直接返回
return value
5. 業務關鍵點標註
適用於:突出業務規則和設計決策
┌─────────────────────────────────────────────────────────────┐
│ 業務關鍵點 │
├──────────────────────┬──────────────────────────────────────┤
│ 為什麼這樣設計? │ 具體決策 │
├──────────────────────┼──────────────────────────────────────┤
│ • 數據精度 │ 金額用 Decimal,2 位小數 │
│ • 冪等性 │ 按 (fund_code, date) 唯一約束 │
│ • 可追溯性 │ record_id 作為全域唯一標識 │
└──────────────────────┴──────────────────────────────────────┘
使用方法
Step 1: 確定分析目標
回答以下問題:
- 用戶想了解哪個功能的流程?
- 這個功能有幾種場景?(成功/失敗、手動/自動等)
- 涉及哪些層次?(CLI → Flow → Data → DB/API)
- 關鍵資料類有哪些?為什麼設計成這樣?
Step 2: 選擇合適的模板
- 多場景對比 → 模板 1(完整流程圖)
- 單一流程 → 模板 3(分層呼叫鏈)
- 資料庫設計 → 模板 2(表結構 + 範例資料)
- 資料類評估 → 模板 4(分析表)
Step 3: 填充內容
原則:
- 用 ASCII 圖表代替長篇文字
- 用箭頭(
│ ▼ ┐ ┘ └ ├ ─)串聯數據流 - 用框線(
┌ ┐ └ ┘ │ ─)分隔層次 - 用雙線框(
╔ ╗ ╚ ╝ ║ ═)突出用戶可⻅部分 - 在關鍵節點加註解(
← 說明)
符號使用規範:
| 符號 | 用途 | 範例 |
|---|---|---|
│ ▼ | 垂直流向 | 數據從上到下 |
→ ← | 水平說明 | record_id: int ← 資料庫主鍵 |
┌ ┐ └ ┘ | 單線框 | 包圍程式碼區塊、命令 |
╔ ╗ ╚ ╝ | 雙線框 | 突出終端輸出、重要結果 |
═══ | 分隔線 | 分隔不同場景 |
Step 4: 添加對比分析
Before vs After(重構場景):
# Before(問題版本)
...程式碼...
# 問題:
# - 過度包裝
# - 欄位冗餘
# - 增加認知負擔
# After(改進版本)
...程式碼...
# 改進:
# - 直接返回有意義類型
# - 減少中間層
# - 降低維護成本
實際案例
案例 1:限額管理流程(完整版)
(⻅上面的模板 1 範例,展開 4 個場景的完整流程)
案例 2:資料類評估(fund_restriction 模組)
| 函數 | 之前返回 | 現在返回 | 判定 | 原因 |
|---|---|---|---|---|
add_restriction | AddRestrictionResult(6欄位) | 保留 | ✅ | CLI 需要展示所有欄位 |
end_restriction | EndRestrictionResult(4欄位) | bool | ❌ | 只需要成功/失敗 |
check_trading_status | CheckStatusResult(2欄位) | ParsedRestriction | None | ❌ | 只是簡單包裝 |
輸出清單(Checklist)
生成流程可視化文檔時,確保包含:
- 頂層概述(功能目標、涉及模組)
- 場景枚舉(成功/失敗、手動/自動等)
- 分層流程圖(CLI → Flow → Data → 外部)
- 資料庫表結構(如果涉及)
- 範例資料和查詢(幫助理解)
- 關鍵資料類說明(為什麼保留/簡化)
- 設計原因(為什麼這樣做?)
- 未來擴展點(TODO 或預留接口)
反模式(不要這樣做)
❌ 純文字描述流程
首先呼叫 CLI 層的 _do_xxx 函數,然後 _do_xxx 會呼叫 Flow 層的 xxx_flow 函數,
xxx_flow 再呼叫 Data 層的 xxx_repo.get 方法...
✅ 用 ASCII 圖表
CLI (_do_xxx) → Flow (xxx_flow) → Data (xxx_repo.get) → SQLite
❌ 表格沒有重點
| 欄位 | 類型 |
|---|---|
| id | int |
| name | str |
✅ 突出業務含義
| 欄位 | 類型 | 說明 | 業務約束 |
|---|---|---|---|
| id | int | 主鍵 | 自動生成,全域唯一 |
| name | str | 基金名稱 | 非空,用於展示 |
❌ SQL 沒有場景說明
SELECT * FROM table WHERE id = ?;
✅ 帶業務場景
-- 場景:用戶查詢某條限制記錄詳情
SELECT * FROM fund_restrictions WHERE id = ?;
-- 場景:DCA 分析時檢查某日是否被限額
SELECT * FROM fund_restrictions
WHERE fund_code = ? AND start_date <= ? AND (end_date IS NULL OR end_date >= ?);
與其他 Skill 的協作
- code-style:輸出程式碼範例時遵循編碼規範
- architecture:流程圖需符合分層架構約束
- dev-workflow:梳理流程前先讀取相關程式碼和文檔
總結
本 Skill 的核心價值:
- 可複用的模板:減少從零開始的時間
- 統一的視覺風格:ASCII 圖 + 表格 + 框線
- 業務視角:不只是程式碼流程,更關注「為什麼」
- 對比分析:重構前後、多場景對比
- 清單檢查:確保不遺漏關鍵資訊
使用頻率:每次需要解釋「某個功能怎麼工作」時都可以用。