コードフロー可視化ガイドライン
このスキルは、コードフローを整理し、可視化ドキュメントを生成するための再利用可能なテンプレートと手法を提供します。
コア原則: 「データがどこから来て、どのレイヤーを通り、最終的にどこへ行くのか」をテキストと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 | ファンド名 | 非NULL、表示用 |
❌ 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図 + 表 + 枠線
- ビジネス視点: コードフローだけでなく、「なぜ」に注目
- 比較分析: リファクタリング前後、複数シナリオの比較
- チェックリスト: 重要な情報の漏れを防止
使用頻度: 「特定の機能がどのように動作するか」を説明する必要があるたびに使用可能。