audit-flow

⚠️ 必須の開始手順 — ほかの操作を行う前に必ず実行

ステップ 1：schema.sql を読む

# ALWAYS read the schema first to understand tables, constraints, views
cat .claude/skills/audit-flow/schema.sql

ステップ 2：データベースが存在するか確認する — 絶対に再作成しない

# Check for existing database
ls -la .audit/audit.db 2>/dev/null && echo "DB EXISTS - DO NOT RECREATE" || echo "No DB - safe to init"

ステップ 3：データベースが存在する場合、現在の状態を表示する

python .claude/skills/audit-flow/scripts/audit.py list

🚫 禁止されている操作

操作	禁止されている理由
rm .audit/audit.db	監査履歴が破棄されます
DB が存在する状態での audit.py init	既存のデータが上書きされます
DROP TABLE	監査履歴が破棄されます
DB が存在する状態での sqlite3 .audit/audit.db < schema.sql	既存のデータが上書きされます

ルール： .audit/audit.db が存在する場合は、audit.py list、show、export、または INSERT 操作のみを使用してください。絶対に再作成しないでください。

---

監査フロー

SQLite に保存しながら、システムフローを対話形式で追跡します。1 セッションで複数の名前付きフローをサポートし、非線形フロー（分岐・統合）や複数形式でのエクスポートにも対応します。

構成の原則

目的別のディレクトリー構成：

• 監査／ドキュメント／コンプライアンス： docs/audits/{name}-{YYYY-MM-DD}/
• アイデア出し／ブレインストーミング： docs/ideation/{name}-{YYYY-MM-DD}.md（単一ファイル。成果物が必要な場合を除き、サブディレクトリーは作成しません）
• デバッグ／インシデントレビュー： docs/audits/{name}-{YYYY-MM-DD}/（監査と同じ — 証拠を記録します）
• アーキテクチャレビュー： docs/audits/{name}-{YYYY-MM-DD}/（監査と同じ — 構造分析を記録します）

必須ファイル：

• INDEX.md（マニフェスト、開始点）
• README.md（概要）
• {name}-audit.md（フローの追跡記録）

遅延初期化： 成果物が存在する場合にのみサブディレクトリーを作成します

• screenshots/ network-traces/ diagrams/ code-samples/ test-results/ evidence/

命名規則： {audit-name}-{type}.md

データベース優先の原則

不変条件： SQLite が唯一の信頼できる情報源です。コンテキストウィンドウは揮発性で、予告なく圧縮され、状態を幻覚することがあります。

🚨 重大：既存のデータを絶対に破棄しないでください

• .audit/audit.db が存在する場合 → 取り返しのつかない監査履歴が含まれています
• DB が存在する状態で init を絶対に実行しないでください — list を使って内容を確認してください
• 削除、破棄、再作成は絶対にしないでください — 追記のみ行ってください

制約：

操作	ルール	禁止される自己正当化
開始	最初に schema.sql を読み、次に DB が存在するか確認します	「とりあえず作業を始めよう」
初期化	.audit/audit.db が存在しない場合にのみ実行します	「最初からやり直すために再初期化しよう」
スキーマ	SQLite コマンドを実行する前に schema.sql を読み、まずテーブル、制約、ビューを把握します	「コンテキストからスキーマはわかっている」
書き込み	次のコード位置に進む前に、各タプル／エッジ／所見を INSERT します	「最後にまとめて INSERT しよう」
読み取り	タプル ID、件数、フロー構造を参照する前に、DB から SELECT します	「ここまでのフローは覚えている」
エクスポート	audit.py export のみを使用します — コンテキストから mermaid／markdown を生成しないでください	「mermaid を直接生成しよう」
再開	以前のタプルを参照する操作の前に audit.py show <session> を実行します	「トレース全体はコンテキストにある」
参照	DB からタプル ID を照会します — ID は DB が割り当てるものであり、推測してはいけません	「タプル ID は N のはず」
既定	フローの状態が不明な場合 → 続行する前に DB を照会します	(記載されていないあらゆる自己正当化)

チェックポイント： タプルを 5 つ追加するごとに audit.py show <session> <flow> を実行します

---

対話型ワークフロー — 必ずユーザーに確認してください

1. セッション開始時 - 質問：

Name: ___
Purpose: security-audit | documentation | compliance | ideation | brainstorming | debugging | architecture-review | incident-review
Description: ___ (optional)

ディレクトリはすぐに初期化します。成果物の生成時にサブディレクトリを遅延作成します。

2. 粒度 - 質問：

[fine]   Function-level trace (~50-200 tuples)
         Use: Security audits, debugging

[coarse] Boundary-level trace (~10-30 tuples)
         Use: Documentation, high-level flows

Choose: fine / coarse

3. トレース中：

判断が必要な箇所で質問します：さらに深くトレースしますか？懸念事項としてマークしますか？指摘事項（重要度）を追加しますか？メモを残しますか？

4. エクスポート時：

形式を確認します：json | yaml | md | mermaid | all

エクスポート後：INDEX.md マニフェストを生成します。成果物を種類別に整理します。空のディレクトリを削除します。

クイックリファレンス

コマンド	目的
/audit-flow start	新しいセッションを開始（名前、目的、粒度）
/audit-flow flow {name}	セッションに新しいフローを追加
/audit-flow add {layer} {desc}	現在のフローにタプルを追加
/audit-flow link {from} {to} {rel}	エッジを作成（分岐条件に対応）
/audit-flow finding {desc}	指摘事項を記録
/audit-flow show	セッション／フローの詳細を表示
/audit-flow export	エクスポート（json/yaml/md/mermaid）
/audit-flow git-setup	Git のマージ／差分ドライバーを設定（一度のみ）

レイヤー： CODE | API | NETWORK | AUTH | DATA

関係： TRIGGERS | READS | WRITES | VALIDATES | TRANSFORMS | BRANCHES | MERGES

関係の意味ルール

関係	意味	使用する場面	使用しない場面
TRIGGERS	A によって B が実行される	関数呼び出し、イベントハンドラー、HTTP リクエスト	静的な観察事項
READS	A が B からデータを読み取る	Cookie の読み取り、DB クエリ、設定の参照	データの変更
WRITES	A が B のデータを変更する	Cookie の書き込み、DB への挿入、状態の更新	読み取り専用アクセス
VALIDATES	A が B をチェック／検証する	認証チェック、入力検証、有効期限チェック	分析者の観察事項を連結すること
TRANSFORMS	A が B のためにデータを変換する	トークン交換、レスポンスの整形	無関係な処理
BRANCHES	A に条件分岐の経路がある	if/else、switch、エラー対成功	条件ラベルが必須
MERGES	複数の経路が B で合流する	並行経路の再合流、エラーからの復旧	単一経路のフロー

重要：BRANCHES には条件が必須です。 すべての BRANCHES エッジには、どの経路かを示す condition が必要です。例：BRANCHES [token expired] と BRANCHES [token valid]。

観察事項とフローステップ

フローステップ = システムが行うこと（関数呼び出し、データの読み取り、ネットワークリクエスト）。コードをトレースして確認します。

観察事項 = 分析者が記録すること（機能の欠如、潜在的なリスク）。タプルではなく、指摘事項として記録します。

誤ったパターン：

T50 "NO cross-tab sync"       ← observation, not a system action
T51 "React state NOT shared"  ← observation
T50 --VALIDATES--> T51         ← chaining observations as flow

正しいパターン：

-- Record as finding instead:
INSERT INTO findings (flow_id, session_id, severity, category, description)
VALUES (?, ?, 'medium', 'state-management',
        'No cross-tab sync: React state not shared across tabs');

ルール： 観察事項を VALIDATES で連結してはいけません。システムが行わないことを説明する場合は、指摘事項を使用します。

データモデル

Session (audit container)
  └── Flow (named DAG with entry point)
       └── Tuple (node: layer + action + subject)
            └── Edge (relation + optional condition)

ストレージと CLI

# Core
python .claude/skills/audit-flow/scripts/audit.py init              # Initialize DB
python .claude/skills/audit-flow/scripts/audit.py list              # List sessions
python .claude/skills/audit-flow/scripts/audit.py show <session>    # Show flows
python .claude/skills/audit-flow/scripts/audit.py show <session> <flow>  # Show flow details
python .claude/skills/audit-flow/scripts/audit.py export <session>  # Export all
python .claude/skills/audit-flow/scripts/audit.py export <session> -f <flow>  # Export one flow
python .claude/skills/audit-flow/scripts/audit.py validate <session>         # Validate flows

# Git integration
python .claude/skills/audit-flow/scripts/audit.py git-setup         # Configure merge/diff drivers (once)
python .claude/skills/audit-flow/scripts/audit.py db-merge %O %A %B # Git merge driver (auto-called)

# CSV backup/portability (optional)
python .claude/skills/audit-flow/scripts/audit.py csv-export               # DB → .audit/csv/*.csv
python .claude/skills/audit-flow/scripts/audit.py csv-import               # .audit/csv/*.csv → DB
python .claude/skills/audit-flow/scripts/audit.py csv-merge <theirs_dir>   # Merge two CSV sets

非線形フロー

分岐： 1 つのタプルから、条件付きで複数の出力エッジへ

INSERT INTO edges (from_tuple, to_tuple, relation, condition)
VALUES (5, 6, 'BRANCHES', 'token valid'),
       (5, 7, 'BRANCHES', 'token expired');

マージ： 複数のタプルから、1 つのタプルへ

INSERT INTO edges (from_tuple, to_tuple, relation)
VALUES (6, 8, 'TRIGGERS'),
       (9, 8, 'MERGES');  -- refresh path merges back

ファイル

• scripts/audit.py - すべてのコマンド（init、list、show、export、validate、db-merge、git-setup、csv-*）用の CLI
• COMMANDS.md - SQL リファレンスの詳細
• EXAMPLES.md - 非線形フローを含む完全な例
• schema.sql - データベーススキーマ
• .gitattributes - audit.db 用の Git マージ／差分ドライバー設定

Git コンテキスト

セッション開始時に、コミットハッシュ、ブランチ、作業ツリーの状態を記録します。すべてのエクスポートに含めます。

Mermaid の検証

エクスポート前に python .claude/skills/audit-flow/scripts/audit.py validate <session> を実行してください。

チェック	深刻度	説明
条件のない BRANCHES	ERROR	すべての BRANCHES エッジに条件ラベルが必要です
ノード数 >= 60	ERROR	サブフローに分割してください
ノード数 >= 40	WARN	分割を検討してください
孤立ノード	WARN	エッジのない（接続されていない）ノード
ラベルの重複	WARN	主語で区別されていない同一のアクションテキスト
エントリーポイントなし	WARN	すべてのノードに入ってくるエッジがあります

エクスポート後の機能（自動）：

• ステップ番号：エントリーポイントからの BFS トポロジカル順序（1. action、2. action）
• エントリーポイント：緑色のスタイルが適用されたスタジアム形状
• エッジの矢印：--> は実線（TRIGGERS/VALIDATES/TRANSFORMS/BRANCHES/MERGES）、-.-> は点線（READS）、==> は太線（WRITES）
• 観察事項：破線の枠線を持つ OBSERVATIONS サブグラフに分離
• 方向：横向きのレイアウトには --direction LR フラグを使用

図の読みやすさに関する要件

すべての図は audit.py export で生成する必要があります。 Mermaid を手作業で作成しないでください。エクスポーターにより、次の項目が確実に適用されます。

1. エントリーポイントのマーカー — 緑色のスタジアム形状のノード ([label]):::entryPoint
2. ステップ番号 — BFS トポロジカル順序：1. action、2. action、3. action
3. 凡例ブロック — entryPoint、concern、observation の classDef スタイル
4. 観察事項の分離 — 懸念事項のみのチェーンはメインフローではなく、OBSERVATIONS サブグラフに配置
5. ラベルの安全性 — ()、""、<>、|、[] 文字には HTML エンティティを使用（自動サニタイズ）

読み進め方がひと目で分かる必要があります。 初めて図を開いた読者が、すぐに次の内容を把握できる必要があります。

• どこから始めるか（緑色のエントリーノード）
• どの順序で読むか（ステップ番号）
• どの経路が正常系か、どの経路がエラーか（エッジの分岐条件）
• 色が何を意味するか（凡例）

ノードラベルのルール：

• 具体的な名詞／動詞を使用します：handleCallback()、exchangeCodeForTokens()
• 動詞だけのラベルは使用しません：「設定」、「選択」、「有効化」
• 重複を区別します：アクションが重複する場合は、主語を自動で接尾辞として追加

サイズ制限：

• 40 ノード以上 → 警告。分割を検討してください
• 60 ノード以上 → エラー。サブフローに分割する必要があります
• フローに 5 つ以上の独立したサブフローがある場合 → 目的別に分割してください

---

Git ワークフロー — カスタムマージドライバー

問題： SQLite はバイナリ形式のため、git merge では .audit/audit.db を自動的に解決できません。

解決策： カスタム Git マージドライバーを使用します。audit.db は Git 内に保持されます（小さな単一ファイルです）。競合時には、Git が audit.py db-merge を呼び出して SQL を使った自動マージを行います。

初回セットアップ

python .claude/skills/audit-flow/scripts/audit.py git-setup

次の設定を（.git/config 内に）行います。

• マージドライバー： merge.sqlite-audit — 競合時に audit.py db-merge %O %A %B を呼び出します
• 差分ドライバー： diff.sqlite — 読みやすい git diff 出力のために sqlite3 .dump を使用します

また、.gitattributes も必要です（すでにリポジトリにあります）。

.audit/audit.db diff=sqlite merge=sqlite-audit

動作の仕組み

1. 通常どおり audit.db をコミットします — git add .audit/audit.db && git commit
2. git diff は SQL テキストを表示します（textconv 経由）
3. 競合を伴う git merge の際には、Git が自動的にマージドライバーを呼び出します
4. ドライバーは両方の DB を開き、名前でセッションをマージして（新しい方の updated_at を優先）、ID を再割り当てします
5. 結果が ours に書き込まれ、マージが正常に完了します

マージ戦略

テーブル	マージキー	競合解決
sessions	name（一意）	より新しい updated_at を保持
flows	(session_name, flow_name)	親セッションで採用されたものに従う
tuples	親フロー	採用されたフローのすべてのタプルを保持
edges	両方の端点タプル	両方の端点が残る場合に保持
findings	(session_name, category, description)	内容で重複を排除

すべての INTEGER PK は連番に振り直されます。外部キーも更新されます。

CSV バックアップ（任意）

移植性とバックアップのため、CSV のエクスポート／インポートも引き続き利用できます。

python .claude/skills/audit-flow/scripts/audit.py csv-export   # DB → .audit/csv/*.csv (QUOTE_ALL)
python .claude/skills/audit-flow/scripts/audit.py csv-import   # CSV → DB (recreates from scratch)

---

出力品質

原則：

• 複雑なフローには ASCII シーケンス図を使用
• 代替案には比較表を使用
• file:line 参照を付け、トレースしたファイルから実際のコードを使用
• What／Why／Example のパターン
• 汎用テンプレートは使用しない

完了チェックリスト

• ISO 日付のサフィックスが付いたディレクトリが存在する
• INDEX.md マニフェストが生成されている
• README.md（エグゼクティブサマリー）
• 命名規則：{name}-{type}.md
• 成果物は型別のサブディレクトリに配置されている（遅延初期化）
• Git コンテキストが取得されている
• Git マージドライバーが設定されている（audit.py git-setup）
• 孤立したファイルがない
• 図が audit.py validate に合格する

アンチパターン

フラットな構造、空のディレクトリ、孤立ノード、ラベルのない分岐、汎用的な識別子、Git コンテキストの欠落、マニフェストなし、手作業で作成した Mermaid、動詞だけのラベル。