SKILLOfficialdevelopment

platform-apex-logs-debug

プラグイン: salesforce-development
ソース: GitHub で見る ↗

説明

Salesforce（営業支援クラウド）のデバッグログ解析とトラブルシューティングを100点満点のスコアリング（評価）で提供します。 **次のような場合に使用:** - ユーザーがデバッグログを分析している - ガバナー制限（システムの実行制限）に達した - スタックトレース（エラー発生の経路情報）を読んでいる - Salesforce組織の .log ファイルを操作している **使用しない場合:** - Apex（プログラミング言語）テストを実行している場合 → platform-apex-test-run を使用 - Apex コードを生成・修正している場合 → platform-apex-generate を使用 - Agentforce（AI音声・チャット機能）のセッショントレース（実行履歴の追跡）を行っている場合 → agentforce-observe を使用

原文を表示

Salesforce debug log analysis and troubleshooting with 100-point scoring. TRIGGER when: user analyzes debug logs, hits governor limits, reads stack traces, or touches .log files from Salesforce orgs. DO NOT TRIGGER when: running Apex tests (use platform-apex-test-run), generating or fixing Apex code (use platform-apex-generate), or Agentforce session tracing (use agentforce-observe).

ユースケース

デバッグログを分析している
ガバナー制限に達した
スタックトレースを読んでいる
Salesforce組織の.logファイルを操作している

本文（日本語訳）

platform-apex-logs-debug: Salesforceデバッグログ分析とトラブルシューティング

次のような場合に使用: ユーザーがデバッグログから根本原因を特定する必要がある場合。具体的には、ガバナンスリミット（Salesforceの処理制限）の診断、スタックトレース（エラーが発生した処理の流れ）の読み解き、遅いクエリの調査、メモリやCPU負荷の分析、またはログに基づく再現から修正までの一連の作業が該当します。

このスキルが担当する作業

platform-apex-logs-debugを使用するのは以下の作業が含まれる場合です：

Salesforceの.logファイル
スタックトレースと例外分析
ガバナンスリミット
SOQL・DML・CPU・メモリのトラブルシューティング
ログから抽出されたクエリプラン（実行計画）またはパフォーマンス情報

以下の場合は別のスキルに委ねてください：

Apexテストを実行または修復する → platform-apex-test-run
コードの修正を生成または実装する → platform-apex-generate
Agentforce セッショントレース / Parquetテレメトリ（詳細な性能データ）のデバッグ → agentforce-observe

最初に集めるべき情報

以下の内容を確認または推測してください：

組織の別名（org alias）
失敗したトランザクション・ユーザーフロー・テスト名
概数でのタイムスタンプまたはトランザクション期間
既知であればユーザーID・レコードID・リクエストID
目標が「診断のみ」か「診断＋修正サイクル」か

推奨される進め方

1. ログの取得

references/cli-commands.md のコマンドを使って、対象の組織からログを一覧表示・ダウンロード・ストリーミング（リアルタイム取得）します。

2. この順序で分析する

エントリーポイント（処理の入口）とトランザクションタイプ
例外とエラー
ガバナンスリミット
繰り返されるSOQL・DMLパターン
CPU・メモリのボトルネック
外部API呼び出しのタイミングと失敗

3. 深刻度を分類する

危機的 — 実行時エラー、リミット超過、データ破損の恐れ
警告 — リミット接近、不適切なクエリ、処理の遅延
情報 — 最適化のチャンスまたは保守性の改善点

4. 最小限で正確な修正を提案する

以下を優先します：

根本原因に対処している
大量データ処理に対応している
テスト可能である
再実行で検証しやすい

詳細な進め方: references/analysis-playbook.md

重要な問題パターン

問題	主な兆候	対策の方向性
ループ内のSOQL	ループ処理の中で繰り返される `SOQL_EXECUTE_BEGIN`	クエリを1回に、その結果をマップ・グループ化して使用
ループ内のDML	繰り返される `DML_BEGIN` パターン	行データを集めて1回のDMLを実行
不適切なクエリ	スキャン行数が多い・選択性が低い	インデックス付きフィルタを追加、検索範囲を縮小
CPU負荷	CPU使用量が同期実行の上限に接近	アルゴリズムの複雑さを削減、キャッシュ化、妥当な場合は非同期処理に
メモリ負荷	メモリ使用量が同期実行の上限に接近	SOQLのfor-loopでストリーミング処理、メモリ上のデータ量を削減
ヌルポインタ・致命的エラー	`EXCEPTION_THROWN` / `FATAL_ERROR`	ヌル値チェックの追加、空のクエリ結果の処理を修正

詳細な例: references/common-issues.md

報告形式

分析完了時は、この順序で報告してください：

何が失敗したのか
どこで失敗したのか（クラス・メソッド・行番号・トランザクションのどの段階）
なぜ失敗したのか（表面的な症状ではなく、根本原因）
どの程度深刻か
推奨される修正方法
検証方法

推奨される形式：

問題: <概要>
場所: <クラス / 行番号 / トランザクション段階>
根本原因: <説明>
深刻度: 危機的 | 警告 | 情報
修正: <具体的な対応>
検証: <テストまたは再実行のステップ>

ルールと制約

ルール	理由
修正の推奨は常にログ証拠に基づく	推測診断を避ける — 根本原因はログで追跡可能である必要がある
発見した問題ごとに6つの出力項目すべてを報告する	各問題について実行可能で完全な知見を確保する
すべての発見を「危機的」「警告」「情報」に分類する	ユーザーが対応の優先順位を決めやすくする
コード生成は`platform-apex-generate`に委ねる	このスキルは診断専門——Apexコードの書き直しは行わない
テスト実行は`platform-apex-test-run`に委ねる	このスキルはテストクラスの実行・修復を行わない
`LIMIT_USAGE`イベントを読まずにリミットが安全と仮定しない	リミットは失敗ポイント以前の操作で消費されている可能性がある

よくある落とし穴と対策

落とし穴	対策
ログが2MBで切られている	デバッグレベルを下げ（例：`ApexCode: INFO`、`ApexProfiling: FINE`）、再度キャプチャ
同じ問題がSOQL問題とCPU問題の両方に見える	ループ内のSOQLを先に修正——通常これがCPU急増の二次的な原因
トレースフラグ設定後、ログが表示されない	トレースフラグの有効期限（`ExpirationDate`）が未来の日付か、正しいユーザーがトレース対象か確認
非同期処理ではリミット値が変わる	CPU上限は非同期で60,000ミリ秒、同期で10,000ミリ秒——リミット判定の前にトランザクションタイプを確認
スタックトレースがフレームワークの行を指す	ユーザーコードの発生源を見つけるため、トリガーハンドラを越えてコールスタックを遡る

スキル間の連携

必要な作業	委ねるスキル	理由
Apex修正を実装する	platform-apex-generate	コード変更生成・レビュー
テストで再現する	platform-apex-test-run	テスト実行とカバレッジの確認ループ
修正をデプロイする	platform-metadata-deploy	デプロイメント統制
デバッグ用データを作成する	platform-data-manage	再現用データの準備・供給

リファレンスファイル一覧

ファイル	読むべき場面
`references/analysis-playbook.md`	まずここから——デバッグセッション全般の詳細な進め方
`references/common-issues.md`	ループ内SOQL・ループ内DML・CPU/メモリ負荷・ヌルポインタパターンの辞書
`references/cli-commands.md`	デバッグログの取得・ストリーミング・管理用のSF CLIコマンド
`references/debug-log-reference.md`	イベントタイプ完全カタログ、ログレベル、ガバナンスリミット参照値
`references/log-analysis-tools.md`	Apex Log Analyzer・Developer Console・CLI grep パターンのガイド
`references/benchmarking-guide.md`	パフォーマンス計測の技法、ベンチマークデータ、アンチパターン
`references/scoring-rubric.md`	分析品質を評価するための100点スコアリング基準
`assets/benchmarking-template.cls`	パフォーマンス計測用のApex無名実行テンプレート（コピペ可）
`assets/cpu-heap-optimization.cls`	CPU時間とメモリ割り当てを減らすApexパターン
`assets/dml-in-loop-fix.cls`	ループ内DML問題の修正ビフォー・アフター例
`assets/soql-in-loop-fix.cls`	ループ内SOQL問題の修正ビフォー・アフター例
`assets/null-pointer-fix.cls`	ヌルポインタ例外対策パターン

スコアガイド

スコア	意味
90以上	熟練した分析と優れた修正ガイダンス
80〜89	良好な分析、軽微な漏れあり
70〜79	許容範囲だが二次的な問題を見落とす可能性
60〜69	部分的な診断のみ
60未満	不完全な分析

原文（English）を表示

platform-apex-logs-debug: Salesforce Debug Log Analysis & Troubleshooting

Use this skill when the user needs root-cause analysis from debug logs: governor-limit diagnosis, stack-trace interpretation, slow-query investigation, heap / CPU pressure analysis, or a reproduction-to-fix loop based on log evidence.

When This Skill Owns the Task

Use platform-apex-logs-debug when the work involves:

.log files from Salesforce
stack traces and exception analysis
governor limits
SOQL / DML / CPU / heap troubleshooting
query-plan or performance evidence extracted from logs

Delegate elsewhere when the user is:

running or repairing Apex tests → platform-apex-test-run
generating or implementing the code fix → platform-apex-generate
debugging Agentforce session traces / parquet telemetry → agentforce-observe

Required Context to Gather First

Ask for or infer:

org alias
failing transaction / user flow / test name
approximate timestamp or transaction window
user / record / request ID if known
whether the goal is diagnosis only or diagnosis + fix loop

Recommended Workflow

1. Retrieve logs

Use the commands in references/cli-commands.md to list, download, or stream logs for the target org.

2. Analyze in this order

entry point and transaction type
exceptions / fatal errors
governor limits
repeated SOQL / DML patterns
CPU / heap hotspots
callout timing and external failures

3. Classify severity

Critical — runtime failure, hard limit, corruption risk
Warning — near-limit, non-selective query, slow path
Info — optimization opportunity or hygiene issue

4. Recommend the smallest correct fix

Prefer fixes that are:

root-cause oriented
bulk-safe
testable
easy to verify with a rerun

Expanded workflow: references/analysis-playbook.md

High-Signal Issue Patterns

Issue	Primary signal	Default fix direction
SOQL in loop	repeating `SOQL_EXECUTE_BEGIN` in a repeated call path	query once, use maps / grouped collections
DML in loop	repeated `DML_BEGIN` patterns	collect rows, bulk DML once
Non-selective query	high rows scanned / poor selectivity	add indexed filters, reduce scope
CPU pressure	CPU usage approaching sync limit	reduce algorithmic complexity, cache, async where valid
Heap pressure	heap usage approaching sync limit	stream with SOQL for-loops, reduce in-memory data
Null pointer / fatal error	`EXCEPTION_THROWN` / `FATAL_ERROR`	guard null assumptions, fix empty-query handling

Expanded examples: references/common-issues.md

Output Format

When finishing analysis, report in this order:

What failed
Where it failed (class / method / line / transaction stage)
Why it failed (root cause, not just symptom)
How severe it is
Recommended fix
Verification step

Suggested shape:

Issue: <summary>
Location: <class / line / transaction>
Root cause: <explanation>
Severity: Critical | Warning | Info
Fix: <specific action>
Verify: <test or rerun step>

Rules / Constraints

Rule	Rationale
Always base fix recommendations on log evidence	Avoid speculative diagnosis — root cause must be traceable in the log
Report all six output fields for every issue found	Ensures actionable, complete findings for each problem
Classify every finding as Critical, Warning, or Info	Helps the user prioritize which issues to address first
Delegate code generation to `platform-apex-generate`	This skill diagnoses; it does not rewrite Apex code
Delegate test execution to `platform-apex-test-run`	This skill does not run or repair test classes
Never assume limits are safe without reading `LIMIT_USAGE` events	Limits may be consumed by earlier operations not visible in the failure point

Gotchas

Pitfall	Resolution
Log truncated at 2 MB	Reduce debug levels (e.g., `ApexCode: INFO`, `ApexProfiling: FINE`) and re-capture
Same issue appears as both SOQL and CPU problem	Fix SOQL-in-loop first — it typically drives the CPU spike as a secondary effect
No logs appear after trace flag is set	Verify the trace flag `ExpirationDate` is in the future and the correct user is traced
Async context changes limit values	CPU limit is 60,000 ms async vs 10,000 ms sync — check transaction type before flagging limits
Stack trace points to framework line, not user code	Walk up the call stack past trigger handlers to find the originating user code

Cross-Skill Integration

Need	Delegate to	Reason
Implement Apex fix	platform-apex-generate	code change generation / review
Reproduce via tests	platform-apex-test-run	test execution and coverage loop
Deploy fix	platform-metadata-deploy	deployment orchestration
Create debugging data	platform-data-manage	targeted seed / repro data

Reference File Index

File	When to read
`references/analysis-playbook.md`	Start here — expanded step-by-step workflow for any debugging session
`references/common-issues.md`	Quick lookup for SOQL in loop, DML in loop, CPU/heap pressure, null pointer patterns
`references/cli-commands.md`	SF CLI commands for retrieving, streaming, and managing debug logs
`references/debug-log-reference.md`	Full event type catalog, log levels, and governor limit reference values
`references/log-analysis-tools.md`	Tool guide: Apex Log Analyzer, Developer Console, CLI grep patterns
`references/benchmarking-guide.md`	Performance benchmarking techniques, benchmark data, and anti-patterns
`references/scoring-rubric.md`	100-point scoring rubric for evaluating analysis quality
`assets/benchmarking-template.cls`	Copy-paste Anonymous Apex template for running performance benchmarks
`assets/cpu-heap-optimization.cls`	Apex patterns for reducing CPU time and heap allocation
`assets/dml-in-loop-fix.cls`	Before/after example for resolving DML-in-loop violations
`assets/soql-in-loop-fix.cls`	Before/after example for resolving SOQL-in-loop violations
`assets/null-pointer-fix.cls`	Patterns for guarding against null pointer exceptions

Score Guide

Score	Meaning
90+	Expert analysis with strong fix guidance
80–89	Good analysis with minor gaps
70–79	Acceptable but may miss secondary issues
60–69	Partial diagnosis only
< 60	Incomplete analysis

原文・著作権は Anthropic および各プラグイン作者に帰属します。日本語訳は Claude API による自動翻訳です。