SF改修 → BQ / ダッシュボード
影響事前検知システム 設計提案

読み方・凡例

課題：要は何が問題なのか（結論ファースト）

問題は2クラスある（重要）

根拠（確認済みファクト・補足）

推奨アーキテクチャ（理想形）

設計の核は 依存関係の地図（辞書）を土台に置き、2方向の入口（事後の自動検知／事前の人間起点）から同じ1つの出口（影響の提示＋通知）へ繋ぐこと。

flowchart TB
    classDef core fill:#e8eef7,stroke:#1A365D,color:#1A365D
    classDef auto fill:#dcfce7,stroke:#15803d,color:#14532d
    classDef human fill:#ede9fe,stroke:#7c3aed,color:#4c1d95

    subgraph BASE["土台：依存関係の地図（辞書）"]
        psql["SQLを読み解いて依存を抜き出す"]:::core
        pgas["コクピットGASを読み解いて依存を抜き出す"]:::core
        dg["依存の地図（辞書）
『この項目を変えたら、どのBQ表・SQL・
ダッシュボードのKPIが倒れるか』を引ける"]:::core
        psql --> dg
        pgas --> dg
    end

    subgraph AUTO["事後（自動・必須）：SF変更を毎時みはる"]
        snap["describe で SFの設計図
(項目・型・選択肢値)を読み取る"]:::auto
        diff["前回と差分をとる
(消えた / 増えた / 型変更 / 選択肢値変更)"]:::auto
        snap --> diff
    end

    subgraph PRE["事前（人間）：既存の依頼フローを拡張"]
        form["既存：依頼フォーム→Backlog→Slack→Claude要件Q&A"]:::human
        lookup["変更前に影響を引く /sf-impact (Slack)"]:::human
    end

    engine["影響を照合する
変更 × 依存の地図"]:::auto
    act["影響と直し方をまとめて知らせる
Claude修正案 ＋ Slack通知 ＋ Backlog起票"]:::auto

    dg --> engine
    diff --> engine
    form --> engine
    lookup --> engine
    engine --> act
        

業務フローとシーケンス

運用は2つの流れ。事後（安全網）＝SF変更が起きたら自動で検知して通知。事前（上流）＝開発依頼フォームでSF項目変更の意図を検知したら、影響を要件Q&Aにインライン提示してBQチームへ事前連携。

フロー① 事後（自動の安全網）

sequenceDiagram
    autonumber
    actor admin as SF変更者
    participant sf as Salesforce
    participant sys as 検知システム(raftel)
    participant dg as 依存の地図
    participant slack as Slack(西川/稲川)
    participant bl as Backlog
    admin->>sf: 項目/選択肢値をUI変更
    loop 毎時
        sys->>sf: describe で設計図を読み取る
        sys->>sys: 前回スナップと差分をとる
    end
    sys->>dg: 変更項目/値を照合
    alt 後続に影響あり
        dg-->>sys: 影響先(SQL・ダッシュボード・KPI)
        sys->>slack: 影響 ＋ Claude修正案を通知
        sys->>bl: SYSDEVREQ に自動起票
    else 影響なし
        sys->>sys: 記録のみ（通知しない＝ノイズ抑制）
    end
        

フロー② 事前（依頼インテイク拡張）

sequenceDiagram
    autonumber
    actor req as 依頼者
    participant form as 開発依頼フォーム
    participant claude as ClaudeCode(要件Q&A)
    participant dg as 依存の地図
    participant slack as Slack(西川/稲川)
    req->>form: 開発依頼を送信
    form->>claude: Backlog起票 ＋ 要件整理を開始
    claude->>claude: SF項目変更の意図を検知
    alt SF項目変更を含む
        claude->>dg: 変更前に影響を引く
        dg-->>claude: 影響先一覧
        claude->>req: 要件Q&Aに影響をインライン提示
        claude->>slack: 西川/稲川へ事前連携
    else 通常依頼
        claude->>req: 通常の要件Q&A
    end
        

仕組みの具体例（describe ／ 依存の地図）

① describe＝「SFの設計図を読み取る」

あるオブジェクト（テーブル相当）の全項目の仕様（設計図）を一発で取るSFの機能。sf_utils.py が裏で SF CLI を叩いて返す。これを毎時取って前回と比べる＝検知の心臓。

# describe("OrganizationalCoaching__c") が返す1項目の例
{
  "name": "StageName__c",        // API名（リネーム検知の主キー）
  "label": "商談フェーズ",         // 画面表示名
  "type": "picklist",            // 型（変更を検知）
  "custom": true,
  "nillable": true,
  "picklistValues": [             // ← 選択肢値（StageName__c問題の検知）
    {"label": "担当者ビジネスMTG", "active": true},
    {"label": "フロント受注", "active": true}, ...
  ]
}

② 依存の地図（dependency-graph.json）＝「何が倒れるかを引ける辞書」

「SFのこの項目を変えたら、どのBQテーブル・SQL・ダッシュボードのどのKPIが倒れるか」を機械が引ける地図（辞書）。SQL/GASをパースして自動生成し、手では持たない（CIで再生成＝腐らせない）。

// 変更項目をキーに引くと、影響先(consumed_by)が一覧で返る
{
  "OrganizationalCoaching__c.StageName__c": {
    "type": "picklist",
    "使われている選択肢値": ["担当者ビジネスMTG", "フロント受注", "本契約受注"],
    "consumed_by": [
      { "経路": "B（GAS直結）",
        "資産": "management-cockpit/org-coaching.gs",
        "KPI": ["組織コーチング_ファネル各段階"] }
    ]
  },
  "Lead__c.SurveyLpConcerns__c": {
    "type": "picklist",
    "consumed_by": [
      { "経路": "A（SQL経由）", "資産": "sql/staging/staging_Lead__c.sql" },
      { "経路": "A（SQL経由）", "資産": "sql/analytics/integrated_customer_analytics.sql" },
      { "経路": "A（SQL経由）", "資産": "management-cockpit/carispi.gs", "KPI": ["キャリスピ商談フェーズ"] }
    ]
  }
}

実装論点：現状から理想形への差分

「当初の2ポイント案（①依頼フォーム連携 ②デプロイ前テスト）」で既に実現できている点も含め、理想形に対して何が足りないか＝何を実装するかを差分で整理する。

段階導入ロードマップ

SFDX / GitHub化 — 必要性が実証された構造の本丸（段階導入）

SFDXは、SFの設定（項目・フロー等）をコード化してGitHubで管理するやり方。直近のVISION事故は「テストフロー不在・属人化・レビュー無し」が根因で、SFDXはその根因の構造的な解。検知システムはSFDX無しで完結するが、SFDX化すると検知が「事後の網」→「デプロイ前ゲート」に昇格する。

SFDXとは何か（SF CLIとの違い・3層構造）

SF CLI（sfコマンド）は"道具"、SFDXはそれを使った"設定をコード化してGit管理する開発方法論"。今 sf_utils.py で sf sobject describe を叩いてるのは"CLIの一機能を使ってる"だけで、まだSFDXの運用には入ってない。

[SFDXの3層構造]
道具層     : SF CLI（sf project deploy / sobject describe / apex run ...）
方法論層   : force-app/main/default/{objects, flows, classes, validationRules}/   ← Git管理
統制層     : Git ＋ PR ＋ CI ＋ Scratch Org ＋ ロールバック

何ができて、何は人がやるか（1402結論の更新）

BQ連携以外に、どんな恩恵があるか

業務プロセス・品質 Before / After

UI → SFDX へ移行するステップ（ざっくり）

体制と運用（VISION事故・台帳ふまえた再設計）

SFDX化やデータ整合ゲートはあくまで"道具と仕組み"。それを動かす体制と運用が伴わなければ事故は再発する。直近のSlack(5/22-23)・SF管理台帳・1402の証拠を踏まえて、現状を正直に評価する。

現状ファクト（証拠ベース）

体制再編 3案（トレードオフで提示）

90日アクション順

Claude Codeスキル化で工夫できる内容

SFのベテラン暗黙知をAIスキルに閉じ込めて、横断者・新規メンバーでも踏み外せん仕組みを作る。これが脱属人化の本丸ツール。

付録：再利用資産・検証・リスク

再利用する既存資産

検証方法

未解決リスク・要確認