コードフロー可視化ガイドライン
このスキルは、コードフローを整理し、可視化ドキュメントを生成するための再利用可能なテンプレートと手法を提供します。
コア原則: テキストとASCII図で、「データがどこから来て、どのレイヤーを通過し、最終的にどこへ行くのか」を明確に説明します。
使用タイミング
以下のシナリオで本スキルを使用します:
- ユーザーが「特定の機能はどのように動作するのか」と質問した場合
- 新機能のデータフローを設計する必要がある場合
- リファクタリング前に既存ロジックを整理する必要がある場合
- 技術文書やアーキテクチャ説明を作成する場合
- コードレビューでコールチェーンを可視化する必要がある場合
コアテンプレート
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 # フィールドが1つだけ
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 | ❌ | 単純なラッパーに過ぎない |
出力チェックリスト
フロー可視化ドキュメントを生成する際は、以下を含めていることを確認:
- トップレベルの概要(機能目標、関連モジュール)
- シナリオの列挙(成功/失敗、手動/自動など)
- レイヤー別フローチャート(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 >= ?);
他のスキルとの連携
- code-style: コード例を出力する際はコーディング規約に従う
- architecture: フローチャートはレイヤーアーキテクチャの制約に従う
- dev-workflow: フロー整理の前に、関連コードとドキュメントを読む
まとめ
本スキルのコアバリュー:
- 再利用可能なテンプレート: ゼロから作成する時間を削減
- 統一された視覚スタイル: ASCII図+テーブル+罫線
- ビジネス視点: コードフローだけでなく、「なぜ」に注目
- 比較分析: リファクタリング前後、複数シナリオ比較
- チェックリスト確認: 重要な情報の漏れを防止
使用頻度: 「特定の機能がどのように動作するか」を説明する必要があるたびに使用できます。