init-vscode

Init VSCode

プロジェクトの VSCode 設定ファイルを初期化または更新し、すぐに使えるエディター設定と拡張機能の推奨を提供します。

目標

プロジェクトの VSCode 開発環境を設定します。対象は次のとおりです。

• 拡張機能の推奨（extensions.json）
• 既知の拡張機能の置き換え関係におけるライフサイクル管理とロールバック可能な移行
• ワークスペース設定（settings.json）
• 大規模な monorepo 向けのパフォーマンス既定値：3 層の除外、検索インデックスの収束、TypeScript Server の制限と監視戦略

設定にはスマートマージ戦略を採用し、ユーザーの既存設定を尊重しながらベストプラクティスを補います。ただし、このスキルには対象を限定した強制ポリシーの例外が 2 つあります。

1. files.eol は "\n" に統一する必要があります。
2. 登録済みで、十分な証拠のある extension replacement mapping は、recommendations の通常の和集合ルールより優先されます。不明な拡張機能を推測で自動削除することはありません。

大規模な monorepo では、次の 3 層の除外を同期して維持する必要があります。

• files.exclude：依存関係、ビルド成果物、キャッシュ、ログ、sourcemap をファイルツリーで非表示にし、エクスプローラーの描画負荷を軽減します。
• files.watcherExclude：VSCode のファイル監視機能が無効なディレクトリをスキャンする量を減らし、起動後の継続的な CPU とディスク I/O を軽減します。
• search.exclude：検索とインデックスの対象を減らし、rg、検索インデックス、AI 拡張機能による生成ファイルの重複スキャンを防ぎます。

ワークフロー

1. 対象ディレクトリを確認する

monorepo か単一プロジェクトかを問わず、プロジェクトのルートディレクトリで作業します。.vscode/ ディレクトリが存在することを確認します。

mkdir -p .vscode

2. extensions.json を処理する

テンプレート設定を読み込みます（templates/extensions.json を参照）。

注意：テンプレートファイルの先頭には // 行コメントで説明が記載されています。このファイルが monorepo 内で jsonc としてワークスペースに関連付けられる理由と、JSONC（extensions.json の特例）として記述する際の制約が説明されています。対象プロジェクトの .vscode/extensions.json に書き込んだ後は、VS Code が JSONC として正常に解析します。対象プロジェクトでもテンプレートのコピーを管理する場合は、明示的に jsonc として関連付け、プレーンテキストに格下げしないでください。

JSONC の構文安全性に関する要件：

• .vscode/extensions.json では、VS Code がこのファイルを JSONC として解析するため、// 行コメントとグループコメントを保持できます。
• テンプレート先頭の説明には、必ず // 行コメントを優先して使用してください。
• /* */、*/、コードスニペット、コメント構文の例を含む説明文を、外側の /* ... */ ブロックコメントで囲まないでください。ブロックコメントが途中で終了し、構文エラーが発生します。
• 解析エラーをなくすために、説明コメント、グループコメント、拡張機能の用途に関するコメントを削除しないでください。目指すべきなのは「コメントを保持しつつ、構文を安全に保つ」ことです。
• 対象プロジェクトへの書き込み後は、.vscode/extensions.json を JSONC パーサーで検証する必要があります。VS Code 上で目視確認するだけでは不十分です。
• 「有効な設定」を判定する際は、JSONC に対応した解析機能を使用する必要があります。簡易な正規表現、行ごとの文字列検索、コメント削除後の JSON.parse によって有効なキーを推測することは禁止です。コメント内の拡張機能 ID、設定キー、ラベル、値は有効な設定として扱いません。

ファイルが存在しない場合：

• テンプレートの内容をそのまま作成して書き込みます。

ファイルがすでに存在する場合：

• 既存の設定を読み込みます。
• 既存ファイルにコメントが含まれる場合は、JSONC ファイルとして扱います。解析や検証の唯一の手段として JSON.parse を使用しないでください。
• 通常の場合、recommendations 配列をマージします。重複を除去したうえで、すべての拡張機能（ユーザーのものとテンプレートのもの）を保持します。
• 通常の場合、unwantedRecommendations 配列も同様に重複を除去してマージします。
• 通常の配列の和集合を実行する前に、登録済みの replacement mapping を必ず確認してください。該当する場合は 2.1 の移行ルールに従って処理し、通常の和集合によって旧拡張機能を再び残さないでください。
• ユーザー設定のその他のフィールドがあれば保持します。
• ファイルへの書き戻し時には既存のコメントとグループ分けを保持します。使用するツールがコメントを保持できない場合は、最小限のテキスト挿入または置換で変更を行い、JSONC をコメントなしの JSON に劣化させないでください。
• 見やすい書式を保ちます（インデントは 2 スペース。コメントを保持する場合は JSONC として扱います）。

2.1 拡張機能の置き換え関係とライフサイクル管理

現在の replacement mapping の実行上の正本は reference/extension-replacement-migrations.md です。テンプレート内の拡張機能の推奨が置き換えられた場合、対象プロジェクトに既知の旧拡張機能 ID、旧 settings namespace、旧 command/keybinding がある場合、またはユーザーから拡張機能の非推奨化や有効化の失敗が報告された場合は、通常のマージを行う前に必ずこの reference を読み込んでください。

現在、少なくとも次の置き換え関係を管理しています。

Gruntfuggly.todo-tree -> FanaticPythoner.better-todo-tree

対象プロジェクトが既知の置き換え関係に該当し、ユーザーが旧推奨を保持するよう明示的に求めていない場合：

1. recommendations から旧拡張機能 ID を削除します。
2. recommendations に新しい拡張機能 ID を追加します。
3. unwantedRecommendations に旧拡張機能 ID を追加します。
4. ユーザーのその他の無関係な推奨、unwanted 項目、その他のフィールドを保持します。
5. フィードバックでは、これが「推奨の追加」ではなく replacement migration であることを明確に報告します。

replacement mapping は通常の配列の和集合より優先されますが、自動削除できるのは、このスキルに登録され、十分な証拠がある旧 ID に限られます。不明な拡張機能、同種の拡張機能、名前が似ている拡張機能を推測で自動削除することはできません。

ユーザーが特定の旧拡張機能を引き続き保持するよう明示的に求めた場合：

• ユーザーの判断を尊重し、そのプロジェクトの recommendations から自動削除したり、自動的に unwantedRecommendations に追加したりしないでください。
• 新しい拡張機能を追加してもかまいませんが、「二重推奨／互換性リスク」と、移行が未完了であることを報告する必要があります。
• ユーザーが明示的に保持すると決めたことを、「移行成功」と解釈してはなりません。

unwantedRecommendations は、ワークスペースで「この拡張機能を推奨しない」という意図を表すだけです。アンインストール、無効化、実行時の隔離を行う仕組みではありません。この設定への書き込みを、拡張機能の移行完了を示す証拠として扱うことはできません。

2.2 Replacement の事前確認とスコープの境界

replacement mapping に該当するプロジェクトでは、変更前に最小限の事前確認を行います。対応する機能を利用できる場合は、少なくとも次を確認してください。

• 現在の VS Code バージョン
• 旧／新拡張機能がインストールされているか、およびそのバージョン
• ワークスペース設定に含まれる legacy/current namespace
• 旧拡張機能に関連する keybindings / commands
• 明示的な executable/path override、特に VS Code のプライベートな内部ディレクトリを指すパス
• replacement reference に登録された高リスク設定
• JSONC 内の有効な値（コメント内のテキストではありません）
• ロールバック可能なベースラインがあるかどうか

スコープは次のように階層化して処理する必要があります。

1. ワークスペースの .vscode/*：このスキルが通常変更する範囲です。現在のユーザータスクに従って、作成またはマージできます。
2. VS Code の User Settings / User keybindings：ユーザーレベルの設定です。既定では検出して報告するだけにしてください。変更が必要な場合は、事前にスコープを明確にし、ユーザーの許可を得て、識別可能なバックアップを作成したうえで、最小限の JSONC 対応移行を行います。有効な旧キーのみを移行し、コメントで無効化された項目は保持します。無関係なユーザー設定は整形し直さず、終了時にバックアップの場所と移行した namespace を報告してください。
3. グローバルな拡張機能のインストール／有効化／無効化／アンインストール状態：独立した実行時アクションです。ワークスペースファイルを変更したことを理由に、ユーザーの拡張機能をそのままアンインストールまたは無効化してはなりません。グローバル状態を変更する場合は、個別の許可と根拠が必要です。

外部配布するスキルに、特定のマシンの絶対的な User Settings パスを固定して記載しないでください。ユーザーレベルの移行が必要な場合は、現在のプラットフォーム／VS Code 環境から実際の設定ファイルを特定し、絶対パスは今回の実行結果として報告するだけにしてください。

2.3 Todo Tree -> Better Todo Tree 的专用迁移 gate

命中 Gruntfuggly.todo-tree -> FanaticPythoner.better-todo-tree 时，除通用 preflight 外按 reference 检查以下风险：

• 无效 subTagRegex：BLOCKER，先修复正则再迁移；
• customHighlight：保留人工视觉验收 WARN，不能仅靠静态配置宣称等价；
• multiline regex：保留 runtime 兼容 WARN；
• UTF-16 文件：保留 workspace scan WARN；
• 显式 ripgrep override：如果指向 resources/app/node_modules*、@vscode/ripgrep* 等 VS Code 私有内部布局，视为高风险 WARN/FAIL，禁止把该路径复制成长期新配置；
• legacy keybinding / command：核验新扩展是否提供可用命令或兼容 alias；无法静态证明时要求 GUI 人工测试。

Better Todo Tree 的长期配置应优先使用扩展自身 resolver / packaged ripgrep；不要把 VS Code 私有内部二进制路径当成稳定 API。

替换前若需要确认为什么存在这些门禁，读取 reference/2026-08-16-todo-tree-ripgrep-migration.md。该文件是当前可执行经验层，不依赖源 monorepo 的开发期报告。

2.4 可回滚迁移原则

• replacement 首轮可以在获得用户授权后采用“新扩展安装/启用，旧扩展禁用但暂不卸载”的方式保留一个验收周期，便于快速回滚；这不是永久双安装策略。
• code --list-extensions 只能证明“已安装”，不能单独证明“已禁用”。没有额外证据时只能报告安装状态，不能推断启用状态。
• GUI/runtime 验收稳定后，再提示用户决定是否卸载旧扩展；不得自动卸载。
• User Settings 发生迁移时，回滚依据是迁移前备份 + 已报告的 namespace 变更，不要靠记忆反向编辑。

2.5 配置检查

在合并模板之前，先检查目标项目现有 .vscode/settings.json 中是否存在过时或不合适的配置。参照 init-ai-md 的迁移检测机制，对问题配置进行分类标记并提示用户。

检查项：

1. vue.server.includeLanguages 包含 "markdown"

   • 原因：该配置会导致 Vue 语言服务器错误地处理 Markdown 文件，产生不良影响
   • 标记：[需移除 markdown]
   • 修复方式：将值收敛为 ["vue"]

2. files.eol 不是 "\n"

   • 原因：Windows 上容易产生 CRLF/LF 漂移与 git 幽灵修改
   • 标记：[需收敛为 LF]
   • 修复方式：覆盖为 "\n"

执行流程：

1. 如果 .vscode/settings.json 不存在，跳过本步骤
2. 读取现有配置
3. 扫描上述检查项，生成分类标记
4. 如果存在任何标记项，使用 AskUserQuestion 工具询问用户是否修复
5. 用户确认修复后，先执行修正，再进入步骤 3 的合并流程
6. 用户选择不修复时，保留原配置并进入合并流程（但 files.eol 仍按策略键强制收敛）

询问示例：

检测到以下 VSCode 配置问题：

- vue.server.includeLanguages 包含 "markdown" [需移除 markdown] - 会导致 Vue 语言服务器错误处理 Markdown 文件
- files.eol 为 "auto" [需收敛为 LF] - 建议统一为 "\n" 避免行尾漂移

请选择要修复的项（可多选，用逗号分隔，如：1,2），或输入 0 跳过。

修复策略：

• 用户确认修复后，在合并模板前先修正这些配置
• 修正时保留用户的其他自定义配置
• 修复后的配置再按步骤 3 的合并逻辑处理

3. 处理 settings.json

读取模板配置（见 templates/settings.json），然后：

大型 monorepo 性能策略：

• files.exclude、files.watcherExclude、search.exclude 必须按同一批目录同步补齐；只改其中一层会留下文件树、监听器或搜索索引的性能缺口。
• 默认排除常见依赖、构建产物、缓存、日志、测试报告和 sourcemap，例如 node_modules、.git、dist、dist-ssr、build、.next、.nuxt、.output、.vite、.vitepress/dist、.vitepress/cache、.vuepress/dist、.vuepress/cache、.turbo、.vercel、.cache、.temp、.tmp、coverage、.nyc_output、.vitest-reporter-html、.eslintcache、.stylelintcache、*.tsbuildinfo、*.map、logs、*.log。
• search.indexing.maxFileSize 默认收敛为 1048576，避免 500MB 级别设置导致搜索索引吞入大文件。
• TypeScript 默认补齐 typescript.tsserver.maxTsServerMemory: 4096、typescript.disableAutomaticTypeAcquisition: true、typescript.tsserver.watchOptions 和 typescript.tsdk: "node_modules/typescript/lib"。

如果文件不存在：

• 直接创建并写入模板内容

如果文件已存在：

• 读取现有配置
• 如果现有文件包含注释，按 JSONC 文件处理，并复用后续 Prettier JSONC override 规则
• 深度合并对象：
  • 对于嵌套对象（如 files.exclude、files.watcherExclude、search.exclude），合并所有键值对；explorer.fileNesting.patterns 按 3.4 的迁移规则处理，不得让旧根节点与新根节点并存
  • 对于数组，默认去重合并
  • 对于简单值（字符串、布尔值、数字），默认仍然是用户现有值优先
• 但对以下策略键，必须使用模板值覆盖冲突值：
  • files.eol：必须收敛为 "\n"，不允许保留 "\r\n" 或 "auto"
  • vue.server.includeLanguages：必须收敛为 ["vue"]，移除 "markdown"，避免 Vue 语言服务器错误处理 Markdown 文件
  • search.indexing.maxFileSize：必须收敛为 1048576，不要保留 500MB 级别的大文件索引上限
  • typescript.disableAutomaticTypeAcquisition：默认收敛为 true，避免大仓库自动拉取和扫描额外类型包
  • typescript.tsserver.watchOptions：必须补齐 watchFile: "useFsEvents"、watchDirectory: "useFsEvents"、fallbackPolling: "dynamicPriority"
  • typescript.tsdk：默认使用项目内 node_modules/typescript/lib
  • typescript.tsserver.maxTsServerMemory：缺失或低于 4096 时补为 4096；高风险 monorepo 可提高到 8192
  • explorer.fileNesting.patterns：按 3.4 迁移旧 CLAUDE.md 根节点；不得让新旧根节点并存，用户明确自定义的 AGENTS.md 值除外
• 保留用户配置中的其他字段
• 写回文件，保持 JSON/JSONC 格式美观（2 空格缩进）

3.1. files.eol 的特殊规则

本技能专门负责 .vscode/settings.json 中的：

{
	"files.eol": "\n"
}

处理原则如下：

1. 如果 files.eol 不存在：直接补写为 "\n"
2. 如果 files.eol 已存在但值是 "\r\n"、"auto" 或其他值：必须覆盖为 "\n"
3. 如果用户已经是 "\n"：保持不变

这是一个明确的团队策略键，不适用“用户简单值优先”的默认规则。

3.2. Prettier の JSONC 互換ルール

このスキルで作成する .vscode/extensions.json は、デフォルトでコメントを保持するため、厳密な JSON ではなく JSONC です。実行時には対象プロジェクトの Prettier の処理経路を確認し、「VS Code では読み込めるのに、フォーマッターでエラーになる」事態を避けてください。

処理手順：

1. 今回作成または更新する .vscode/extensions.json と .vscode/settings.json に、// の行コメント、ブロックコメント、末尾のカンマが含まれているか確認します。

2. 対象プロジェクトの package.json、prettier.config.*、lint-staged.config.* を読み取り、format、lint-staged、またはコミットフックが *.json や全ファイルをフォーマットするか判断します。

3. JSONC ファイルが Prettier の対象になる場合、対象プロジェクトの prettier.config.mjs に正確な override を追加します。このテンプレートでは末尾のカンマを禁止しているため、trailingComma: "none" も同時に設定します：

   /** @type {import("prettier").Config} */
   const config = {
     overrides: [
       {
         files: ".vscode/extensions.json",
         parser: "jsonc",
         trailingComma: "none",
       },
     ],
   };
   
   export default config;
   

4. .vscode/settings.json にもコメントを保持する場合は、extensions.json とまとめて正確なファイル配列を指定できます：

   {
     files: [".vscode/extensions.json", ".vscode/settings.json"],
     parser: "jsonc",
     trailingComma: "none",
   }
   

5. overrides がすでにある場合は、不足している項目だけを追加するか、同じファイルの parser / trailingComma を修正します。既存の parser、plugins、printWidth、tabWidth、endOfLine など、プロジェクトの設定項目は削除しないでください。

6. **/*.json 全体を jsonc に設定しないでください。package.json、lockfile、およびサードパーティの厳密な JSON parser が読み込む設定は、厳密な JSON のままにする必要があります。

7. 対象プロジェクトに Prettier の設定がない場合、またはフォーマットコマンドが .vscode/extensions.json を対象にしない場合も、判断結果をフィードバックで明記してください。黙って省略しないでください。

3.3 高リスクプロジェクトの強化

プロジェクトが大規模な pnpm/turbo モノレポである、VSCode の起動が明らかに遅い、Code.exe/rg.exe/tsserver.js が継続的に CPU を使用している、または大量の生成物がある場合は、次の方針で強化してください：

• typescript.tsserver.maxTsServerMemory を 4096 から 8192 に増やすことはできますが、正確な tsconfig と除外ルールの代わりにしないでください。
• リポジトリ全体をインデックス化する AI 拡張を無効化または制限します。たとえば Codegeex.RepoIndex を false に設定するか、拡張機能自体の設定でインデックス範囲を限定します。
• .gitignore と VSCode の 3 層の除外ルールを同期して管理する必要があります。Git の除外はバージョン管理にのみ影響し、VSCode のファイルツリー、監視対象、検索インデックスの負荷は自動的には軽減されません。
• 必要に応じて、Windows Defender でプロジェクト内の node_modules、.git、.tmp など、I/O 頻度の高いディレクトリを除外し、リアルタイムスキャンによる VSCode の起動や検索への影響を軽減できます。
• ルートの tsconfig.json の include はソースディレクトリに正確に限定し、.md、.github、.cursor など、無関係なディレクトリを TypeScript の対象に含めないでください。
• 外部配布するスキルのドキュメントには、一般的な知見と相対パスのみを記載してください。ユーザーにローカルの診断レポートや開発時の絶対パスを確認させないでください。

3.4. AI メモリファイルのファイルネスト移行

テンプレートでは、explorer.fileNesting.patterns の標準ルートノードが次のように変更されています：

{
	"AGENTS.md": "CLAUDE.md,GEMINI.md,DESIGN.md"
}

これは、init-ai-md の AGENTS.md を唯一の信頼できる情報源とする方針に伴う破壊的変更です。既存の settings.json を処理する場合：

• 旧テンプレート項目 "CLAUDE.md": "GEMINI.md,AGENTS.md" がある場合は、先にこの項目を削除し、新しい AGENTS.md 項目を書き込みます。2 つのルートノードを並列で残さないでください。
• ユーザーのその他の無関係な explorer.fileNesting.patterns 設定は保持します。ユーザーが明示的にカスタマイズした AGENTS.md の値は、ユーザー優先の原則に従ってそのままにし、完全には統一していないことをフィードバックで説明します。

4. 検証結果

検証では、3 層の証拠を区別する必要があります。設定が有効で拡張機能がインストール済みでも、拡張機能が正常に実行されているとは限りません。

層 A：静的設定

次の 2 つのファイルが正しく作成または更新されているか確認します：

ls -la .vscode/

.vscode/extensions.json 自体が有効な JSONC であることを検証します：

pnpm exec prettier --parser jsonc --trailing-comma none --check .vscode/extensions.json

対象プロジェクトに Prettier の設定がある場合、または format / lint-staged が JSON ファイルを処理する場合は、プロジェクトレベルの Prettier 設定で正しく処理できることも検証します：

pnpm exec prettier --check .vscode/extensions.json

.vscode/settings.json にコメントを保持する場合も、同様に対象を絞って確認します：

pnpm exec prettier --parser jsonc --trailing-comma none --check .vscode/settings.json
pnpm exec prettier --check .vscode/settings.json

replacement migration の静的な受け入れ確認では、次の点も必ず確認します：

• recommendations / unwantedRecommendations がマッピングに合致していること。
• legacy/current settings namespace が移行計画に合致していること。
• コメントで無効化された項目を、誤って有効な設定に戻していないこと。
• 古くなった VS Code の非公開内部バイナリへの絶対パスを生成していないこと。
• 移行後も維持する必要のあるタグ／設定スナップショットの順序が、有効な値と一致していること。

ワークスペース設定の移行では、次の点も確認します：

• explorer.fileNesting.patterns から古いテンプレートのルートノードが削除され、ユーザー優先のルールに従って AGENTS.md 項目が処理されていること。

pnpm format が既存の多数のファイルに影響する場合は、まず上記の対象を絞った確認を実行し、全体のフォーマットを実行しなかった理由をフィードバックで明記してください。

層 B：CLI / Extension Host の証拠

replacement migration がある場合は、現在の環境で可能な範囲で次の点を確認します：

• 新しい拡張機能が実際にインストールされているか、およびそのバージョン。
• 古い拡張機能のインストール／無効化方針が、今回のロールバック計画に合致しているか。
• 新しいログに activation failure、command not found、実行ファイル／ripgrep の不足など、回帰を示す兆候がないか。

新しい Extension Host / runtime のログがない場合は、WARN / pending としてのみ記載できます。「ログが見つからなかった」ことを、ランタイムの PASS として記載してはいけません。

層 C：GUI / runtime の手動受け入れ確認

replacement が UI、コマンド、またはランタイムでの有効化に関係する場合、少なくともユーザーまたは GUI を操作できる実行環境で、該当項目を確認する必要があります：

• Reload Window。
• 対象のビューが実際に表示されること。
• Refresh／再構築。
• プロジェクト内の移動。
• Filter / Group / Expand/Collapse などの主要操作（拡張機能の機能に応じて適用）。
• ハイライト／視覚的な差異の確認。
• 新たに再起動した後の安定性。
• 大規模リポジトリでのパフォーマンス（タスクにパフォーマンスが関係する場合）。

A + B + C の該当項目をすべて満たした場合に限り、「現在の環境で replacement の検証に合格」と宣言できます。A のみ、または A+B までしか完了できない場合は、フィードバックに「静的／CLI は合格、GUI のランタイム受け入れ確認は pending」と明記する必要があります。

5. フィードバックの提供

ユーザーには次の内容を報告します：

• 更新したファイル（新規作成または統合）。
• 変更内容の概要（追加した拡張機能の推奨数、設定項目数）。
• replacement migration が発生した場合：旧／新拡張機能 ID、recommendations/unwanted の結果、settings namespace の変更、ロールバックの状態。
• User Settings を変更した場合：許可された範囲、バックアップの場所、移行した有効なキー／namespace。タスクと無関係なユーザー設定の内容は開示しないでください。
• ユーザー設定を保持した競合があった場合は、その概要。
• JSONC / Prettier override の判断結果：追加済み、既存設定を再利用可能、またはこのプロジェクトでは追加不要。
• 層 A / B / C それぞれの受け入れ確認の状態。GUI が未完了の場合は、必ず pending と明記します。

フィードバック形式の例：

✅ VSCode 工作区配置已更新

📦 extensions.json: 完成 1 项 replacement migration，并保留其他用户推荐
⚙️ settings.json: 合并工作区配置；User Settings 未修改
🧪 验收: 静态配置 PASS，CLI PASS，GUI runtime acceptance pending

6. オプションのプラグイン設定

AskUserQuestion ツールを使って、プラグイン固有の設定を追加する必要があるかユーザーに尋ねます：

質問内容：

是否需要添加以下插件的特殊配置？

1. git-graph - 自定义分支筛选模式（适合团队有特定分支命名规范）
2. cursor - 将 .cursorignore 识别为 ignore 文件类型
3. i18n-ally - 国际化工具配置（自动识别项目中的语言文件路径）

请选择需要配置的插件（可多选，用逗号分隔，如：1,3），或输入 0 跳过。

ユーザーの選択に応じて、該当する設定を settings.json に統合します（手順 3 と同じ深いマージのロジックを使用します）。

オプションのプラグイン設定

git-graph 插件配置

用途：自定义分支筛选模式，适合团队有特定分支命名规范的场景。

配置示例：

{
	"git-graph.customBranchGlobPatterns": [
		{
			"name": "主要分支",
			"glob": "{main,dev}"
		},
		{
			"name": "功能分支",
			"glob": "feat/*"
		},
		{
			"name": "修复分支",
			"glob": "fix/*"
		},
		{
			"name": "发布分支",
			"glob": "release/*"
		}
	]
}

如何自定义：

• customBranchGlobPatterns 是一个对象数组，每个对象包含 name 和 glob 字段
• name：分支组的显示名称，用于在 Git Graph 界面中标识
• glob：分支匹配模式，支持 glob 语法（如 *、{}、? 等）
• 常见团队分支模式：feat/*、fix/*、hotfix/*、release/*
• 可根据团队的 Git Flow 或 GitHub Flow 规范调整
• 支持使用花括号匹配多个分支：{main,dev,master}

cursor 文件关联配置

用途：将 .cursorignore 文件识别为 ignore 文件类型，提供语法高亮和编辑体验。

配置说明：

{
	"files.associations": {
		".cursorignore": "ignore"
	}
}

此配置会让 VSCode 将 .cursorignore 文件视为与 .gitignore 相同的文件类型，提供相应的语法支持。

i18n-ally 插件配置

用途：国际化工具配置，自动识别项目中的语言文件路径。

模板占位符： 模板文件 templates/plugin-configs/i18n-ally.json 使用 {{LOCALES_PATH}} 占位符，需要在应用配置时替换为实际路径。

占位符替换逻辑：

1. 检测项目中的 i18n 路径： 使用 Glob 工具搜索常见的国际化目录模式：

   // 搜索模式（按优先级排序）
   const patterns = ["**/locales", "**/i18n", "**/lang", "**/locale", "**/translations"];
   

2. 路径处理：

   • 找到的路径需要转换为相对于项目根目录的路径
   • 如果找到多个路径，选择最短的（通常是最顶层的）
   • 排除 node_modules、dist、.git 等目录中的路径

3. 替换占位符：

   // 伪代码示例
   let localesPath = detectI18nPath(); // 返回如 "src/locales"
   
   if (!localesPath) {
   	// 如果未找到，使用默认值或询问用户
   	localesPath = "src/locales"; // 默认值
   	// 或使用 AskUserQuestion 询问用户
   }
   
   // 替换模板中的占位符
   config["i18n-ally.localesPaths"] = localesPath;
   

4. 处理失败情况：

   • 如果自动检测失败，使用默认值 "src/locales"
   • 或使用 AskUserQuestion 工具询问用户实际的 i18n 路径
   • 在反馈中告知用户使用了默认值，建议手动检查

常见路径模式：

{
	"i18n-ally.localesPaths": "src/locales"
}

配置参数说明：

• localesPaths：语言文件所在目录的相对路径（字符串）或路径数组
• 路径相对于项目根目录
• 支持单个路径（字符串）或多个路径（数组）

完整配置示例：

{
	"i18n-ally.localesPaths": "src/locales",
	"i18n-ally.pathMatcher": "{locale}/{namespace}.{ext}",
	"i18n-ally.keystyle": "nested",
	"i18n-ally.sortKeys": true,
	"i18n-ally.namespace": true,
	"i18n-ally.enabledParsers": ["yaml", "js", "json"],
	"i18n-ally.sourceLanguage": "en",
	"i18n-ally.displayLanguage": "zh-CN",
	"i18n-ally.enabledFrameworks": ["vue"]
}

实现步骤：

1. 读取模板文件 templates/plugin-configs/i18n-ally.json
2. 使用 Glob 搜索项目中的 i18n 目录：

   # 搜索常见的 i18n 目录（排除 node_modules 等）
   **/locales
   **/i18n
   **/lang
   

3. 选择找到的第一个路径（优先选择 src/ 下的路径）
4. 如果未找到任何路径：
   • 使用默认值 "src/locales"
   • 在反馈中提示用户："未检测到 i18n 目录，使用默认路径 'src/locales'，请根据实际情况调整"
5. 替换模板中的 {{LOCALES_PATH}} 占位符
6. 将处理后的配置合并到 settings.json

合并逻辑详解

数组合并

对于 recommendations、unwantedRecommendations 等数组字段，默认去重合并：

// 伪代码
merged = [...new Set([...userArray, ...templateArray])];

去重后保留所有项。

replacement 例外： 在执行上述并集前，先应用 reference/extension-replacement-migrations.md 中的映射。命中的旧扩展先从 recommendations 移除，再加入新扩展，并把旧扩展加入 unwantedRecommendations；用户明确要求保留旧扩展时除外。普通并集不得把已被 mapping 移除的旧 ID 重新加回来。

vue.server.includeLanguages 虽为数组，但属于策略键，不适用默认去重合并，必须收敛为 ["vue"]，不得包含 "markdown"。

对象深度合并

对于嵌套对象（如 files.exclude、files.watcherExclude、search.exclude）：

// 伪代码
merged = {
	...templateObject,
	...userObject, // 用户的键值对优先
};

用户已有的键保持不变，模板中新增的键会被添加。

简单值优先级

对于 explorer.fileNesting.enabled、terminal.integrated.cwd 等简单值：

• 如果用户已有配置，完全保留用户的值
• 如果用户没有配置，使用模板值

策略键例外

以下键不走“用户优先”，而是必须按模板收敛：

• files.eol → 必须为 "\n"
• vue.server.includeLanguages → 必须为 ["vue"]，不得包含 "markdown"
• search.indexing.maxFileSize → 必须为 1048576
• typescript.disableAutomaticTypeAcquisition → 必须为 true
• typescript.tsserver.watchOptions → 必须补齐 useFsEvents 与 dynamicPriority
• typescript.tsdk → 默认使用 node_modules/typescript/lib
• typescript.tsserver.maxTsServerMemory → 缺失或低于 4096 时补齐，高风险项目可升到 8192

可选插件配置合并

对于用户选择添加的可选插件配置（git-graph、cursor、i18n-ally）：

• 使用与 settings.json 相同的深度合并逻辑
• 对于 git-graph.repository.onLoad.showSpecificBranches 等数组字段，去重合并
• 对于 files.associations 等对象字段，合并键值对
• 用户现有配置始终优先，不会被覆盖

模板与参考内容

模板文件位于 templates/ 目录：

• templates/extensions.json - 扩展推荐列表
• templates/settings.json - 工作区设置

当前执行参考位于 reference/：

• reference/README.md - 当前 reference 索引与加载边界
• reference/extension-replacement-migrations.md - 已知扩展替代关系、scope、preflight/postflight 与回滚规则
• reference/2026-08-16-todo-tree-ripgrep-migration.md - Todo Tree 激活失败事故提炼出的当前迁移经验

这些模板包含了常用的开发工具扩展、三层排除规则和性能优化设置，适用于大多数前端项目与大型 monorepo。reference 只保存对安装后技能仍有执行价值的当前规则，不要求回源读取 monorepo 内部报告。

注意事項

• デフォルトでは、ユーザーの既存設定のうち無関係なものは削除しません。登録済みの extension replacement mapping は限定的な例外であり、マッピングが明確な旧 ID／旧 namespace のみを対象とします。
• 明確な許可がない限り、VS Code User Settings、User keybindings、グローバルな拡張機能のインストール／無効化／アンインストール状態は変更しません。
• unwantedRecommendations は、拡張機能のアンインストールや無効化を意味するものではありません。
• files.eol は明示的なポリシーキーであり、このスキルの要件に従って "\n" に統一する必要があります。
• files.exclude、files.watcherExclude、search.exclude は同期して管理する必要があります。パフォーマンスのための除外項目を追加または削除するときは、いずれか1つの層だけを変更しないでください。
• .vscode/extensions.json をプレーンテキストとして扱わないでください。JSONC のセマンティクスを維持し、正確な Prettier JSONC override によってフォーマットのワークフローに対応させる必要があります。
• JSON／JSONC ファイルは、整った形式（インデントは2スペース、末尾のカンマなし）を維持してください。
• コメントを保持する設定ファイルでは、JSON.parse、単純な正規表現、行単位の検索を、アクティブな設定の検証基準として使用しないでください。JSONC 対応の parser／CST 機能、または同等のコメント対応編集方式を使用し、Prettier の --parser jsonc で構文を検証してください。
• VS Code の resources/app/node_modules*、@vscode/ripgrep* などの非公開内部ディレクトリを長期的に指す、バイナリの絶対パスを生成しないでください。
• 静的設定の PASS は runtime の PASS を意味しません。新しい runtime／GUI の証拠がない場合は、pending／WARN のままにしてください。
• JSONC の解析に失敗した場合は、エラーを報告し、ファイル形式を手動で確認するようユーザーに提案してください。
• 外部配布するドキュメントおよび reference に、開発マシンの絶対パス、ソース monorepo 内部のテスト／レポートパス、またはソースに戻らなければ実行できないルールを書かないでください。

このスキルを使用するタイミング

ユーザーが以下のように述べた場合、このスキルを使用してください。

• 「vscode の設定を初期化」
• 「エディターを設定」
• 「vscode をセットアップ」
• 「新しいプロジェクトに開発環境の設定が必要」
• 「vscode の推奨拡張機能を追加」
• 「非推奨の vscode 拡張機能を置換／移行」
• 「拡張機能の command not found／アクティベーション失敗」
• 「ワークスペース設定を更新」
• 「チーム開発規約の設定」
• 「VSCode の起動が遅い」
• 「大規模リポジトリを開くと動作が重い」
• 「ファイル監視を最適化」
• 「検索インデックスを最適化」
• 「tsserver の使用率が高い」

ユーザーが「vscode」と明確に述べていなくても、プロジェクトの初期化、開発環境のセットアップ、エディター設定などに関連する概念に触れている場合は、このスキルの使用を検討してください。