Communitygithub.com

代碼流程可視化規範

用於梳理和可視化代碼流程,生成清晰的 ASCII 流程圖、數據流圖和表格分析。適用於既有代碼的梳理、新功能設計的說明,以及技術文檔的編寫。

代碼流程可視化規範 是什麼?

這個技能提供了一套全面的模板和方法,幫助開發者梳理代碼流程並生成可視化文檔。其核心目標是「用文字和 ASCII 圖表說清楚數據從哪裡來、經過哪些層、最後到哪裡去」。它適用於解釋功能運作方式、設計新功能的數據流、重構前釐清既有邏輯、撰寫技術文檔或架構說明,以及代碼審查時可視化呼叫鏈。該技能支援多種平台(如 Claude Code、Cursor、Codex),提供了五種核心模板:包含多場景對比的完整流程圖、數據庫表結構說明、簡化分層呼叫鏈圖、數據類設計分析表,以及業務關鍵點標註。使用方法分為四個步驟:確定分析目標、選擇合適模板、填充內容、添加對比分析。此外,它還強調了避免純文字描述流程、無重點表格、無場景說明的 SQL 等反模式,並能與 code-style、architecture 和 dev-workflow 等其他技能協作,確保可視化結果的清晰度、一致性和業務相關性。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/majiayu000/claude-skill-registry-data/tree/HEAD/analysis/code-flow-viz-mmorit00-fund-portfolio-bot-2

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

代碼流程可視化規範 是做什麼的?

本 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);

範例資料表:

idfield1field2field3說明
42value1value2value3解釋這條記錄的業務含義
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. 資料類設計分析表

適用於:評估中間資料類是否必要

類名欄位數用途判定理由
XxxResult6多欄位聚合 + CLI 展示✅ 保留滿足「最小必要原則」
XxxWrapper1單欄位包裝❌ 刪除過度包裝,直接返回原始類型
XxxItem3列表明細項✅ 保留有業務語義

對比範例:

# ❌ 過度包裝
@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: 確定分析目標

回答以下問題:

  1. 用戶想了解哪個功能的流程?
  2. 這個功能有幾種場景?(成功/失敗、手動/自動等)
  3. 涉及哪些層次?(CLI → Flow → Data → DB/API)
  4. 關鍵資料類有哪些?為什麼設計成這樣?

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_restrictionAddRestrictionResult(6欄位)保留✅CLI 需要展示所有欄位
end_restrictionEndRestrictionResult(4欄位)bool❌只需要成功/失敗
check_trading_statusCheckStatusResult(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

❌ 表格沒有重點

欄位類型
idint
namestr

✅ 突出業務含義

欄位類型說明業務約束
idint主鍵自動生成,全域唯一
namestr基金名稱非空,用於展示

❌ 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 的核心價值:

  1. 可複用的模板:減少從零開始的時間
  2. 統一的視覺風格:ASCII 圖 + 表格 + 框線
  3. 業務視角:不只是程式碼流程,更關注「為什麼」
  4. 對比分析:重構前後、多場景對比
  5. 清單檢查:確保不遺漏關鍵資訊

使用頻率:每次需要解釋「某個功能怎麼工作」時都可以用。

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

majiayu000/claude-skill-registry-data

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry-data

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry-data

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry-data

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry-data

Analyzes current state and user query to answer BMad questions or recommend the next workflow or agent. Use when user says what should I do next, what do I do now, or asks a question about BMad

majiayu000/claude-skill-registry-data

Build AI agents with Google ADK Python (Agent Development Kit). Use for multi-agent systems, workflow agents (sequential/parallel/loop), Vertex AI deployment, tool integration, human-in-the-loop.

majiayu000/claude-skill-registry-data

Build AI agents with Google ADK Python (Agent Development Kit). Use for multi-agent systems, workflow agents (sequential/parallel/loop), Vertex AI deployment, tool integration, human-in-the-loop.

majiayu000/claude-skill-registry-data

Portfolio allocation and rebalancing optimizer. Manages asset allocation across stocks/cash/bonds, performs periodic rebalancing, and ensures diversification according to market regime and risk tolerance.

majiayu000/claude-skill-registry-data

Create a hilarious and ultra-realistic video of an anthropomorphic animal acting like a human vlogger in a real-world setting.

majiayu000/claude-skill-registry-data

Speech-to-text transcription and translation via OpenAI Audio API -- models, response formats, timestamps, prompting, streaming, chunking, and diarization

majiayu000/claude-skill-registry-data

This skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc.

majiayu000/claude-skill-registry-data

小省导购员数字人带货版即梦视频提示词生成系统,基于四大智能体协同(提示词生成师、质量管控师、知识库运维师、跨环节适配师),按照"主体+运动+场景+(镜头语言+光影+氛围)"公式输出中英文双版提示词,适配5s短视频。确保人物一致性、视觉连贯性、情绪连贯性,支持知识库智能复用和跨工具适配(Suno音乐、AI绘画),为数字人带货视频提供高质量提示词生成服务。

majiayu000/claude-skill-registry-data

Upload and manage files using Google Gemini File API via scripts/. Use for uploading images, audio, video, PDFs, and other files for use with Gemini models. Supports file upload, status checking, and file management. Triggers on "upload file", "file API", "upload image", "upload PDF", "upload video", "file management".

majiayu000/claude-skill-registry-data

Analyze images/audio/video with Gemini API (better vision than Claude). Generate images (Imagen 4), videos (Veo 3). Use for vision analysis, transcription, OCR, design extraction, multimodal AI.

majiayu000/claude-skill-registry-data

Analyze images/audio/video with Gemini API (better vision than Claude). Generate images (Imagen 4), videos (Veo 3). Use for vision analysis, transcription, OCR, design extraction, multimodal AI.

majiayu000/claude-skill-registry-data

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

majiayu000/claude-skill-registry-data

Conduct domain and industry research. Use when the user says "lets create a research report on [domain or industry]

majiayu000/claude-skill-registry-data

Conduct market research on competition and customers. Use when the user says "create a market research report about [business idea]".

majiayu000/claude-skill-registry-data

Conduct technical research on technologies and architecture. Use when the user says "create a technical research report on [topic]".

majiayu000/claude-skill-registry-data

Builds, edit or validate Agent Skill through conversational discovery. Use when the user requests to "Create an Agent", "Optimize an Agent" or "Edit an Agent".

相關技能