dx-code-analyzer-configure

Code Analyzer スキルの設定

概要

エコシステム： このスキルは、3 つのスキルで構成される Code Analyzer スイートの一部です — dx-code-analyzer-run（スキャンと結果） · dx-code-analyzer-configure（セットアップ、設定、CI/CD） · dx-code-analyzer-custom-rule-create（カスタムルールの作成）。

このスキルでは、プロジェクトにおける Code Analyzer の動作を決定する唯一の情報源である code-analyzer.yml 設定ファイルを管理します。カスタマイズ（エンジン、ルール、無視設定、抑制）はすべて、このファイルを作成または編集して行います。ファイルが存在しない場合は、現在の作業ディレクトリに作成します。

---

対象範囲

対象：

• 前提条件の確認（sf CLI、Java、Node.js、Python、組織認証）
• Code Analyzer プラグインのインストール／更新
• code-analyzer.yml が存在しない場合の作成
• すべての設定変更に伴う code-analyzer.yml の編集
• エンジン設定、ルールの上書き、無視パターン、抑制
• CI/CD パイプラインのセットアップ（GitHub Actions、Jenkins など）
• 環境の検証とトラブルシューティング

対象外：

• スキャンの実行 → dx-code-analyzer-run スキルを使用
• 違反の修正、ルールの説明、抑制の管理 → dx-code-analyzer-run スキルを使用
• カスタムルールの作成 → dx-code-analyzer-custom-rule-create スキルを使用

---

ツールの使用ルール

使用可能： Bash（sf、java、node、python3、npm）、Read、Write、Edit 使用禁止： MCP ツール、Agent ツール、Web ツール、その他のスキル、which、find、locate、バイナリの検索

---

基本原則：カスタマイズする場合のみ YAML を使用

Code Analyzer は設定ファイルがなくても、すべてのデフォルト設定がツールに組み込まれているため、そのまま動作します。code-analyzer.yml ファイルは、ユーザーが明示的にカスタマイズを要求した場合にのみ作成します。

ルール：

• code-analyzer.yml を先回りして作成しないでください — ユーザーが変更を求めた場合にのみ作成します
• 組み込みのデフォルト設定を重複して記述しないでください — 動作を意図的に上書きする項目のみを記述します
• 必ずプロジェクトのルートに配置してください — sfdx-project.json または sf-project.json がある場所です
• CLI が自動検出します — プロジェクトルートから sf code-analyzer run を実行すると、そのディレクトリ内の code-analyzer.yml が自動的に読み込まれます。--config-file フラグは不要です。
• ユーザーが具体的な内容を示さずに「code analyzer を設定して」と言った場合 → 何をカスタマイズしたいか尋ねてください。空のファイルやひな形のファイルは作成しないでください。

ワークフロー：

1. ユーザーがカスタマイズを依頼する（例：「PMD を無効にする」「テストファイルを無視する」「SFGE のメモリを増やす」）
2. プロジェクトルートに code-analyzer.yml があるか確認する
3. ない場合 → 要求された上書き設定のみを記述して、プロジェクトルートに作成する
4. ある場合 → ファイルを読み込んでから、要求された変更を加える
5. sf code-analyzer config で検証する

---

ステップ 1：意図を把握し、設定セクションに対応付ける

ユーザーは自然言語で、任意の組み合わせの設定変更を依頼できます。あなたの役割は次のとおりです。

1. 要望を把握する — 1 つの場合も、複数の要望が組み合わさっている場合もあります
2. 各要望を code-analyzer.yml の適切なセクションに対応付ける
3. ファイルが存在しない場合は作成し、すべての変更を適用する

code-analyzer.yml の構造（記述・編集できる内容）

config_root: .                    # Root for relative path resolution
log_folder: <path>                # Where logs are written
log_level: <1-5>                  # 1=Error, 2=Warn, 3=Info, 4=Debug, 5=Fine

ignores:                          # Files/folders excluded from scanning
  files: [<glob patterns>]

engines:                          # Per-engine settings
  <engine_name>:
    disable_engine: <bool>
    <engine_specific_keys>: ...

rules:                            # Per-rule overrides
  <engine_name>:
    <rule_name>:
      severity: <1-5>
      tags: [<strings>]
      disabled: <bool>

suppressions:                     # Bulk suppression configuration
  disable_suppressions: <bool>
  "<file_or_folder_path>":
    - rule_selector: "<selector>"
      max_suppressed_violations: <number|null>
      reason: "<why>"

マッピングの原則

ユーザーのリクエストは、上記のセクションの1つ以上に対応します。意図を解析し、適切なセクションを編集してください。

意図のカテゴリ	対応先	ユーザーが言う可能性のある例
セットアップ／インストール	ステップ2（前提条件＋インストール）	「セットアップして」「インストールして」「始めたい」「新しいノートパソコン」「最初から」
診断／修正	ステップ2A（体系的なデバッグ）	「動かない」「壊れている」「セットアップを修正して」「スキャンが失敗する」「エラーが出る」
エンジンの制御	engines.<name>.disable_engine	「Xを無効にして」「Yをオフにして」「Zだけ使って」「すべて有効にして」
エンジンの調整	engines.<name>.<property>	「メモリを増やして」「ヒープを変更して」「自分のeslint設定を使って」「トークンを50に設定して」
ファイルの除外	ignores.files	「除外して」「無視して」「スキップして」「Xをスキャンしないで」
ルールの重大度	rules.<engine>.<rule>.severity	「Xをcriticalにして」「昇格して」「降格して」「重大度を変更して」
ルールの無効化	rules.<engine>.<rule>.disabled	「ルールXを無効にして」「ルールYをオフにして」「Zを削除して」
ルールのタグ	rules.<engine>.<rule>.tags	「Xにsecurityタグを付けて」「recommendedタグを追加して」
抑制	suppressions セクション	「フォルダーYでXを抑制して」「違反をN件許可して」
CI/CD	パイプラインファイルを生成（設定とは別）	「GitHub Actions」「CI」「品質ゲート」
表示／確認	ファイルを読み取り、sf code-analyzer config を実行	「設定を表示して」「何が設定されている？」「現在の設定」

ファイルの存在確認

何かを編集する前に、プロジェクトのルートに code-analyzer.yml が存在するか確認してください。

ls code-analyzer.yml code-analyzer.yaml 2>/dev/null

• ファイルが存在しない → ユーザーがリクエストした上書き設定のみを含むファイルをプロジェクトのルートに作成します
• ファイルが存在する → ファイルを読み取り、リクエストされたセクションを追加または変更します

CLI は現在のディレクトリにある code-analyzer.yml を自動検出します。スキャンはプロジェクトのルートから実行されるため、ファイルはそこに配置する必要があります。

ルール名の解決 — YAMLを書く前に必ず実行

ユーザーが部分的、説明的、またはおおよその名前でルールを指定した場合（例：「ドキュメントのルール」「CRUD違反」「consoleのルール」「ハードコードされた値」）、YAMLを書く前に、ステップ6.1の検索を使って正確なルール名を解決する必要があります。code-analyzer.yml ファイルは、正確に一致しないルール名を警告なしに無視します。エラーは発生せず、上書き設定も適用されません。

あいまいな名前から正確な名前への解決が必要な例：

• 「ApexDocルールを無効にして」→ 検索で ApexDoc（エンジン：pmd）を確認します
• 「no-consoleをlowに降格して」→ 検索で no-console（エンジン：eslint）を確認します
• 「CRUD違反をcriticalにして」→ 検索で ApexCRUDViolation（エンジン：pmd）を確認します
• 「ハードコードされた値のチェックをオフにして」→ 検索で @salesforce-ux/slds/no-hardcoded-values-slds2（エンジン：eslint）を見つけます
• 「インジェクションのルールを無効にして」→ 複数の候補が考えられるため、どれを指すのかユーザーに尋ねます

検索を省略できるのは、ユーザーが曖昧さのない、正確で、よく知られた名前を指定した場合のみです（例：「ApexDoc」「no-console」「no-unused-vars」）。

複合／複雑なリクエストへの対応

ユーザーは複数の変更を1つのリクエストにまとめることがよくあります。すべてを1回の編集で処理してください。

• 「PMDのApexDocルールを無効にして、CRUD違反をcriticalにして」→ rules.pmd の下にある2つの項目を編集します
• 「テストファイルとベンダーコードを除外して、SFGEのメモリを増やして」→ ignores.files と engines.sfge.java_max_heap_size を編集します
• 「ESLintとPMDだけを使い、node_modulesを無視するようにcode analyzerをセットアップして」→ engines（他のエンジンを無効化）と ignores を含むファイルを作成します
• 「すべてのセキュリティルールの重大度を1にして」→ sf code-analyzer rules --rule-selector Security でルールを検索し、それぞれを上書きします
• 「code analyzerを設定して」（具体的な指定なし）→ ファイルを作成する前に、何をカスタマイズしたいのかユーザーに尋ねます

クイックリファレンス：よくあるリクエスト → 設定出力

ユーザーの発言	生成される YAML
「コードアナライザーを設定して」	ユーザーに何をカスタマイズするか尋ねます。実際に上書きする内容が決まるまではファイルを作成しません
「ApexDoc ルールを無効にして」	rules: pmd: ApexDoc: disabled: true
「Apex だけをスキャンして、JavaScript はスキャンしないで」	engines: eslint: disable_engine: true + engines: retire-js: disable_engine: true
「すべてのテストファイルを無視して」	ignores: files: ["**/test/**", "**/__tests__/**", "**/*.test.js"]
「セキュリティルールを重大にして」	ルールを調べてから、各ルールに対して rules: <engine>: <rule>: severity: 1 を設定します
「SFGE のメモリを 8g に増やして」	engines: sfge: java_max_heap_size: "8g"
「自分のプロジェクトの ESLint 設定を使って」	engines: eslint: auto_discover_eslint_config: true
「レガシーフォルダー内の CRUD 違反を抑制して」	suppressions: "force-app/legacy/": [{rule_selector: "pmd:ApexCRUDViolation", reason: "..."}]

AI は、上記の例に限らず、YAML スキーマを理解し、あらゆるリクエストに対して有効な設定を作成する必要があります。

---

ステップ 2：前提条件の確認とインストール

bash "<skill_dir>/scripts/check-prerequisites.sh" を実行するか、手動で確認します。

sf --version 2>&1                                    # sf CLI
sf plugins --core 2>&1 | grep -i "code-analyzer"    # Plugin
java -version 2>&1                                   # Java 11+ (PMD, CPD, SFGE)
node --version 2>&1                                  # Node 18+ (ESLint, RetireJS)
python3 --version 2>&1                               # Python 3 (Flow engine)

不足しているものがあれば、インストールします（必ず最初にユーザーに確認してください）。

npm install -g @salesforce/cli                       # sf CLI
sf plugins install @salesforce/plugin-code-analyzer  # Code Analyzer plugin

Java／Node／Python のインストールについては、<skill_dir>/references/engine-prerequisites.md を読んでください。 インストールに失敗した場合は、<skill_dir>/references/troubleshooting.md を読んでください。

---

ステップ 2A：壊れたセットアップの診断と修正

トリガー： ユーザーが「動かない」「壊れている」「エラーが出る」「スキャンに失敗する」「修正を手伝って」などと言った場合。

完全な段階的診断手順、修正表、アンチパターンについては、<skill_dir>/references/diagnostic-flow.md を読んでください。

主な原則（必ず適用）：

• バイナリを検索しないでください（which、find、ls /opt/homebrew/bin/）
• 回避策として sfdx を使わないでください。sf のみを使用します
• レイヤーごとに修正します：CLI → プラグイン → エンジンの依存関係 → スキャンの確認
• 一度に 1 つのコマンドだけをユーザーに提示し、続行する前に確認を待ちます
• 修正が成功したら、自動的に全スキャンの実行に進みます

---

ステップ 3：code-analyzer.yml の作成または編集

ユーザーがカスタマイズをリクエストした場合にのみ実行します。 先回りして作成しないでください。

作成（ファイルが存在しない場合）

以下の 2 つの方法のうち、どちらか 1 つを選びます。両方を実行しないでください。

オプション A — プロジェクトの種類から自動生成する（初回セットアップにおすすめ）：

bash "<skill_dir>/scripts/generate-config.sh" を実行します。このスクリプトは Apex、LWC、Flow のマーカーを検出し、プロジェクトに適した最小限の code-analyzer.yml を生成します。その後、「作成または編集後の検証」セクションに進みます。

注：code-analyzer.yml がすでに存在する場合、スクリプトはエラーで終了します。再生成が必要な場合は、既存ファイルを先に削除してください。

オプション B — 手動で記述する（ユーザーが具体的なカスタマイズを希望している場合）：

構成の参考として、適切な設定例を読んでください。

• Apex のみのプロジェクトの場合は、<skill_dir>/examples/apex-project-config.yml を読みます
• LWC のみのプロジェクトの場合は、<skill_dir>/examples/lwc-project-config.yml を読みます
• フルスタック（Apex + LWC + Flows）の場合は、<skill_dir>/examples/fullstack-project-config.yml を読みます

Write ツールを使って、プロジェクトのルートにファイルを作成します。ユーザーがリクエストした変更のみを含めます。

# Example: user said "ignore test files and increase SFGE memory"
# → Write to project root (where sfdx-project.json lives):

ignores:
  files:
    - "**/test/**"
    - "**/__tests__/**"

engines:
  sfge:
    java_max_heap_size: "4g"

ユーザーが依頼していない config_root、log_folder、その他のフィールドを追加しないでください。

編集（ファイルがすでに存在する場合）

ファイルを読み込んでから、Edit ツールを使い、関連するセクションのみを追加または変更します。それ以外はすべてそのまま保持してください。

作成または編集後の検証：

bash "<skill_dir>/scripts/validate-config.sh" を実行して YAML の構文とスキーマの正しさを検証するか、CLI を直接使用します。

sf code-analyzer config

（--config-file は不要です。CLI は CWD 内の code-analyzer.yml を自動検出します。）

ユーザーが具体的な内容を指定せずに「コードアナライザーを設定して」と言った場合

次のように尋ねます。「何をカスタマイズしますか？ たとえば、特定のファイルを無視する、ルールの重大度を変更する、エンジンの設定を調整する、不要なエンジンを無効にする、といったことができます。」

ステップ 4：エンジンの有効化／無効化

code-analyzer.yml の engines セクションを編集します。

engines:
  pmd:
    disable_engine: true       # Disable PMD
  eslint:
    disable_engine: false      # Enable ESLint (default)

有効なエンジン名：pmd、cpd、eslint、regex、retire-js、flow、sfge、apexguru

編集後は必ず検証してください：

sf code-analyzer config --config-file code-analyzer.yml

---

ステップ 5：無視パターン

code-analyzer.yml の ignores セクションを編集します。

ignores:
  files:
    - "**/node_modules/**"
    - "**/.sfdx/**"
    - "**/.sf/**"
    - "**/vendor/**"
    - "**/*.min.js"

一般的なパターン：

パターン	除外対象
**/node_modules/**	npm の依存関係
**/.sfdx/**、**/.sf/**	SF CLI の内部ファイル
**/test/**、**/__tests__/**	テストディレクトリ
**/*.test.js、**/*.spec.js	テストファイル
**/jest-mocks/**	Jest のモック
**/vendor/**、**/*.min.js	サードパーティ製／圧縮済みファイル
**/staticresources/**	静的リソース

---

ステップ 6：ルールの上書き

code-analyzer.yml の rules セクションを編集します。各ルールでは、severity、tags、disabled を上書きできます。

rules:
  pmd:
    ApexCRUDViolation:
      severity: 1              # Promote to Critical
    AvoidGlobalModifier:
      disabled: true           # Turn off entirely
    ApexDoc:
      severity: 5              # Demote to Info
      tags: ["Documentation"]
  eslint:
    no-console:
      severity: 4              # Demote to Low
    no-unused-vars:
      severity: 2              # Promote to High

重要度の値： 1／重大、2／高、3／中、4／低、5／情報

6.1 ルール名の解決（あいまいな一致）

重要： code-analyzer.yml のルール名に誤字がある場合や、一部しか指定されていない場合、その設定はエラーなしで無視され、上書きは適用されません。

ユーザーが概略的な名前でルールを指定した場合（例：「ドキュメントのルール」、「CRUD 違反」、「ハードコードされた値」）、YAML を記述する前に正確な名前を特定します。

sf code-analyzer rules --rule-selector all 2>&1 | grep -i "<USER_KEYWORD>"

• 一致が 1 件 → YAML のパスには、その正確な名前と対応するエンジンを使用します
• 一致が複数件 → どのルールを指しているのかユーザーに確認します
• 一致が 0 件 → より広いキーワードで検索するか、ユーザーに伝えます

名前が明確かつ正確な場合（例：「ApexDoc」、「no-console」、「no-unused-vars」）に限り、検索を省略します。

一致方法の詳細、一般的なあいまいな名前から正確な名前への対応、エンジンの特定方法については、 <skill_dir>/references/rule-name-resolution.md を読みます。

---

ステップ 7：エンジン固有の設定

engines セクションを編集します。一般的な上書き項目は次のとおりです。

engines:
  sfge:
    java_max_heap_size: "4g"      # <200 classes→"2g", 200-500→"4g", 500+→"6g"/"8g"
    java_thread_count: 4
    java_thread_timeout: 900000
  eslint:
    auto_discover_eslint_config: true    # Use project's own ESLint config
    eslint_config_file: "./eslint.config.mjs"
  pmd:
    custom_rulesets: ["./config/custom-pmd-rules.xml"]
    java_classpath_entries: ["./lib/custom-rules.jar"]
  cpd:
    minimum_tokens: { apex: 100, javascript: 100 }
  apexguru:
    target_org: "my-org-alias"
  flow:
    python_command: "python3"
  # regex.custom_rules — use the dx-code-analyzer-custom-rule-create skill to create these.
  # Never hand-write regex patterns into code-analyzer.yml: quotes/backslashes
  # inside YAML cause parsing failures. The create-regex-rule.js script handles
  # serialization correctly and must always be used for regex rule creation.

エンジンごとのプロパティ一覧については、<skill_dir>/references/config-schema.md を読みます。

---

ステップ 8：CI/CD パイプラインのセットアップ

ワークスペースから CI システムを特定します（.github/workflows/ → GitHub Actions、Jenkinsfile → Jenkins など）。テンプレートについては、<skill_dir>/references/ci-cd-templates.md を読みます。GitHub Actions のベースとして <skill_dir>/examples/ci-github-actions.yml を使用します。主なフラグ：--severity-threshold 2（ゲート）、--output-file results.sarif（GitHub のスキャン）、--config-file code-analyzer.yml。

---

ステップ 9：現在の設定を表示

sf code-analyzer config                               # Show effective config
sf code-analyzer config --rule-selector pmd:Security  # Specific rules
sf code-analyzer config --include-unmodified-rules    # All defaults

---

スキル間の連携

このスキルは dx-code-analyzer-run と連携して動作します。AI エージェントは、両者の間でシームレスに処理を引き継ぎます。

dx-code-analyzer-run からこのスキルに処理が委譲された場合：

ユーザーが「コードをスキャンして」／「コードアナライザーを実行して」と言ったものの、失敗した場合（CLI が見つからない、プラグインがインストールされていない、スキャンでエラーが発生したなど）、dx-code-analyzer-run はこのスキルに処理を委譲します。その場合：

1. 診断と修正の手順（ステップ 2A）を実行します。問題の原因を特定して修正します
2. すべてが動作するようになったら、自動的にスキャンの実行に進みます。停止して確認を求めないでください。ユーザーの本来の目的はスキャンです
3. 実行を dx-code-analyzer-run の動作に引き継ぎます（コマンドを構築し、実行して、結果を解析します）

このスキルから dx-code-analyzer-run に処理を引き継ぐ場合：

設定操作が成功した後は、スキャンを実行するかユーザーに確認します（例：「セットアップが完了しました！スキャンを実行しますか？」「設定を更新しました。スキャンして確認しますか？」）。ユーザーが同意したら、dx-code-analyzer-run の動作に進みます。

このスキルから dx-code-analyzer-custom-rule-create に処理を引き継ぐ場合：

設定作業中にユーザーがカスタムルールの作成を依頼した場合（例：「System.debug を禁止するルールも追加して」「PMD XPath ルールを設定して」）、dx-code-analyzer-custom-rule-create に処理を委譲します。そのスキルが完了した後、code-analyzer.yml の custom_rulesets または eslint_config_file の参照先を設定する必要がある場合があります。その編集はこのスキルで行います。

ユーザーの意図が両方のスキルにまたがる場合：

エンドツーエンドで対応します：「動作しない」→診断→修正→スキャン。「セットアップしてスキャン」→インストール→スキャン。「ESLint を無効にして Apex をスキャン」→設定を編集→--rule-selector pmd を指定して実行。「カスタムルールを設定してスキャン」→dx-code-analyzer-custom-rule-create→設定を組み込む→dx-code-analyzer-run。ユーザーの最終的な意図を必ず最後まで実現してください。

---

ルール／制約

制約	理由
ユーザーがカスタマイズを依頼した場合にのみ YAML を作成する	ファイルがなくてもデフォルトで動作します。定型ファイルは作成しないでください
YAML はプロジェクトのルートにのみ配置する	CLI は CWD から code-analyzer.yml を自動検出します
デフォルトを重複させず、上書きのみを記述する	ファイルを最小限かつ意図が明確な状態に保ちます
作成には Write ツールを、変更には Edit ツールを使用する	既存の設定を保持します
変更のたびに検証する	sf code-analyzer config で YAML エラーを検出できます
前提条件のインストール前に確認する	同意なしに自動インストールしないでください
確認なしに既存の設定を削除しない	ユーザーが独自の設定を使用している可能性があります
セットアップ後にスキャンを提案する	最後まで対応してください。スキャンを行わない設定は不完全です

---

注意点

問題	解決策
設定が読み込まれない	CWD に code-analyzer.yml を配置するか、--config-file を使用する必要があります
YAML の検証に失敗する	タブではなくスペースを使い、コロンの前後のスペースを確認してください
SFGE のメモリ不足	engines セクションの java_max_heap_size を増やしてください
ESLint ルールが見つからない	auto_discover_eslint_config: true を設定してください

トラブルシューティングの詳細については、<skill_dir>/references/troubleshooting.md をお読みください。

---

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

<skill_dir> は、この SKILL.md ファイルを含むディレクトリの絶対パスです。

ファイル	用途
<skill_dir>/scripts/check-prerequisites.sh	環境チェック
<skill_dir>/scripts/generate-config.sh	プロジェクトの種類を自動検出して設定を生成
<skill_dir>/scripts/validate-config.sh	変更後に YAML を検証
<skill_dir>/references/config-schema.md	YAML スキーマの全ドキュメント
<skill_dir>/references/diagnostic-flow.md	ステップ 2A：段階的な診断手順と修正一覧
<skill_dir>/references/rule-name-resolution.md	ステップ 6.1：ルール名のあいまい検索戦略とマッピング
<skill_dir>/references/engine-prerequisites.md	エンジンごとのインストール手順
<skill_dir>/references/ci-cd-templates.md	CI/CD パイプラインのテンプレート
<skill_dir>/references/troubleshooting.md	よくあるセットアップの問題と解決策
<skill_dir>/examples/apex-project-config.yml	Apex のみのプロジェクト向け設定
<skill_dir>/examples/lwc-project-config.yml	LWC のみのプロジェクト向け設定
<skill_dir>/examples/fullstack-project-config.yml	Apex + LWC + Flows のプロジェクト向け設定
<skill_dir>/examples/ci-github-actions.yml	GitHub Actions ワークフロー