---
name: deviation-comment
description: Coverity の警告の逸脱コメント（直さない理由として Coverity に登録する200文字以内の短い文）を決まりに沿って書き、Classification・Action・Severity の案と一緒に返す。書いたコメントの形はスクリプトで確かめる。チャットで「この警告の逸脱コメントを書いて」「CID 12345 を逸脱にするコメントを考えて」「この逸脱コメントで大丈夫か見て」のように頼まれたとき、警告のトリアージで逸脱案を作るとき、まとめた警告の逸脱コメントを作るときに使う。Coverity に登録する逸脱コメントを書く・直すときは、短い文でも必ずこのスキルを使う。
allowed-tools: ["shell(uv run:*)"]
---

# 逸脱コメントの書き方

逸脱コメントは、この警告が**どんな状況でも問題にならない**ことを述べる短い文です。
Coverity に登録され、後で読む人が「直さなくてよい理由」として使います。だから、言い切れることだけを、コードの場所と一緒に書きます。

## 進め方

```
- [ ] 1. 材料をそろえる（判定区分・理由・実際に読んだコードの場所）
- [ ] 2. 書く
- [ ] 3. 確かめる（スクリプト。だめなら直して、もう一度）
- [ ] 4. Classification・Action・Severity を選ぶ
- [ ] 5. 返す
```

### 1. 材料をそろえる

- 要るもの：判定区分（誤検知・意図的・本物の不具合）、問題にならない理由、それを示すコードの場所（関数名とファイル・行）。
- 頼みに真偽の見立てや根拠の場所がなければ、まずコードを読んで確かめる。警告の真偽を調べる手順があれば、それで決める。
- 警告の情報（CID、チェッカー、ファイルと行、警告経路）が足りないとき：Coverity から警告経路を取れる道具があれば、それで取る。なければ頼んだ人に聞く。聞けないとき（ほかのエージェントからの頼みなど）は、分かることだけで書き、足りないことを返事に書く。推測で補わない。
- リポジトリに `.coverity-triage/knowledge.md` があれば読む。その「## 逸脱コメントの書き方」の決まりは、このスキルより優先する（チームの書き方）。

### 2. 書く

- 日本語で、見出し・箇条書き・改行・書式（`` ` `` や `**`）のない、**判定区分のあと1〜2文**。
- **200文字以内**。前後に空白を入れない。
- 順番は次のとおり。
  1. **判定区分**：「誤検知。」「意図的。」「本物の不具合。」のどれかで始める。
  2. **問題にならない理由**：条件を付けずに言い切る。
  3. **根拠の場所**：理由を示す関数名とファイル・行。例 `open_session()（src/net/session.c:120）`、範囲は `src/reader.c:55〜60`。パスはリポジトリの一番上から。

例：

> 誤検知。find_slot() の戻り値は NULL になりうるが、呼び出し元 open_session()（src/net/session.c:120）で NULL を除いてから渡しているため、NULL を参照することはない。

> 意図的。case 2 から case 3 へのフォールスルーは、状態 2 の処理のあと状態 3 の処理を続けて行う設計（src/fsm.c:88 のコメントに記載）であり、break の書き忘れではない。

> 本物の不具合。v1 形式の読み込みは今の製品では無効（include/features.h:31）で、この処理は実行されない。

ほかの例と、だめな例の直し方は [references/examples.md](references/examples.md) にあります。書き方に迷ったら読みます。

### 書かないこと

逸脱コメントには、問題にならない理由だけを書きます。次のことは、結果の根拠の説明（rationale や確信度の理由）のほうに書きます。

- 条件や但し書き：「ただし」「〜の場合に限る」「〜する場合は」「〜に対して」。コードの振る舞いも「場合は」を使わずに書く（「失敗すると -1 を返す」）
- 前提や、見直しの指示：「この判断の前提：…」「〜の間だけ有効」「〜を変えたら、この判断を見直すこと」（前提が要るなら、言い切れていない）
- 推量：「おそらく」「〜と思われる」「〜かもしれない」
- 調べた過程や、調べきれなかったこと：解析したリビジョンが分からない、警告の説明とコードが合わない、など
- 推奨や人への依頼・指示：「修正を推奨」「確認してください」「〜すべき」「〜前に直すこと。」（「〜こと。」で終わる文は指示になる）

根拠の場所には、実際に読んで確かめた場所だけを書きます。読んでいない場所を推測で書きません。

### 言い切れないとき

- 条件を付けないと「問題にならない」と書けないなら、それは問題になりうるということです。**推奨は修正**にします。逸脱コメントは形として作り、言える範囲の理由だけを短く書きます（例「本物の不具合。src/reader.c:42 で fgets の戻り値を確かめずに使っており、直さない理由は説明できない。」。決まった文ではありません）。
- 本物の不具合でも、今は実行されないことや影響がないことをコードで示せるなら、その**事実をそのまま**書きます。「ただし」「〜なら」のような条件の言い方は使いません（上の3つ目の例）。示せなければ、推奨は修正にします。

### 3. 確かめる

コマンドを使えるときは、書いたコメントを次のスクリプトで確かめます（RUN。中を読む必要はありません）。

```
uv run --native-tls --quiet "<このスキルのフォルダ>/scripts/check_comment.py" --comment "<逸脱コメント>"
```

- `<このスキルのフォルダ>` は、この SKILL.md があるフォルダです。
- 結果は JSON が1つです。例 `{"ok": true, "length": 86, "problems": []}`。
- `ok` が `false` なら、`problems` の `message` のとおりにコメントを直し、もう一度確かめます。通るまで繰り返します。確かめを別のやり方で済ませたり、決まりを曲げたりしません。3 回直しても `ok` にならなければ、それ以上は直さず、残った `problems` と今の案をそのまま返して止めます（決まりは曲げません）。
- 引用符などでコマンドに渡しにくいときは、`--stdin` を付け、標準入力に `{"comment": "…"}` の JSON を渡します。

コマンドを使えないとき（ほかのエージェントからの作業など）は、確かめる点を自分で1つずつ見て、最後まで進めます（決まった形の確かめは、頼んだ側が行います）。

- 200文字以内か（数える）／判定区分で始まるか／判定区分のあと1〜2文か／改行や書式がないか／「書かないこと」の言い方がないか

### 4. Classification・Action・Severity を選ぶ

値は Coverity Connect の選択肢の名前のまま書きます。

| 判定区分 | Classification | Action | Severity |
| --- | --- | --- | --- |
| 誤検知 | False Positive | Ignore | Unspecified |
| 意図的 | Intentional | Ignore | Unspecified |
| 本物の不具合で、直さない | Bug | Ignore | 影響の大きさで Major / Moderate / Minor |

- 修正の案と組にするときは、修正の側を Bug / Fix Required にし、Severity は警告の Impact に合わせます（High → Major、Medium → Moderate、Low → Minor）。
- チームの値が違うときは、`knowledge.md` の決まりに従います。

### 5. 返す

- 頼みの文や、それが指すファイル（指示ファイル）が、書く場所と返す形を決めていれば、それに従います。
- チャットで頼まれたときは、次をチャットで返します。頼まれない限り、ファイルを作らず、Coverity にも書き込みません。
  - 逸脱コメントの文と字数（確かめの結果）
  - Classification・Action・Severity
  - 判定区分と、根拠の場所（ファイルと行）
  - 言い切れないときは、そのことと、推奨は修正になること