エンジニアリング組織が AI コーディングアシスタントを導入する際、直面しやすい課題が「開発メンバーごとのプロンプト記述スキルのばらつき」です。シニアエンジニアが制約条件や境界値を考慮した緻密な指示を作成できる一方で、他のメンバーが「このコードを修正して」「テストを書いて」といった曖昧な指示を入力してしまうケースは少なくありません。その結果、生成される単体テストのフレームワーク混在、アサーション規則の乖離、コード解説の品質不均衡が生じ、チームが培ってきた設計思想やベストプラクティスが定着しにくくなります。
Sourcegraph Cody は、この課題をリポジトリ単位で根本から解決する仕組みとして カスタムコマンド（Custom Commands） を備えています。リポジトリルートの .vscode/cody.json に設定を記述することで、実績のあるプロンプトテンプレート、実行モード、正確なコンテキスト取得範囲を「Prompts as Code（コードとしてのプロンプト）」として共有できます。リポジトリをクローンした開発者は、即座に同一のスラッシュコマンドを利用可能となり、コード補完・リファクタリング・テスト生成の品質水準を組織全体で均一化できます。
.vscode/cody.json のアーキテクチャと基本仕様
Cody のカスタムコマンドには、ユーザー個人設定に保存されるグローバル定義と、リポジトリに紐づくワークスペース定義が存在します。設定ファイル cody.json をプロジェクト直下の .vscode/ ディレクトリに配置することで、対象コードベースの技術スタックやテスト規約にコマンドを固定できます。
repository-root/
├── .vscode/
│ ├── cody.json <-- チーム共有のカスタムコマンド定義
│ └── settings.json
├── src/
├── tests/
└── package.json
このファイルを Git で管理すると、チームメンバーが VS Code でプロジェクトを開いた際に Cody が自動的に設定を認識します。コマンドパレットのショートカット（macOS: Option + C、Windows/Linux: Alt + C）や、Cody Chat の入力欄でスラッシュコマンド（例: /unit-test）を入力することで呼び出せます。
JSON スキーマの構成
.vscode/cody.json はルートに commands オブジェクトを持ち、各キーが起動用のスラッシュコマンド名となります。
{
"commands": {
"command-identifier": {
"prompt": "LLMに送信される具体的な指示テンプレート。",
"description": "Codyコマンドメニューに表示される概要説明。",
"mode": "ask",
"context": {
"codebase": false,
"selection": true,
"currentDir": false,
"openTabs": false
}
}
}
}
主要属性の定義は以下の通りです。
| フィールド | 型 | 説明 |
|---|---|---|
prompt | String | LLMへ送信されるシステムプロンプト。役割定義、コーディング規約、テスト制約、出力形式を記述します。 |
description | String | コマンドパレットやドロップダウンに表示される説明文。用途の判別を助けます。 |
mode | String | コマンド実行時の挙動および結果の反映先を指定します（ask、edit、insert）。 |
context | Object | プロンプト実行時に Cody が自動収集するソースコード情報のスコープを精密に制御します。 |
実行モードの使い分け（ask・edit・insert）
mode プロパティは、生成されたコードを開発環境のエディタへどのように反映させるかを決定します。
-
ask（対話・レビュー型）：- サイドバーの Cody Chat ウィンドウに応答を出力します。
- セキュリティレビュー、アーキテクチャ検証、アルゴリズムの解説、PR概要作成など、開発者が内容を吟味してから採用を判断したい処理に適しています。
-
edit（インライン直接置換型）：- エディタ上で現在選択されているコードブロックを、生成されたコードで直接置き換えます。
- TypeScript の型厳格化、ネストされた三項演算子の解消、イミュータブル処理への変更など、明確なリファクタリング作業に最適です。
-
insert（カーソル位置挿入型）：- カーソル位置、または選択範囲の直上に生成結果を挿入します。
- 既存関数への TSDoc/JSDoc コメント付与や、新規テストファイルへのテストスイート構造の初期生成に適しています。
コンテキスト取得のスコープ制御：精度と応答速度の両立
AI コード生成において、コンテキストの不足はハルシネーション（誤情報生成）の原因となり、過剰なコンテキスト投入はトークン消費とレイテンシの増大を招きます。context ブロックを活用することで、必要十分な情報範囲に絞り込めます。
selection（boolean）： 現在エディタで選択している行を含めるかどうか。関数のリファクタリングや型定義の改善など、局所的な作業ではtrueに設定してモデルの焦点を絞ります。codebase（boolean）： Sourcegraph のコード検索およびエンベディングを活用してリポジトリ全体を横断検索するかどうか。プロジェクト固有のテストヘルパーや共通型定義を参照する必要があるテスト生成では有効ですが、局所的なコード変更では無駄な検索処理を省くためにfalseに設定することが推奨されます。currentDir（boolean）： アクティブファイルと同じディレクトリに存在するファイルを含めるかどうか。コンポーネントとそのスタイル定義、モックデータが同一階層にまとまっている場合に有用です。openTabs（boolean）： 現在開いているエディタタブの内容を含めるかどうか。複数ファイルにまたがる実装時には役立ちますが、無関係なファイルが開かれているとノイズになるため注意が必要です。
チーム向け実践設定レシピ
以下は、TypeScript および React 開発チームを想定した本番仕様の .vscode/cody.json 設定例です。
{
"commands": {
"unit-test": {
"description": "VitestおよびTesting Libraryに準拠した単体テストを生成",
"mode": "ask",
"context": {
"selection": true,
"codebase": true,
"currentDir": true,
"openTabs": false
},
"prompt": "あなたはシニアテスト自動化エンジニアです。選択されたコードに対して Vitest および @testing-library/react を用いたテストスイートを作成してください。\n\n遵守ルール:\n1. AAA（Arrange-Act-Assert）パターンでテストを構成すること。\n2. コードベース内に存在する既存のテスト用FixtureやMockパターンを踏襲すること。\n3. 正常系、境界値、Null/Undefinedの入力、および非同期処理のエラー（Reject）を網羅すること。\n4. 未承認の外部ライブラリは使用せず、Vitest標準の vi.fn() と vi.spyOn() を使用すること。\n5. '// 実装してください' 等の省略コメントを使わず、実行可能な完全なコードを出力すること。"
},
"refactor-clean": {
"description": "厳格なTypeScriptルールとイミュータブル設計に基づきコードをリファクタリング",
"mode": "edit",
"context": {
"selection": true,
"codebase": false,
"currentDir": false,
"openTabs": false
},
"prompt": "選択されたコードブロックをクリーンコードおよび厳格な TypeScript 規約に準拠してリファクタリングしてください:\n1. 既存の公開 API シグネチャ、引数契約、実行時挙動は維持すること。\n2. 曖昧な any 型を具体的な判別可能なユニオン型またはジェネリクス制約に置き換えること。\n3. 可変操作を純粋関数とイミュータブルなデータ更新に書き換えること。\n4. 深いネストや複雑な三項演算子を早期リターン（Early Return）に整理すること。\n5. 解説文やMarkdownブロックを含めず、置換用のコードのみを出力すること。"
},
"security-audit": {
"description": "OWASP Top 10脆弱性および機密情報漏洩リスクの検証",
"mode": "ask",
"context": {
"selection": true,
"codebase": true,
"currentDir": false,
"openTabs": false
},
"prompt": "選択されたコードに対してセキュリティコードレビューを実施してください。\n\n以下の観点を検証すること:\n1. インジェクション脆弱性（SQL、NoSQL、OSコマンド、テンプレートインジェクション）。\n2. 認可制御の欠落、不適切な権限検証、特権昇格リスク。\n3. 安全でない直接オブジェクト参照（IDOR）およびバリデーション不備。\n4. ソースコードやログ出力における秘密鍵、トークン、個人情報（PII）の露出。\n5. 例外処理の不備による内部スタックトレースの漏洩。\n\n出力形式: [重要度: 高/中/低] | [課題名] | [該当行] | [修正方針およびDiff]。"
},
"doc-api": {
"description": "関数やインターフェースに対するTSDocコメントの生成と挿入",
"mode": "insert",
"context": {
"selection": true,
"codebase": false,
"currentDir": false,
"openTabs": false
},
"prompt": "選択された関数またはインターフェースに対して本番基準の TSDoc ドキュメントを生成してください:\n1. 1行目で簡潔な概要を述べ、続けて仕様の詳細を説明すること。\n2. すべての @param タグを正確な型と意味を明記して記述すること。\n3. @returns タグで返り値の型と条件を明確にすること。\n4. 発生し得る例外を @throws タグで網羅すること。\n5. 実用的な呼び出し例を示す @example ブロックを含めること。\n6. コードの直上にそのまま挿入可能な JSDoc/TSDoc 形式で出力すること。"
}
}
}
チーム運用におけるガバナンスと展開
.vscode/cody.json の効果を継続的に高めるために、開発チームは以下の運用プラクティスを定着させることが推奨されます。
1. プロンプトをコード資産として扱う（Prompts as Code）
.vscode/cody.json に格納されたプロンプトは、プロジェクトのコード資産の一部です。プロンプトの追加や変更は Pull Request を通じたコードレビューの対象とし、構文エラーによる拡張機能の不具合を防ぐために CI での JSON スキーマ検証を導入します。
2. コードベース全体のコンテキスト使用を最適化する
すべてのコマンドで "codebase": true を有効にすると、ローカルなリファクタリング作業でもネットワーク問い合わせが発生し、レイテンシが増大します。グローバルな型やモジュール依存が必要なコマンドのみに限定し、局所的なロジック編集には "selection": true を中心に構成します。
3. Sourcegraph Prompt Library への拡張
複数のマイクロサービスリポジトリを抱える組織では、リポジトリごとの設定同期が課題になることがあります。Sourcegraph Enterprise および Cody v1.30 以降では、Web UI ベースの Prompt Library（プロンプトライブラリ） が提供されています。
個別のリポジトリで .vscode/cody.json を通じて検証・洗練させたプロンプトは、組織全体の Prompt Library に登録することで、タグ付け管理、推奨プロンプト（Promoted Prompts）の設定、動的な @selection や @file 参照を活かし、VS Code や JetBrains など複数の IDE を横断して全社展開できます。