/vscode-extension-guide

VS Code Extension Guide

Create, develop, and publish VS Code extensions.

For extensions with a management UI, default to a dedicated Activity Bar icon and sidebar unless another entry point is explicitly chosen. A Marketplace icon alone does not create that navigation; use the TreeView reference below.

For user-facing extensions, provide a clearly labeled bug-report/feature-request entry in the primary sidebar or management UI and a Command Palette fallback; a README or Marketplace link alone is insufficient. Preview minimal, non-sensitive metadata before opening a fixed feedback destination; leave submission to the user and never auto-attach prompts, raw logs, secrets or private paths.

When to Use

• VS Code extension, extension development, vscode plugin
• Creating a new VS Code extension from scratch
• Adding commands, keybindings, or settings to an extension
• Publishing to VS Code Marketplace

Quick Start

# Scaffold new extension (recommended)
npm install -g yo generator-code
yo code

# Or minimal manual setup
mkdir my-extension && cd my-extension
npm init -y && npm install -D typescript @types/vscode

Project Structure

my-extension/
├── package.json          # Extension manifest (CRITICAL)
├── src/extension.ts      # Entry point
├── out/                  # Compiled JS (gitignore)
├── artifacts/vsix/       # Keep local VSIX archives out of the repo root
├── images/icon.png       # 128x128 PNG for Marketplace
└── .vscodeignore         # Exclude files from VSIX

Building & Packaging

npm run compile      # Build once
npm run watch        # Watch mode (F5 to launch debug)
mkdir -p artifacts/vsix
npx @vscode/vsce package --out artifacts/vsix/my-extension-1.0.0.vsix

Keep local .vsix archives under artifacts/vsix/ instead of the repository root, and prune old local builds on a schedule so release artifacts do not pile up.

Done Criteria

• The packaged VSIX installs and activates in an isolated profile; changed user-facing integrations complete their real workflow there
• Primary sidebar entry and commands work; referenced icons are present in the VSIX
• Package size < 5MB (use .vscodeignore)
• README links and feedback UI reach the intended support destination; verify the UI-to-form path with synthetic data without submitting
• Local VSIX artifacts stored outside the repo root and pruned regularly

Quick Troubleshooting

Reference Map

Best Practices

Extension Host 境界

• Extension Host 上で動く scanner / provider / TreeView は、同じことができるなら Node 固有の path / Buffer / 生 fs より VS Code API を優先する。Problems と実ビルドの環境差を避けやすい。
• 自分の拡張に同梱したリソースは、ユーザーのホーム配下や VS Code のインストール先を推測せず、context.extensionUri と vscode.Uri.joinPath など extension context から解決する。
• 他の installed extension に同梱されたリソースを読む必要がある場合も、resources/agents|skills|prompts|instructions|hooks|mcp の既知 root と、manifest の chatAgents / chatPromptFiles 宣言を優先して見る。built-in resource とは別の read-only resource として扱い、削除や再インストール導線を混ぜない。
• Runtime の診断ログは console.log に散らさず、Output Channel ベースの logger に集約する。ユーザーがログを開ける導線も command / notification / README のどこかに用意する。
• 大きい入力の parse や集計を Extension Host スレッドで同期実行しない。上限付きの bytes を node:worker_threads へ渡し、cancel / opt-out では await worker.terminate() と listener 解除を済ませ、世代 ID が一致する結果だけで cache / UI を更新する。
• transfer するのは専有した非 SharedArrayBuffer だけにし、transfer 後は送信側の view を使わない（同じ backing store の view はすべて detach される）。Buffer は pool を共有し得るので、offset 付き view や所有が曖昧な buffer は必要範囲だけを別 buffer へ copy して渡す。
• worker や別プロセスから受け取った結果をそのまま cache / 表示しない。許可キー検査は Reflect.ownKeys、必須キーの存在確認は Object.hasOwn で行う（Object.keys は非列挙の own property を見逃し、in や素の property 参照は継承値を通す）。
• 例外の Error.name や FileSystemError.code をそのままログ / UI へ出さない。既知 code の allowlist へ正規化し、未知は単一の汎用 code に落とす。path や token が名前に混ざるケースを防げる。

Manifest / Docs / Localization

• package.json の commands、views、configuration、menus を変えたら、コード上の command ID / setting key と同時に確認する。
• Marketplace 表示や設定説明をローカライズしている拡張では、package.nls.json と対象言語の package.nls.*.json を同じ変更で更新する。
• In markdownDescription, use native setting references such as `#editor.wordWrap#`, not [label](#editor.wordWrap#): the latter can leave a trailing hash in the Settings @id: filter. Guard each locale's syntax and verify the resolved target.
• 設定の並び順や説明を変えたら README の設定表、manifest consistency test、release notes の必要有無までまとめて見る。

Language Model Tools

• Extension-provided LM Tools need strong modelDescription intent phrases. Prefer Use when the user asks to ... plus natural-language verbs for create/update/delete/toggle paths, and add a manifest/doc guard so future wording changes do not silently weaken agent-mode tool selection.
• For configuration from VS Code Chat, prefer native LM Tools when no external client is required; do not call them an external MCP server. Share validated domain operations with the GUI, expose only necessary actions, and use explicit enable/disable values rather than retry-sensitive toggles.
• Keep prepareInvocation side-effect free and request confirmation for mutations or sensitive disclosure. Revalidate input, cancellation, trust and the queried revision inside the locked write after confirmation. Host approval UI/policies still apply; custom confirmation text is not a bypass. Never accept secret values through tool arguments or silently widen execution permissions.
• Page query results and omit prompt, environment and raw-output payloads by default. Make sensitive detail retrieval explicit with disclosure confirmation; describe which metadata reaches the model and treat stored strings as data, not instructions.
• Return typed outcomes from shared operations; a GUI handler that catches errors and returns nothing cannot prove a tool succeeded. Keep committed IDs/success when only presentation fails, return a sanitized warning and tell the caller to query rather than repeat the mutation. Configuration saved is not work executed.
• Before publishing an extension with LM Tools, inspect the packaged VSIX rather than trusting source files: confirm extension/package.json has the intended version, expected contributes.languageModelTools count, and no src/, test payloads, or sourcemaps unless intentionally shipped.

Generated Sections

• START / END marker で囲む generated section は単一の SSOT として扱う。
• 重複した marker pair を見つけたら、両方を残して追記せず、内容を統合して marker pair を1つに戻す。

命名の一貫性

公開前にパッケージ名・設定キー・コマンド名を統一：

通知の一元管理

通知は共通helperへ集約し、設定値をruntimeで既知enumへ正規化する。重複抑止、ログとの分離、action、securityの設計は Notification Normalization を参照する。