2026年5月5日前後に更新が確認された「Microsoft developer platform documentation update: feat(prompts): add cspell-config prompt for automated spell check maintenance」は、CSpellの設定ファイルをAIプロンプトで保守しやすくする変更です。結論から言うと、すでに cspell.json や .cspell.json を使ってスペルチェックをCIやレビューに組み込んでいるチームは、設定ファイル・辞書・除外パスの運用を見直す価値があります。一方で、対象は experimental 扱いのプロンプトであり、すぐ本番運用へ組み込むよりも、まず検証ブランチで差分を確認するのが安全です。(GitHub)
この更新のポイントは、GitHub Copilotなどで使うプロンプトファイルを通じて、cspell の実行、未知語の分類、プロジェクト固有用語の辞書登録、ignorePaths の調整、再検証までを一連の作業として進められるようにした点です。ドキュメントやコードのtypo対策を「気づいた人が都度追加する」運用から、「定期的に棚卸しして保守する」運用へ寄せられる変更と考えると分かりやすいでしょう。
Microsoft developer platformの今回の更新で何が変わったのか
今回のPull Requestでは、cspell-config という新しい experimental prompt が追加されています。追加先は .github/prompts/experimental/cspell-config.prompt.md で、あわせて experimental collection や hve-core-all collection、plugin出力にも登録されています。PR本文では、このプロンプトが cspell.json の保守を自動化し、ワークスペース全体のスペルチェック、プロジェクト固有語の整理、words 配列のアルファベット順・重複排除、.gitignore と ignorePaths の同期を行うと説明されています。(GitHub)
重要なのは、単に「辞書に単語を足すプロンプト」ではないことです。プロンプトの中身を見ると、プロジェクトの言語やパッケージマネージャー、既存のタスクランナー、CSpell設定ファイル、カスタム辞書、既存の除外パスを確認したうえで作業する流れになっています。CSpell公式ドキュメントでも、設定ファイルは cspell.json だけでなく、YAML、JSONC、JavaScript、TypeScript、TOML、.vscode/cspell.json など複数形式が扱われます。今回のプロンプトは、その前提に合わせて特定のファイル名へ決め打ちしない方向に調整されています。(GitHub)
| 変更点 | 内容 | 実務で確認すべきこと |
|---|---|---|
cspell-config prompt の追加 | CSpell設定の作成・更新・検証を支援するプロンプトが experimental collection に追加 | 利用環境でプロンプトが読み込まれるか、experimental artifact を許容するか |
| 設定ファイル検出の汎用化 | .cspell.json、cspell.json、cspell.config.js、YAMLなど複数形式を検出 | 既存設定を無視して新規 cspell.json を作らないか |
| 未知語の分類 | プロジェクト固有語、略語、技術名、環境変数、固有名詞、typo候補に分類 | typoを辞書へ登録せず、修正対象として分けられるか |
ignorePaths の調整 | .gitignore や .dockerignore と整合する除外パスを追加・整理 | 生成物だけを除外し、ソースやドキュメントを広く無視していないか |
| 再実行とレポート | CSpellを再実行し、残件数や要対応項目を報告 | CIの合格条件やレビュー基準に合うか |
対応すべき人と、急がなくてよい人
今回のMicrosoft developer platform documentation updateで優先的に確認したいのは、CSpellをすでに使っているリポジトリのメンテナーです。特に、英語ドキュメント、API名、製品名、クラウドリソース名、環境変数名、社内用語が多く、スペルチェックの誤検知が積み上がっているプロジェクトでは効果が出やすいです。
一方で、CSpellをまだ導入していない小規模リポジトリや、スペルチェックを開発フローに組み込んでいないチームは、すぐに対応しなくても大きな影響はありません。ただし、ドキュメント品質をCIで担保したい場合は、今回の変更をきっかけにCSpell運用を検討できます。
| 対象 | 対応優先度 | 理由 |
|---|---|---|
| CSpellをCIで実行している開発チーム | 高 | words や ignorePaths の変更がCI結果に直結する |
| GitHub Copilotのprompt filesを使っているチーム | 高 | / から呼び出す再利用プロンプトとして活用できる可能性がある |
| ドキュメント、README、Markdownを多く管理するチーム | 中 | typo修正と固有用語辞書の整理に向いている |
| 生成物やvendorファイルが多いモノレポ | 中 | ignorePaths の見直しで誤検知を減らせる |
| CSpell未導入の小規模プロジェクト | 低 | まずは通常のCSpell導入判断から始めればよい |
なお、GitHub Copilotのprompt files自体は公開プレビューで、利用できる環境や仕様が変わる可能性があります。GitHub Docsでは、prompt filesは公開プレビューであり、VS Code、Visual Studio、JetBrains IDEで利用できると説明されています。experimental promptをチーム標準にする場合は、この前提を明示しておきましょう。(GitHub Docs)
cspell-config promptが行う作業の流れ
今回追加された cspell-config prompt は、CSpell設定をいきなり書き換えるのではなく、検出、実行、分類、更新、検証という順序で進める設計です。VS Codeのprompt filesは、共通タスクをMarkdownファイルとして定義し、チャット内で手動実行できる仕組みです。ワークスペース用のprompt fileは標準で .github/prompts に置かれ、ファイル名または設定された名前を / に続けて呼び出せます。(Visual Studio Code)
まずプロジェクトの前提を検出する
プロンプトは、ワークスペース直下の package.json、pyproject.toml、Cargo.toml、go.mod、*.csproj、pom.xml、Gemfile などを確認し、主要言語やパッケージマネージャーを把握します。さらに、CSpellがプロジェクト依存関係として入っているか、グローバルで使えるか、npx などで実行できるかを確認します。
実務では、この段階で「どのコマンドを正とするか」を決めることが大切です。たとえばNode.jsプロジェクトなら、直接 npx cspell "**/*" を実行するより、既存の npm run spell-check があるならそちらを優先した方が、CIと同じ条件で検証できます。
npm run spell-check既存スクリプトがない場合は、検証用として次のようなコマンドを使う形になります。
npx cspell "**/*"CSpell設定ファイルを検出または作成する
次に、既存のCSpell設定を探します。CSpellは複数の設定ファイル名・形式に対応しているため、cspell.json だけを探す運用では見落としが起きます。公式ドキュメントでも、.cspell.json、cspell.jsonc、cspell.config.js、cspell.config.yaml、.vscode/cspell.json などが候補として挙げられています。(CSpell)
既存設定がない場合、プロンプトは最小構成の cspell.json を作る流れになっています。ただし、すでに package.json の中に cspell キーがある、または .vscode/settings.json でチーム向け設定をしている場合は、重複設定にならないよう注意が必要です。
カスタム辞書を検出する
プロンプトは .cspell/ ディレクトリや dictionaryDefinitions を探し、既存のカスタム辞書ファイルがあればそれを尊重します。これは大事なポイントです。プロジェクト固有語をすべて words 配列へ詰め込むと、設定ファイルが肥大化し、レビューもしづらくなります。
たとえば、次のように分類できます。
| 追加先 | 向いている単語の例 | 判断基準 |
|---|---|---|
words 配列 | プロジェクト名、独自コンポーネント名、短い略語 | そのリポジトリだけで使う用語 |
| カスタム辞書 | 社内共通用語、製品名、クラウド・インフラ用語 | 複数リポジトリで再利用する用語 |
| ソース修正 | recieve、adress のような明らかなtypo | ユーザー向け文言やドキュメントに残すべきでない誤字 |
ignorePaths | dist/、build/、minify済みファイル、lockfile | 人が編集しない生成物・外部依存物 |
影響範囲は「辞書」だけでなくレビュー品質にも及ぶ
CSpell設定の保守で失敗しやすいのは、誤検知を減らすために何でも辞書登録してしまうことです。これを続けると、本来修正すべきtypoまで「正しい単語」として扱われ、スペルチェックの意味が薄れます。
今回のプロンプトは、未知語を分類し、明らかなtypoはソース修正候補として報告する設計になっています。これは実務上かなり重要です。たとえば、APIレスポンスのキー、README、画面表示文言、ログメッセージにtypoがある場合、辞書登録ではなく修正すべきです。逆に、Kubernetes関連の略語、クラウドリソース名、製品コード名、環境変数名などは辞書登録した方がレビュー効率は上がります。
ignorePaths の増やしすぎに注意する
PR内のプロンプトでは、.gitignore や .dockerignore と整合するように ignorePaths を調整する流れが示されています。ただし、.gitignore にあるからといって、すべてをスペルチェック対象外にしてよいとは限りません。CSpellのGitHub Action設定でも、ignorePaths はチェック対象の除外に効くため、ここを広く設定しすぎるとCIで見つけたいtypoまで隠れてしまいます。(CSpell)
| パスの種類 | 除外判断 | 理由 |
|---|---|---|
node_modules/、vendor/ | 除外してよい | 外部依存であり自チームが修正しない |
dist/、build/、.next/ | 多くの場合は除外 | 生成物の誤検知が多い |
package-lock.json、yarn.lock | 多くの場合は除外 | 人が直接編集する用途ではない |
docs/ | 原則として除外しない | ドキュメント品質に直結する |
src/、lib/、app/ | 除外しない | コード内の命名や文字列を検出したい |
tests/ | 原則として除外しない | テストデータ内のtypoや表示文言を見つけられる |
特にモノレポでは、生成物、サンプル、外部取り込みコード、アーカイブ済みプロジェクトが混在しがちです。ignorePaths は「誤検知を消すリスト」ではなく、「品質管理の対象外にする範囲」を決める設定として扱うべきです。
移行・設定確認の手順
今回のMicrosoft developer platform documentation updateを受けて実際に確認するなら、次の順序で進めると安全です。
検証ブランチで現在のCSpell結果を記録する
まず、mainブランチの状態でCSpellを実行し、ベースラインを取ります。結果として、チェック対象ファイル数、指摘件数、指摘の多いディレクトリ、未知語の代表例をメモします。
npm run spell-checkスクリプトがない場合は、プロジェクトに合わせて対象拡張子を絞ります。
npx cspell "**/*.{ts,tsx,js,jsx,md,json,yml,yaml}"ここで大切なのは、最初から全件ゼロを目標にしないことです。大規模リポジトリでは、既存の誤検知が数百件あることも珍しくありません。まずは「どれだけ減ったか」を比較できる状態にします。
cspell-config promptを実行する
プロンプトが利用環境に読み込まれている場合は、チャットから cspell-config を呼び出します。VS Codeのprompt filesでは、prompt fileはチャット内で / に続けて実行でき、ファイルに name がない場合はファイル名が使われます。今回のファイル名は cspell-config.prompt.md なので、環境上の表示名を確認して実行します。(Visual Studio Code)
実行時は、次のような依頼にすると意図が伝わりやすくなります。
このリポジトリのCSpell設定を確認し、プロジェクト固有語の辞書登録、明らかなtypo候補の分離、生成物のignorePaths整理を行ってください。変更後はCSpellを再実行し、変更内容と残件を報告してください。差分レビューで見るべきポイント
プロンプト実行後は、生成された差分を必ず人間が確認します。PR本文にも「Human review is recommended」とあり、AIが作ったサンプルや分類結果をそのまま採用しないことが前提になっています。(GitHub)
レビューでは、最低限次の項目を確認してください。
| 確認項目 | OKの状態 | NGの例 |
|---|---|---|
words の追加 | 製品名、API名、略語など妥当な固有語だけが追加されている | 明らかなスペルミスが登録されている |
| 並び順 | 大文字小文字を考慮しつつ読みやすく整列されている | 追加順のままで重複がある |
| カスタム辞書 | 既存の辞書構成を壊さず、適切な辞書に追加されている | すべて words に詰め込まれている |
ignorePaths | 生成物、外部依存、lockfileなどが対象 | src/** や docs/** まで除外している |
| 設定形式 | 既存のJSON、YAML、JS形式を維持している | JS設定をJSONへ変換している |
| 実行結果 | 指摘件数が減り、残件の理由が説明されている | 件数だけ出て、残件の分類がない |
「50件未満」を絶対基準にしない
PRの説明やプロンプト内では、最終的なCSpell指摘数について「50件未満」が目安として示されています。ただし、レビューコメントでは、この絶対数はリポジトリ規模によって恣意的になりやすく、ベースラインからの削減率で見る方がよいという指摘も出ています。大規模なモノレポと小規模なCLIツールを同じ50件基準で評価するのは現実的ではありません。(GitHub)
実務では、次のように段階的な基準を置くのがおすすめです。
| フェーズ | 目標 | 判断基準 |
|---|---|---|
| 初回棚卸し | 誤検知を大きく減らす | ベースライン比で大幅に減っている |
| CI導入前 | 残件をカテゴリ別に整理する | typo、固有語、生成物が分かれている |
| CI運用開始 | 新規差分を厳しく見る | 既存残件ではなく変更ファイル中心にチェック |
| 定期メンテナンス | 辞書肥大化を防ぐ | 不要な単語、重複、広すぎる除外を削除 |
たとえば初回実行で300件から70件に減ったなら、50件未満ではなくても十分に前進です。逆に、30件から25件にしか減らず、しかも src/ を大きく除外しているなら、見かけ上の件数が少なくても品質は下がっています。
失敗しやすいポイントと対策
typoを辞書へ入れてしまう
もっとも避けたいのは、誤字を words へ追加することです。たとえば recieve のような典型的なtypoや、READMEの見出しにある誤字は修正すべきです。辞書登録してしまうと、同じ誤字が今後も検出されなくなります。
対策として、辞書追加のレビューでは「この単語は社内・製品・技術用語として説明できるか」を確認します。説明できない単語は、追加せずにソース修正候補へ回すのが安全です。
生成物由来のランダム文字列を登録する
ハッシュ、Base64風の文字列、ビルド成果物、minify済みファイルに出てくるトークンは、辞書登録に向きません。PRのレビューコメントでも、16文字以上のhex文字列やBase64風文字列、lockfile・minified assets・build outputにだけ出るトークンを除外するような具体的ヒューリスティックが提案されています。(GitHub)
こうしたトークンは、単語としての価値がないため、words ではなく ignorePaths や対象globの調整で対応します。
設定ファイルを増やしてしまう
既存の .cspell.json があるのに、新しく cspell.json を作ってしまうと、開発者のエディタ、CI、GitHub Actionsで参照する設定がずれることがあります。CSpellは複数形式に対応しているため、プロンプト実行後に「新しい設定ファイルが増えていないか」を必ず確認してください。
特に、package.json にCSpell設定を入れているプロジェクトや、cspell.config.js で動的に辞書を読み込んでいるプロジェクトでは、既存構造を壊さないことが重要です。
CIの合格条件をいきなり厳しくしすぎる
CSpellの導入初期に、すべての既存指摘をゼロにしようとすると、辞書登録が雑になりがちです。まずは既存残件を分類し、新規差分だけ厳しく見る運用から始める方が現実的です。
GitHub ActionでCSpellを使う場合、変更ファイルだけを見る設定や、ignorePaths の効き方を理解しておく必要があります。CSpellのGitHub Action設定では、デフォルトでpull requestやpushで変更されたファイルをチェック対象にし、ignorePaths が適用されることが説明されています。(CSpell)
チームで運用するための現実的なルール
cspell-config promptを使う場合でも、最終的な品質はチームの運用ルールで決まります。おすすめは、辞書追加・typo修正・除外パス追加を同じPRで混ぜすぎないことです。
たとえば、次のように分けるとレビューしやすくなります。
| PRの種類 | 内容 | レビュー担当 |
|---|---|---|
| 辞書メンテナンスPR | 固有語の追加、重複削除、並び替え | 開発リード、ドキュメント担当 |
| typo修正PR | README、コメント、UI文言、ログ文言の修正 | 該当機能の担当者 |
| 除外パス整理PR | 生成物、vendor、lockfileの除外 | ビルド・CI担当 |
| CI導入PR | CSpell実行スクリプト、GitHub Actions設定 | DevOps担当 |
AIプロンプトで作業を自動化しても、「どの単語を正しいと認めるか」はプロジェクトの言葉を管理する判断です。特に製品名、ブランド名、社内略語、ユーザー向け文言は、開発者だけでなくドキュメント担当やプロダクト担当の確認を入れると品質が安定します。
まず何を確認すべきか
今回の更新を受けて、最初にやるべきことは「自分のリポジトリがCSpell設定をどの形式で持っているか」を確認することです。次に、現在のスペルチェック結果をベースラインとして保存し、cspell-config promptを検証ブランチで実行します。その後、words、カスタム辞書、ignorePaths、残件レポートをレビューし、CIの結果が改善しているかを確認します。
すでにCSpellを運用しているチームにとって、このMicrosoft developer platform documentation updateは、辞書メンテナンスの手作業を減らすきっかけになります。ただし、experimental promptであり、Copilotのprompt files自体もプレビュー扱いのため、いきなり標準運用へ組み込むのではなく、まずは「検証ブランチで実行し、人間が差分をレビューする」形から始めるのが最も安全です。
最終的には、CSpellの指摘件数を減らすこと自体が目的ではありません。目的は、誤字を見逃さず、プロジェクト固有の正しい用語を守り、ドキュメントとコードの品質を継続的に保つことです。cspell-config promptは、そのための棚卸し作業を効率化する補助ツールとして活用するとよいでしょう。
コメント