Guides

# スキル作成ガイド（Skill Authoring Guide / How-to）

このガイドは、River Review のスキル（`skills/**/*.md`）を追加・更新するときに、迷いを減らし、品質のブレを抑えるための「書き方」をまとめたものです。

## 目的（Goals）

- 1スキル = 1観点で、指摘の粒度と意図を揃える
- 誤検知（うるさいだけ）を減らし、レビューを読みやすくする
- 変更に強い（拡張しても運用が崩れない）スキルを書く
- 人間のレビューで「毎回言っていること」を自動化する

## 非目的（Non-goals）

- 好み・宗教論争（インデント、命名の流派など）をしない
- スキル本文で「実装方法」や「プロジェクト固有の事情」を断定しない
- “nit” を増やすためのスキルを作らない（重要度と効果が薄い指摘の濫発は避ける）
- 変更されていないコードへの網羅的な指摘をしない

## スキルの構造

スキルは YAML frontmatter（メタデータ）と Markdown 本文（指示文）で構成します。

- メタデータ: ルーティング・検証・優先度のための情報
- 本文: レビュアー（LLM/ヒューリスティック）が従うチェック観点と書き方

メタデータの定義は `schemas/skill.schema.json`、一覧は `pages/reference/metadata-fields.md` を参照してください。

スキル名の付け方（新規作成・外部からの取り込みの命名規則）は [skills/README.md の「Naming」節](https://github.com/s977043/river-review/blob/main/skills/README.md#naming) を参照してください。

最小の frontmatter（必須）:

- `id`: 安定した識別子（移動・リネームしても不変）
- `name`: 人間向けの短い名前
- `description`: 何をチェックするか（1文）
- `phase`: `upstream` / `midstream` / `downstream`
- `applyTo`: 対象ファイルの glob

## 推奨テンプレ（最小）

新規作成時は `skills/_template.md` をベースにし、まずは次を揃えます。

- `applyTo` を絞る（いきなり `**/*` にしない）
- “抑制条件” を書く（誤検知ガード）
- “扱わない領域” を書く（Non-goals）
- 指摘文は短くし、次の行動へつながるようにする

## スキルの粒度（1テーマ/1観点）

スキルは「1テーマ/1観点」で分けるのが基本です。1つのスキルに異なる目的を詰め込まないことで、誤検知が減り、運用が安定します。

- 1スキル = 1種類のリスク（例: 入力検証の欠落、Accessible Name の欠落）
- フレームワーク固有の知識は1スキルに閉じる（汎用ルールと混ぜない）
- 例外や派生条件が多い場合は別スキルに分割する

## Diff を主入力にする（Diff-first）

スキルは diff を主入力として、再現可能な指摘を行うレビュー単位です。

- 可能な限り「変更行」を優先して評価する
- 変更外に言及する場合は、Confidence を下げて断定を避ける
- 「プロジェクトの文脈がなければ判断できない設計批評」は避ける

## 推奨: Signals（適用判断材料）

`signals` は frontmatter のフィールドではありませんが、本文に「このスキルを適用する判断材料」を書くとブレが減ります。

- 例: 「例外を握りつぶす `catch`（ログなし、再throwなし）が差分に含まれる場合は適用する」
- 例: 「認証情報らしき文字列（AKIA/ghp\_/sk- など）が差分に含まれる場合は適用する」

## Severity の基準（目安）

`severity` は「レビューを受けた人がどう扱うべきか」の目安です。

- `critical`: セキュリティ事故やデータ破壊につながる、即対応が必要
- `major`: バグ・運用障害のリスクが高い、原則対応したい
- `minor`: 将来の保守性・読みやすさに効く、余力があれば直したい
- `info`: 判断材料の提示（“検討ポイント”）

補足:

- しばしば `blocker` / `warning` / `nit` の3段階で語られるが、本リポジトリの enum は `info` / `minor` / `major` / `critical` である。

## Confidence（確信度）の表現（特に low の場合）

Confidence が low（推測が混じる）場合は、読み手に「断定ではない」ことが伝わる書き方にする。

- `must` / `should` / `definitely` などの断定表現を避ける
- `may` / `might` / `consider` など “可能性/提案” を示す表現を使う
- 事実（Evidence）と提案（推測）を分けて書く（例: “差分上は X が見える。Y の可能性があるため確認を検討する”）

## Evidence（根拠）の必須要件

River Review のコメントは `<file>:<line>: <message>` 形式で投稿されます。最低限、以下を満たしてください。

- **どこを見て言っているか**が分かる（ファイルと行に紐づく）
- **推測を断定しない**（不確実な場合は “可能性” として書く）
- **再現や確認の手がかり**がある（何を確認すれば良いか）
- **日本語でコメントする**（レビューコメントは日本語で返す）

## 出力フォーマット（必須）

スキルが返す `message` は長くできません。最低限、次の要素が読み取れるように書きます。

- Finding: 何が問題か（短く、断定しすぎない）
- Evidence: 根拠（どのファイル/行の、どの差分か）
- Impact: 放置した場合の影響（短く）
- Fix: 最小の修正案（次の一手）

補足:

- Evidence が書けない指摘は、原則として書かない。
- Confidence や Severity はスキーマフィールド（`confidence: high|medium|low`, `severity: critical|major|minor|info`）として JSON 出力に含まれる。LLM に出力させる場合は `Confidence:` や `Severity:` ラベルをメッセージ中に含めると自動的にパースされる。

## 推奨: 指摘文の型（短文版）

`<message>` は長くできないため、短くても読みやすい「型」を揃えます。

- Finding: 何が問題か（1文）
- Evidence: 根拠（ファイルと行、diff で見える事実）
- Impact: 何が困るか（短く）
- Fix: 最小の修正案（次の一手）

例:

- `src/foo.ts:42: 例外が握りつぶされる可能性。障害調査が困難。Fix: catch でログ+再throw（or 呼び出し元へ返す）`

## 禁止事項（アンチパターン）

- 断定口調の決め打ち（「必ず〜」「〜に違いない」）
- 状況依存の押し付け（プロジェクトの前提が不明なのに “こうすべき” を断言）
- “nit” の濫発（意味の薄い指摘を大量に出す）
- 差分と無関係な一般論の連発
- 他スキルと役割が被る実装（重複が増えてノイズになる）

## 誤検知を減らすためのルール（Guards）

スキルは「抑制条件」を持つ必要があります。誤検知は “直す価値がある不具合” として扱います。

例:

- 既に入力検証が存在する場合は指摘しない
- context 付きログがある場合はログ改善を提案しない

## PR 時の最小チェック

スキルを追加・更新したら、PR 本文に以下を残します。

- `npm run skills:validate`
- `npm test`
- 可能なら “誤検知ガード/Non-goals” の確認観点（何を言わないか）

## Fixtures と評価ワークフロー

各スキルには `fixtures/`（入力 diff サンプル）と `golden/`（期待出力）という兄弟ディレクトリを用意できます。これらは Minimum Acceptance Bar を客観的に検証するための評価セットです。

### ディレクトリ構造

```text
skills/<phase>/<skill-id>/
├── SKILL.md
├── fixtures/
│   ├── 01-true-positive-<説明>.md   # 指摘すべきケース
│   └── 02-false-positive-<説明>.md  # 指摘しないべきケース
├── golden/
│   ├── 01-true-positive-<説明>.md   # 期待される出力
│   └── 02-false-positive-<説明>.md  # 期待される出力（指摘なし）
└── eval/
    └── promptfoo.yaml               # promptfoo 設定（任意）
```

- ファイル名は `<数字プレフィックス>-<種別>-<説明>.md` の形式にします（例: `01-true-positive-undocumented-dependency.md`）。
- `fixtures/` と `golden/` のファイル名は完全一致させます（ペアで評価するため）。
- `true-positive` ケースでは、スキルが少なくとも1件の指摘を返すことを確認する。
- `false-positive` ケースでは、スキルが指摘を返さないこと（または無関係な指摘を返さないこと）を確認する。

### 評価の実行

```bash
npm run eval:fixtures
```

promptfoo を直接使う場合は `npx promptfoo eval` でも実行できます。eval の詳細なセットアップは `pages/guides/repo-wide-review.md` を参照してください。

### なぜ fixtures が重要か

fixtures がないと、スキルが「本当に指摘すべき差分を検知できるか」「誤検知ガードが機能しているか」を人手でしか確認できません。Minimum Acceptance Bar（下記）の検証は fixtures があって初めて再現可能になります。

## スキル追加・変更時のチェックリスト

- [ ] 指摘が 1 観点に絞られている
- [ ] Evidence（ファイル/行、diff の事実）が明確である
- [ ] 誤検知ガード（抑制条件）がある
- [ ] Non-goals（扱わないこと）が書かれている
- [ ] `fixtures/` と `golden/` に true-positive / false-positive ケースがある（Minimum Acceptance Bar の検証に必須）

## Minimum Acceptance Bar（最低合格ライン）

A skill is considered “acceptable” when it meets the following minimum bar:
（スキルが「合格」と見なされるのは、次の最低基準を満たしている場合です。）

- It produces at least one actionable finding when applicable (a concrete next step, not just a vague note).
- （該当する場合、少なくとも1つの具体的な次の一手につながる指摘があること。）
- It includes clear evidence that can be traced to the diff (file and line).
- （差分（ファイルと行）に追跡できる明確な根拠が含まれること。）
- It avoids noise (no “nit” spam) and stays focused on meaningful risks.
- （ノイズ（“nit”の濫発）を避け、意味のあるリスクに集中していること。）

## 良いスキルの目安

- 指摘が「当たる」確率が高い（誤検知が少ない）
- 修正案が具体的で、次の一手が明確である
- ノイズが少なく、1観点に集中している

より厳密な採用基準（優先順）は `pages/guides/governance/skill-policy.md` を参照してください。