configuring-code-analyzer

Code Analyzer スキルの設定

概要

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

---

対象範囲

対象:

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

対象外:

• スキャンの実行（running-code-analyzer スキルを使用）
• 違反の修正、ルールの説明、カスタムルールの作成、抑制の管理

---

ツールの使用ルール

使用可能: Bash（sf、java、node、python3、git、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>"

マッピングの原則

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

意図のカテゴリ	対応先	ユーザーの発言例
セットアップ／インストール	Step 2（前提条件＋インストール）	「セットアップして」「インストールして」「始めたい」「新しいノートパソコン」「最初から」
診断／修正	Step 2A（体系的なデバッグ）	「動かない」「壊れている」「セットアップを修正して」「スキャンに失敗する」「エラーが出る」
エンジンの制御	engines.<name>.disable_engine	「Xを無効にして」「Yをオフにして」「Zだけを使って」「すべて有効にして」
エンジンの調整	engines.<name>.<property>	「メモリを増やして」「ヒープを変更して」「自分のeslint設定を使って」「トークンを50に設定して」
ファイルの除外	ignores.files	「除外して」「無視して」「スキップして」「Xをスキャンしないで」
ルールの重大度	rules.<engine>.<rule>.severity	「Xを重大にして」「昇格して」「降格して」「重大度を変更して」
ルールの無効化	rules.<engine>.<rule>.disabled	「ルールXを無効にして」「ルールYをオフにして」「Zを削除して」
ルールのタグ	rules.<engine>.<rule>.tags	「Xにセキュリティのタグを付けて」「推奨タグを追加して」
抑制	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 を書き込む前に、Step 6.1 の検索を使用して正確なルール名を必ず確認してください。code-analyzer.yml ファイルは、正確に一致しないルール名をエラーなしで無視するため、オーバーライドは適用されません。

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

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

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

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

ユーザーは、複数の変更を一度のリクエストで組み合わせることがよくあります。すべての変更を一度の編集で行ってください。

• 「PMDのApexDocルールを無効にして、CRUD違反を重大にして」→ rules.pmd の2つの項目を編集します
• 「テストファイルとベンダーコードを除外して、SFGEのメモリを増やして」→ ignores.files と engines.sfge.java_max_heap_size を編集します
• 「ESLintとPMDだけを使うようにCode Analyzerをセットアップして、node_modulesを無視して」→ 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 パス用のエンジンを使用します
• 複数件一致 → どのルールを指しているかユーザーに確認します
• 一致なし → より広いキーワードで検索するか、ユーザーに伝えます

名前が明確かつ正確な場合（例：「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:
      NoHardcodedIds:
        regex: "/[a-zA-Z0-9]{15,18}/"
        file_extensions: [".cls", ".trigger"]
        description: "Detects hardcoded Salesforce record IDs"
        severity: 2
        tags: ["Security"]

エンジンごとのプロパティ一覧は、<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

---

スキル間の連携

このスキルは running-code-analyzer と連携します。AI エージェントは両者の間をシームレスに引き継ぐ必要があります：

running-code-analyzer からこのスキルに委任された場合：

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

1. 診断と修正の手順（ステップ 2A）を実行し、問題を特定して修正します
2. すべてが動作するようになったら、自動的にスキャンを実行します。停止して確認を求めてはいけません。ユーザーの当初の意図はスキャンだからです。
3. 実行を running-code-analyzer の動作に引き継ぎます（コマンドの作成、実行、結果の解析）。

このスキルから running-code-analyzer に引き継ぐ場合：

設定操作が正常に完了したら、スキャンの実行を提案します（例：「セットアップが完了しました！スキャンを実行しますか？」、「設定を更新しました。スキャンして確認しますか？」）。ユーザーが「はい」と答えた場合は、running-code-analyzer の動作に従って進めます。

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

最初から最後まで対応します：「動かない」→ 診断 → 修正 → スキャン。「セットアップしてスキャン」→ インストール → スキャン。「ESLint を無効にして Apex をスキャン」→ 設定を編集 → --rule-selector pmd を指定して実行。ユーザーの最終的な意図が達成されるまで、必ず対応を続けます。

---

ルール／制約

制約	理由
ユーザーがカスタマイズを依頼した場合に限り、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ワークフロー