---
name: coverity-setup
description: Coverity トリアージを使う準備をする（uv、MCP サーバの環境、サブエージェント（取得・作業・統合・検証）の配置、設定ファイル、認証情報、接続の確認、オプションでビルドでの検証・初回解析・統合と検証）。何度実行してもよく、足りないものだけを補う。人が /coverity-setup で頼む。引数は省略可。
allowed-tools: ["coverity-triage", "shell(uv run:*)"]
---

# Coverity トリアージの準備

利用者はこのプラグインの仕組みを知りません。**一度に 1 つずつ**、短く、ふつうの言葉で案内します。
何度実行されてもかまいません。`ct.py doctor` で足りないものを調べ、それだけを補います。

最初にスキル `coverity-triage-scripts` を読み、スクリプト `ct.py` の場所と使い方を確かめます。以下の `ct.py X` は、そこに書かれた方法（`uv run --native-tls <フォルダ>/scripts/ct.py X`）で実行します。

## 0. 準備のしかたを選ぶ（最初に聞く）

何よりも先に、次を聞きます。

> 準備のしかたを選んでください。
> 1. **対話で準備する**：これまでどおり、チャットで 1 つずつ答えます。
> 2. **画面で準備する**：ブラウザに設定の画面を開き、設定をまとめて入れます。この画面は、あとで AI の動きの監視と結果の確認にも使います。

- 1 なら、下の 1〜12 をそのまま進めます。
- 2 なら、最後の「画面で準備する場合」の順に進めます。
- 再起動のあとにもう一度 `/coverity-setup` が入力されたときも聞きます。どちらでも、済んだところは `ct.py doctor` で分かるので飛ばします。

## 守ること

- ターミナルでコマンドを実行する前に、何のために実行するかを 1 行で伝える。
- git / svn / VS Code / Coverity の設定は変えない。足りないものは社内の手順で入れてもらう。
- **認証キーをチャットで聞かない。** 入力は、下の「認証情報」の方法で、利用者がターミナルの伏せ字の欄に入れる。チャットに貼られたら使わずに、「漏れたおそれがあるので、認証キーを作り直してください」と伝える。
- 設定ファイルを書く前に、書く値を表で見せて同意を得る。
- 確かめられることは推測しない。`ct.py doctor` と MCP の `check_connection` で確かめる。

## 1. 確認の画面を減らす

準備の間は、コマンドの実行ごとに確認の画面が出ます。最初に次を案内します（決定 2）。

> 準備の間だけ、チャットの許可のレベルを「すべて許可」にすると、確認の画面が出なくなります。VS Code ではチャットの入力欄の許可のメニューで **Allow all**（すべて許可）を選びます。Copilot CLI では `/allow-all` と入力します。終わったら元に戻せます。

選ばなくても準備はできます（確認の画面で、その都度「許可」を押します）。

## 2. uv

このプラグインは uv（Python とライブラリを用意する道具）で動きます。

1. ターミナルで `uv --version` を実行する。
2. 無ければ「uv を入れます」と伝え、次を実行する（PowerShell）。
   ```powershell
   powershell -ExecutionPolicy ByPass -NoProfile -Command "irm https://astral.sh/uv/install.ps1 | iex"
   ```
   - 社内のプロキシで失敗したら、環境変数 `HTTPS_PROXY` の設定が要るか、社内の担当に確かめるよう伝える。
   - 入れた直後は、この会話の中で `uv` が見つからないことがあります。そのときは `%USERPROFILE%\.local\bin\uv.exe` のフルパスで動かす。
   - **uv を入れたことを覚えておく**（最後に再起動が要る）。

## 3. 準備の状況

1. `ct.py prewarm` を実行する（MCP サーバの Python 環境を作る。初回は 1〜2 分）。
2. 対象リポジトリの一番上のフォルダ（`.git` か `.svn` があるフォルダ）を決める。開いているフォルダがそうでなければ、利用者に聞く。
3. `ct.py doctor --repo <フォルダ>` を実行し、「できていること」と「足りないこと」を短く伝える。足りないものを、上から順に次の 4〜6 で補う（「初回解析の」で始まる行は、10 で扱う）。

## 4. サブエージェント

`/coverity-run` は、仕事ごとに 4 つのサブエージェントを使います。

| サブエージェント | 仕事 |
|---|---|
| `coverity-triage-collector`（取得） | Coverity から警告を検索し、警告経路を取る（読むだけ） |
| `coverity-triage-worker`（作業） | 警告を 1 件ずつ調べ、修正案と逸脱コメント案を作る |
| `coverity-triage-integrator`（統合。オプション） | 同じ原因の作業をまとめる計画を書く |
| `coverity-triage-reviewer`（検証。オプション） | 結果を独立に確かめる |

`doctor` でサブエージェントのどれかが ng、または「古いサブエージェント」の行があれば、「警告を取る・調べる・まとめる・確かめる AI（サブエージェント）の定義を、あなたのフォルダ `%USERPROFILE%\.copilot\agents`（環境変数 `COPILOT_HOME` があれば、その中の `agents`）に置きます」と伝えて `ct.py install-agent` を実行する（決定 1）。

- 4 つとも置きます（統合と検証を使わない設定でも置きます）。書くのは、無いものと古いものだけです。
- プラグインに無くなった古い定義（`coverity-triage-` で始まるもの）は消します。ほかの定義には触りません。
- 結果の `agents` に、エージェントごとの結果があります（`installed`：置いた、`updated`：新しくした、`unchanged`：そのまま、`removed`：消した）。置いた場所は `folder` です。
- `restart_needed` が true なら、**最後に再起動が要る**ことを覚えておく。

## 5. 設定ファイル（リポジトリにまだ無いときだけ）

チームで最初に使う人だけが作り、コミットして共有します。

1. `ct.py detect --repo <フォルダ>` を実行する。
2. 次の 3 つを、1 つずつ聞く。
   - Coverity Connect の URL（ブラウザで開く Coverity のアドレス。例 `https://coverity.example.co.jp:8443`）
   - プロジェクト名
   - ストリーム名
3. 書く値を表で見せて同意を得る。

   | 項目 | 値 |
   |---|---|
   | Coverity の URL・プロジェクト・ストリーム | 聞いた値 |
   | git / svn、取り込み先のブランチ | `detect` の値 |
   | 結果を置く場所 | リポジトリの隣のフォルダ（`../coverity-triage-out`） |
   | 最初に調べる警告 | 分類がまだの警告を 20 件まで（条件ファイル `untriaged.yaml`） |

4. 同意を得たら `ct.py init-config --repo <フォルダ> --url <URL> --project <名前> --stream <名前>` を実行する（変えたい値があれば引数で渡す）。
5. 「`.coverity-triage/` フォルダをコミットして、チームで共有してください（認証情報は入っていません）」と伝える。知識のファイル `knowledge.md` もできたこと、AI が調べる前に読むので、チームの判断の方針などを書いておけることを 1 行で伝える。

## 6. 認証情報（PC ごと）

`doctor` で ng の環境変数だけを設定します。

- **ユーザ名**：利用者に聞いて、次で保存する。
  ```powershell
  powershell -NoProfile -Command "[Environment]::SetEnvironmentVariable('COV_USER', '<ユーザ名>', 'User')"
  ```
- **認証キー**：値は聞かない。次をターミナルで実行し、表示された伏せ字の欄に利用者が入れる。
  ```powershell
  powershell -NoProfile -Command "$s = Read-Host 'COV_AUTH_KEY を入力してください（表示されません）' -AsSecureString; $v = [Runtime.InteropServices.Marshal]::PtrToStringBSTR([Runtime.InteropServices.Marshal]::SecureStringToBSTR($s)); [Environment]::SetEnvironmentVariable('COV_AUTH_KEY', $v, 'User'); Write-Host '保存しました'"
  ```
  - ターミナルで入力できないときは、このコマンドを利用者に渡し、自分で PowerShell を開いて実行してもらう。
  - 認証キーの作り方が分からないと言われたら、Coverity Connect の画面のユーザのメニューから作れること（社内の案内があればそれ）を伝える。

GitHub のトークンは要りません（プルリクエストは Copilot の機能で作ります）。

## 7. 再起動（必要なときだけ、1 回）

2 で uv を入れた、または 4 で `restart_needed` が true だったときだけ、次を伝えて、ここで止まります（決定 1）。

> 準備の続きのために、VS Code（Copilot CLI の場合は Copilot CLI）を一度終了して、起動し直してください。起動したら、もう一度 `/coverity-setup` を入力してください。続きから進めます。

- サブエージェントの定義は、Copilot CLI が起動するときに読み込まれます。起動し直すまでは、新しく置いた定義が見つからなかったり、古い定義のまま動いたりします。

どちらでもなければ、そのまま 8 へ進みます。

## 8. Coverity への接続

1. MCP の `check_connection` を `repo_root` で呼ぶ。
   - MCP のツールが見つからない、または起動に失敗したときは、スキル `coverity-help` の「困ったとき」の「MCP サーバが動かない」に沿って案内する。
2. 認証できたら、かかった秒数と一緒に伝える。`warning` があればそのまま伝える。
3. `ct.py doctor` をもう一度実行し、すべて ok であることを確かめる。

## 9. トリアージ中の確認を減らす（決定 4）

トリアージは件数が多いので、このプラグインのツールだけは確認なしで動くようにします。

- Copilot CLI：`/coverity-run` と `/coverity-apply` の間は、このプラグインのツールとスクリプトが自動で許可されます。することはありません。
  - 取得のエージェント（サブエージェント）が呼ぶ Coverity のツールで確認の画面が出たら、「このセッションでは許可」を選んでもらいます。人が見ていない間に、確認の画面で止まらないようにするためです。
- VS Code：次の 2 つを案内する。
  1. コマンドパレットで **Chat: Manage Tool Approval** を開き、`coverity-triage` のツールを「確認なしで実行」にする。
  2. コマンドパレットで **Preferences: Open User Settings (JSON)** を開き、次を足す（スクリプトの実行だけを確認なしにする）。
     ```json
     "chat.tools.terminal.autoApprove": {
       "/^.*uv(\\.exe)?\"? run .*coverity-triage-scripts[\\\\/]scripts[\\\\/]ct\\.py\"? /": true
     }
     ```
  - 難しければ、トリアージの間だけ「すべて許可」にしてもよいと伝える。

## 10. ビルドでの検証（オプション）

ビルドのコマンドを設定すると、次の 2 つに使えます。どちらも既定では使いません。

| 使い方 | すること |
|---|---|
| 修正案の検証（`verify.default`） | `/coverity-run` の最後に、修正案をすべて当てたコードをビルドして確かめる（`build`）。Coverity で解析し直して、警告が消えたかも確かめる（`build+analyze`） |
| 初回解析（`verify.initial`） | `/coverity-run` の最初に、開いているフォルダをビルドして Coverity で解析し、結果をサーバに登録してから警告を取る。今まで手で「解析してサーバに登録する」をしていたなら、その代わりになる |

「修正案をビルドで確かめる設定や、最初に解析してサーバに登録する設定（初回解析）もしますか？（使わなくてもかまいません。あとからでも設定できます）」と聞く。使わないなら 11 へ。

使う場合は、1 つずつ聞く（推測で決めない）。

1. ビルドの前に実行する環境設定のコマンド（例 `envset.bat "{root}" <引数>`）。引数の数と、それぞれに何を渡すかを聞く。ビルド用のフォルダを渡す引数は `{root}` と書く。不要なら空。
2. ビルドするフォルダ（makefile がある場所。リポジトリからの相対パス）。一番上でよければ空。
3. ビルドのコマンド（例 `make -f makefileXX`）。
4. 修正案の確かめ方：確かめない（`none`。初回解析だけを使うとき）、ビルドだけ（`build`）、ビルドと Coverity の再解析（`build+analyze`）のどれか。
5. 初回解析を使うか。聞く前に、次を短く伝える。
   - 開いているフォルダを、そのままビルド・解析します。結果は、条件ファイルのストリームに、開いているフォルダの今のコミット（またはリビジョン）を版として登録します。登録まで終わってから、警告を取ります。
   - Coverity のトリアージ（分類やコメント）は変えません。スナップショットが 1 つ増えるだけです（手で解析して登録していたときと同じ）。
   - ビルドの生成物と、解析の中間ディレクトリ（`cov-build` の `--dir`）は、開いているフォルダの中にできます（手で解析していたときと同じ）。
   - 失敗したら、トリアージを始めずに止まり、失敗した段（ビルド・解析・登録）とログの最後を伝えます。
6. （初回解析を使うとき）`cov-commit-defects` に足す引数。`--dir`・`--url`・`--stream`・`--user`・`--version` はスクリプトが付けます。認証キーは環境変数 `COVERITY_PASSPHRASE` で渡す（コマンドラインとログには出さない）ので、ふつうは空です。認証キーのファイルを使うサイトでは、`--auth-key-file <ファイル>` などをここに書きます。
7. （初回解析を使うとき）時間切れの分（既定 180 分）。ビルドと解析に、ふだんかかる時間より長くします。超えると止めて、失敗として扱います（人が見ていない間に、固まったビルドを止めるため）。

「修正前のコードで試しにビルドします（時間がかかることがあります。サーバには登録しません）」と伝えて `ct.py trial-build` を実行する。失敗したら `log_tail` を見て、コマンドの誤りか環境の問題かを伝え、直して試す。成功したら、保存する値を見せて同意を得てから `ct.py set-verify` を実行し、コミットして共有するよう伝える。

- `set-verify` には、1〜3 の値（`--setup-command`・`--build-dir`・`--build-command`）と 4（`--default`）を渡す。`--default` を省くと `build` になる。
- 初回解析を使うときは `--initial --cov-commit-args="<6>" --timeout-minutes <7>`、使わないときは `--no-initial` を足す（省いた項目は、今の設定のまま残る）。`--cov-commit-args` は、値が `--` で始まっても受け取れるように、`=` でつなぐ形で書く（`--cov-build-args`、`--cov-analyze-args` も同じ）。
- 初回解析を使うときは、保存のあとに `ct.py doctor --repo <フォルダ>` を実行し、初回解析の行（`cov-build`・`cov-analyze`・`cov-commit-defects` が PATH にあるか、登録の認証情報があるか）を確かめる。ng があれば伝える（Coverity のツールの bin フォルダを PATH に足すのは、社内の手順で行ってもらう）。warning は「環境設定のコマンドで PATH に足されるなら問題ありません」と伝える。

## 11. 統合と検証（オプション）

次の 2 つも、オプションで使えます（既定は使いません）。短く紹介して、使うかどうかを聞きます。

| 設定 | すること |
|---|---|
| `agents.integration`（統合） | 作業エージェントが調べ終わったあとで、統合エージェントが、同じ原因の作業を 1 つにまとめる。コードは書かない（まとめた修正は、スクリプトか作業エージェントが作る） |
| `agents.review`（検証） | 統合のあとで、検証エージェントが、出来上がった結果を 1 件ずつ独立に確かめる。直す点があれば作業エージェントに差し戻す（`agents.max_rework` 回まで。既定 1）。一覧の確信度は、検証で下がることはあっても、上がることはない |

- どちらも、使うと実行の時間が延びます。
- 使うと、`/coverity-run` が終わって一覧ができるまで、画面で承認を選べません（統合と検証で、結果が変わることがあるため）。

「同じ原因の警告を 1 つにまとめる『統合』と、結果を別の AI が独立に確かめる『検証』も使えます（既定は使いません。あとからでも設定できます）。使いますか？」と聞く。使わないなら 12 へ。

使うと言われたら、使うものだけを true にして、`.coverity-triage/config.yaml` に足す内容を見せて同意を得てから書き、`ct.py doctor` で設定が読めることを確かめる。コミットして共有するよう伝える。

```yaml
agents:
  integration: true   # 統合を使う
  review: true        # 検証を使う
  max_rework: 1       # 検証からの差し戻しの回数（0〜2）
```

## 12. 終わり

「準備ができました。`/coverity-run` で始められます。最初は件数の少ない条件で試すのがおすすめです」と伝える。1 で「すべて許可」にしてもらった場合は、元に戻してよいことも伝える。初回解析を使う設定にした場合は、「`/coverity-run` の最初に、ビルド・解析・サーバへの登録をします（数十分かかることがあります）」とも伝える。

## 画面で準備する場合

0 で「画面で準備する」を選んだときの順番です。5・6・10・11（設定ファイル、認証情報、ビルドでの検証と初回解析、統合と検証）の代わりに、画面で設定します。ほかは上と同じです。

1. 上の 1〜4 を同じように進める。
2. 「設定の画面をブラウザで開きます」と伝えて `ct.py gui --repo <フォルダ> --view settings` を実行する。画面は裏で動くので、コマンドはすぐ戻る。
   - `reused` が true のときは、このリポジトリの画面がもう動いていたので、それを使い回している（新しく起動していない）。
   - `browser_opened` が false のとき、または利用者が「開かない」と言ったときは、結果の `url` を伝えて、ブラウザで開いてもらう。
   - `ok` が false なら、`error` と `log_tail` を伝える。直せなければ、対話での準備（上の 5・6・10）に切り替えるか聞く。
3. 次を伝えて、利用者の知らせを待つ。

   > ブラウザに設定の画面を開きました。「基本設定」に Coverity の URL・プロジェクト・ストリーム・認証情報などを入れ、必要なら「オプション設定」でビルドでの検証・初回解析・統合と検証などを選んで、「保存」を押してください。認証キーは画面で入れます（チャットには書かないでください）。保存したら、ここで知らせてください。
   > 画面は閉じずに、そのまま残しておいてください。`/coverity-run` のときに、AI の動きの監視と結果の確認にも、この画面を使います。

   - 画面でできること（聞かれたら答える）：基本設定（Coverity の URL、最初の条件のプロジェクトとストリーム、取り込み先のブランチ、結果を置く場所、ユーザ名と認証キー）、オプション設定（アノテーション、1 つのブランチにまとめる、知識の追記の提案、効果測定の記録、Markdown も出す、統合と検証、ビルドでの検証と初回解析と試しのビルド、詳細設定）、条件ファイル、知識 `knowledge.md`、グループ化しない CID。画面には「設定」のほかに「監視」と「結果」もある（実行を始めると使う）。
   - 画面は、保存の前に書く値を表で見せて、利用者に確かめてもらう。認証キーは画面から Windows のユーザの環境変数に保存され、チャットにも設定ファイルにも出ない。
   - 画面には「終了」のボタンはない。保存しても、ブラウザのタブを閉じても、画面のサーバは動き続ける。止めるのは、画面の右上のメニューの「サーバを止める」だけ（確認が出る）。タブを閉じたときは、同じアドレスを開き直すか、`ct.py gui --repo <フォルダ> --view settings` をもう一度実行する（動いていれば同じ画面を開き、止まっていれば起動し直す）。
4. 知らせを受けたら `ct.py doctor --repo <フォルダ>` を実行する。初回解析をオンにしていれば、初回解析の行も 10 の最後と同じように確かめて伝える。設定ファイル・条件ファイル・認証情報に ng が残っていれば、何が足りないかを伝え、画面の「設定」で直してもらう（画面を閉じていたら `ct.py gui --repo <フォルダ> --view settings` で開き直す。チャットで値を聞かない）。
5. 設定ファイルを新しく作ったときは、「`.coverity-triage/` フォルダをコミットして、チームで共有してください（認証情報は入っていません）」と伝える。知識のファイル `knowledge.md` もできたこと、AI が調べる前に読むので、チームの判断の方針などを書いておけることを 1 行で伝える。
6. 上の 7（再起動）、8（Coverity への接続）、9（トリアージ中の確認を減らす）、12（終わり）を同じように進める。10・11 は画面で済んでいるので飛ばす。8 で認証できなかったときは、画面の「設定」で URL や認証キーを直してもらう（閉じていたら `ct.py gui --repo <フォルダ> --view settings` で開き直す）。12 では、「画面はそのまま残しておいてかまいません。`/coverity-run` を始めると、同じ画面で AI の動きを見られます。止めるときは画面の『サーバを止める』を押してください」とも伝える。